From 63a8fefd5badfc5c653efa55cf0fb3fba29e4290 Mon Sep 17 00:00:00 2001 From: syn7xx Date: Tue, 17 Nov 2026 18:48:54 +0300 Subject: [PATCH] refactor(unit)!: rename handle.resume() to handle.ask() MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `resume` was the wrong name in a codebase that already has `resumeRun` (restart a whole Run from its journal, RPC `resumeRun`, input `ResumeRunInput`). Four meanings of one word makes every reader stop and disambiguate, and the semantics differ: `resumeRun` continues an INTERRUPTED Run, while this sends a new question into a session whose last turn finished successfully. `ask` says what it does — ask the same conversation something else — and leaves `resume` to the Run. No behavioural change: `handle.ask(prompt, opts)` is the same call as before, still sugar over `agent(prompt, { session, keepSession: true })`. BREAKING CHANGE: `UnitHandle.resume()` is now `UnitHandle.ask()`. The API was merged but has not shipped in a release yet, so no published version is affected; for a Workflow written against the branch, rename `handle.resume(` to `handle.ask(`. Also rename the same-word docs and examples (README "Continuing a Unit", the `dynamic-workflows` skill, `docs/examples/review-loop.ts`) so nobody learns the old name. Verified: `bun run check` — 427 tests, format/lint/types green. --- README.md | 10 ++--- packages/plugin/README.md | 10 ++--- packages/plugin/docs/examples/review-loop.ts | 2 +- .../plugin/skill/dynamic-workflows/SKILL.md | 34 +++++++-------- packages/plugin/src/context.ts | 16 +++---- packages/plugin/src/workflow/index.ts | 22 ++++++---- packages/plugin/test/conversation.test.ts | 42 +++++++++---------- packages/plugin/test/service.test.ts | 2 +- .../plugin/test/workflow/agent-types.types.ts | 14 +++---- 9 files changed, 78 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index f8bded8..333dd99 100644 --- a/README.md +++ b/README.md @@ -325,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). With `{ keepSession: true }` it returns a handle with `sessionID` and `resume()` — see [Continuing a Unit](#continuing-a-unit). | +| `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 `ask()` — 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. | @@ -437,14 +437,14 @@ let review = await agent("Review the diff. List every issue you find.", { 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.", { + review = await review.ask("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 +`ask(prompt, opts?)` and `close()`. `ask` 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. @@ -460,7 +460,7 @@ one of those on a continuation is an **error** (the turn fails with a legible me 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 +Conversations are **sequential**: one turn at a time per session, so a second concurrent `ask` 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 @@ -479,7 +479,7 @@ falling back to the whole session. Reporting another turn's text as this turn's `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` +`boolean` variable selects no overload. A handle journals as `{ value, unitId, sessionID }` — `toolCalls`, `ask` and `close` are not enumerable. ### Resume diff --git a/packages/plugin/README.md b/packages/plugin/README.md index 14da422..6771575 100644 --- a/packages/plugin/README.md +++ b/packages/plugin/README.md @@ -327,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). With `{ keepSession: true }` it returns a handle with `sessionID` and `resume()` — see [Continuing a Unit](#continuing-a-unit). | +| `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 `ask()` — 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. | @@ -439,14 +439,14 @@ let review = await agent("Review the diff. List every issue you find.", { 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.", { + review = await review.ask("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 +`ask(prompt, opts?)` and `close()`. `ask` 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. @@ -462,7 +462,7 @@ one of those on a continuation is an **error** (the turn fails with a legible me 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 +Conversations are **sequential**: one turn at a time per session, so a second concurrent `ask` 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 @@ -481,7 +481,7 @@ falling back to the whole session. Reporting another turn's text as this turn's `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` +`boolean` variable selects no overload. A handle journals as `{ value, unitId, sessionID }` — `toolCalls`, `ask` and `close` are not enumerable. ### Resume diff --git a/packages/plugin/docs/examples/review-loop.ts b/packages/plugin/docs/examples/review-loop.ts index 5f985d5..1160238 100644 --- a/packages/plugin/docs/examples/review-loop.ts +++ b/packages/plugin/docs/examples/review-loop.ts @@ -53,7 +53,7 @@ export default defineWorkflow({ break } phase("re-review") - review = await review.resume( + review = await review.ask( "Re-check your previous findings against the fixes just made. " + "Report only the issues that are still present after the fixes.", { schema: Finding }, diff --git a/packages/plugin/skill/dynamic-workflows/SKILL.md b/packages/plugin/skill/dynamic-workflows/SKILL.md index 0ce33df..e7de33f 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). 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. | +| 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 `ask()` — 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 @@ -105,7 +105,7 @@ let review = await agent("Review the diff. List every issue you find.", { 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.", { + review = await review.ask("Re-check your previous findings against the fixes you just made.", { schema: Findings, }) } @@ -127,7 +127,7 @@ Rules worth knowing: (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 +- **One turn at a time.** Never `Promise.all` over `ask()` (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. diff --git a/packages/plugin/src/context.ts b/packages/plugin/src/context.ts index edef08d..6930095 100644 --- a/packages/plugin/src/context.ts +++ b/packages/plugin/src/context.ts @@ -478,7 +478,7 @@ export function createWorkflowContext(input: CreateContextInput): Workflow // 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\`.`, + `Take the id from \`agent(prompt, { keepSession: true })\` (its \`sessionID\`) or from a handle's \`ask\`.`, ) } if (session.closed) @@ -859,23 +859,23 @@ export function createWorkflowContext(input: CreateContextInput): Workflow /** * 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). + * conversation needs — `ask` (next turn, same session) and `close` (end it). * - * Serializes to `{ value, unitId, sessionID }`: `toolCalls`, `resume` and `close` are non-enumerable, so a handle + * Serializes to `{ value, unitId, sessionID }`: `toolCalls`, `ask` 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: { + ask: { 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`, + `ask: Unit ${outcome.label ?? outcome.unitId} never had a session (it failed before one existed), so there is nothing to ask`, outcome, ), ) @@ -893,15 +893,15 @@ export function createWorkflowContext(input: CreateContextInput): Workflow } /** - * A `resume()` with nothing to resume. It is recorded in `errors` like any other dropped Unit — never a rejected + * An `ask()` with nothing to ask into. 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. + * session, so a mistaken second `ask()` 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)", + prompt: "(ask: no session)", subagent: "(unknown)", error, }) diff --git a/packages/plugin/src/workflow/index.ts b/packages/plugin/src/workflow/index.ts index 5774b16..71a83e4 100644 --- a/packages/plugin/src/workflow/index.ts +++ b/packages/plugin/src/workflow/index.ts @@ -248,7 +248,7 @@ export type UnitValue = S ext /** * 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. + * `{ receipts: true }` folded in), plus the session's id and an `ask` 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 @@ -257,22 +257,26 @@ export type UnitValue = S ext 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`. + * session existed). `ask` 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. + * Ask the same conversation something else: sends the next turn into this session and resolves 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. + * Named `ask` rather than `resume` on purpose: this codebase already has `resumeRun` (restart a whole Run from its + * journal), and two different "resumes" is one too many. A turn that finished successfully is not resumed — it is + * asked again in the same chat. + * + * One turn at a time: never `ask` (or `agent({ session })`) twice concurrently on the same session. */ - resume( + ask( prompt: string, opts?: ContinuationOpts, ): Promise>> /** - * End the conversation: a later `agent({ session })` or `resume` on it fails legibly, and the session is + * End the conversation: a later `agent({ session })` or `ask` 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, @@ -299,7 +303,7 @@ export type ContinuationOpts { expect(first.value).toBe("about review") expect(first.sessionID).toBe("ses_fake_1") - const second = await first.resume("re-check") + const second = await first.ask("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") @@ -67,7 +67,7 @@ describe("agent({ keepSession }) — a conversation", () => { 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 }) + const second = await first.ask("list them", { schema: Findings }) expect(second.value).toEqual({ issues: ["a", "b"] }) }) @@ -122,8 +122,8 @@ describe("agent({ keepSession }) — a conversation", () => { { 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 second = await first.ask("t2", { label: "t2" }) + await second.ask("t3", { label: "t3" }) const settled = units.filter((unit) => unit.status === "succeeded") expect(settled.map((unit) => unit.label)).toEqual(["t1", "t2", "t3"]) @@ -155,7 +155,7 @@ describe("agent({ keepSession }) — a conversation", () => { const handle = await ctx.agent("one", { keepSession: true }) expect(handle.value).toBeNull() expect(handle.sessionID).toBeNull() - const again = await handle.resume("two") + const again = await handle.ask("two") expect(again.value).toBeNull() expect(state.errors.at(-1)!.error).toContain("never had a session") }) @@ -175,7 +175,7 @@ describe("agent({ keepSession }) — a conversation", () => { 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") + await first.ask("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") @@ -187,7 +187,7 @@ describe("agent({ keepSession }) — a conversation", () => { 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") + const second = await first.ask("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() @@ -196,7 +196,7 @@ describe("agent({ keepSession }) — a conversation", () => { 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") + const second = await first.ask("review2") expect(second.value).toBeNull() expect(state.errors).toHaveLength(1) expect(state.errors[0]!.error).toContain("provider exploded") @@ -210,7 +210,7 @@ describe("agent({ keepSession }) — a conversation", () => { }) 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 }) + const second = await first.ask("review2", { schema: Findings, retries: 0 }) expect(second.value).toBeNull() }) @@ -223,7 +223,7 @@ describe("agent({ keepSession }) — a conversation", () => { }) 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") + const second = await first.ask("t2") expect((await second.toolCalls).map((call) => JSON.parse(call.input))).toEqual([{ command: "second" }]) }) @@ -237,7 +237,7 @@ describe("agent({ keepSession }) — a conversation", () => { ], }) const first = await ctx.agent("t1", { keepSession: true }) - await first.resume("t2") + await first.ask("t2") // Read only now: both turns are in the session. expect((await first.toolCalls).map((call) => call.name)).toEqual(["read"]) }) @@ -281,7 +281,7 @@ describe("agent({ keepSession }) — a conversation", () => { 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") + const second = await first.ask("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 @@ -299,7 +299,7 @@ describe("agent({ keepSession }) — a conversation", () => { }) const first = await ctx.agent("t1", { keepSession: true }) expect(first.value).toBe("one") - const second = await first.resume("t2") + const second = await first.ask("t2") expect(second.value).toBe("two") }) @@ -317,7 +317,7 @@ describe("agent({ keepSession }) — a conversation", () => { contextError: "transcript vanished", }) const first = await ctx.agent("t1", { keepSession: true }) - const second = await first.resume("t2") + const second = await first.ask("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`. @@ -334,7 +334,7 @@ describe("agent({ keepSession }) — a conversation", () => { 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 }) + const second = await first.ask("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. @@ -375,7 +375,7 @@ describe("agent({ keepSession }) — a conversation", () => { ) const first = await ctx.agent("review1", { label: "review", keepSession: true }) await ctx.agent("fix", { label: "fix" }) - await first.resume("review2", { label: "review2" }) + await first.ask("review2", { label: "review2" }) // The latest state of each Unit, in ordinal order — what a surface renders as rows. const latest = new Map() @@ -397,7 +397,7 @@ describe("agent({ keepSession }) — a conversation", () => { { 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" }) + const running = first.ask("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)! @@ -442,7 +442,7 @@ describe("a conversation across a resume — replay", () => { ) const first = await ctx.agent("review", { keepSession: true }) expect(first.value).toBe("first pass") - const second = await first.resume("re-check") + const second = await first.ask("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) @@ -461,7 +461,7 @@ describe("a conversation across a resume — replay", () => { 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") + const second = await first.ask("re-check") expect(second.value).toBe("live answer") expect(host.prompts).toEqual([{ sessionID: "ses_fake_old", text: "re-check", turn: 0 }]) }) @@ -479,7 +479,7 @@ describe("a conversation across a resume — replay", () => { 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") + const second = await first.ask("re-check") expect(second.value).toBe("live") expect(host.prompts).toHaveLength(1) expect(state.errors).toHaveLength(0) diff --git a/packages/plugin/test/service.test.ts b/packages/plugin/test/service.test.ts index 44bd71d..4748a2b 100644 --- a/packages/plugin/test/service.test.ts +++ b/packages/plugin/test/service.test.ts @@ -600,7 +600,7 @@ 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" }) + await first.ask("second turn", { label: "two" }) return "done" }, }) diff --git a/packages/plugin/test/workflow/agent-types.types.ts b/packages/plugin/test/workflow/agent-types.types.ts index 17fb97a..aefa248 100644 --- a/packages/plugin/test/workflow/agent-types.types.ts +++ b/packages/plugin/test/workflow/agent-types.types.ts @@ -114,7 +114,7 @@ async function proof() { 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 next = await handle.ask("re-check", { schema: Finding }) const _nextTitle: string | undefined = next.value?.title const _nextSession: string | null = next.sessionID void _nextTitle @@ -124,7 +124,7 @@ async function proof() { const textHandle = await agent("draft", { keepSession: true }) const _draft: string | null = textHandle.value void _draft - const redraft = await textHandle.resume("polish it") + const redraft = await textHandle.ask("polish it") const _polished: string | null = redraft.value void _polished @@ -134,15 +134,15 @@ async function proof() { // 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" }) + await handle.ask("next", { subagent: "reviewer" }) // @ts-expect-error — `model` is not a continuation option. - await handle.resume("next", { model: "acme/other" }) + await handle.ask("next", { model: "acme/other" }) // @ts-expect-error — a continuation is never itself a continuation. - await handle.resume("next", { session: "ses_x" }) + await handle.ask("next", { session: "ses_x" }) // @ts-expect-error — nor does it take `keepSession`; a handle is already a handle. - await handle.resume("next", { keepSession: true }) + await handle.ask("next", { keepSession: true }) // @ts-expect-error — nor `receipts`: a handle carries the receipt. - await handle.resume("next", { receipts: true }) + await handle.ask("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 })