Repository navigation
feat(unit): continue a Unit in its existing session - #34
Merged
Merged
Conversation
A review -> fix -> re-review loop could not keep a conversation: every
`agent()` call starts a fresh session, so the second reviewer knew nothing
the first one had learned and re-read the same files. A loop that genuinely
converges — "re-check exactly what you found" — was impossible without
stuffing the transcript back into a new prompt, which loses the prompt
cache and the Unit's own tool results.
Add a conversation:
const review = await agent("Review the diff.", {
label: "reviewer",
schema: Findings,
keepSession: true, // -> UnitHandle
})
review = await review.resume("Re-check against the fixes.", { schema: Findings })
await review.close()
`keepSession: true` resolves to a `UnitHandle`: the same receipt (`value`,
`unitId`, `toolCalls`) plus `sessionID`, `resume(prompt, opts)` and
`close()`. `agent(prompt, { session })` is the same thing without a handle.
A continuation is still a NEW Unit of the Run — its own `unitId`, ordinal
and prompt, journaled and replayed like any other — so limits, budget,
errors, the surfaces and resume all behave unchanged. What it shares is the
session, which is the point: its own transcript, its own tool results, its
prompt cache.
What the session fixed at create time cannot be re-decided by a turn —
`subagent`, `model`, `effort`, `location`, `isolation`, `permissions` — because
the host's `prompt` takes a session id and text. Passing one is an error
with a legible message (a failed Unit), never a silent ignore: a turn that
runs on the old agent while the author believes they changed it is the one
outcome worth refusing.
Accounting is per turn, not per session. `session.get` reports lifetime
totals, so a baseline is taken before each turn and subtracted: three turns
that each spend 10 report 10, 10, 10 while the Run's total is 30. The same
rule applies to the crash path (a backstop without a baseline would bill the
whole conversation to one Unit) and to `toolCalls`, which is sliced to the
turn the runner measured when that turn ended — a lazy receipt read after
the next turn must not report the next turn's calls, and a repair turn must
not shrink it to the repair prompt.
A turn whose own extent cannot be measured fails instead of falling back to
the whole transcript: reporting another turn's text as this turn's answer is
worse than an error. Sequential by construction — one turn at a time per
session, a second concurrent one is refused.
The transcript view follows the same idea: `getTranscript` returns the
Unit's own turn and `earlier` (how much came before), `?whole=1` returns the
conversation, and the web panel shows "this turn only" with a
"Show whole conversation" action.
Refs #33
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #33.
The problem
A review → fix → re-review loop could not keep a conversation. Every
agent()call starts a fresh session, so thesecond reviewer knew nothing the first one had learned: it re-read the same files, paid full price for context that was
already in the previous session, and was a different agent instance with no memory of what it had already verified.
The workaround — threading the transcript back as text — works, but loses the prompt cache and the Unit's own tool
results, and grows the prompt every round. For a loop that is supposed to converge ("re-check exactly what you
found"), that defeats the purpose.
What this adds
keepSession: trueresolves to aUnitHandle: the same receipt (value,unitId,toolCalls) plussessionID,resume(prompt, opts)andclose().agent(prompt, { session })is the same thing without a handle, for scripts thatthread the id themselves.
Design decisions
A continuation is still a new Unit. Its own
unitId, ordinal and prompt — journaled, replayed, counted and renderedlike any other. Two Units that share a
sessionIDare two turns of one conversation, which is why limits, budget,errors, the TUI/web surfaces and resume need no changes at all. A surface keys a Unit byunitId, never by session,so a finished turn stays finished while the next one runs; only session retention dedupes on the id.
The session decides once.
subagent/agentType,model,effort,location,isolationandpermissionsarefixed at create time — the host's
prompttakes a session id and text, nothing else. Passing one on a turn is anerror (a failed Unit with a legible message), never a silent ignore. A turn that ran on the old agent while the
author believed they changed it is worse than a failure. Per-turn options still work:
schema,retries,timeoutMs,label,phase.Accounting is per turn.
session.getreports lifetime totals, so a baseline is taken before each turn andsubtracted: three turns that each spend 10 report 10, 10, 10 while the Run's total is 30. The same rule covers the
crash path (a backstop without a baseline would bill the whole conversation to one Unit) and
toolCalls, which issliced to the extent the runner measured when that turn ended — a lazy receipt read after the next turn must not
report the next turn's calls, and a repair turn must not shrink it to the repair prompt.
An unmeasurable turn fails. If the session transcript cannot be read when a continuation starts, the turn fails with
a legible error instead of falling back to the whole transcript: reporting another turn's text as this turn's answer is
worse than an error. Likewise a continuation that dies before its answer read reports
[]tool calls (unknown), neverthe earlier turn's.
Sequential by construction. One turn at a time per session; a second concurrent
resumeis refused rather thaninterleaved into the same transcript.
Transcript view
A continued Unit's transcript is sliced at its own prompt (measured, not re-derived), with
earliercounting what camebefore;
?whole=1(or?whole=true) returns the conversation. The web panel shows "Showing this turn only — N earliermessages hidden" with a Show whole conversation action, so a three-turn loop does not read as one long log by
default. Additive to protocol v1 (
GetTranscriptOutput.earlier/turns,TranscriptRef.whole), documented in theOpenAPI document.
Verification
bun run check— 427 tests, format/lint/typecheck clean; protocol JSON Schemas andopenapi.jsonregenerated.packages/plugin/test/conversation.test.ts— 30 tests covering: same-session turns, refused fixed parameters,per-turn schema/usage/toolCalls, busy guard,
close(), unknown/stray session ids, replay without prompting the model,divergence mid-conversation, and the failure paths above.
service.test.tscase drives two turns throughWorkflowServiceand checks own-turn vswholetranscripts.
dynamic-workflowsskill, and a runnablepackages/plugin/docs/examples/review-loop.ts.Review: five rounds of adversarial review (blocker: a continuation returning the previous turn's answer; major:
double-counted budget on the crash path, a stray session id reaching cleanup, tautological tests) — all closed and each
fix confirmed by reverting it.