Skip to content

v0.5.0

Choose a tag to compare

@github-actions github-actions released this 03 Oct 19:14
· 45 commits to main since this release

Added

  • Subagent prompts and results are observed as part of the session: the
    Agent tool call's prompt and the SubagentStop answer are consulted like
    the user's own prompt and answer end, under the parent's session id. The
    plugin now registers SubagentStart, the first hook to carry the id Claude
    Code gave the agent; the relay records it as an agent_start and pairs it
    with the Agent call that spawned it, oldest of the type first. Advice from
    a subagent's prompt is queued at the action level, addressed to that call
    and from there to the id, and lands at the subagent's start when it is
    ready by then or at its next tool call; neither the main thread nor a
    sibling takes it. A subagent's injections are charged to the session's
    character cap and leave the main thread's event gap alone. A subagent's event
    may add findings and facts but never rules or preferences: those are
    dropped before the write, counted in
    shoulder_facts_agent_rule_dropped_total, and logged with their content. A
    subagent's stop does not advance the session's event counter and does not start the
    periodic tidy. A neutral event that names an agent_id is taken as the
    agent's whether or not it also sends origin.
  • An optional triage step in front of the decision model, backed by TypeSafe's
    Jev (System One). With SHOULDER_TRIAGE=jev and TYPESAFE_API_KEY, every
    event is first classified as needing nothing, a new fact, a change to a stored
    fact, or a stored fact repeated to the session. A confident "repeat" injects
    the stored fact as it is at the next tool call, and a confident "nothing" at
    pickiness balanced or stricter settles it, both without calling the
    decision model; everything else, including "nothing" at eager or open, a
    verdict under SHOULDER_JEV_MIN_CONFIDENCE (0.6) and any triage failure,
    goes to the decision model unchanged. Triage is cut off after a quarter of
    ADVISOR_TIMEOUT_SECONDS, at most 5s, so a stalled Jev does not use up the
    decision model's time, and its latency is reported as
    shoulder_hook_latency_seconds{event="triage"}. Triage also runs with no
    SHOULDER_LLM, where a fact it wants written is counted in
    shoulder_triage_unhandled_total rather than dropped. shoulderd config show reports the triage in use.
  • shoulderd doctor reports the decision model on an llm: line and compares
    the provider, the model where the env file names one, and the store with
    what the env file asks for. /v1/cli/config and /v1/cli/memory now say
    where each value came from - the env file, the process environment,
    config set, or nothing - and which file the daemon read. A difference in a
    value from the file or from nothing is a daemon started before the file was
    edited or from another file, and fails as MISMATCH; one from the process
    environment or config set was chosen over the file and is printed as a
    note. Doctor also fails when there is no decision model, and when the store
    failed to open at start, which it reports with the reason rather than as no
    store. A triage with no decision model reads llm: none (triage only) and
    passes. While nothing listens, it shows the end of the start command's
    output. --liveness is unchanged.
  • shoulderd env path|get|set|unset reads and writes the env file with the
    grammar the daemon reads it with; set changes a setting where it first
    stands, takes a secret on standard input and writes through a link. The
    setup skill's env-set.sh and make install-plugins now go through it, and
    the token the daemon generates is written single-quoted, so every value they
    write reads back as itself. A leading ~/ in SHOULDER_ENV_FILE is home
    everywhere the file is resolved.
  • make up-check prints whether make up would recreate the relay, and the
    names of the variables behind the answer, without doing anything.
  • make check-stack runs the compose stack through make up under a project,
    a port, a volume, an env file, a deploy/.env and a state directory of its
    own, with a stub model and a stub store, and fails unless compose reads that
    env file and no other, make up recreates a relay that is stale or predates
    the hash and leaves a current one alone, and doctor reports the configured
    model and store as coming from the file. It leaves a running install alone
    and removes what it created.

Changed

  • The word "turn" is gone from the project: the unit is the event, one
    utterance by the user or by an agent, and nothing groups a prompt with its
    answer. Renamed with it:
    • the wire kind turn_end is answer_end. /v1/events still accepts
      turn_end from an adapter installed before this, and records it as an
      answer_end; the OpenCode adapter sends the new name;
    • the setting BUDGET_MIN_TURN_GAP is BUDGET_MIN_EVENT_GAP. The old key
      is still read while the new one is unset, and the daemon logs one line
      at start naming the replacement;
    • the metric shoulder_advice_suppressed_turn_gap_total is
      shoulder_advice_suppressed_event_gap_total, with no alias;
    • in the advice a neutral adapter is answered with, created_turn and
      ttl_turns are created_event and ttl_events; in the /v1/sessions
      listing, turn is main_events; in the log, the turn attribute of
      advice queued is main_events, which shoulderd monitor prints as
      event N;
    • the decision prompt's <recent-turn> tag is <recent-events>, the state
      sent to Jev names the window recent_events, and both prompts speak of
      events;
    • replay -max-turns is replay -max-answers.
  • The session's counter, which advice is aged and budgeted in, advances on
    every prompt of the user and on every answer end of the main thread, where
    it advanced on the answer end alone; a subagent's prompt and stop still
    leave it alone. Everything counted in it is doubled so that a session
    behaves as before: the default of BUDGET_MIN_EVENT_GAP is 6 where it was 3,
    advice expires 4 counts after it was written where it was 2, and the
    periodic tidy runs every 10 where it was 5. A gap set in
    an env file keeps its number and now spans half as much of the session:
    double it to keep the gap it had. The tidy runs at the first answer end in
    each span of 10, so a prompt whose answer was interrupted does not put it
    off. A note delivered before the first answer ended did not open the gap;
    it does now. A note written at an answer end is current for the next two
    prompts, where it was three.
  • Every prompt and every answer end is consulted, the main thread's and a
    subagent's alike, and the consults of one session run concurrently. Before,
    one consult ran per session at a time and a prompt or an answer end that
    arrived meanwhile was dropped, so agents spawned together were not all
    advised and an answer end behind a slow consult lost its facts.
    shoulder_advisor_skipped_inflight_total is gone with the drop, and
    advisor_in_flight is gone from the session summary. Only the rewrite of
    the session's keyword record is serialised, one consult at a time. Advice
    whose text is already pending for the same session and addressee is not
    queued twice and is counted in shoulder_advice_duplicate_total.
  • The fact categories are now finding (something a session established by
    looking), fact (a durable truth about the project or the machine), rule
    (a constraint or decision that governs how work is done here) and
    preference (how the person wants work or communication done; private).
    A rule or a preference is stored only when the user said it: the
    decision prompt refuses one from an agent line or from what the assistant
    concluded, and facts.UserOnly names the two for the pipeline to enforce on
    a consult that comes from a subagent. The old names map forward on read, on
    fact add, on migration and in the model's reply: decision, constraint
    and correction become rule, structure and reference become fact.
    The docs store files new records in FINDINGS, FACTS, RULES and
    USER.shoulder.md, writes every category under its current name, and keeps
    reading and correcting in place the ARCHITECTURE, DECISIONS,
    CONVENTIONS and REFERENCES.shoulder.md files an older daemon wrote.
  • Recall searches each scope for the recent prose as a whole and once more for
    each of its sentences, up to sixteen, and merges the hits by record with the
    best score kept, so a stored fact that matches one sentence closely is found
    rather than averaged away by the rest of the window. A sentence ends at a
    line break or at a terminator that ends a word, so a file name, a version
    or a hostname is not cut in two; a one-word piece is not searched, and a
    window over the cap keeps its newest sentences. The searches run four at a
    time; the cut is counted in shoulder_recall_sentences_dropped_total.
  • The built-in store returns a legacy category under its current name on
    every read, as the docs store and the memory service already did, so a
    facts.json written by an older daemon no longer puts decision or
    structure in front of the decision model or in shoulderd fact list.
  • The registry no longer holds facts recorded explicitly for an event: nothing
    ever recorded one, so the path that reconciled them with the model's was
    dead, and an event triage settles now writes nothing.

Fixed

  • The container reads the daemon's one env file, $SHOULDER_ENV_FILE or
    ${XDG_CONFIG_HOME:-~/.config}/shoulder-daemon/env, the file the docs tell
    you to write and the CLI and the adapters read, and no other. It used to read
    deploy/.env instead, so an install configured as documented ran with no
    model and the built-in store, silently. deploy/.env is no longer read for
    the daemon's settings: move them into the env file. The Makefile resolves
    the path; compose run by hand needs SHOULDER_ENV_FILE set and refuses to
    start without it. make up and make update name, without values,
    whatever deploy/.env still sets, so a setting left there is not lost
    unannounced. ADVISOR_BASE_URL, ADVISOR_MODEL,
    ADVISOR_API_KEY and ADVISOR_SYSTEM_PROMPT, which had no effect, are no
    longer read at all.
  • The stack is run with podman and podman-compose by name. It needed podman
    already, for userns_mode: keep-id; docker compose and podman compose,
    which picks docker-compose when it is installed, are no longer used.
  • The daemon, the CLI and the OpenCode adapter read the env file with the
    grammar podman-compose reads it with, python-dotenv's: a # comment after
    an unquoted value is dropped, a # inside quotes is kept, double quotes take
    escapes such as \n and \", single quotes take only \' and \\, and
    ${NAME} and ${NAME:-default} are expanded. They used to keep the comment
    and the backslashes and leave ${...} alone, so a containerised daemon and
    doctor, or a bare daemon and compose, could read one line two ways.
  • make up recreates the relay when its env file changed since the relay was
    created, by the file's hash, which compose puts in the relay's environment.
    It passes --no-recreate, so an edited file used to reach a running install
    only after a make down. The relay is recreated alone, with --no-deps; the
    memory service is not restarted. A relay created before this release is
    recreated once, and two sessions starting together are kept apart with
    flock.
  • make update fails when a relay exists and could not be recreated, rather
    than reporting success; an install with no stack is still skipped.
  • The plugin keeps the start command's output in
    ~/.local/state/shoulder-daemon/up.log instead of discarding it, says when
    the start failed, and waits thirty seconds before trying again.