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 })