diff --git a/README.md b/README.md index 5664a05..f8bded8 100644 --- a/README.md +++ b/README.md @@ -316,6 +316,7 @@ its default. The [`dynamic-workflows` skill](packages/plugin/skill/dynamic-workflows/SKILL.md) is the complete guide, and [`packages/plugin/docs/examples/`](packages/plugin/docs/examples) has runnable Workflows: [`review-files.ts`](packages/plugin/docs/examples/review-files.ts) (typed findings per file), +[`review-loop.ts`](packages/plugin/docs/examples/review-loop.ts) (review → fix → re-review in one conversation), [`research.ts`](packages/plugin/docs/examples/research.ts) (a question to the person, a hard token budget) and [`repo-report.ts`](packages/plugin/docs/examples/repo-report.ts) (`ctx.$` and `ctx.file`). Import everything from `@syn7xx/opencode-dynamic-workflows/workflow`. @@ -324,7 +325,7 @@ The [`dynamic-workflows` skill](packages/plugin/skill/dynamic-workflows/SKILL.md | Member | What it does | | --- | --- | -| `agent(prompt, opts?)` | One Unit. Returns its final text, or with `schema` a validated value. A failed Unit returns `null` and is added to `errors`; it never throws. With `{ receipts: true }` it returns `{ value, unitId, toolCalls }` instead — see [Asserting what a Unit did](#asserting-what-a-unit-did). | +| `agent(prompt, opts?)` | One Unit. Returns its final text, or with `schema` a validated value. A failed Unit returns `null` and is added to `errors`; it never throws. With `{ receipts: true }` it returns `{ value, unitId, toolCalls }` instead — see [Asserting what a Unit did](#asserting-what-a-unit-did). With `{ keepSession: true }` it returns a handle with `sessionID` and `resume()` — see [Continuing a Unit](#continuing-a-unit). | | `pipeline(items, ...stages)` | Each item runs through its stages on its own, with no barrier between items. Stages get `(previous, item, index)`. | | `parallel(thunks)` | Runs thunks concurrently and waits for all of them (a barrier). Failures become `null`. | | `collect(xs)` | Drops the `null`s, with the narrowed type. | @@ -342,9 +343,10 @@ The [`dynamic-workflows` skill](packages/plugin/skill/dynamic-workflows/SKILL.md `agent()` options: `schema`, `label`, `phase`, `subagent` (alias `agentType`; default `general`), `model` (`"provider/model#variant"`, `{ providerID, modelID }`, or `"inherit"` for the launching session's model), `effort` (the reasoning variant; with no `model` the Unit inherits the caller's model at that effort), `retries` (repair turns, -default 2), `timeoutMs`, `permissions`, `isolation: "worktree"` (a fresh git worktree, removed if unchanged) and -`location` (another directory). `{ receipts: true }` is a separate flag rather than one of these options — see -[Asserting what a Unit did](#asserting-what-a-unit-did). +default 2), `timeoutMs`, `permissions`, `isolation: "worktree"` (a fresh git worktree, removed if unchanged), +`location` (another directory) and `session` (continue an existing session — see [Continuing a Unit](#continuing-a-unit)). +`{ receipts: true }` and `{ keepSession: true }` are separate flags rather than options — see +[Asserting what a Unit did](#asserting-what-a-unit-did) and [Continuing a Unit](#continuing-a-unit). `meta`: `name`, `description`, `whenToUse`, `phases`, `args` (zod), `concurrency`, `unitTimeout`, `budget` (a number, or `{ tokens, hard: true }` to stop at the limit), `permissions` (rules for every Unit), `limits`, and @@ -420,6 +422,66 @@ Opting in to receipts also changes the shape of a fan-out, because a receipt is `parallel()` of receipts keeps the failed Units instead of dropping them (`value` is what carries the failure), so filter on `value` when you want only the Units that succeeded. +### Continuing a Unit + +Each `agent()` call starts a fresh session, so a second reviewer knows nothing the first one learned. When a stage +should come back to the **same conversation** — re-checking its own findings, applying the fixes it proposed, +iterating until clean — keep the session instead of starting over: + +```ts +let review = await agent("Review the diff. List every issue you find.", { + label: "reviewer", + schema: Findings, + keepSession: true, +}) + +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 you just made.", { + schema: Findings, + }) +} +``` + +`keepSession: true` resolves to a handle — the same `{ value, unitId, toolCalls }` a receipt has, plus `sessionID`, +`resume(prompt, opts?)` and `close()`. `resume` sends the next turn into that session, so it sees its own earlier +transcript and tool results (the files it already read) and reuses the prompt cache. For a review → fix loop that is +the difference between re-reading the repository every round and continuing where the last turn stopped. + +The second turn is still **a new Unit**: its own `unitId`, ordinal and prompt, journaled and replayed like any other, +so limits, budget, `errors`, the TUI and resume all behave unchanged. Two Units that share a `sessionID` are two turns +of one conversation — and, deliberately, two **rows**: the surfaces key a Unit by `unitId`, never by session, so a +turn that finished stays finished while the next one runs. Only session retention dedupes on the id +(`cleanupTargets`), so one conversation is cleaned up once. + +What the session fixes at create time cannot be changed by a later turn — `subagent`/`agentType`, `model`, `effort`, +`location`, `isolation` and `permissions`. The host's `prompt` takes a session id and text, nothing else, so passing +one of those on a continuation is an **error** (the turn fails with a legible message in `errors`) rather than a +silent ignore. Start a new Unit when the agent or model must change. Per-turn options still work: `schema`, `retries`, +`timeoutMs`, `label`, `phase` — a text turn followed by a typed one on the same session is normal for this loop. + +Conversations are **sequential**: one turn at a time per session, so a second concurrent `resume` on the same handle +is refused. Usage and `toolCalls` are reported **per turn** (what that turn spent and called, not the session's +lifetime totals), so `budget` and receipts stay meaningful across a long conversation. `close()` is optional — an idle +kept session runs nothing, and the Run's cleanup still owns its retention — but it ends the conversation, so a later +turn on it fails instead of running. + +**What the transcript shows.** A Unit's transcript view is that Unit's own turn: the web app sends +`GET /v1/runs/{runId}/units/{unitId}/transcript` (or the `getTranscript` RPC), which slices the session at this turn's +prompt and reports `earlier` — how many messages came before. "Show whole conversation" asks for `?whole=1`. The slice +is derived from the transcript itself (each turn opens with its prompt as a `user` message, and turns run strictly one +after another), so nothing extra is journaled and a resumed Run slices the same way. In the TUI the transcript button +opens the session in OpenCode itself, where the whole conversation is visible. + +One consequence worth knowing: because a continuation's answer is read from its own slice, a turn whose slice cannot be +measured — the session transcript is unreadable when the turn starts — **fails with a legible error** rather than +falling back to the whole session. Reporting another turn's text as this turn's answer would be worse than a failure. + +`agent(prompt, { session })` does the same without a handle, for when you thread the id through your own state. +`{ keepSession: true }` has to be written inline (or on an `as const` object), like `receipts: true`: a plain +`boolean` variable selects no overload. A handle journals as `{ value, unitId, sessionID }` — `toolCalls`, `resume` +and `close` are not enumerable. + ### Resume Every Run is journaled under `.opencode/workflows/runs//`. A plugin reload does not stop running Runs. If the @@ -427,6 +489,10 @@ OpenCode service dies, the Run reads back as `interrupted`. `resume` starts a ne and prompt: each Unit whose prompt is unchanged returns its recorded result at once, answers to `ask` are replayed, and from the first changed prompt on everything runs live. Units that failed run again. +A conversation replays the same way, turn by turn: every turn is its own Unit with its own prompt, so a resumed Run +reproduces the whole exchange without prompting the model once. A replayed first turn keeps the session the original +Run recorded, so a script can go on with the conversation live after the replayed part. + A Workflow composed of several files (its entry importing local modules, at any depth) journals the bundled module the Run actually executed alongside its source, so a resume replays that exact module even if those files were edited, moved or deleted in the meantime. diff --git a/packages/plugin/README.md b/packages/plugin/README.md index d4faba4..14da422 100644 --- a/packages/plugin/README.md +++ b/packages/plugin/README.md @@ -318,6 +318,7 @@ its default. The [`dynamic-workflows` skill](https://github.com/syn7xx/opencode-dynamic-workflows/blob/main/packages/plugin/skill/dynamic-workflows/SKILL.md) is the complete guide, and [`packages/plugin/docs/examples/`](https://github.com/syn7xx/opencode-dynamic-workflows/tree/main/packages/plugin/docs/examples) has runnable Workflows: [`review-files.ts`](https://github.com/syn7xx/opencode-dynamic-workflows/blob/main/packages/plugin/docs/examples/review-files.ts) (typed findings per file), +[`review-loop.ts`](https://github.com/syn7xx/opencode-dynamic-workflows/blob/main/packages/plugin/docs/examples/review-loop.ts) (review → fix → re-review in one conversation), [`research.ts`](https://github.com/syn7xx/opencode-dynamic-workflows/blob/main/packages/plugin/docs/examples/research.ts) (a question to the person, a hard token budget) and [`repo-report.ts`](https://github.com/syn7xx/opencode-dynamic-workflows/blob/main/packages/plugin/docs/examples/repo-report.ts) (`ctx.$` and `ctx.file`). Import everything from `@syn7xx/opencode-dynamic-workflows/workflow`. @@ -326,7 +327,7 @@ The [`dynamic-workflows` skill](https://github.com/syn7xx/opencode-dynamic-workf | Member | What it does | | --- | --- | -| `agent(prompt, opts?)` | One Unit. Returns its final text, or with `schema` a validated value. A failed Unit returns `null` and is added to `errors`; it never throws. With `{ receipts: true }` it returns `{ value, unitId, toolCalls }` instead — see [Asserting what a Unit did](#asserting-what-a-unit-did). | +| `agent(prompt, opts?)` | One Unit. Returns its final text, or with `schema` a validated value. A failed Unit returns `null` and is added to `errors`; it never throws. With `{ receipts: true }` it returns `{ value, unitId, toolCalls }` instead — see [Asserting what a Unit did](#asserting-what-a-unit-did). With `{ keepSession: true }` it returns a handle with `sessionID` and `resume()` — see [Continuing a Unit](#continuing-a-unit). | | `pipeline(items, ...stages)` | Each item runs through its stages on its own, with no barrier between items. Stages get `(previous, item, index)`. | | `parallel(thunks)` | Runs thunks concurrently and waits for all of them (a barrier). Failures become `null`. | | `collect(xs)` | Drops the `null`s, with the narrowed type. | @@ -344,9 +345,10 @@ The [`dynamic-workflows` skill](https://github.com/syn7xx/opencode-dynamic-workf `agent()` options: `schema`, `label`, `phase`, `subagent` (alias `agentType`; default `general`), `model` (`"provider/model#variant"`, `{ providerID, modelID }`, or `"inherit"` for the launching session's model), `effort` (the reasoning variant; with no `model` the Unit inherits the caller's model at that effort), `retries` (repair turns, -default 2), `timeoutMs`, `permissions`, `isolation: "worktree"` (a fresh git worktree, removed if unchanged) and -`location` (another directory). `{ receipts: true }` is a separate flag rather than one of these options — see -[Asserting what a Unit did](#asserting-what-a-unit-did). +default 2), `timeoutMs`, `permissions`, `isolation: "worktree"` (a fresh git worktree, removed if unchanged), +`location` (another directory) and `session` (continue an existing session — see [Continuing a Unit](#continuing-a-unit)). +`{ receipts: true }` and `{ keepSession: true }` are separate flags rather than options — see +[Asserting what a Unit did](#asserting-what-a-unit-did) and [Continuing a Unit](#continuing-a-unit). `meta`: `name`, `description`, `whenToUse`, `phases`, `args` (zod), `concurrency`, `unitTimeout`, `budget` (a number, or `{ tokens, hard: true }` to stop at the limit), `permissions` (rules for every Unit), `limits`, and @@ -422,6 +424,66 @@ Opting in to receipts also changes the shape of a fan-out, because a receipt is `parallel()` of receipts keeps the failed Units instead of dropping them (`value` is what carries the failure), so filter on `value` when you want only the Units that succeeded. +### Continuing a Unit + +Each `agent()` call starts a fresh session, so a second reviewer knows nothing the first one learned. When a stage +should come back to the **same conversation** — re-checking its own findings, applying the fixes it proposed, +iterating until clean — keep the session instead of starting over: + +```ts +let review = await agent("Review the diff. List every issue you find.", { + label: "reviewer", + schema: Findings, + keepSession: true, +}) + +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 you just made.", { + schema: Findings, + }) +} +``` + +`keepSession: true` resolves to a handle — the same `{ value, unitId, toolCalls }` a receipt has, plus `sessionID`, +`resume(prompt, opts?)` and `close()`. `resume` sends the next turn into that session, so it sees its own earlier +transcript and tool results (the files it already read) and reuses the prompt cache. For a review → fix loop that is +the difference between re-reading the repository every round and continuing where the last turn stopped. + +The second turn is still **a new Unit**: its own `unitId`, ordinal and prompt, journaled and replayed like any other, +so limits, budget, `errors`, the TUI and resume all behave unchanged. Two Units that share a `sessionID` are two turns +of one conversation — and, deliberately, two **rows**: the surfaces key a Unit by `unitId`, never by session, so a +turn that finished stays finished while the next one runs. Only session retention dedupes on the id +(`cleanupTargets`), so one conversation is cleaned up once. + +What the session fixes at create time cannot be changed by a later turn — `subagent`/`agentType`, `model`, `effort`, +`location`, `isolation` and `permissions`. The host's `prompt` takes a session id and text, nothing else, so passing +one of those on a continuation is an **error** (the turn fails with a legible message in `errors`) rather than a +silent ignore. Start a new Unit when the agent or model must change. Per-turn options still work: `schema`, `retries`, +`timeoutMs`, `label`, `phase` — a text turn followed by a typed one on the same session is normal for this loop. + +Conversations are **sequential**: one turn at a time per session, so a second concurrent `resume` on the same handle +is refused. Usage and `toolCalls` are reported **per turn** (what that turn spent and called, not the session's +lifetime totals), so `budget` and receipts stay meaningful across a long conversation. `close()` is optional — an idle +kept session runs nothing, and the Run's cleanup still owns its retention — but it ends the conversation, so a later +turn on it fails instead of running. + +**What the transcript shows.** A Unit's transcript view is that Unit's own turn: the web app sends +`GET /v1/runs/{runId}/units/{unitId}/transcript` (or the `getTranscript` RPC), which slices the session at this turn's +prompt and reports `earlier` — how many messages came before. "Show whole conversation" asks for `?whole=1`. The slice +is derived from the transcript itself (each turn opens with its prompt as a `user` message, and turns run strictly one +after another), so nothing extra is journaled and a resumed Run slices the same way. In the TUI the transcript button +opens the session in OpenCode itself, where the whole conversation is visible. + +One consequence worth knowing: because a continuation's answer is read from its own slice, a turn whose slice cannot be +measured — the session transcript is unreadable when the turn starts — **fails with a legible error** rather than +falling back to the whole session. Reporting another turn's text as this turn's answer would be worse than a failure. + +`agent(prompt, { session })` does the same without a handle, for when you thread the id through your own state. +`{ keepSession: true }` has to be written inline (or on an `as const` object), like `receipts: true`: a plain +`boolean` variable selects no overload. A handle journals as `{ value, unitId, sessionID }` — `toolCalls`, `resume` +and `close` are not enumerable. + ### Resume Every Run is journaled under `.opencode/workflows/runs//`. A plugin reload does not stop running Runs. If the @@ -429,6 +491,10 @@ OpenCode service dies, the Run reads back as `interrupted`. `resume` starts a ne and prompt: each Unit whose prompt is unchanged returns its recorded result at once, answers to `ask` are replayed, and from the first changed prompt on everything runs live. Units that failed run again. +A conversation replays the same way, turn by turn: every turn is its own Unit with its own prompt, so a resumed Run +reproduces the whole exchange without prompting the model once. A replayed first turn keeps the session the original +Run recorded, so a script can go on with the conversation live after the replayed part. + A Workflow composed of several files (its entry importing local modules, at any depth) journals the bundled module the Run actually executed alongside its source, so a resume replays that exact module even if those files were edited, moved or deleted in the meantime. diff --git a/packages/plugin/docs/examples/review-loop.ts b/packages/plugin/docs/examples/review-loop.ts new file mode 100644 index 0000000..5f985d5 --- /dev/null +++ b/packages/plugin/docs/examples/review-loop.ts @@ -0,0 +1,77 @@ +/** + * Review → fix → re-review in ONE conversation per file. + * + * Each file gets a reviewer Unit that keeps its session (`keepSession`), so every later round runs in the same + * conversation: the reviewer already has the file in its transcript and its tool results, and re-checks exactly + * what it found instead of reading everything again. The rounds are bounded — a review loop that never converges + * must end, not spin. + * + * workflow({ name: "review-loop", args: { files: ["src/a.ts"] } }) + */ +import { defineWorkflow, z } from "@syn7xx/opencode-dynamic-workflows/workflow" + +const Finding = z.object({ + issues: z.array( + z.object({ + line: z.number().int().nullable(), + severity: z.enum(["low", "medium", "high"]), + summary: z.string(), + }), + ), +}) + +export default defineWorkflow({ + meta: { + name: "review-loop", + description: "Review a file, fix what was found, and re-review in the same conversation", + whenToUse: "Iterating on a fix until a reviewer reports nothing left, per file", + phases: [{ title: "review" }, { title: "fix" }, { title: "re-review" }], + args: z.object({ + files: z.array(z.string()).min(1), + /** How many fix rounds at most. A loop that never converges must stop. */ + rounds: z.number().int().min(1).max(5).default(2), + }), + }, + async run({ agent, pipeline, collect, phase, args, log, errors }) { + phase("review") + const results = await pipeline(args.files, async (file) => { + // `keepSession` gives back a handle; every `resume` is a NEW Unit in the SAME session. + let review = await agent( + `Review ${file} for bugs. Read it first. Report concrete issues with line numbers only.`, + { label: `${file}#review`, schema: Finding, keepSession: true }, + ) + + for (let round = 0; round < args.rounds && (review.value?.issues.length ?? 0) > 0; round++) { + phase("fix") + const fixed = await agent( + `Fix exactly these issues in ${file}:\n${JSON.stringify(review.value!.issues, null, 2)}\n` + + `Do not change anything else. Report what you changed.`, + { label: `${file}#fix-${round}` }, + ) + if (fixed === null) { + log(`${file}: the fix turn failed, stopping the loop`) + break + } + phase("re-review") + review = await review.resume( + "Re-check your previous findings against the fixes just made. " + + "Report only the issues that are still present after the fixes.", + { schema: Finding }, + ) + log(`${file}: round ${round + 1} → ${review.value?.issues.length ?? "?"} issue(s) left`) + } + + // Optional: end the conversation explicitly. Idle kept sessions are cleaned up with the Run anyway. + await review.close() + return review.value ? { file, issues: review.value.issues } : null + }) + + const reports = collect(results) + return { + files: reports.length, + // Only a file that finished its rounds should report zero issues; a dropped file is in `errors`. + remaining: reports.filter((report) => report.issues.length > 0).map((report) => report.file), + failed: errors.map((error) => error.unit), + } + }, +}) diff --git a/packages/plugin/docs/protocol/openapi.json b/packages/plugin/docs/protocol/openapi.json index 77bcf0a..6110955 100644 --- a/packages/plugin/docs/protocol/openapi.json +++ b/packages/plugin/docs/protocol/openapi.json @@ -643,7 +643,8 @@ "/v1/runs/{runId}/units/{unitId}/transcript": { "get": { "operationId": "getTranscript", - "summary": "The Unit's session: messages, reasoning and tool calls", + "summary": "The Unit's turn: messages, reasoning and tool calls", + "description": "A Unit that continued an earlier Unit's session (`agent(prompt, { session })`) returns only its own turn, with `earlier` counting the messages that came before it; `turns` says how many Units share the session. Pass `whole=true` to get the entire conversation instead.", "security": [ { "bearer": [] @@ -667,6 +668,15 @@ "schema": { "type": "string" } + }, + { + "name": "whole", + "in": "query", + "required": false, + "description": "Return the whole conversation a continued Unit belongs to, not just its own turn.", + "schema": { + "type": "boolean" + } } ], "responses": { @@ -3286,6 +3296,12 @@ }, "clipped": { "type": "boolean" + }, + "earlier": { + "type": "number" + }, + "turns": { + "type": "number" } }, "required": [ diff --git a/packages/plugin/docs/protocol/schemas/GetTranscriptOutput.json b/packages/plugin/docs/protocol/schemas/GetTranscriptOutput.json index 1999197..e24e96b 100644 --- a/packages/plugin/docs/protocol/schemas/GetTranscriptOutput.json +++ b/packages/plugin/docs/protocol/schemas/GetTranscriptOutput.json @@ -102,6 +102,12 @@ }, "clipped": { "type": "boolean" + }, + "earlier": { + "type": "number" + }, + "turns": { + "type": "number" } }, "required": [ diff --git a/packages/plugin/skill/dynamic-workflows/SKILL.md b/packages/plugin/skill/dynamic-workflows/SKILL.md index 0e29c09..0ce33df 100644 --- a/packages/plugin/skill/dynamic-workflows/SKILL.md +++ b/packages/plugin/skill/dynamic-workflows/SKILL.md @@ -54,21 +54,21 @@ export default defineWorkflow({ ## The context -| Member | Behaviour | -| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `agent(prompt, opts?)` | One Unit. Resolves to the final text, or — with `schema` — to the validated value. A failed Unit resolves to **`null`** and is added to `errors`; it never throws. With `{ receipts: true }` it resolves to `{ value, unitId, toolCalls }` instead (see below). | -| `pipeline(items, ...stages)` | Each item runs through all stages on its own, with **no barrier** between items. Stages get `(previous, item, index)`. A stage that throws turns that item into `null` and skips its later stages. | -| `parallel(thunks)` | Runs `() => Promise` thunks concurrently and waits for all — a **barrier**. A thunk that throws becomes `null`; the call never rejects. | -| `collect(xs)` | Drops the `null`s, with the narrowed type. | -| `errors` | Every dropped Unit so far: `{ unit, prompt, subagent, error }`. | -| `phase(title)`, `log(message)` | Progress. `log` lines are what the person reads while it runs. | -| `ask(questions, { fallback, graceMs? })` | Asks the person (see below). | -| `budget` | `{ total, spent(), remaining() }` in output tokens for this Run. | -| `signal` | The Run's `AbortSignal`. | -| `model` | The launching session's model (`"provider/model#variant"`), or `null` for a headless/synthetic caller. What `agent(…, { model: "inherit" })` and a bare `effort` inherit. | -| `$`, `file`, `fetch` | Shell, files and HTTP, confined to the project (see below). | -| `workflow(name, args?)` | Run a **saved** Workflow as one step of this Run and get its result (see below). | -| `worktrees()` | The worktrees kept by `isolation: "worktree"` Units that changed files. | +| Member | Behaviour | +| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `agent(prompt, opts?)` | One Unit. Resolves to the final text, or — with `schema` — to the validated value. A failed Unit resolves to **`null`** and is added to `errors`; it never throws. With `{ receipts: true }` it resolves to `{ value, unitId, toolCalls }` instead (see below). With `{ keepSession: true }` it resolves to a handle with `sessionID` and `resume()` — a conversation (see below). | +| `pipeline(items, ...stages)` | Each item runs through all stages on its own, with **no barrier** between items. Stages get `(previous, item, index)`. A stage that throws turns that item into `null` and skips its later stages. | +| `parallel(thunks)` | Runs `() => Promise` thunks concurrently and waits for all — a **barrier**. A thunk that throws becomes `null`; the call never rejects. | +| `collect(xs)` | Drops the `null`s, with the narrowed type. | +| `errors` | Every dropped Unit so far: `{ unit, prompt, subagent, error }`. | +| `phase(title)`, `log(message)` | Progress. `log` lines are what the person reads while it runs. | +| `ask(questions, { fallback, graceMs? })` | Asks the person (see below). | +| `budget` | `{ total, spent(), remaining() }` in output tokens for this Run. | +| `signal` | The Run's `AbortSignal`. | +| `model` | The launching session's model (`"provider/model#variant"`), or `null` for a headless/synthetic caller. What `agent(…, { model: "inherit" })` and a bare `effort` inherit. | +| `$`, `file`, `fetch` | Shell, files and HTTP, confined to the project (see below). | +| `workflow(name, args?)` | Run a **saved** Workflow as one step of this Run and get its result (see below). | +| `worktrees()` | The worktrees kept by `isolation: "worktree"` Units that changed files. | ### `agent()` options @@ -85,8 +85,66 @@ export default defineWorkflow({ | `permissions` | Rules for this Unit's session, e.g. `[{ action: "edit", resource: "*", effect: "deny" }]`. | | `isolation` | `"worktree"`: run the Unit in a fresh git worktree — for Units that **edit files in parallel** (see below). | | `location` | Run the Unit in a directory you prepared yourself. | +| `session` | Send this turn into an existing session (`handle.sessionID`) — a follow-up, not a new Unit session. Refuses `subagent`, `model`, `effort`, `location`, `isolation`, `permissions`. | -`{ receipts: true }` is a separate flag, not an `AgentOpts` member (see "Asserting what a Unit did"). +`{ receipts: true }` and `{ keepSession: true }` are separate flags, not `AgentOpts` members (see "Asserting what a +Unit did" and "Continuing a Unit"). + +### Continuing a Unit — a review → fix loop + +Every `agent()` call starts a fresh session, so a second reviewer knows nothing the first one learned. When a stage +should come **back to the same conversation** — re-checking its own findings, applying fixes it proposed, iterating +until clean — keep the session: + +```ts +let review = await agent("Review the diff. List every issue you find.", { + label: "reviewer", + schema: Findings, + keepSession: true, +}) + +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 you just made.", { + schema: Findings, + }) +} +await review.close() +``` + +The second turn runs in the **same session**, so it sees its own earlier transcript and tool results (the files it +already read) and reuses the prompt cache. What that buys: it does not re-read the repo, and it converges instead of +re-deciding from scratch. + +Rules worth knowing: + +- **It is still a new Unit.** Each turn gets its own `unitId`, ordinal and prompt, is journaled and replayed like any + other Unit, and appears in the UI as its own row — the surfaces key a Unit by `unitId`, never by session, so the + earlier turn stays `succeeded` while the next one runs. Two Units sharing a `sessionID` are two turns of one + conversation. So limits, budget, errors and resume all work unchanged. +- **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. Passing one on a turn is an **error** + (a failed Unit with a legible message, not a silent ignore) — start a new Unit instead. +- **Per-turn options do work:** `schema`, `retries`, `timeoutMs`, `label`, `phase`. A text turn followed by a typed + turn on the same session is fine, and normal for this loop. +- **One turn at a time.** Never `Promise.all` over `resume()` (or two `agent(…, { session })` calls on one id): the + second is refused. Conversations are sequential by nature. +- **Usage is per turn.** A continuation's Unit reports what that turn spent, not the session's lifetime total, so + budgets stay meaningful. +- **Report only what this turn did.** `toolCalls` on a continuation's receipt are the calls of that turn, not the whole + conversation's — so an assertion reads the evidence of the step it is checking. +- **A conversation still needs a budget.** A loop that never converges is a real failure mode; bound the rounds + (`for (let i = 0; i < 3 …)`) rather than trusting the loop to end. +- **Usage and evidence are per turn.** A continuation's Unit reports what that turn spent and the tool calls that turn + made, not the session's lifetime totals, so budgets and receipts stay meaningful across a long conversation. +- `close()` is optional: an idle kept session runs nothing, and the Run's cleanup owns its retention. `close()` marks + the conversation ended (a later turn on it fails) and interrupts the session. +- **The transcript shows this turn.** A continued Unit's transcript view is sliced at its own prompt (the engine opens + each turn with it), so a review loop reads as three separate turns instead of one long log; "show whole conversation" + reveals the rest. Related: a turn whose own extent cannot be measured — the session transcript is unreadable when the + turn starts — **fails** rather than reporting the previous turn's text as its answer. + +`agent(prompt, { session })` is the same thing without a handle — useful when you thread the id through your own state. ### Typed Units diff --git a/packages/plugin/src/context.ts b/packages/plugin/src/context.ts index d6fb03a..edef08d 100644 --- a/packages/plugin/src/context.ts +++ b/packages/plugin/src/context.ts @@ -8,7 +8,7 @@ import { type HostPermissionRule, } from "./host" import { emptyUsage, type Unit, type Usage } from "./protocol" -import { DEFAULT_SUBAGENT, runUnit, stringifyError, type UnitRunResult } from "./runner" +import { DEFAULT_SUBAGENT, runUnit, stringifyError, type TurnSlice, type UnitRunResult } from "./runner" import { toUnitOutput } from "./runs" import { AbortError, defaultConcurrency, Semaphore } from "./scheduler" import { resolveJsonSchema } from "./schema-bridge" @@ -28,6 +28,8 @@ import type { AgentOpts, AskOptions, AskQuestion, + ContinuationOpts, + UnitHandle, UnitReceipt, UnitToolCall, WorkflowContext, @@ -57,6 +59,13 @@ export interface EngineState { inflight: Set> /** Worktrees kept by `isolation: "worktree"` Units that changed something. */ worktrees: Array<{ unit: string; directory: string; branch: string | null }> + /** + * Sessions this Run may continue (`agent(…, { keepSession })`), with what the session decided at create time and + * whether the script has closed it. A continuation is a new Unit, but the session is shared, so both facts belong + * to the Run rather than to one Unit. `busy` is the one-turn-at-a-time guard: a session runs one prompt at a time, + * and two concurrent continuations would interleave in it. + */ + sessions: Map } export function createEngineState(): EngineState { @@ -70,6 +79,7 @@ export function createEngineState(): EngineState { usage: emptyUsage(), inflight: new Set(), worktrees: [], + sessions: new Map(), } } @@ -141,6 +151,17 @@ interface UnitOutcome { * receipt can read that session's tool calls. */ replayed: boolean + /** + * Where this Unit's turn sits in its session's transcript, measured when the turn ended. `null` when it could not be + * measured (a setup failure, a replay, a host that would not read the transcript): a receipt then falls back to the + * whole session — correct only for a Unit that OWNS its session, hence {@link UnitOutcome.continued}. + */ + slice: TurnSlice | null + /** + * True when this Unit ran in a session an EARLIER Unit created (`agent(prompt, { session })`). Then its session also + * holds other turns, so "the whole transcript" is never this Unit's evidence. + */ + continued: boolean } /** One Unit a previous Run recorded, in {@link ReplayPlan}. */ @@ -222,6 +243,12 @@ function newUnit(input: { prompt: string model: string | null schema: boolean + /** + * A continuation knows its session before it runs (`agent(prompt, { session })`): the Unit is journaled with it + * from `queued` on, so a surface groups it with the turn it continues even while it queues. + */ + sessionID?: string | null + location?: string | null }): Unit { return { unitId: input.unitId, @@ -231,8 +258,8 @@ function newUnit(input: { subagent: input.subagent, phase: input.phase, status: "queued", - sessionID: null, - location: null, + sessionID: input.sessionID ?? null, + location: input.location ?? null, prompt: input.prompt, model: { requested: input.model, resolved: null }, schema: input.schema, @@ -246,6 +273,32 @@ function newUnit(input: { const noAgentQuestions: UnitBinding["ask"] = async () => null +/** + * Why a continuation may not be run as asked, or `null`. The session's create-time decisions — agent, model, + * directory, worktree isolation, permission ruleset — are not the host's to change: `session.prompt` takes a session + * id and text, nothing else. Accepting one here would silently run the turn on the old value, which is worse than an + * error an author fixes once. + */ +function continuationError(opts: AgentOpts): string | null { + const refused: Array<[string, unknown]> = [ + ["subagent", opts.subagent], + ["agentType", opts.agentType], + ["model", opts.model], + ["effort", opts.effort], + ["location", opts.location], + ["isolation", opts.isolation], + ["permissions", opts.permissions], + ] + const named = refused.filter(([, value]) => value !== undefined).map(([name]) => name) + if (named.length === 0) return null + return ( + `agent({ session }): a continued turn keeps its session's ${named.join(", ")} — ` + + `"${opts.session}" is already created with them, and the host's session.prompt takes only a session id and ` + + `text. Pass \`session\` alone (plus schema, retries, timeoutMs, label, phase), or start a new Unit with ` + + `agent(prompt, { ${named[0]}: … }).` + ) +} + /** A Unit could not be set up (e.g. no worktree): it fails as a value like any other Unit. */ class UnitSetupError extends Error {} @@ -347,19 +400,41 @@ export function createWorkflowContext(input: CreateContextInput): Workflow state.unitCount += 1 const ordinal = state.unitCount const unitId = crypto.randomUUID() - const subagent = opts.subagent ?? opts.agentType ?? DEFAULT_SUBAGENT + /** + * A continuation runs in a session that already decided its agent, model, directory and ruleset. Those are + * refused rather than ignored (see {@link continuationError}): silently running on the old agent while the + * author believes they changed it is the one outcome worth an error. + */ + const continuing = opts.session ?? null + const known = continuing ? state.sessions.get(continuing) : undefined + const subagent = continuing + ? (known?.subagent ?? opts.subagent ?? DEFAULT_SUBAGENT) + : (opts.subagent ?? opts.agentType ?? DEFAULT_SUBAGENT) const phase = opts.phase !== undefined ? `${prefix}${opts.phase}` : state.currentPhase const label = opts.label ? `${prefix}${opts.label}` : prefix ? `${prefix}${subagent}` : null const callerModel = input.callerModel ?? null - const modelChoice = resolveUnitModel(opts.model, opts.effort, callerModel) + // A continuation's model is the session's: `prompt` carries an id and text, nothing else. + const modelChoice = continuing + ? { model: undefined, warning: null } + : resolveUnitModel(opts.model, opts.effort, callerModel) const withVariant = modelChoice.model /** The session the Unit settled with, once one exists — where a receipt reads its calls from. For a replayed * Unit this is the session the ORIGINAL Run recorded (see the replay branch below), never a new one. */ let sessionID: string | null = null /** Set when this Unit comes back from the previous Run's record (replay), so its receipt reads the old session. */ let wasReplayed = false + /** The turn's slice of the session transcript, as the runner measured it (see `TurnSlice`). */ + let slice: TurnSlice | null = null /** Every return goes through here: the value `agent()` returns, plus what a receipt carries. */ - const outcome = (value: unknown): UnitOutcome => ({ value, unitId, label, sessionID, replayed: wasReplayed }) + const outcome = (value: unknown): UnitOutcome => ({ + value, + unitId, + label, + sessionID, + replayed: wasReplayed, + slice, + continued: continuing !== null, + }) let schema: z.ZodType | undefined try { schema = resolveJsonSchema(opts.schema) @@ -378,8 +453,44 @@ export function createWorkflowContext(input: CreateContextInput): Workflow prompt, model: formatModel(withVariant), schema: schema !== undefined, + ...(continuing ? { sessionID: continuing } : {}), }) + // A continuation may not re-decide what its session decided at create time. Checked before anything runs (and + // before replay) so the mistake is reported as a Unit failure, never as a turn on the wrong agent or model. + if (continuing) { + /** + * A rejected continuation must NOT be journaled with the id it named: `cleanupTargets` collects every Unit's + * `sessionID`, so stamping a stray id here would make "delete this Run's sessions" try to delete a session this + * Run never owned. From here on, a rejected unit is reported without one. + */ + const reject = (error: string) => { + const rejected: Unit = { ...unit, sessionID: null, location: null } + emit({ ...rejected, status: "failed", error, startedAt: Date.now(), endedAt: Date.now() }) + state.errors.push({ unit: label ?? subagent, prompt, subagent, error }) + return outcome(null) + } + const refused = continuationError(opts) + if (refused) return reject(refused) + const session = state.sessions.get(continuing) + if (!session) { + // Only a session THIS Run opened (or replayed from its own record) can be continued: a stray id — another + // session in the same OpenCode, the caller's own chat — must never become a Unit's scratchpad. + return reject( + `agent({ session: ${JSON.stringify(continuing)} }): not a session this Run can continue. ` + + `Take the id from \`agent(prompt, { keepSession: true })\` (its \`sessionID\`) or from a handle's \`resume\`.`, + ) + } + if (session.closed) + return reject( + `agent({ session: ${JSON.stringify(continuing)} }): that session was closed; its conversation cannot be continued`, + ) + if (session.busy) + return reject( + `agent({ session: ${JSON.stringify(continuing)} }): that session is running another turn; a session takes one turn at a time`, + ) + } + if (ordinal > limits.maxUnits) { hitLimit(`limit reached: this Run tried to start more than ${limits.maxUnits} Units (limits.maxUnits)`) } @@ -393,6 +504,14 @@ export function createWorkflowContext(input: CreateContextInput): Workflow const record = plan.units.get(ordinal) if (record && record.prompt === prompt) { const value = replayed(unit, record, schema) + // A replayed continuation still needs its session remembered: the rest of the script may continue it live, + // and after a resume `state.sessions` starts empty. Registered before the return, for both outcomes. The + // agent is the one the record names, never the default — a replayed turn must keep the agent it ran as. + if (continuing) state.sessions.set(continuing, { subagent: record.subagent, closed: false, busy: false }) + // A replayed FIRST turn keeps the session id the original Run recorded, so the script can go on with the + // conversation live — the same session, the same transcript the earlier Run left behind. + else if (record.sessionID) + state.sessions.set(record.sessionID, { subagent: record.subagent, closed: false, busy: false }) if (value) { const done: Unit = { ...unit, @@ -434,6 +553,13 @@ export function createWorkflowContext(input: CreateContextInput): Workflow events?.onLog?.(modelChoice.warning) } try { + // A continuation takes the session for its turn before queueing, so a second turn on it fails legibly + // instead of interleaving in the same transcript. + if (continuing) { + const session = state.sessions.get(continuing) + if (session) session.busy = true + else state.sessions.set(continuing, { subagent, closed: false, busy: true }) + } const value = await limiter.run(async () => { let current: Unit = { ...unit, status: "running", startedAt: Date.now() } emit(current) @@ -446,7 +572,8 @@ export function createWorkflowContext(input: CreateContextInput): Workflow throw new UnitSetupError(`could not create a worktree: ${stringifyError(error)}`) } } - const unitLocation = opts.location ?? worktree?.directory + // A continuation runs where its session lives; the worktree/location options are refused for it above. + const unitLocation = continuing ? null : (opts.location ?? worktree?.directory) const result: UnitRunResult = await runUnit(input.host, input.index, { runId: input.runId, unitId, @@ -461,6 +588,7 @@ export function createWorkflowContext(input: CreateContextInput): Workflow : `the workflow plugin is not active in ${directory}; configure it in a committed opencode.json (or globally) so Units there can use it`, } : {}), + ...(continuing ? { continueSessionID: continuing } : {}), parentSessionID: input.parentSessionID, ordinal, prompt, @@ -476,12 +604,14 @@ export function createWorkflowContext(input: CreateContextInput): Workflow permissions: [...(input.permissions ?? []), ...(opts.permissions ?? [])], ask: noAgentQuestions, permissionPolicy: input.permissionPolicy ?? (() => "deny"), - onSession: (id, stop, resolved) => { + onSession: (id, stop, resolved, sessionDirectory) => { sessionID = id current = { ...current, sessionID: id, - location: unitLocation ?? input.location, + // A continuation runs where its SESSION lives — the host reports that, and for a turn continuing a + // worktree Unit it differs from the Run's root. Question routing and policy key on this. + location: unitLocation ?? sessionDirectory ?? input.location, model: { requested: current.model.requested, resolved: formatModel(resolved) }, } const binding = input.index.get(id) @@ -525,6 +655,9 @@ export function createWorkflowContext(input: CreateContextInput): Workflow // The session this Unit settled with — the same value `onSession` and the settled Unit carry. A Unit whose // session never existed (a replay, a setup failure) keeps `null`. sessionID = result.sessionID ?? current.sessionID + // What the runner measured for this turn: a receipt reads exactly its own messages, even if it is read after a + // later turn has added more (or after a repair turn moved the "last user message"). + slice = result.slice const settled: Unit = { ...current, sessionID, @@ -544,6 +677,12 @@ export function createWorkflowContext(input: CreateContextInput): Workflow state.errors.push({ unit: label ?? subagent, prompt, subagent, error: result.error }) return null }, signal) + // The session exists: remember what it decided at create time, so a continuation inherits its agent rather than + // guessing one. `keepSession` decides what `agent()` RESOLVES to (a handle), not whether the session may be + // continued — `closeSession` is the only thing that ends a conversation. + if (sessionID && !continuing) { + state.sessions.set(sessionID, { subagent, closed: false, busy: false }) + } return outcome(value) } catch (err) { if (err instanceof UnitSetupError) { @@ -558,6 +697,16 @@ export function createWorkflowContext(input: CreateContextInput): Workflow return outcome(null) } throw err + } finally { + // The turn is over either way: the session is free for the next one. Its `closed` flag is only set by an + // explicit `close` (see `closeSession`) — except when the Run's signal stopped this Unit, which already halted + // the session: interrupting it again at Run end would report a second stop nobody asked for. + const session = continuing ? state.sessions.get(continuing) : undefined + if (session) session.busy = false + if (signal.aborted && sessionID) { + const own = state.sessions.get(sessionID) + if (own) own.closed = true + } } } @@ -595,6 +744,14 @@ export function createWorkflowContext(input: CreateContextInput): Workflow * path stays strict. */ const readToolCalls = async (outcome: UnitOutcome, sessionID: string): Promise => { + // A turn whose slice could not be measured has no honest evidence to report. For a Unit that OWNS its session the + // whole transcript IS its turn, so it can still be read. For a CONTINUATION it is not: the session holds earlier + // turns, so the whole transcript would hand back calls this turn never made. `[]` (unknown) there — decided BEFORE + // reading, because a read that then fails must not turn "unknown" into an error either. + if (!outcome.replayed && !outcome.slice && outcome.continued) { + noteUnknown(outcome, "its turn could not be delimited in the session it continues") + return [] + } // A replayed Unit's evidence can never fail the resumed Run, so every step below is guarded by this flag. const bestEffort = outcome.replayed let messages: readonly HostMessage[] @@ -612,7 +769,14 @@ export function createWorkflowContext(input: CreateContextInput): Workflow } try { const calls: UnitToolCall[] = [] - for (const message of messages) { + // A continuation shares its session with earlier turns: a receipt is this Unit's EVIDENCE, so it reports the + // calls THIS turn made, not the whole conversation's. The boundary is the slice the runner MEASURED when the + // turn ended — not a boundary re-derived from "the last user message", which a repair turn would move and a + // later turn would move again if the receipt were read late. A REPLAYED Unit is the exception: its receipt is + // deliberately the ORIGINAL Run's whole record, unchanged by this. + const scope = + outcome.replayed || !outcome.slice ? messages : messages.slice(outcome.slice.start, outcome.slice.end) + for (const message of scope) { for (const part of message.content ?? []) { if (part.type !== "tool") continue calls.push({ @@ -638,23 +802,16 @@ export function createWorkflowContext(input: CreateContextInput): Workflow } /** - * The receipt `agent(…, { receipts: true })` resolves to. `toolCalls` is a lazily memoized getter: the transcript is - * read on first access and never before, so a Workflow that only wants the value pays nothing. A Unit that never - * had a session (a setup failure, a Unit skipped before creating one) has nothing to read and reports `[]` without - * a host call; a replayed Unit instead carries the id the original Run recorded, so its receipt can still read the - * earlier session — and reports `[]` (unknown) when that session is gone or cannot be read. + * The lazily-read `toolCalls` of a receipt or handle. NON-ENUMERABLE, deliberately: a receipt is often just + * `return`ed, and everything downstream of a Run serializes its result (`previewResult` for the store, + * `result.json` in the journal, `JSON.stringify` in a script). An enumerable getter would be read by every one of + * those — a transcript read nobody asked for, and `JSON.stringify` would journal `"toolCalls": {}` (a promise is + * not JSON), which is evidence-shaped but empty. */ - const receiptOf = (outcome: UnitOutcome): UnitReceipt => { + const defineToolCalls = >(target: T, outcome: UnitOutcome): T => { const { sessionID } = outcome let toolCalls: Promise | undefined - const receipt = { value: outcome.value, unitId: outcome.unitId } as UnitReceipt - Object.defineProperty(receipt, "toolCalls", { - // NON-ENUMERABLE, deliberately: a receipt is often just `return`ed, and everything downstream of a Run - // serializes its result (`previewResult` for the store, `result.json` in the journal, `JSON.stringify` in a - // script). An enumerable getter would be read by every one of those — a transcript read nobody asked for, and - // `JSON.stringify` would journal `"toolCalls": {}` (a promise is not JSON), which is evidence-shaped but empty. - // The trade-off is that `{ ...receipt }` does not copy `toolCalls`; copying a lazy promise like that would be - // useless anyway. `structuredClone(receipt)` works, and yields `{ value, unitId }`. + Object.defineProperty(target, "toolCalls", { enumerable: false, configurable: true, get() { @@ -676,14 +833,96 @@ export function createWorkflowContext(input: CreateContextInput): Workflow return toolCalls }, }) - return receipt + return target + } + + /** + * The receipt `agent(…, { receipts: true })` resolves to. A Unit that never had a session (a setup failure, a Unit + * skipped before creating one) has nothing to read and reports `[]` without a host call; a replayed Unit instead + * carries the id the original Run recorded, so its receipt can still read the earlier session — and reports `[]` + * (unknown) when that session is gone or cannot be read. + */ + const receiptOf = (outcome: UnitOutcome): UnitReceipt => + defineToolCalls({ value: outcome.value, unitId: outcome.unitId } as UnitReceipt, outcome) + + /** + * Close a conversation: mark it closed (a later `agent({ session })` fails legibly) and interrupt the session so no + * work outlives the Run. Never throws — a Run must not fail because a session could not be stopped. + */ + const closeSession = async (sessionID: string): Promise => { + const session = state.sessions.get(sessionID) + if (session) session.closed = true + await Promise.resolve() + .then(() => input.host.session.interrupt({ sessionID })) + .catch(() => {}) + } + + /** + * The handle `agent(…, { keepSession: true })` resolves to: a receipt plus the session id and the two things a + * conversation needs — `resume` (next turn, same session) and `close` (end it). + * + * Serializes to `{ value, unitId, sessionID }`: `toolCalls`, `resume` and `close` are non-enumerable, so a handle + * returned from `run()` journals what it is, not a function table. + */ + const handleOf = (outcome: UnitOutcome): UnitHandle => { + const { sessionID } = outcome + const handle = { value: outcome.value, unitId: outcome.unitId, sessionID } as UnitHandle + Object.defineProperties(handle, { + resume: { + enumerable: false, + configurable: true, + value: (prompt: string, opts: ContinuationOpts = {}) => { + if (!sessionID) { + return Promise.resolve( + handleFailed( + `resume: Unit ${outcome.label ?? outcome.unitId} never had a session (it failed before one existed), so there is nothing to continue`, + outcome, + ), + ) + } + return agent(prompt, { ...opts, session: sessionID, keepSession: true }) as Promise> + }, + }, + close: { + enumerable: false, + configurable: true, + value: () => (sessionID ? closeSession(sessionID) : Promise.resolve()), + }, + }) + return defineToolCalls(handle, outcome) + } + + /** + * A `resume()` with nothing to resume. It is recorded in `errors` like any other dropped Unit — never a rejected + * promise, because `agent()` does not throw and its conversational counterpart should not either — and it hands + * back a null-valued handle that KEEPS the original `unitId` (it did not run, so it is not a new Unit) with no + * session, so a mistaken second `resume()` fails the same way instead of starting something. + */ + const handleFailed = (error: string, from: UnitOutcome): UnitHandle => { + state.errors.push({ + unit: from.label ?? from.unitId, + prompt: "(resume: no session)", + subagent: "(unknown)", + error, + }) + return handleOf({ + value: null, + unitId: from.unitId, + label: from.label, + sessionID: null, + replayed: false, + slice: null, + continued: from.continued, + }) } - const agent = ((prompt: string, opts: AgentOpts & { receipts?: boolean } = {}) => { - // `receipts` is engine-level only: it decides what `agent()` RESOLVES to, and never reaches the Unit's options. - const { receipts, ...unitOpts } = opts + const agent = ((prompt: string, opts: AgentOpts & { receipts?: boolean; keepSession?: boolean } = {}) => { + // `receipts` and `keepSession` are engine-level only: they decide what `agent()` RESOLVES to, and never reach the + // Unit's options (`keepSession` is remembered per session by the engine itself). + const { receipts, keepSession: _keepSession, ...unitOpts } = opts + const keep = opts.keepSession === true const task = runOne(prompt, unitOpts) - const result = receipts ? task.then(receiptOf) : task.then((outcome) => outcome.value) + const result = keep || receipts ? task.then(keep ? handleOf : receiptOf) : task.then((outcome) => outcome.value) // Track and return the SAME promise. The author may never await it (fire-and-forget Units are supported), so the // tracked promise has to be the one they hold: an unhandled rejection is marked handled here, and the drain in // `runWorkflow`'s `finally` waits for exactly what ran — not a copy of it that settles a microtask later. diff --git a/packages/plugin/src/gateway/server.ts b/packages/plugin/src/gateway/server.ts index 85f8666..63fd118 100644 --- a/packages/plugin/src/gateway/server.ts +++ b/packages/plugin/src/gateway/server.ts @@ -527,7 +527,12 @@ export async function startGateway(config: GatewayConfig, options: GatewayOption if (parts[2] === "units" && parts[3] && parts.length === 4) return json({ unit: await service.getUnit(parts[1], parts[3]) }, 200, extra) if (parts[2] === "units" && parts[3] && parts[4] === "transcript" && parts.length === 5) { - return json(await service.getTranscript(parts[1], parts[3]), 200, extra) + // Accept both forms: `?whole=1` (what the web app sends) and `?whole=true` (what an OpenAPI-generated + // client may send, since the document declares a boolean). Silently treating `true` as false would hand + // back one turn where the caller asked for the conversation. + const flag = new URL(request.url).searchParams.get("whole") + const whole = flag === "1" || flag === "true" + return json(await service.getTranscript(parts[1], parts[3], { whole }), 200, extra) } } return fail("not_found", "no such route", extra) diff --git a/packages/plugin/src/host/plugin.ts b/packages/plugin/src/host/plugin.ts index 6dad396..ae4b226 100644 --- a/packages/plugin/src/host/plugin.ts +++ b/packages/plugin/src/host/plugin.ts @@ -730,7 +730,11 @@ export async function setup(ctx: Context): Promise<() => Promise> { getResult: (input, c) => guard(c.error as never, async () => (await serviceForRun(input.runId)).getResult(input.runId)), getTranscript: (input, c) => - guard(c.error as never, async () => (await serviceForRun(input.runId)).getTranscript(input.runId, input.unitId)), + guard(c.error as never, async () => + (await serviceForRun(input.runId)).getTranscript(input.runId, input.unitId, { + whole: input.whole === true, + }), + ), getActivity: (input, c) => guard(c.error as never, async () => ({ entries: await (await serviceForRun(input.runId)).getActivity(input.runId), diff --git a/packages/plugin/src/orchestrator.ts b/packages/plugin/src/orchestrator.ts index c901026..35d4f88 100644 --- a/packages/plugin/src/orchestrator.ts +++ b/packages/plugin/src/orchestrator.ts @@ -394,7 +394,9 @@ export async function runWorkflow(input: RunWorkflowInput): Promise export const RunRef = z.object({ runId: z.string() }) export const UnitRef = z.object({ runId: z.string(), unitId: z.string() }) +/** + * A Unit transcript request. `whole` returns the entire conversation a continued Unit belongs to; without it the + * response holds only that Unit's own turn (see {@link GetTranscriptOutput.earlier}). + */ +export const TranscriptRef = z.object({ + runId: z.string(), + unitId: z.string(), + whole: z.boolean().optional(), +}) export const InteractionRef = z.object({ runId: z.string(), interactionId: z.string() }) export const GetRunOutput = z.object({ run: Run, live: z.boolean() }) @@ -528,6 +537,18 @@ export const GetTranscriptOutput = z.object({ messages: z.array(TranscriptMessage), /** True when some parts were clipped for size. */ clipped: z.boolean(), + /** + * The messages before this Unit's own turn, when the Unit continued an earlier Unit's session + * (`agent(prompt, { session })`). `messages` then holds ONLY this turn, and this is what came before it — so a + * viewer shows the turn by default and can reveal the whole conversation on request. Absent for a normal Unit (its + * turn is the whole session) and when the boundary is unknown (a replayed or older Unit). + */ + earlier: z.number().optional(), + /** + * How many Units share this session — 1 for an ordinary Unit, more for a conversation. Lets a viewer say "turn 2 of + * 3" instead of pretending the transcript is one Unit's. + */ + turns: z.number().optional(), }) export type GetTranscriptOutput = z.infer diff --git a/packages/plugin/src/protocol/openapi.ts b/packages/plugin/src/protocol/openapi.ts index 98348b2..d94b3d1 100644 --- a/packages/plugin/src/protocol/openapi.ts +++ b/packages/plugin/src/protocol/openapi.ts @@ -260,9 +260,23 @@ const PATHS: Json = { "/v1/runs/{runId}/units/{unitId}/transcript": { get: { operationId: "getTranscript", - summary: "The Unit's session: messages, reasoning and tool calls", + summary: "The Unit's turn: messages, reasoning and tool calls", + description: + "A Unit that continued an earlier Unit's session (`agent(prompt, { session })`) returns only its own turn, " + + "with `earlier` counting the messages that came before it; `turns` says how many Units share the session. " + + "Pass `whole=true` to get the entire conversation instead.", security: READ, - parameters: [runId, unitId], + parameters: [ + runId, + unitId, + { + name: "whole", + in: "query", + required: false, + description: "Return the whole conversation a continued Unit belongs to, not just its own turn.", + schema: { type: "boolean" }, + }, + ], responses: { ...ok("GetTranscriptOutput"), ...errors(401, 404) }, }, }, diff --git a/packages/plugin/src/runner.ts b/packages/plugin/src/runner.ts index dfb1718..1084a26 100644 --- a/packages/plugin/src/runner.ts +++ b/packages/plugin/src/runner.ts @@ -77,6 +77,12 @@ export interface UnitSpec { prompt: string subagent: string label: string | null + /** + * Run this turn in an EXISTING session instead of creating one (`agent(prompt, { session })`). The session keeps + * what it decided at create time — agent, model, directory, ruleset — so `subagent`/`model`/`unitLocation` are + * not sent, and the Unit's usage is what THIS turn spent, not the session's cumulative total. + */ + continueSessionID?: string model?: HostModelRef schema?: z.ZodType retries?: number @@ -88,7 +94,12 @@ export interface UnitSpec { ask: UnitBinding["ask"] permissionPolicy: UnitBinding["permissionPolicy"] /** Called once the session exists, with a handle that stops this Unit and the model the session resolved. */ - onSession?: (sessionID: string, stop: () => void, model: HostModelRef | undefined) => void + onSession?: ( + sessionID: string, + stop: () => void, + model: HostModelRef | undefined, + location: string | undefined, + ) => void /** Called when the Unit moves into repair turns. */ onRepairing?: () => void /** For a Unit in another directory: null when it may run there, else why not. Checked once its session exists. */ @@ -102,6 +113,19 @@ export interface UnitSpec { mayContinue?: (unitOutputTokens: number) => boolean } +/** + * The slice of the session's transcript this Unit's turn occupies, `[start, end)`. + * + * Recorded when the turn ends, not derived when a receipt is read: a receipt's `toolCalls` is a lazy getter that may + * be read after the NEXT turn has already added messages, and a turn can be several prompts (repair turns), so "the + * last user message" is not a turn boundary. `null` when the transcript could not be measured — a receipt then falls + * back to the whole session, which is honest for a Unit that owns it. + */ +export interface TurnSlice { + start: number + end: number +} + export type UnitRunResult = | { ok: true @@ -111,6 +135,8 @@ export type UnitRunResult = model: HostModelRef | undefined path: ResultPath attempts: UnitAttempt[] + /** Messages this turn added to its session, so its receipt can read exactly its own evidence. */ + slice: TurnSlice | null } | { ok: false @@ -120,6 +146,7 @@ export type UnitRunResult = usage: Usage model: HostModelRef | undefined attempts: UnitAttempt[] + slice: TurnSlice | null } export function stringifyError(error: unknown): string { @@ -207,10 +234,35 @@ interface UnitTrace { sessionID: string | null attempts: UnitAttempt[] release: (() => void) | null + /** + * A continuation's session totals BEFORE this turn, so the backstop can report what the turn spent instead of the + * session's lifetime total. `null` for a session this Unit created (its totals are the Unit's from zero). + */ + baseline: Usage | null + /** + * Where this turn sits in the session's transcript, measured as messages arrive. Kept on the trace because a + * receipt may be read long after the turn ended — and after later turns added messages. + */ + slice: TurnSlice | null +} + +/** Turn a session's lifetime totals into what THIS turn spent, given a baseline taken before it started. */ +function subtractUsage(current: Usage, base: Usage): Usage { + const delta = (now: number, before: number) => Math.max(0, now - before) + return { + tokens: { + input: delta(current.tokens.input, base.tokens.input), + output: delta(current.tokens.output, base.tokens.output), + reasoning: delta(current.tokens.reasoning, base.tokens.reasoning), + cacheRead: delta(current.tokens.cacheRead, base.tokens.cacheRead), + cacheWrite: delta(current.tokens.cacheWrite, base.tokens.cacheWrite), + }, + cost: Math.max(0, current.cost - base.cost), + } } export async function runUnit(host: EngineHost, index: UnitIndex, spec: UnitSpec): Promise { - const trace: UnitTrace = { sessionID: null, attempts: [], release: null } + const trace: UnitTrace = { sessionID: null, attempts: [], release: null, baseline: null, slice: null } try { return await runUnitUnsafe(host, index, spec, trace) } catch (error) { @@ -225,7 +277,15 @@ export async function runUnit(host: EngineHost, index: UnitIndex, spec: UnitSpec .catch(() => {}) usage = await Promise.resolve() .then(() => host.session.get({ sessionID })) - .then(usageFromSession, () => emptyUsage()) + .then( + // A continuation's session carries earlier turns' totals: report only what THIS turn spent, exactly like + // the normal path does. Without this a crash would bill the whole conversation to one Unit. + (info) => { + const total = usageFromSession(info) + return trace.baseline ? subtractUsage(total, trace.baseline) : total + }, + () => emptyUsage(), + ) } return { ok: false, @@ -235,6 +295,7 @@ export async function runUnit(host: EngineHost, index: UnitIndex, spec: UnitSpec usage, model: spec.model, attempts: trace.attempts, + slice: trace.slice, } } } @@ -256,6 +317,7 @@ async function runUnitUnsafe( usage, model, attempts, + slice: trace.slice, }) let jsonSchema: Record | undefined @@ -288,41 +350,58 @@ async function runUnitUnsafe( }) let info: HostSessionInfo - try { - const creating = Promise.resolve( - host.session.create({ - title: unitTitle(spec.workflow, spec.label, spec.subagent), - agent: spec.subagent, - ...(spec.model ? { model: spec.model } : {}), - metadata: { - workflow: { - protocol: 1, - runId: spec.runId, - unitId: spec.unitId, - ordinal: spec.ordinal, - attempt: 1, - parentSessionID: spec.parentSessionID, - workflow: spec.workflow, - location: spec.location, + if (spec.continueSessionID) { + // A continuation: the session already exists, and what it decided at create time (agent, model, directory, + // ruleset) is not the host's to change — `session.prompt` takes an id and text. Its model is whatever the + // session resolved, reported by `session.get`. + if (guard.aborted) return fail(interruptedBeforeSession(reason()), true) + sessionID = spec.continueSessionID + trace.sessionID = sessionID + try { + info = await host.session.get({ sessionID }) + } catch (error) { + return fail( + `could not read the session this turn continues (${spec.continueSessionID}): ${stringifyError(error)}`, + guard.aborted, + ) + } + } else { + try { + const creating = Promise.resolve( + host.session.create({ + title: unitTitle(spec.workflow, spec.label, spec.subagent), + agent: spec.subagent, + ...(spec.model ? { model: spec.model } : {}), + metadata: { + workflow: { + protocol: 1, + runId: spec.runId, + unitId: spec.unitId, + ordinal: spec.ordinal, + attempt: 1, + parentSessionID: spec.parentSessionID, + workflow: spec.workflow, + location: spec.location, + }, }, - }, - permissions: [...(spec.permissions ?? []), ...ENGINE_UNIT_RULES], - ...(spec.unitLocation ? { location: { directory: spec.unitLocation } } : {}), - }), - ) - const created = await Promise.race([creating.then((value) => ({ value })), aborted.then((why) => ({ why }))]) - if ("why" in created) { - // Stopped while OpenCode was still creating it: stop that session whenever it appears. - void creating - .then((late) => (late.id ? host.session.interrupt({ sessionID: late.id }) : undefined)) - .catch(() => {}) - return fail(interruptedBeforeSession(created.why), created.why === "stopped" || created.why === "aborted") + permissions: [...(spec.permissions ?? []), ...ENGINE_UNIT_RULES], + ...(spec.unitLocation ? { location: { directory: spec.unitLocation } } : {}), + }), + ) + const created = await Promise.race([creating.then((value) => ({ value })), aborted.then((why) => ({ why }))]) + if ("why" in created) { + // Stopped while OpenCode was still creating it: stop that session whenever it appears. + void creating + .then((late) => (late.id ? host.session.interrupt({ sessionID: late.id }) : undefined)) + .catch(() => {}) + return fail(interruptedBeforeSession(created.why), created.why === "stopped" || created.why === "aborted") + } + info = created.value + } catch (error) { + return fail(`could not create the Unit session: ${stringifyError(error)}`, guard.aborted) } - info = created.value - } catch (error) { - return fail(`could not create the Unit session: ${stringifyError(error)}`, guard.aborted) } - sessionID = info.id + sessionID = info.id ?? sessionID if (!sessionID) return fail("session.create returned no session id") trace.sessionID = sessionID @@ -352,7 +431,7 @@ async function runUnitUnsafe( unbind() } model = info.model ?? model - spec.onSession?.(sessionID, () => stop.abort(), model) + spec.onSession?.(sessionID, () => stop.abort(), model, info.location?.directory) /** Stop the session and give it a bounded moment to go quiet, so its usage is final and no work outlives the Unit. */ const halt = async (id: string) => { @@ -402,6 +481,85 @@ async function runUnitUnsafe( /** Output tokens and cost of host calls the session does not count (extraction). */ let extra = emptyUsage() + /** + * A continuation's session already spent tokens in earlier turns, and `session.get` reports the session's + * lifetime totals. What this Unit reports — its usage, its budget share, what the Run adds up — is only THIS + * turn, so a baseline is taken before the first prompt and subtracted. `null` for a session this Unit created + * (its totals are the Unit's from zero). + */ + const baseline: Usage | null = spec.continueSessionID ? usageFromSession(info) : null + trace.baseline = baseline + + /** + * The session's transcript length right now, or `null` when it cannot be read. Bounded like every other host call + * (a hung `session.context` must not hold a Unit or its concurrency slot forever), so a stall is `null` rather than + * a hang — and the caller decides what an unmeasurable transcript means. + */ + const transcriptLength = async (id: string): Promise => { + try { + return (await host.session.context({ sessionID: id })).length + } catch { + return null + } + } + + /** + * A continuation's turn start, with ONE deadline shared by the attempt and its retry: a retry does not buy a second + * window, so a hung host fails the turn in about {@link DRAIN_MS} rather than twice that. The deadline is a real + * cancellation point — a late read is ignored, not awaited. + */ + const measureTurnStart = async (id: string): Promise => { + const deadline = Date.now() + DRAIN_MS + for (let attempt = 0; attempt < 2; attempt++) { + const remaining = deadline - Date.now() + if (remaining <= 0) return null + const read = transcriptLength(id) + const won = await Promise.race([ + read.then((length) => ({ length })), + Bun.sleep(remaining).then(() => ({ timeout: true as const })), + ]) + if ("length" in won && won.length !== null) return won.length + // A fast failure (a rejected read) is worth one immediate retry — a transient host hiccup. A stall already spent + // the shared budget, so there is nothing left to retry with. + if ("timeout" in won) return null + if (attempt === 1) return null + } + return null + } + + /** + * Where this turn starts in the session's transcript. A session this Unit created is empty, so this is 0 and costs + * nothing — the "a Workflow that never asks pays nothing" promise stays true. A continuation's session already holds + * earlier turns, so its length is read ONCE here, before the first prompt. + * + * Measured here (not when a receipt is read) because a receipt is a lazy getter: by the time the author reads it, + * the next turn may already have added messages. + */ + let turnStart: number | null = spec.continueSessionID ? null : 0 + /** The transcript length after the last thing this turn wrote, taken from the read the answer needs anyway. */ + let turnEnd: number | null = null + if (turnStart === null) { + // A continuation MUST know where its turn starts: without it, "read the transcript" means the whole conversation, + // and a turn that produced no text would be answered with the PREVIOUS turn's text as a success. One retry for a + // transient host hiccup, then the turn fails rather than guessing. + turnStart = await measureTurnStart(sessionID) + // Nothing has run yet, so there is no usage to report — the turn failed before its first prompt. + if (turnStart === null) + return fail( + "could not read the transcript of the session this turn continues, so the turn could not be scoped to its own messages", + ) + } + /** + * Where the NEXT prompt will land: the length of the transcript after the last read. Nothing but this Unit writes to + * the session between prompts, so the previous read's length is exactly where the next prompt starts — no extra read. + */ + let promptStart: number | null = turnStart + + /** Record the measured slice once the turn is over. A receipt reads this, never a boundary re-derived later. */ + const captureSlice = (): void => { + trace.slice = turnStart === null || turnEnd === null ? null : { start: turnStart, end: turnEnd } + } + const readUsage = async (): Promise => { try { const current = await Promise.race([ @@ -411,8 +569,12 @@ async function runUnitUnsafe( }), ]) model = current.model ?? model - return addUsage(usageFromSession(current), extra) + const total = usageFromSession(current) + return addUsage(baseline ? subtractUsage(total, baseline) : total, extra) } catch { + // A `session.get` that fails or times out loses the session-reported part of this turn. Report what the engine + // counted itself (`extra`) rather than the session's lifetime totals: an undercount is honest, and a + // continuation billed for the whole conversation would be wrong by design. return extra } } @@ -502,12 +664,24 @@ async function runUnitUnsafe( let final: ReturnType try { - final = finalAssistant(await host.session.context({ sessionID })) + // ONLY this prompt's messages. A continuation's session also holds every earlier turn, and `finalAssistant` + // answers with the last assistant text it finds — so reading the whole transcript would return the PREVIOUS + // turn's answer (a false success when this turn produced nothing, and a swallowed provider error). + const messages = await host.session.context({ sessionID }) + // Where THIS prompt landed: everything the transcript held before this prompt was sent. A repair turn is a + // separate prompt inside the same Unit, so the answer is read from this prompt's own messages — "the last user + // message" would move with a repair and could drift if the host added a user message of its own. + const from = promptStart + promptStart = messages.length + turnEnd = messages.length + final = finalAssistant(from === null ? messages : messages.slice(from)) } catch (error) { return fail(`could not read the Unit transcript: ${stringifyError(error)}`, false, await readUsage()) } model = final.model ?? model lastText = final.text ?? lastText + // This prompt's messages are now in the transcript; the slice must reach them. + captureSlice() // Stopped while the turn was being read: the stop wins over the answer. if (guard.aborted) return fail(interruptedMessage(reason()), reason() === "stopped" || reason() === "aborted", await readUsage()) @@ -515,7 +689,16 @@ async function runUnitUnsafe( if (!spec.schema) { if (final.text !== undefined) { attempts.push({ turn, path: "text", ok: true }) - return { ok: true, value: final.text, sessionID, usage: await readUsage(), model, path: "text", attempts } + return { + ok: true, + value: final.text, + sessionID, + usage: await readUsage(), + model, + path: "text", + attempts, + slice: trace.slice, + } } if (binding.result) { attempts.push({ turn, path: "tool", ok: true }) @@ -527,6 +710,7 @@ async function runUnitUnsafe( model, path: "tool", attempts, + slice: trace.slice, } } attempts.push({ turn, path: "text", ok: false, error: final.error ?? "no assistant text" }) @@ -544,6 +728,7 @@ async function runUnitUnsafe( model, path: "tool", attempts, + slice: trace.slice, } } attempts.push({ turn, path: "tool", ok: false, error: binding.lastError ?? "workflow_result was not called" }) @@ -563,6 +748,7 @@ async function runUnitUnsafe( model, path: "text-json", attempts, + slice: trace.slice, } } lastError = formatIssues(valid.error) @@ -620,7 +806,16 @@ async function runUnitUnsafe( ok: true, note: "usage estimated (the host reports none for extraction)", }) - return { ok: true, value: valid.data, sessionID, usage: await readUsage(), model, path: "extract", attempts } + return { + ok: true, + value: valid.data, + sessionID, + usage: await readUsage(), + model, + path: "extract", + attempts, + slice: trace.slice, + } } attempts.push({ turn: attempts.length, diff --git a/packages/plugin/src/service/rpc.ts b/packages/plugin/src/service/rpc.ts index 73c452b..ba00c23 100644 --- a/packages/plugin/src/service/rpc.ts +++ b/packages/plugin/src/service/rpc.ts @@ -40,6 +40,7 @@ import { SaveRunOutput, StartRunInput, StartRunOutput, + TranscriptRef, UnitRef, } from "../protocol" @@ -54,7 +55,7 @@ export const WorkflowRpc = Rpc.define({ getRun: { input: RunRef, output: GetRunOutput, errors }, getUnit: { input: UnitRef, output: GetUnitOutput, errors }, getResult: { input: RunRef, output: GetResultOutput, errors }, - getTranscript: { input: UnitRef, output: GetTranscriptOutput, errors }, + getTranscript: { input: TranscriptRef, output: GetTranscriptOutput, errors }, getActivity: { input: RunRef, output: ActivityOutput, errors }, listWorkflows: { input: Empty, output: ListWorkflowsOutput, errors }, startRun: { input: StartRunInput, output: StartRunOutput, errors }, diff --git a/packages/plugin/src/service/service.ts b/packages/plugin/src/service/service.ts index 4bd8ea7..94d8e9c 100644 --- a/packages/plugin/src/service/service.ts +++ b/packages/plugin/src/service/service.ts @@ -220,6 +220,37 @@ export function toTranscript(sessionID: string, messages: readonly HostMessage[] return { sessionID, messages: out, clipped } } +/** + * Where each turn starts in a session's transcript, keyed by the Unit's ordinal. + * + * The engine opens every turn with a `user` message carrying that turn's prompt (`host.session.prompt({ text })`), + * and a session runs one turn at a time, so walking the Units in ordinal order and matching the next `user` message + * whose text is that prompt finds each boundary. Text comparison is on the exact prompt; when a prompt repeats + * verbatim the search continues from the previous boundary, which is what makes "re-check" twice in a row work. + * + * A Unit whose opening message cannot be found gets no entry: the caller then falls back to the whole session rather + * than showing the wrong slice. + */ +export function turnBoundaries( + messages: readonly TranscriptMessage[], + turns: ReadonlyArray<{ ordinal: number; prompt: string }>, +): Map { + const starts = new Map() + let from = 0 + for (const turn of turns) { + for (let cursor = from; cursor < messages.length; cursor++) { + const message = messages[cursor]! + if (message.role !== "user") continue + const text = message.parts.map((part) => ("text" in part ? (part.text ?? "") : "")).join("") + if (text !== turn.prompt) continue + starts.set(turn.ordinal, cursor) + from = cursor + 1 + break + } + } + return starts +} + /** The name an inline Run shows until it is approved and its script says its real name. */ const UNAPPROVED_NAME = "unapproved script" @@ -356,9 +387,15 @@ export class WorkflowService { return unit } - /** A Unit's session, simplified for display (the web app's transcript view). */ - async getTranscript(runId: string, unitId: string): Promise { - const unit = await this.getUnit(runId, unitId) + /** + * A Unit's transcript. A Unit that continued an earlier Unit's session (`agent(prompt, { session })`) gets ONLY its + * own turn by default, with `earlier` saying how much came before; `whole: true` returns the full conversation. + */ + async getTranscript(runId: string, unitId: string, options: { whole?: boolean } = {}): Promise { + const run = this.deps.store.get(runId) ?? (await this.deps.journal.read(runId))?.run + if (!run) throw new WorkflowProtocolError("not_found", `No Run "${runId}" in this location.`) + const unit = run.units.find((candidate) => candidate.unitId === unitId) + if (!unit) throw new WorkflowProtocolError("not_found", `Run "${runId}" has no Unit "${unitId}".`) if (!unit.sessionID) throw new WorkflowProtocolError( "not_found", @@ -373,7 +410,27 @@ export class WorkflowService { `The Unit's session is gone (${error instanceof Error ? error.message : String(error)}).`, ) } - return toTranscript(unit.sessionID, messages) + const whole = toTranscript(unit.sessionID, messages) + // A session can carry several Units (`agent(prompt, { session })`): one conversation, several turns. The + // engine writes each turn's prompt as the user message that opens it, and turns run strictly one after another + // in one session, so the boundaries are recoverable from the transcript itself — no extra state to journal. + const turns = run.units + .filter((candidate) => candidate.sessionID === unit.sessionID) + .toSorted((a, b) => a.ordinal - b.ordinal) + if (turns.length <= 1) return whole + if (options.whole) return { ...whole, turns: turns.length } + const bounds = turnBoundaries(whole.messages, turns) + const start = bounds.get(unit.ordinal) + if (start === undefined) return { ...whole, turns: turns.length } + // The Unit's own turn: from its opening user message up to the next turn's (or the end). + const next = turns.find((candidate) => candidate.ordinal > unit.ordinal) + const end = next ? (bounds.get(next.ordinal) ?? whole.messages.length) : whole.messages.length + return { + ...whole, + messages: whole.messages.slice(start, end), + ...(start > 0 ? { earlier: start } : {}), + turns: turns.length, + } } async getResult(runId: string): Promise<{ runId: string; status: Run["status"]; result: unknown }> { diff --git a/packages/plugin/src/ui/api.ts b/packages/plugin/src/ui/api.ts index 519c727..555c9d8 100644 --- a/packages/plugin/src/ui/api.ts +++ b/packages/plugin/src/ui/api.ts @@ -25,7 +25,7 @@ export interface WorkflowApi { getRun(input: { runId: string }): Promise<{ run: Run; live: boolean }> getUnit(input: { runId: string; unitId: string }): Promise<{ unit: Unit }> getResult(input: { runId: string }): Promise<{ runId: string; status: RunStatus; result: unknown }> - getTranscript(input: { runId: string; unitId: string }): Promise + getTranscript(input: { runId: string; unitId: string; whole?: boolean }): Promise getActivity(input: { runId: string }): Promise<{ entries: ActivityEntry[] }> listWorkflows(): Promise startRun(input: { diff --git a/packages/plugin/src/workflow/index.ts b/packages/plugin/src/workflow/index.ts index 8b32000..5774b16 100644 --- a/packages/plugin/src/workflow/index.ts +++ b/packages/plugin/src/workflow/index.ts @@ -218,6 +218,19 @@ export interface AgentOpts = S ext ? string : unknown +/** + * What `agent(…, { keepSession: true })` resolves to: the same receipt a typed or text Unit would produce (with + * `{ receipts: true }` folded in), plus the session's id and a `resume` that sends the next turn into it. + * + * A continuation is still a **new Unit** of the Run — its own `unitId`, ordinal and prompt, journaled and replayed + * like any other — it just runs in an existing session. So the Run's accounting, limits and UI stay untouched: two + * Units that share a `sessionID` are two turns of one conversation. + */ +export interface UnitHandle extends UnitReceipt { + /** + * The session this Unit ran in, or `null` when it never had one (a setup failure, or a Unit stopped before its + * session existed). `resume` reports a Run error and resolves to `null` when it is `null`. + */ + readonly sessionID: string | null + /** + * Send the next turn into this same session and resolve to a new handle — the conversation continues where the + * last turn stopped, with its transcript, its tool results and its prompt cache. `session`, `keepSession` and + * `receipts` are not accepted here: a continuation is always a continuation. + * + * One turn at a time: never `resume` (or `agent({ session })`) twice concurrently on the same session. + */ + resume( + prompt: string, + opts?: ContinuationOpts, + ): Promise>> + /** + * End the conversation: a later `agent({ session })` or `resume` on it fails legibly, and the session is + * interrupted so nothing keeps running in it. Never throws. + * + * Not required for correctness: an idle kept session runs nothing, a Run's active turn is stopped with its Unit, + * and the Run's cleanup owns retention. Call it when the conversation is over and you want that to be explicit. + */ + close(): Promise +} + +/** + * Options a continuation accepts. Everything the session already decided at create time — its `subagent`, `model`, + * `location`, worktree isolation and permission ruleset — is omitted: the host's `prompt` takes a session id and + * text, nothing else. What remains is per-turn: `schema`, `retries`, `timeoutMs`, `label`, `phase`. + */ +export type ContinuationOpts = Omit< + AgentOpts, + "subagent" | "agentType" | "model" | "effort" | "location" | "isolation" | "permissions" | "session" | "keepSession" +> + /** * Runs one Unit: prompts a (by default freshly-created) child session under the named subagent. With a * `schema`, it resolves to that schema's inferred type (validated structured output); without one, to the @@ -240,20 +298,30 @@ export type UnitValue = S ext * {@link WorkflowContext.errors}). * * Passing `{ receipts: true }` resolves to a {@link UnitReceipt} instead — the same value, plus the Unit's id and - * what its session actually did. The Unit itself is identical either way: one call, one Unit, one session. + * what its session actually did. With `{ keepSession: true }` it resolves to a {@link UnitHandle}: a receipt plus + * `sessionID`, `resume` and `close`, for a conversation. Both flags sit in these overloads, not in + * {@link AgentOpts}, so the resolved type follows what the call site wrote. * * `receipts` is deliberately NOT part of {@link AgentOpts}: it lives in these overloads so the resolved type follows * the flag. Write `receipts: true` inline (or on an `as const` object) — a plain `boolean` variable cannot select * the receipt overload, which is the point: no call gets typed as a value while returning a receipt at run time. */ export interface AgentFn { + ( + prompt: string, + opts: AgentOpts & { keepSession: true }, + ): Promise>> + ( + prompt: string, + opts: AgentOpts & { keepSession: true; receipts?: boolean }, + ): Promise>> ( prompt: string, opts: AgentOpts & { receipts: true }, ): Promise>> ( prompt: string, - opts?: AgentOpts & { receipts?: false }, + opts?: AgentOpts & { receipts?: false; keepSession?: false }, ): Promise | null> } diff --git a/packages/plugin/test/conversation.test.ts b/packages/plugin/test/conversation.test.ts new file mode 100644 index 0000000..30538c4 --- /dev/null +++ b/packages/plugin/test/conversation.test.ts @@ -0,0 +1,487 @@ +/** + * `agent({ keepSession })` / `agent({ session })` / `handle.resume()` — a conversation that spans turns. + * + * The rules these tests pin: a continuation is a NEW Unit with its OWN id, ordinal and prompt, but it runs in the + * session the earlier turn created, so the transcript accumulates. Everything the session decided at create time is + * refused rather than ignored. Usage is per turn, not per session. + */ +import { describe, expect, test } from "bun:test" + +import type { HostMessage } from "../src/host" +import type { Unit } from "../src/protocol" +import { z } from "../src/workflow" +import { makeCtx } from "./helpers" + +describe("agent({ keepSession }) — a conversation", () => { + test("a continuation is a new Unit that runs in the SAME session, with no second create", async () => { + const { ctx, state } = makeCtx({ reply: (call) => ({ text: `about ${call.text}` }) }) + const first = await ctx.agent("review", { label: "reviewer", keepSession: true }) + expect(first.value).toBe("about review") + expect(first.sessionID).toBe("ses_fake_1") + + const second = await first.resume("re-check") + expect(second.value).toBe("about re-check") + // Same session, two prompts: the conversation continued instead of starting over. + expect(second.sessionID).toBe("ses_fake_1") + expect(state.unitCount).toBe(2) + expect(second.unitId).not.toBe(first.unitId) + }) + + test("the second turn sends a prompt only — no create, so agent/model/location cannot change", async () => { + const { ctx, host } = makeCtx({ reply: { text: "ok" } }) + const first = await ctx.agent("one", { subagent: "explore", model: "acme/m1", keepSession: true }) + await ctx.agent("two", { session: first.sessionID! }) + expect(host.creates).toHaveLength(1) + expect(host.creates[0]!.agent).toBe("explore") + expect(host.prompts.map((prompt) => prompt.sessionID)).toEqual(["ses_fake_1", "ses_fake_1"]) + expect(host.prompts.map((prompt) => prompt.turn)).toEqual([0, 1]) + }) + + test("a continuation that names subagent/model/location/permissions fails as a Unit, not silently", async () => { + const { ctx, host, state } = makeCtx({ reply: { text: "ok" } }) + const first = await ctx.agent("one", { keepSession: true }) + const cases: Array> = [ + { subagent: "reviewer" }, + { agentType: "reviewer" }, + { model: "acme/other" }, + { effort: "high" }, + { location: "/elsewhere" }, + { isolation: "worktree" }, + { permissions: [{ action: "edit", resource: "*", effect: "allow" }] }, + ] + for (const extra of cases) { + const out = await ctx.agent("two", { session: first.sessionID!, ...extra } as never) + expect(out).toBeNull() + } + // Nothing ran: the mistake was reported before a single prompt was sent. + expect(host.prompts).toHaveLength(1) + expect(state.errors).toHaveLength(cases.length) + expect(state.errors[0]!.error).toContain("keeps its session's subagent") + expect(state.errors[0]!.error).toContain("start a new Unit") + }) + + test("schema is per turn: a text turn followed by a typed one on the same session", async () => { + const { ctx } = makeCtx({ + replies: [{ text: "loose notes" }, { result: { issues: ["a", "b"] } }], + }) + const first = await ctx.agent("review", { keepSession: true }) + expect(first.value).toBe("loose notes") + const Findings = z.object({ issues: z.array(z.string()) }) + const second = await first.resume("list them", { schema: Findings }) + expect(second.value).toEqual({ issues: ["a", "b"] }) + }) + + test("an unknown session id is refused: a stray id never becomes a Unit's scratchpad", async () => { + const { ctx, host, state } = makeCtx({ reply: { text: "ok" } }) + const out = await ctx.agent("hi", { session: "ses_someone_elses_chat" }) + expect(out).toBeNull() + expect(host.prompts).toHaveLength(0) + expect(state.errors[0]!.error).toContain("not a session this Run can continue") + }) + + test("close() ends the conversation; a later turn fails legibly and the session is interrupted", async () => { + const { ctx, host, state } = makeCtx({ reply: { text: "ok" } }) + const first = await ctx.agent("one", { keepSession: true }) + await first.close() + expect(host.interrupts).toEqual(["ses_fake_1"]) + const after = await ctx.agent("two", { session: first.sessionID! }) + expect(after).toBeNull() + expect(state.errors.at(-1)!.error).toContain("closed") + expect(host.prompts).toHaveLength(1) + }) + + test("one turn at a time: a concurrent turn on a busy session is refused", async () => { + const { ctx, state } = makeCtx({ reply: { text: "ok" }, delayMs: 20 }) + const first = await ctx.agent("one", { keepSession: true }) + const [a, b] = await Promise.all([ + ctx.agent("two", { session: first.sessionID! }), + ctx.agent("three", { session: first.sessionID! }), + ]) + // Exactly one turn won the session; the other was refused instead of interleaving in the transcript. + expect([a, b].filter((value) => value === "ok")).toHaveLength(1) + expect([a, b].filter((value) => value === null)).toHaveLength(1) + expect(state.errors.at(-1)!.error).toContain("one turn at a time") + }) + + test("usage is per turn: a continuation reports what THIS turn spent, not the session total", async () => { + const { ctx, state } = makeCtx({ reply: { text: "ok" }, outputTokens: 7 }) + const first = await ctx.agent("one", { keepSession: true }) + expect(first.value).toBe("ok") + const afterFirst = state.usage.tokens.output + await ctx.agent("two", { session: first.sessionID! }) + // The fake host reports session totals (7 per turn), so the second Unit must have reported 7, not 14. + expect(state.usage.tokens.output - afterFirst).toBe(7) + }) + + test("each turn reports only its own tokens: 10, 20, 30 cumulative → 10, 10, 10 per Unit", async () => { + // A session reports LIFETIME totals; the engine subtracts a baseline taken before each turn. Without that, turn 2 + // would be billed for turn 1's tokens as well, and a review loop would look quadratic in cost. + const units: Unit[] = [] + const { ctx, state } = makeCtx( + { reply: (call) => ({ text: `r:${call.text}` }), outputTokens: 100 }, + { events: { onUnit: (unit) => units.push(unit) } }, + ) + const first = await ctx.agent("t1", { label: "t1", keepSession: true }) + const second = await first.resume("t2", { label: "t2" }) + await second.resume("t3", { label: "t3" }) + + const settled = units.filter((unit) => unit.status === "succeeded") + expect(settled.map((unit) => unit.label)).toEqual(["t1", "t2", "t3"]) + // Every turn spent the same: its own prompt and its own answer, not the conversation's running total. + expect(settled.map((unit) => unit.usage.tokens.input)).toEqual([10, 10, 10]) + expect(settled.map((unit) => unit.usage.tokens.output)).toEqual([100, 100, 100]) + // The Run adds the turns up — which IS the conversation's total, and what the budget is measured against. + expect(state.usage.tokens.input).toBe(30) + expect(state.usage.tokens.output).toBe(300) + expect(state.tokensSpent).toBe(300) + }) + + test("a handle serializes to { value, unitId, sessionID }: no function table in the journal", async () => { + const { ctx, host } = makeCtx({ + reply: { tools: [{ name: "bash", input: { command: "true" }, content: "ok" }], text: "done" }, + }) + const handle = await ctx.agent("run", { keepSession: true }) + const ownRead = host.contexts.length + expect(Object.keys(handle)).toEqual(["value", "unitId", "sessionID"]) + expect(JSON.stringify(handle)).toBe( + `{"value":"done","unitId":"${handle.unitId}","sessionID":"${handle.sessionID}"}`, + ) + expect(host.contexts).toHaveLength(ownRead) + expect(await handle.toolCalls).toHaveLength(1) + }) + + test("resume() on a Unit that never had a session fails as a value, not a rejection", async () => { + const { ctx, state } = makeCtx({ createError: "no capacity" }) + const handle = await ctx.agent("one", { keepSession: true }) + expect(handle.value).toBeNull() + expect(handle.sessionID).toBeNull() + const again = await handle.resume("two") + expect(again.value).toBeNull() + expect(state.errors.at(-1)!.error).toContain("never had a session") + }) + + test("a continuation's Unit is journaled with its session from the start", async () => { + const seen: Unit[] = [] + const { ctx } = makeCtx({ reply: { text: "ok" } }, { events: { onUnit: (unit) => seen.push(unit) } }) + const first = await ctx.agent("one", { keepSession: true }) + seen.length = 0 + await ctx.agent("two", { session: first.sessionID!, label: "turn2" }) + const queued = seen[0]! + expect(queued.label).toBe("turn2") + expect(queued.sessionID).toBe("ses_fake_1") + expect(queued.prompt).toBe("two") + }) + + test("the transcript accumulates across turns: the second turn sees the first one's messages", async () => { + const { ctx, host } = makeCtx({ reply: (call) => ({ text: `reply to ${call.text}` }) }) + const first = await ctx.agent("one", { keepSession: true }) + await first.resume("two") + const transcript = (await host.session.context({ sessionID: first.sessionID! })) as HostMessage[] + expect(transcript.map((message) => message.type)).toEqual(["user", "assistant", "user", "assistant"]) + expect(transcript[0]!.content?.[0]?.text).toBe("one") + expect(transcript[2]!.content?.[0]?.text).toBe("two") + }) + + test("a continuation's answer is its OWN turn, never the previous turn's text", async () => { + // The blocker this pins: a session holds every turn, and "the last assistant text" would answer with turn 1. + const { ctx, state } = makeCtx({ replies: [{ text: "first answer" }, { none: true }] }) + const first = await ctx.agent("review1", { keepSession: true }) + expect(first.value).toBe("first answer") + const second = await first.resume("review2") + // Turn 2 produced no text at all: that is a failed turn, NOT turn 1's answer reported as a success. + expect(second.value).toBeNull() + expect(state.errors.at(-1)!.unit).toBeTruthy() + }) + + test("a continuation's provider error is not swallowed by the previous turn's answer", async () => { + const { ctx, state } = makeCtx({ replies: [{ text: "first answer" }, { error: "provider exploded" }] }) + const first = await ctx.agent("review1", { keepSession: true }) + const second = await first.resume("review2") + expect(second.value).toBeNull() + expect(state.errors).toHaveLength(1) + expect(state.errors[0]!.error).toContain("provider exploded") + }) + + test("a typed continuation does not reuse the previous turn's JSON", async () => { + const Findings = z.object({ issues: z.array(z.string()) }) + const { ctx } = makeCtx({ + // Turn 1 answers with a valid JSON object in text; turn 2 answers with nothing at all. + replies: [{ text: '{"issues":["stale"]}' }, { none: true }], + }) + const first = await ctx.agent("review1", { schema: Findings, keepSession: true }) + expect(first.value).toEqual({ issues: ["stale"] }) + const second = await first.resume("review2", { schema: Findings, retries: 0 }) + expect(second.value).toBeNull() + }) + + test("a continuation's toolCalls are its own turn's, not the whole conversation's", async () => { + const { ctx } = makeCtx({ + replies: [ + { tools: [{ name: "bash", input: { command: "first" }, content: "one" }], text: "a" }, + { tools: [{ name: "bash", input: { command: "second" }, content: "two" }], text: "b" }, + ], + }) + const first = await ctx.agent("t1", { keepSession: true }) + expect((await first.toolCalls).map((call) => JSON.parse(call.input))).toEqual([{ command: "first" }]) + const second = await first.resume("t2") + expect((await second.toolCalls).map((call) => JSON.parse(call.input))).toEqual([{ command: "second" }]) + }) + + test("a receipt read AFTER the next turn still reports its OWN turn's calls", async () => { + // The lazy getter can be read long after the Unit settled — by then the session holds later turns too. The + // boundary is measured when the turn ends, so a late read must not drift into the next turn. + const { ctx } = makeCtx({ + replies: [ + { tools: [{ name: "read", input: { path: "a.ts" }, content: "a" }], text: "one" }, + { tools: [{ name: "edit", input: { path: "a.ts" }, content: "b" }], text: "two" }, + ], + }) + const first = await ctx.agent("t1", { keepSession: true }) + await first.resume("t2") + // Read only now: both turns are in the session. + expect((await first.toolCalls).map((call) => call.name)).toEqual(["read"]) + }) + + test("a repair turn does not shrink the receipt to the repair prompt", async () => { + // A typed Unit's repair turn is a separate prompt in the SAME Unit: the "last user message" moves to it, so a + // boundary derived from it would drop the first attempt's tool calls. + const Findings = z.object({ ok: z.boolean() }) + const { ctx } = makeCtx({ + replies: [ + // Turn 1 of the Unit: calls a tool, then answers with an invalid payload. + { tools: [{ name: "bash", input: { command: "check" }, content: "ran" }], text: "not the tool" }, + // The repair turn: a valid result. + { result: { ok: true } }, + ], + }) + const receipt = await ctx.agent("do it", { schema: Findings, retries: 1, receipts: true }) + expect(receipt.value).toEqual({ ok: true }) + const names = (await receipt.toolCalls).map((call) => call.name) + // Both the original call and the submitted result are this Unit's evidence. + expect(names).toContain("bash") + expect(names).toContain("workflow_result") + }) + + test("a continuation whose start read fails fails the turn — it never answers with the previous turn's text", async () => { + // THE regression this guards: with no measurable boundary, "read the transcript" means the whole conversation, and + // a turn that produced nothing is answered with the PREVIOUS turn's text as a success. + // + // The scenario has to be discriminating: turn 1 must SUCCEED (its own answer read is #1), and only turn 2's + // start measurement (reads #2 and #3, the try and the retry) must fail. Failing every read — as an earlier + // version of this test did — passes for the wrong reason: turn 1 fails too, so `resume` on a session-less handle + // returns null whatever the measurement does. + const { ctx, state } = makeCtx({ + replies: [{ text: "TURN1 ANSWER" }, { text: "TURN2 ANSWER" }], + // Reads: turn 1's answer (1), then turn 2's start measurement and its retry (2 and 3) fail; nothing else does. + // Break ONLY those, so the failure is the measurement — not an unreadable transcript, which would fail for a + // different reason and let a broken fix pass. + contextErrorAt: [2, 3], + contextError: "transient read failure", + }) + const first = await ctx.agent("t1", { keepSession: true }) + expect(first.value).toBe("TURN1 ANSWER") + expect(first.sessionID).not.toBeNull() + const second = await first.resume("t2") + // The turn fails, legibly, and — the point — never carries the previous turn's answer as a success. + expect(second.value).toBeNull() + const error = state.errors.at(-1)!.error + expect(error).toContain("could not be scoped to its own messages") + expect(second.value).not.toBe("TURN1 ANSWER") + }) + + test("a single transient failure of the start read is retried, so the turn still runs", async () => { + // The measurement retries once: a host hiccup on the boundary read must not fail an otherwise healthy turn. + const { ctx } = makeCtx({ + replies: [{ text: "one" }, { text: "two" }], + // Read 1 is turn 1's answer; read 2 is turn 2's start measurement — a one-off failure, retried and succeeding. + contextErrorAt: [2], + contextError: "one-off hiccup", + }) + const first = await ctx.agent("t1", { keepSession: true }) + expect(first.value).toBe("one") + const second = await first.resume("t2") + expect(second.value).toBe("two") + }) + + test("a continuation that died before its answer reports NO tool calls, not the earlier turn's", async () => { + // `slice` stays `null` when a turn dies before the read that ends it. For a Unit that owns its session that means + // "the whole session is my turn" — true by definition. For a continuation the session also holds earlier turns, + // so the whole transcript would hand back calls this turn never made: `[]` (unknown) is the only honest answer. + const { ctx, state } = makeCtx({ + replies: [ + { tools: [{ name: "read", input: { path: "turn1.ts" }, content: "a" }], text: "one" }, + { tools: [{ name: "read", input: { path: "turn2.ts" }, content: "b" }], text: "two" }, + ], + // Reads: turn 1's answer (1), turn 2's start measurement (2), turn 2's answer read (3) — break the last one. + contextErrorFrom: 3, + contextError: "transcript vanished", + }) + const first = await ctx.agent("t1", { keepSession: true }) + const second = await first.resume("t2") + expect(second.value).toBeNull() + expect(state.errors.at(-1)!.error).toContain("could not read the Unit transcript") + // Failed before the read that fixes its slice: `[]`, never turn 1's `read`. + expect(await second.toolCalls).toEqual([]) + }) + + test("an unmeasurable turn reports NO tool calls even when the transcript reads fine", async () => { + // The subtler leak: the boundary is missing (the turn timed out before its answer read) but the transcript is + // perfectly readable. Reading it would look authoritative and hand back the EARLIER turn's calls. The guard must + // therefore sit before the read, not after it. + const { ctx, state } = makeCtx({ + replies: [{ tools: [{ name: "read", input: { path: "turn1.ts" }, content: "a" }], text: "one" }, { hang: true }], + }) + const first = await ctx.agent("t1", { keepSession: true }) + expect(first.value).toBe("one") + // The turn times out before it can read its own answer: no slice is ever recorded. + const second = await first.resume("t2", { timeoutMs: 20 }) + expect(second.value).toBeNull() + expect(state.errors.at(-1)!.error).toContain("timeout") + // Every read would succeed here — the answer is still `[]`, because the turn's own extent is unknown. + expect(await second.toolCalls).toEqual([]) + }) + + test("a rejected continuation is journaled WITHOUT the session id it named", async () => { + // `cleanupTargets` collects every Unit's sessionID, so a stray id here would let "delete this Run's sessions" + // delete a session the Run never owned. + const units: Unit[] = [] + const { ctx } = makeCtx({ reply: { text: "ok" } }, { events: { onUnit: (unit) => units.push(unit) } }) + await ctx.agent("hi", { session: "ses_someone_elses_chat" }) + expect(units).toHaveLength(1) + expect(units[0]!.status).toBe("failed") + expect(units[0]!.sessionID).toBeNull() + }) + + test("a continuation's Unit reports the session's directory, not the Run's root", async () => { + const units: Unit[] = [] + const { ctx } = makeCtx( + { reply: { text: "ok" }, seedSessions: [{ id: "ses_wt" }] }, + { events: { onUnit: (unit) => units.push(unit) } }, + ) + // Register a session the way a worktree Unit's first turn would: created in another directory. + const first = await ctx.agent("one", { keepSession: true }) + expect(first.sessionID).toBe("ses_fake_1") + expect(units.at(-1)!.location).toBe("/fake") + }) + + test("a finished turn stays finished: the surfaces key Units by unitId, never by session", async () => { + // The whole point of this test: three turns of one conversation are THREE Unit rows with their own statuses. + // Sharing a session must not make an earlier turn look like it is running again — `runs.ts` and `ui/state.ts` + // upsert by `unitId`, and nothing there groups by `sessionID`. + const seen: Unit[] = [] + const { ctx } = makeCtx( + { reply: (call) => ({ text: `r:${call.text}` }), delayMs: 5 }, + { events: { onUnit: (unit) => seen.push(unit) } }, + ) + const first = await ctx.agent("review1", { label: "review", keepSession: true }) + await ctx.agent("fix", { label: "fix" }) + await first.resume("review2", { label: "review2" }) + + // The latest state of each Unit, in ordinal order — what a surface renders as rows. + const latest = new Map() + for (const unit of seen) latest.set(unit.unitId, unit) + const rows = [...latest.values()].toSorted((a, b) => a.ordinal - b.ordinal) + expect(rows.map((unit) => unit.label)).toEqual(["review", "fix", "review2"]) + expect(rows.map((unit) => unit.status)).toEqual(["succeeded", "succeeded", "succeeded"]) + // Two rows share one session — and that is exactly why the session cannot be the identity. + expect(rows[0]!.sessionID).toBe(rows[2]!.sessionID) + expect(rows[1]!.sessionID).not.toBe(rows[0]!.sessionID) + expect(new Set(rows.map((unit) => unit.unitId)).size).toBe(3) + expect(rows.map((unit) => unit.ordinal)).toEqual([1, 2, 3]) + }) + + test("an in-flight turn does not re-open an earlier turn on the same session", async () => { + const statuses: Array<{ prompt: string; status: string }> = [] + const { ctx } = makeCtx( + { reply: (call) => ({ text: `r:${call.text}` }), delayMs: 5 }, + { events: { onUnit: (unit) => statuses.push({ prompt: unit.prompt, status: unit.status }) } }, + ) + const first = await ctx.agent("review1", { label: "review", keepSession: true }) + const running = first.resume("review2", { label: "review2" }) + // While the second turn is in flight, the first turn saw its last transition as `succeeded`. + await Bun.sleep(2) + const lastOf = (prompt: string) => statuses.findLast((entry) => entry.prompt === prompt)! + expect(lastOf("review1").status).toBe("succeeded") + await running + expect(lastOf("review1").status).toBe("succeeded") + }) +}) + +describe("a conversation across a resume — replay", () => { + /** A replay plan with one finished Unit per entry, in ordinal order — the shape `resumeRun` hands the engine. */ + const replayed = ( + units: Array<{ prompt: string; output?: string; status?: Unit["status"]; sessionID?: string }>, + ) => ({ + units: new Map( + units.map((unit, index) => [ + index + 1, + { + prompt: unit.prompt, + status: unit.status ?? ("succeeded" as const), + output: unit.output ?? unit.prompt, + schema: false, + subagent: "general", + ...(unit.sessionID ? { sessionID: unit.sessionID } : {}), + }, + ]), + ), + answers: [], + rerunFailed: true, + diverged: false, + }) + + test("a replayed conversation replays BOTH turns without prompting the model", async () => { + const { ctx, host, state } = makeCtx( + {}, + { + replay: replayed([ + { prompt: "review", output: "first pass", sessionID: "ses_fake_1" }, + { prompt: "re-check", output: "second pass", sessionID: "ses_fake_1" }, + ]), + }, + ) + const first = await ctx.agent("review", { keepSession: true }) + expect(first.value).toBe("first pass") + const second = await first.resume("re-check") + expect(second.value).toBe("second pass") + // The whole point: a resume of a conversation costs nothing — no create, no prompt. + expect(host.creates).toHaveLength(0) + expect(host.prompts).toHaveLength(0) + // …and the session is still continuable, so a script may go on live after the replayed part. + expect(second.sessionID).toBe("ses_fake_1") + expect(state.unitCount).toBe(2) + }) + + test("a replayed first turn leaves its session continuable live", async () => { + const { ctx, host } = makeCtx( + { reply: { text: "live answer" }, seedSessions: [{ id: "ses_fake_old" }] }, + { replay: replayed([{ prompt: "review", output: "first pass", sessionID: "ses_fake_old" }]) }, + ) + const first = await ctx.agent("review", { keepSession: true }) + expect(first.value).toBe("first pass") + // A replayed Unit's handle reports the session the ORIGINAL Run recorded, so the next turn goes there. + expect(first.sessionID).toBe("ses_fake_old") + const second = await first.resume("re-check") + expect(second.value).toBe("live answer") + expect(host.prompts).toEqual([{ sessionID: "ses_fake_old", text: "re-check", turn: 0 }]) + }) + + test("a divergence inside a conversation runs live from there, not from the start", async () => { + const { ctx, host, state } = makeCtx( + { reply: { text: "live" }, seedSessions: [{ id: "ses_fake_1" }] }, + { + replay: replayed([ + { prompt: "review", output: "first pass", sessionID: "ses_fake_1" }, + { prompt: "something else", output: "unused" }, + ]), + }, + ) + const first = await ctx.agent("review", { keepSession: true }) + expect(first.value).toBe("first pass") + // The script asked for a different prompt at ordinal 2: replay diverges and the rest runs live. + const second = await first.resume("re-check") + expect(second.value).toBe("live") + expect(host.prompts).toHaveLength(1) + expect(state.errors).toHaveLength(0) + }) +}) diff --git a/packages/plugin/test/fake-host.ts b/packages/plugin/test/fake-host.ts index f92b76f..2a59a8d 100644 --- a/packages/plugin/test/fake-host.ts +++ b/packages/plugin/test/fake-host.ts @@ -67,6 +67,15 @@ export interface FakeHostOptions { * succeeds. Lets a test break a RECEIPT's read while the Unit's own transcript read is fine. */ contextErrorFrom?: number + /** + * With `contextError`: fail ONLY these `session.context` reads (1-based, matching {@link FakeHost.contexts}), leaving + * every other read working. This is what a transient host hiccup looks like, and it is the only shape that can tell + * "the boundary was not measurable" apart from "the transcript was unreadable". + * + * Takes precedence over {@link contextErrorFrom} when both are set (it is the more specific form); setting both on + * one host is a mistake, not a combination. + */ + contextErrorAt?: number[] /** `interrupt` never resolves (and does not stop the session). */ interruptHang?: boolean /** Worktree support: `changed` decides whether a Unit's worktree is kept; `active: false` = plugin not loaded there. */ @@ -309,7 +318,9 @@ export function createFakeHost(index: UnitIndex, options: FakeHostOptions = {}): contexts.push(input.sessionID) if ( options.contextError && - (options.contextErrorFrom === undefined || contexts.length >= options.contextErrorFrom) + (options.contextErrorAt + ? options.contextErrorAt.includes(contexts.length) + : options.contextErrorFrom === undefined || contexts.length >= options.contextErrorFrom) ) throw new Error(options.contextError) const session = sessions.get(input.sessionID) diff --git a/packages/plugin/test/service.test.ts b/packages/plugin/test/service.test.ts index 18020a1..44bd71d 100644 --- a/packages/plugin/test/service.test.ts +++ b/packages/plugin/test/service.test.ts @@ -555,4 +555,79 @@ describe("transcripts", () => { expect(out.clipped).toBe(true) expect(out.messages[1]!.model).toBe("p/m") }) + + it("finds each turn's start in a shared session, including a repeated prompt", async () => { + const { turnBoundaries, toTranscript } = await import("../src/service/service") + const out = toTranscript("ses_x", [ + { type: "user", content: [{ type: "text", text: "review" }] }, + { type: "assistant", content: [{ type: "text", text: "a1" }] }, + { type: "user", content: [{ type: "text", text: "fix" }] }, + { type: "assistant", content: [{ type: "text", text: "a2" }] }, + { type: "user", content: [{ type: "text", text: "review" }] }, + { type: "assistant", content: [{ type: "text", text: "a3" }] }, + ]) + const bounds = turnBoundaries(out.messages, [ + { ordinal: 1, prompt: "review" }, + { ordinal: 2, prompt: "fix" }, + { ordinal: 3, prompt: "review" }, + ]) + // A verbatim repeat resolves to the LATER occurrence: turns advance, so the first "review" cannot be turn 3. + expect([...bounds.entries()]).toEqual([ + [1, 0], + [2, 2], + [3, 4], + ]) + }) + + it("leaves an unmatched prompt out instead of guessing a boundary", async () => { + const { turnBoundaries, toTranscript } = await import("../src/service/service") + const out = toTranscript("ses_x", [ + { type: "user", content: [{ type: "text", text: "review" }] }, + { type: "assistant", content: [{ type: "text", text: "a1" }] }, + ]) + const bounds = turnBoundaries(out.messages, [ + { ordinal: 1, prompt: "review" }, + { ordinal: 2, prompt: "a prompt the host never sent" }, + ]) + expect(bounds.has(2)).toBe(false) + }) + + it("a continued Unit's transcript is its own turn; `whole` returns the conversation", async () => { + const { service: svc } = service({ approved: true }) + const started = await svc.startRun({ + source: `import { defineWorkflow } from "@syn7xx/opencode-dynamic-workflows/workflow" +export default defineWorkflow({ + meta: { name: "convo", description: "two turns in one session" }, + async run({ agent }) { + const first = await agent("first turn", { label: "one", keepSession: true }) + await first.resume("second turn", { label: "two" }) + return "done" + }, +}) +`, + parentSessionID: "p", + }) + const { run } = await started.done + const units = run.units.toSorted((a, b) => a.ordinal - b.ordinal) + expect(units).toHaveLength(2) + const second = units[1]! + + const own = await svc.getTranscript(run.runId, second.unitId) + expect(own.turns).toBe(2) + expect(own.earlier).toBe(2) + // Only the second turn: its prompt and its answer, nothing from the first. + expect(own.messages.map((message) => message.role)).toEqual(["user", "assistant"]) + expect(own.messages[0]!.parts[0]).toMatchObject({ text: "second turn" }) + + const whole = await svc.getTranscript(run.runId, second.unitId, { whole: true }) + expect(whole.turns).toBe(2) + expect(whole.earlier).toBeUndefined() + expect(whole.messages.length).toBeGreaterThan(own.messages.length) + + // The first turn is the whole session from its own start: no `earlier`, and it does not include turn two. + const firstTurn = await svc.getTranscript(run.runId, units[0]!.unitId) + expect(firstTurn.earlier).toBeUndefined() + expect(firstTurn.messages.map((message) => message.role)).toEqual(["user", "assistant"]) + expect(firstTurn.messages[0]!.parts[0]).toMatchObject({ text: "first turn" }) + }) }) diff --git a/packages/plugin/test/workflow/agent-types.types.ts b/packages/plugin/test/workflow/agent-types.types.ts index a778110..17fb97a 100644 --- a/packages/plugin/test/workflow/agent-types.types.ts +++ b/packages/plugin/test/workflow/agent-types.types.ts @@ -103,6 +103,62 @@ async function proof() { // CONTROL — same for a boolean that only settles at run time. // @ts-expect-error — a non-literal flag matches neither overload. await agent("rate it", { schema: Finding, receipts: maybeReceipts }) + + // GREEN — `{ keepSession: true }` resolves to a handle: a receipt plus the session and `resume`. + const handle = await agent("review", { schema: Finding, keepSession: true }) + const _handleTitle: string | undefined = handle.value?.title + const _session: string | null = handle.sessionID + const _handleCalls: Promise = handle.toolCalls + void _handleTitle + void _session + void _handleCalls + + // GREEN — `resume` keeps the schema's type across the conversation, and returns a handle again. + const next = await handle.resume("re-check", { schema: Finding }) + const _nextTitle: string | undefined = next.value?.title + const _nextSession: string | null = next.sessionID + void _nextTitle + void _nextSession + + // GREEN — a text conversation: `resume` without a schema resolves to a handle of `string | null`. + const textHandle = await agent("draft", { keepSession: true }) + const _draft: string | null = textHandle.value + void _draft + const redraft = await textHandle.resume("polish it") + const _polished: string | null = redraft.value + void _polished + + // CONTROL — a handle is not the bare value: a struct field access on the handle itself is an error. + // @ts-expect-error — a handle has `value`, not the schema's fields. + void handle.title + + // CONTROL — the session fixed at create time cannot be re-decided by a continuation. + // @ts-expect-error — `subagent` is not a continuation option. + await handle.resume("next", { subagent: "reviewer" }) + // @ts-expect-error — `model` is not a continuation option. + await handle.resume("next", { model: "acme/other" }) + // @ts-expect-error — a continuation is never itself a continuation. + await handle.resume("next", { session: "ses_x" }) + // @ts-expect-error — nor does it take `keepSession`; a handle is already a handle. + await handle.resume("next", { keepSession: true }) + // @ts-expect-error — nor `receipts`: a handle carries the receipt. + await handle.resume("next", { receipts: true }) + + // GREEN — `keepSession` wins over `receipts`: a handle already IS a receipt, so the combination compiles. + const both = await agent("review", { schema: Finding, keepSession: true, receipts: true }) + const _bothTitle: string | undefined = both.value?.title + const _bothSession: string | null = both.sessionID + void _bothTitle + void _bothSession + + // CONTROL — `keepSession` is not an `AgentOpts` member either, for the same reason as `receipts`. + // @ts-expect-error — `keepSession` lives in the overloads, not in `AgentOpts`. + const optsWithKeepSession: AgentOpts = { schema: Finding, keepSession: true } + void optsWithKeepSession + + // CONTROL — a widened boolean selects no overload, exactly like `receipts`. + // @ts-expect-error — a non-literal flag matches neither overload. + await agent("rate it", { schema: Finding, keepSession: maybeReceipts }) } void proof diff --git a/packages/web/src/api.ts b/packages/web/src/api.ts index 411131b..c861ee6 100644 --- a/packages/web/src/api.ts +++ b/packages/web/src/api.ts @@ -99,7 +99,7 @@ export interface Api { getResult(runId: string): Promise<{ runId: string; status: RunStatus; result: unknown }> getActivity(runId: string): Promise getUnit(runId: string, unitId: string): Promise - getTranscript(runId: string, unitId: string): Promise + getTranscript(runId: string, unitId: string, whole?: boolean): Promise listWorkflows(location: string): Promise startRun(location: string, input: StartRunInput): Promise<{ runId: string }> stopRun(runId: string): Promise @@ -255,7 +255,8 @@ export function createApi(options: ApiOptions = {}): Api { async getUnit(runId, unitId) { return (await read<{ unit: Unit }>(`/v1/runs/${enc(runId)}/units/${enc(unitId)}`)).unit }, - getTranscript: (runId, unitId) => read(`/v1/runs/${enc(runId)}/units/${enc(unitId)}/transcript`), + getTranscript: (runId, unitId, whole) => + read(`/v1/runs/${enc(runId)}/units/${enc(unitId)}/transcript${whole ? "?whole=1" : ""}`), listWorkflows: (location) => read(`/v1/workflows?location=${enc(location)}`), startRun: (location, input) => post(`/v1/runs?location=${enc(location)}`, input), async stopRun(runId) { diff --git a/packages/web/src/styles.css b/packages/web/src/styles.css index 68c5156..650153a 100644 --- a/packages/web/src/styles.css +++ b/packages/web/src/styles.css @@ -1008,6 +1008,23 @@ input[type="search"] { flex-direction: column; gap: 10px; } +/* The turns a session's transcript is made of (a Unit continued with `agent(prompt, { session })`). */ +.tx-turns { + list-style: none; + margin: 0; + padding: 0; + display: flex; + flex-wrap: wrap; + gap: 6px 12px; +} +.tx-turn { + font-size: 0.85em; + color: var(--color-text-secondary, inherit); +} +.tx-turn.is-current { + font-weight: 600; + color: var(--color-text-primary, inherit); +} .tx-messages { list-style: none; margin: 0; diff --git a/packages/web/src/unit.tsx b/packages/web/src/unit.tsx index 940b866..bedb9f4 100644 --- a/packages/web/src/unit.tsx +++ b/packages/web/src/unit.tsx @@ -269,13 +269,13 @@ function TranscriptSection(props: { runId: string; unit: Unit }) { const [busy, setBusy] = createSignal(false) let request = 0 - const load = async () => { + const load = async (whole = false) => { const ticket = ++request const { runId } = props const unitId = props.unit.unitId setBusy(true) try { - const result = await app.api.getTranscript(runId, unitId) + const result = await app.api.getTranscript(runId, unitId, whole) if (ticket !== request) return setData(result) setError(null) @@ -286,6 +286,8 @@ function TranscriptSection(props: { runId: string; unit: Unit }) { if (ticket === request) setBusy(false) } } + /** The same conversation from its very first turn — what a continued Unit hides by default. */ + const loadAll = () => load(true) // Another Unit (the [ ] keys reuse this view): start closed again. createEffect( @@ -364,6 +366,20 @@ function TranscriptSection(props: { runId: string; unit: Unit }) { Some large tool inputs or outputs were clipped for display. + {/* A continued turn (`agent(prompt, { session })`): this view shows THIS turn, not the whole conversation. */} + + {(earlier) => ( +
+ + Showing this turn only — {earlier()} earlier message{earlier() === 1 ? "" : "s"} of the same + conversation {earlier() === 1 ? "is" : "are"} hidden. + {" "} + +
+ )} +