You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.