Skip to content

feat(unit): continue a Unit in its existing session - #34

Merged
syn7xx merged 1 commit into
mainfrom
feat/continue-unit-session
Nov 17, 2026
Merged

syn7xx merged 1 commit into
mainfrom
feat/continue-unit-session

Conversation

@syn7xx

@syn7xx syn7xx commented Nov 17, 2026

Copy link
Copy Markdown
Owner

Closes #33.

The problem

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: 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

const review = await agent("Review the diff. List every issue you find.", {
  label: "reviewer",
  schema: Findings,
  keepSession: true,                                     // → UnitHandle
})

for (let round = 0; round < 3 && (review.value?.issues.length ?? 0) > 0; round++) {
  await agent(`Fix exactly these:\n${JSON.stringify(review.value.issues)}`, { label: `fix-${round}` })
  review = await review.resume("Re-check your previous findings 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, for scripts that
thread the id themselves.

Design decisions

A continuation is still a new Unit. Its own unitId, ordinal and prompt — journaled, replayed, counted and rendered
like any other. Two Units that share a sessionID are 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 by unitId, 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, isolation and permissions are
fixed at create time — the host's prompt takes a session id and text, nothing else. Passing one on a turn is an
error (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.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 covers the
crash path (a backstop without a baseline would bill the whole conversation to one Unit) and toolCalls, which is
sliced 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), never
the earlier turn's.

Sequential by construction. One turn at a time per session; a second concurrent resume is refused rather than
interleaved into the same transcript.

Transcript view

A continued Unit's transcript is sliced at its own prompt (measured, not re-derived), with earlier counting what came
before; ?whole=1 (or ?whole=true) returns the conversation. The web panel shows "Showing this turn only — N earlier
messages 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 the
OpenAPI document.

Verification

  • bun run check — 427 tests, format/lint/typecheck clean; protocol JSON Schemas and openapi.json regenerated.
  • 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.
  • Every key regression test was verified by reverting the fix and confirming it fails.
  • An end-to-end service.test.ts case drives two turns through WorkflowService and checks own-turn vs whole
    transcripts.
  • Docs: README ("Continuing a Unit"), the dynamic-workflows skill, and a runnable
    packages/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.

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
@syn7xx
syn7xx merged commit 7564e21 into main Nov 17, 2026
4 checks passed
@syn7xx
syn7xx deleted the feat/continue-unit-session branch November 17, 2026 15:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

workflow: no way to continue a Unit — every agent() call starts a fresh session, so review→fix loops lose context

1 participant