Skip to content

refactor(unit)!: rename handle.resume() to handle.ask() - #37

Merged
syn7xx merged 1 commit into
mainfrom
feat/handle-ask
Nov 17, 2026
Merged

syn7xx merged 1 commit into
mainfrom
feat/handle-ask

Conversation

@syn7xx

@syn7xx syn7xx commented Nov 17, 2026

Copy link
Copy Markdown
Owner

Follow-up to #34. Renames the handle method before the API ships in a release.

Why

resume was already taken — and meant something else:

Name Means
service.resumeRun() / RPC resumeRun / ResumeRunInput restart a whole Run from its journal (it was interrupted)
handle.resume() → handle.ask() send the next turn into a session whose last turn finished successfully

Four meanings of one word in one codebase is a trap: a reader has to stop and disambiguate every time, and the
semantics genuinely differ — resuming implies continuing something interrupted, whereas this asks the same
conversation something new.

What changed

- review = await review.resume("Re-check against the fixes.", { schema: Findings })
+ review = await review.ask("Re-check against the fixes.", { schema: Findings })

ask is identical in behaviour: still sugar over agent(prompt, { session, keepSession: true }), still refuses
session/keepSession/receipts, still sequential per session, still per-turn usage and toolCalls.

Also renamed in the places people learn it from: README ("Continuing a Unit"), the dynamic-workflows skill,
docs/examples/review-loop.ts, the type-level tests, and the failure message (ask: Unit … never had a session).
The JSDoc on UnitHandle.ask now says why ask and not resume, so the decision is not re-litigated later.

Breaking change

UnitHandle.resume() → UnitHandle.ask(). The feature merged in #34 but has not shipped in a release (0.6.3 is
still current), so no published version is affected; for a Workflow written against main, rename
handle.resume( to handle.ask(.

Verification

  • bun run check — 427 tests, format/lint/types green
  • sync-readme run (the npm README copy matches)
  • No handle.resume left anywhere: checked src, test, docs/examples, README and the skill. The remaining
    "resume" occurrences all refer to a Run (resumeRun, replay on resume), which is the point of the rename.

`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.
@syn7xx
syn7xx merged commit 07fe9e7 into main Nov 17, 2026
7 of 8 checks passed
@syn7xx
syn7xx deleted the feat/handle-ask branch November 17, 2026 16:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant