diff --git a/.changeset/user-suspension-reasons.md b/.changeset/user-suspension-reasons.md new file mode 100644 index 0000000000..2daad28a22 --- /dev/null +++ b/.changeset/user-suspension-reasons.md @@ -0,0 +1,9 @@ +--- +"@flow-state-dev/contracts": minor +"@flow-state-dev/core": minor +"@flow-state-dev/engine": minor +"@flow-state-dev/client": minor +"@flow-state-dev/react": minor +--- + +The suspension reasons that wait for a user are now `"user_approval"` and `"user_input"`, renamed from `"human_approval"` and `"human_input"`. Nothing reads the old values: `SuspensionReason` still accepts any string, so a `ctx.suspend` or a `useSuspensions({ reasons })` filter that still passes an old value compiles but is treated as a custom reason: it is not a user's stop, gets no Inbox item, and an old `"human_input"` stop defaults to approve/reject instead of submit. Search your code for both old strings and replace them. Stored suspensions with the old reasons are not migrated (FIX-2151). diff --git a/.changeset/wait-for-user.md b/.changeset/wait-for-user.md index 5984c4a834..7cccf90af4 100644 --- a/.changeset/wait-for-user.md +++ b/.changeset/wait-for-user.md @@ -22,7 +22,7 @@ A stop that waits for a user holds its task and ends exactly once (FIX-2129). **Migration:** - `TaskWaitingOn` reads `"user"` where it read `"person"`. Stored rows are not migrated. -- A raw `ctx.suspend` with `human_approval` or `human_input` now gets the same mark, cancel and stop as `waitForUser`. A raw `human_input` stop past its `timeoutMs` now resumes its block with `SuspensionTimeoutError` instead of staying parked, and a cancelled one throws `SuspensionRejectedError` with `cancelled: true`. +- A raw `ctx.suspend` with `user_approval` or `user_input` now gets the same mark, cancel and stop as `waitForUser`. A raw `user_input` stop past its `timeoutMs` now resumes its block with `SuspensionTimeoutError` instead of staying parked, and a cancelled one throws `SuspensionRejectedError` with `cancelled: true`. - `isExpiredApproval` is now `continuesAtExpiry`, which also covers a user's review and input. - A filing by a cancelled task is refused (`TaskFilingRefusedError`, rule `parent_cancelled`), and a piece filed on a task session's board under a cancelled task is refused before it is added, so it is never claimable. - Shift Manager answers every ask through the answer route; `REOPENED_SOURCES` and `DISPATCHED_RUN_UNANSWERABLE` are gone. diff --git a/apps/docs/docs/advanced/block-memoization-and-replay.md b/apps/docs/docs/advanced/block-memoization-and-replay.md index 49090d5744..4c5cbd90ec 100644 --- a/apps/docs/docs/advanced/block-memoization-and-replay.md +++ b/apps/docs/docs/advanced/block-memoization-and-replay.md @@ -31,7 +31,7 @@ const notifyAndWait = handler({ execute: async (input, ctx) => { await sendEmail(input.email, `Please review: ${input.draft}`); const decision = await ctx.suspend!({ - reason: "human_approval", + reason: "user_approval", message: "Awaiting review", }); return decision as { approved: boolean }; @@ -57,7 +57,7 @@ const notifyAndWait = handler({ await sendEmail(input.email, `Please review: ${input.draft}`); }); const decision = await ctx.suspend!({ - reason: "human_approval", + reason: "user_approval", message: "Awaiting review", }); return decision as { approved: boolean }; diff --git a/apps/docs/docs/advanced/durable-execution.md b/apps/docs/docs/advanced/durable-execution.md index 0fd3038c3f..bdcc06f08a 100644 --- a/apps/docs/docs/advanced/durable-execution.md +++ b/apps/docs/docs/advanced/durable-execution.md @@ -85,7 +85,7 @@ const reviewStep = handler({ outputSchema: z.object({ approved: z.boolean(), feedback: z.nullable(z.string()) }), execute: async (input, ctx) => { const decision = await ctx.suspend!({ - reason: "human_approval", + reason: "user_approval", message: `Review content: "${input.content.slice(0, 50)}..."`, resumeSchema: { type: "object", @@ -135,14 +135,14 @@ On the React side, `useSuspensions(session)` derives pending and resolved suspen | Field | Type | Description | |---|---|---| -| `reason` | `"human_approval" \| "human_input" \| "external_event" \| string` | Machine-readable category for the suspension | +| `reason` | `"user_approval" \| "user_input" \| "external_event" \| string` | Machine-readable category for the suspension | | `title` | `string` | Optional short heading for the suspension, a few words. A UI that lists or heads pending suspensions can show this and put `message` underneath as the body. Leave it out when `message` is already one short line | | `message` | `string` | Human-readable description, emitted in the `SuspensionItem`. With a `title`, it's the body and may be markdown | | `data` | `Record` | Arbitrary metadata attached to the suspension record | | `resumeSchema` | `Record` | JSON Schema describing the expected resume payload shape | | `timeoutMs` | `number` | Optional expiry. Once this duration passes unanswered, the sweeper marks the suspension `expired`. If the suspension allows `reject` (an approval), the request then carries on as if it had been rejected: see [Retention and cleanup](#retention-and-cleanup). | | `render` | `{ component: string; props?: Record }` | Hint for client-side rendering of the approval UI | -| `allow` | `ResumeAction[]` | Which resolution actions this suspension permits. Omit to take the reason-based default: `human_input` → `["submit"]`; everything else (including `human_approval`) → `["approve", "reject"]`. Add `"skip"` to make the step optional. The resume route returns `409` for an action outside this set. | +| `allow` | `ResumeAction[]` | Which resolution actions this suspension permits. Omit to take the reason-based default: `user_input` → `["submit"]`; everything else (including `user_approval`) → `["approve", "reject"]`. Add `"skip"` to make the step optional. The resume route returns `409` for an action outside this set. | ## Resuming a suspended request @@ -195,7 +195,7 @@ Sequence numbers stay monotonic across the whole thing. An item-log sequence for ```jsonc { "seq": 1, "type": "message", "text": "Drafted the summary." } -{ "seq": 2, "type": "suspension", "suspensionId": "susp_abc123", "reason": "human_approval" } +{ "seq": 2, "type": "suspension", "suspensionId": "susp_abc123", "reason": "user_approval" } // --- request pauses here, SSE stream closes, status = "suspended" --- // --- resume endpoint called; status walks suspended → in_progress --- { "seq": 3, "type": "suspension_resume", "suspensionId": "susp_abc123", "resolution": "approved", "resolvedBy": "user_xyz" } @@ -237,7 +237,7 @@ On resume, `ctx.suspend()` returns the resolver's payload (`data`) for `approve` import { SUSPENSION_SKIPPED } from "@flow-state-dev/core"; const answer = await ctx.suspend!({ - reason: "human_input", + reason: "user_input", message: "Add a reviewer note? (optional)", resumeSchema: z.object({ note: z.string() }), allow: ["submit", "skip"], diff --git a/apps/docs/docs/advanced/generator-and-router-suspend-resume.md b/apps/docs/docs/advanced/generator-and-router-suspend-resume.md index d6bb754884..1a30fb06d7 100644 --- a/apps/docs/docs/advanced/generator-and-router-suspend-resume.md +++ b/apps/docs/docs/advanced/generator-and-router-suspend-resume.md @@ -28,7 +28,7 @@ const publishPost = handler({ // Suspend BEFORE the side effect. On resume this call returns the // human's typed payload; on rejection it throws instead of returning. const decision = await ctx.suspend!({ - reason: "human_approval", + reason: "user_approval", message: `Publish "${input.title}"?`, resumeSchema: z.object({ note: z.string().nullable() }), }); diff --git a/apps/docs/docs/api/cli.md b/apps/docs/docs/api/cli.md index 4ca0bba1ef..9b8041e386 100644 --- a/apps/docs/docs/api/cli.md +++ b/apps/docs/docs/api/cli.md @@ -55,7 +55,7 @@ Each line of stdout is a JSON object with a `type` field: A run that ends waiting for a person ends with a `suspended` event instead of `flow_complete`: ```jsonl -{"type":"suspended","requestId":"req_...","sessionId":"sess_...","suspensionId":"susp_...","reason":"human_approval","message":"Publish \"Q3 notes\"?","answer":"Answer it in fsdev dev, which reads this store: .fsdev/data/fsdev.db (SQLite)."} +{"type":"suspended","requestId":"req_...","sessionId":"sess_...","suspensionId":"susp_...","reason":"user_approval","message":"Publish \"Q3 notes\"?","answer":"Answer it in fsdev dev, which reads this store: .fsdev/data/fsdev.db (SQLite)."} ``` | Event type | When it fires | diff --git a/apps/docs/docs/api/client.md b/apps/docs/docs/api/client.md index d733232a93..92208f8afd 100644 --- a/apps/docs/docs/api/client.md +++ b/apps/docs/docs/api/client.md @@ -144,7 +144,7 @@ The React layer (`useSession().resumeSuspension`, `useSuspensions`) wires this u ### `answer(body)` -An [Inbox](/docs/orchestration/task-board#building-an-inbox) answers a stop that waits for a user (a `ctx.waitForUser`, or a `human_approval` / `human_input` suspension) with `answer`. Unlike `resume`, it works on any run, including one a task board started, because it takes only where the stop is and the answer: +An [Inbox](/docs/orchestration/task-board#building-an-inbox) answers a stop that waits for a user (a `ctx.waitForUser`, or a `user_approval` / `user_input` suspension) with `answer`. Unlike `resume`, it works on any run, including one a task board started, because it takes only where the stop is and the answer: ```ts await fsd.flow(flowId).request(item.requestId).answer({ diff --git a/apps/docs/docs/api/react.md b/apps/docs/docs/api/react.md index 307a5afabb..931e6d14eb 100644 --- a/apps/docs/docs/api/react.md +++ b/apps/docs/docs/api/react.md @@ -272,7 +272,7 @@ const { error, // Error | null — most recent failed resolve call } = useSuspensions(session, { requestId: "req_abc", // optional: restrict to one request - reasons: ["human_approval"], // optional: restrict by reason + reasons: ["user_approval"], // optional: restrict by reason }); ``` @@ -350,13 +350,13 @@ When the schema is richer than a flat object of scalars/enums (nested objects, a ### `QuestionRenderer`, `SelectionRenderer`, `SchemaFormRenderer` -The default cards for `human_input` suspensions, all thin views over `useSuspensionForm`: +The default cards for `user_input` suspensions, all thin views over `useSuspensionForm`: - `QuestionRenderer` — a free-text answer (no flat schema). - `SelectionRenderer` — single choice (a `z.enum`) or multi (`z.array(z.enum)`). - `SchemaFormRenderer` — a flat object of scalars and enums, one control per property. -`ItemRenderer` auto-picks one for a `suspension` item with `reason: "human_input"` by `render.component` hint → reason → `resumeSchema` shape. A registered `renderers.suspension` overrides this, and `renderers.suspension: false` suppresses inline cards. `human_approval` suspensions still get `ApprovalRenderer`. +`ItemRenderer` auto-picks one for a `suspension` item with `reason: "user_input"` by `render.component` hint → reason → `resumeSchema` shape. A registered `renderers.suspension` overrides this, and `renderers.suspension: false` suppresses inline cards. `user_approval` suspensions still get `ApprovalRenderer`. ```tsx import { QuestionRenderer, SelectionRenderer, SchemaFormRenderer } from "@flow-state-dev/react"; diff --git a/apps/docs/docs/client/react.md b/apps/docs/docs/client/react.md index e029664967..c0152aa8c2 100644 --- a/apps/docs/docs/client/react.md +++ b/apps/docs/docs/client/react.md @@ -427,7 +427,7 @@ Filter to a specific reason or request: ```tsx const { pending } = useSuspensions(session, { - reasons: ["human_approval"], + reasons: ["user_approval"], requestId: "req_abc", }); ``` @@ -464,12 +464,12 @@ A suspension doesn't have to be a yes/no gate. The same pause-and-resume machine Which card renders is decided by the suspension's `reason` and the shape of its `resumeSchema`: -- `reason: "human_approval"` renders the Approve / Reject card. -- `reason: "human_input"` picks by schema shape: a free-text **question** when there's no flat schema, a **selection** when the schema is a single enum (or array of enums), and a **form** when it's a flat object of scalars and enums. +- `reason: "user_approval"` renders the Approve / Reject card. +- `reason: "user_input"` picks by schema shape: a free-text **question** when there's no flat schema, a **selection** when the schema is a single enum (or array of enums), and a **form** when it's a flat object of scalars and enums. -`` makes that choice automatically, so a `human_input` suspension renders an actionable card with no extra wiring. A registered `renderers.suspension` still wins, and `renderers.suspension: false` still suppresses inline cards. +`` makes that choice automatically, so a `user_input` suspension renders an actionable card with no extra wiring. A registered `renderers.suspension` still wins, and `renderers.suspension: false` still suppresses inline cards. -On the server, a `human_input` gate defaults to `allow: ["submit"]`. Add `"skip"` to make the step optional. When a human skips, `ctx.suspend()` returns the `SUSPENSION_SKIPPED` sentinel instead of throwing, so the flow author branches on it and falls back to a default. +On the server, a `user_input` gate defaults to `allow: ["submit"]`. Add `"skip"` to make the step optional. When a human skips, `ctx.suspend()` returns the `SUSPENSION_SKIPPED` sentinel instead of throwing, so the flow author branches on it and falls back to a default. ```ts import { handler, SUSPENSION_SKIPPED } from "@flow-state-dev/core"; @@ -481,7 +481,7 @@ const clarify = handler({ outputSchema: z.object({ priority: z.string() }), execute: async (input, ctx) => { const answer = await ctx.suspend!({ - reason: "human_input", + reason: "user_input", message: "How should we triage this draft?", resumeSchema: z.object({ priority: z.enum(["low", "normal", "urgent"]), @@ -496,7 +496,7 @@ const clarify = handler({ ``` ```tsx -// Client: ItemsRenderer auto-picks the form card for this human_input gate. +// Client: ItemsRenderer auto-picks the form card for this user_input gate. diff --git a/apps/docs/docs/orchestration/task-board.md b/apps/docs/docs/orchestration/task-board.md index 8d1be7d520..50395b36c7 100644 --- a/apps/docs/docs/orchestration/task-board.md +++ b/apps/docs/docs/orchestration/task-board.md @@ -818,7 +818,7 @@ Until then the task stays `in_progress`, and its row's `keptOpenBy` says what it | `"filed"` | tasks it filed that haven't ended, or whose ending the run's session hasn't heard yet | none | | `"wait"` | a stop: `ctx.waitForUser()`, `ctx.suspend()`, or an external event | none | -A stop that waits for a user (`ctx.waitForUser()`, or `ctx.suspend()` with `human_approval` or `human_input`) is also listed in the task's `questions`. +A stop that waits for a user (`ctx.waitForUser()`, or `ctx.suspend()` with `user_approval` or `user_input`) is also listed in the task's `questions`. A task with no lease stays with its run. It isn't handed out again however long the wait lasts, including across a server restart. diff --git a/apps/docs/docs/streaming/items.md b/apps/docs/docs/streaming/items.md index dcaff9c67c..7202ba1579 100644 --- a/apps/docs/docs/streaming/items.md +++ b/apps/docs/docs/streaming/items.md @@ -235,7 +235,7 @@ The `suspension` item carries an `allow: ResumeAction[]` field (`"approve" | "re A log fragment across one cycle: ```jsonc -{ "type": "suspension", "suspensionId": "susp_abc123", "reason": "human_input", "allow": ["submit", "skip"] } +{ "type": "suspension", "suspensionId": "susp_abc123", "reason": "user_input", "allow": ["submit", "skip"] } { "type": "suspension_resume", "suspensionId": "susp_abc123", "resolution": "submitted", "resolvedBy": "user_xyz" } ``` diff --git a/apps/docs/docs/workforce/shift-coordinator.md b/apps/docs/docs/workforce/shift-coordinator.md index df9a739f56..fd46137c00 100644 --- a/apps/docs/docs/workforce/shift-coordinator.md +++ b/apps/docs/docs/workforce/shift-coordinator.md @@ -88,7 +88,7 @@ import { coderFlow } from "./flows/coder"; import { emFlow } from "./flows/em"; import { roster } from "./roster"; -/** A fire waits for the user: a `human_approval` naming the worker. On Deny, nothing changes. */ +/** A fire waits for the user: a `user_approval` naming the worker. On Deny, nothing changes. */ const askFire = handler({ name: "ask-fire", inputSchema: z.object({ id: z.string() }).passthrough(), @@ -97,7 +97,7 @@ const askFire = handler({ if (ctx.suspend === undefined) { throw new Error(`firing "${input.id}" waits for a user's approval, and this app can't ask for one. Nothing was changed.`); } - await ctx.suspend({ reason: "human_approval", message: `Fire worker "${input.id}"?`, data: { worker: input.id }, allow: ["approve", "reject"] }); + await ctx.suspend({ reason: "user_approval", message: `Fire worker "${input.id}"?`, data: { worker: input.id }, allow: ["approve", "reject"] }); }, }); @@ -292,11 +292,11 @@ The roster tools work on the user's own workers. Another user's workers are thei ## What asks first -A fire wrapped as above pauses the request with a `human_approval` suspension before anything changes: +A fire wrapped as above pauses the request with a `user_approval` suspension before anything changes: ```json { - "reason": "human_approval", + "reason": "user_approval", "message": "Fire worker \"scribe\"?", "data": { "worker": "scribe" }, "allow": ["approve", "reject"] diff --git a/apps/docs/guides/human-in-the-loop.md b/apps/docs/guides/human-in-the-loop.md index 9bdaa66a8b..5e326fca32 100644 --- a/apps/docs/guides/human-in-the-loop.md +++ b/apps/docs/guides/human-in-the-loop.md @@ -17,7 +17,7 @@ If what you're gating is a task on a board rather than one step of a flow, the s - **The work can go on from the answer later.** A question: the worker's model calls `askQuestion`, or its code calls `askMidway`. The task waits on the question, the turn ends, and the answer starts the task's next turn. - **You need a form.** `ctx.suspend()` with your own schema, as this guide builds. -The first two show in the user's [Inbox](/docs/orchestration/task-board#building-an-inbox), and so does a `ctx.suspend()` whose reason is `human_approval` or `human_input`; one with a reason of your own doesn't. See [A task waiting on a user](/docs/orchestration/task-board#a-task-waiting-on-a-user) and [A task's questions](/docs/orchestration/task-board#a-tasks-questions). +The first two show in the user's [Inbox](/docs/orchestration/task-board#building-an-inbox), and so does a `ctx.suspend()` whose reason is `user_approval` or `user_input`; one with a reason of your own doesn't. See [A task waiting on a user](/docs/orchestration/task-board#a-task-waiting-on-a-user) and [A task's questions](/docs/orchestration/task-board#a-tasks-questions). ## How a pause works @@ -66,7 +66,7 @@ const reviewGate = handler({ }), execute: async (input, ctx) => { const decision = await ctx.suspend!({ - reason: "human_approval", + reason: "user_approval", message: `Review before publishing: "${input.content.slice(0, 80)}…"`, resumeSchema: { type: "object", @@ -188,13 +188,13 @@ If you're not using `@flow-state-dev/ui`, the `@flow-state-dev/react` package sh Approve / reject is the simplest gate, but a pause can ask for more than a yes/no. The same suspend/resume cycle handles a free-text answer, a small form, or a choice from a fixed set. Two resolution actions drive this: `submit` (the human returns a typed payload) and `skip` (the human declines an optional step). -The server decides what a gate asks for through its `reason` and `resumeSchema`. Use `reason: "human_input"` for an input gate; it defaults to `allow: ["submit"]`. On the client, `ItemsRenderer` reads the schema shape and renders the matching card. The renderer picks a free-text question for no flat schema, a selection for an enum, and a form for a flat object — automatically, with the same wiring as the approval example above. +The server decides what a gate asks for through its `reason` and `resumeSchema`. Use `reason: "user_input"` for an input gate; it defaults to `allow: ["submit"]`. On the client, `ItemsRenderer` reads the schema shape and renders the matching card. The renderer picks a free-text question for no flat schema, a selection for an enum, and a form for a flat object — automatically, with the same wiring as the approval example above. ### A question (free text) ```ts const askName = await ctx.suspend!({ - reason: "human_input", + reason: "user_input", message: "What should we title this draft?", resumeSchema: z.object({ title: z.string() }), }); @@ -208,7 +208,7 @@ A flat object of scalars and enums renders as one combined form, one control per ```ts const details = await ctx.suspend!({ - reason: "human_input", + reason: "user_input", message: "Add publishing details.", resumeSchema: z.object({ clarification: z @@ -234,7 +234,7 @@ A single enum renders as a single-choice control; an array of enums renders as m ```ts const pick = await ctx.suspend!({ - reason: "human_input", + reason: "user_input", message: "Which channels should this post to?", resumeSchema: z.object({ channels: z.array(z.enum(["blog", "email", "social"])), @@ -250,7 +250,7 @@ Add `"skip"` to `allow` to let a human decline a step. A skip is normal control import { SUSPENSION_SKIPPED } from "@flow-state-dev/core"; const answer = await ctx.suspend!({ - reason: "human_input", + reason: "user_input", message: "Add a reviewer note? (optional)", resumeSchema: z.object({ note: z.string() }), allow: ["submit", "skip"], @@ -281,7 +281,7 @@ const publishPost = handler({ // Pause before publishing. On resume this returns the human's payload; // on reject it throws, and the model sees a denial result. const decision = await ctx.suspend!({ - reason: "human_approval", + reason: "user_approval", message: `Publish "${input.title}"?`, resumeSchema: z.object({ note: z.string().nullable() }), }); @@ -373,7 +373,7 @@ import { useSuspensions } from "@flow-state-dev/react"; function ReviewQueue({ session }) { const { pending, approve, reject } = useSuspensions(session, { - reasons: ["human_approval"], + reasons: ["user_approval"], }); return ( diff --git a/apps/kitchen-sink/components/flow-state/suspension-card.tsx b/apps/kitchen-sink/components/flow-state/suspension-card.tsx index 7b39b359d1..5b8aa13075 100644 --- a/apps/kitchen-sink/components/flow-state/suspension-card.tsx +++ b/apps/kitchen-sink/components/flow-state/suspension-card.tsx @@ -22,8 +22,8 @@ import { useSuspensionResolution } from "./suspension-resolution"; * author-supplied component (for schemas richer than the bounded defaults) * before any shape dispatch. * - * `human_approval` keeps the existing `Approval` card (which derives its own - * resolved state). For `human_input`, this derives resolved state once from the + * `user_approval` keeps the existing `Approval` card (which derives its own + * resolved state). For `user_input`, this derives resolved state once from the * session stream and passes it to the chosen non-binary card. */ export function SuspensionCard({ item }: { item: SuspensionItem }) { diff --git a/apps/kitchen-sink/flows/chat-agent/approval-gate.ts b/apps/kitchen-sink/flows/chat-agent/approval-gate.ts index 7006aebb70..a9fcce2485 100644 --- a/apps/kitchen-sink/flows/chat-agent/approval-gate.ts +++ b/apps/kitchen-sink/flows/chat-agent/approval-gate.ts @@ -87,7 +87,7 @@ const approvalGateStep = handler({ try { ctx.emit.message(`Approval ${input.approvalId} requested: "${input.request}"`); const data = (await ctx.suspend!({ - reason: "human_approval", + reason: "user_approval", message: `Approve action: "${input.request}"?`, resumeSchema: approvalResumeSchema, })) as z.infer | undefined; diff --git a/apps/kitchen-sink/flows/chat-agent/human-input.ts b/apps/kitchen-sink/flows/chat-agent/human-input.ts index 68dad651ec..3d4d8c6e3d 100644 --- a/apps/kitchen-sink/flows/chat-agent/human-input.ts +++ b/apps/kitchen-sink/flows/chat-agent/human-input.ts @@ -35,9 +35,9 @@ const askQuestionStep = handler({ // The `message` IS the question — it renders once as the card heading. Don't // emit a separate "we're about to ask…" line or wrap the question in a // meta-question; that just restates it. A single-string resumeSchema renders - // a free-text box; the default `allow` for `human_input` is `["submit"]`. + // a free-text box; the default `allow` for `user_input` is `["submit"]`. const answer = (await ctx.suspend!({ - reason: "human_input", + reason: "user_input", message: input.question, resumeSchema: z.string().min(1), })) as string; @@ -88,7 +88,7 @@ const collectFormStep = handler({ // `ctx.suspend()` returns the SUSPENSION_SKIPPED sentinel instead of a // payload, so the run continues with a default rather than aborting. const result = await ctx.suspend!({ - reason: "human_input", + reason: "user_input", message: `Share feedback on "${input.subject}" (optional)`, resumeSchema: feedbackSchema, allow: ["submit", "skip"], @@ -123,7 +123,7 @@ const chooseOptionStep = handler({ execute: async (input, ctx) => { // A top-level enum renders as a single-choice selection card. const choice = (await ctx.suspend!({ - reason: "human_input", + reason: "user_input", message: input.question, resumeSchema: z.enum(["yes", "no", "not sure"]), })) as string; diff --git a/docs/architecture/execution-and-errors.md b/docs/architecture/execution-and-errors.md index 6d3ee389b1..05c74a8c7a 100644 --- a/docs/architecture/execution-and-errors.md +++ b/docs/architecture/execution-and-errors.md @@ -451,7 +451,7 @@ Completed blocks are not re-executed. The runtime replays each one's recorded `b #### Waiting for a user -`ctx.waitForUser({ kind, prompt, deadline? })` is `ctx.suspend` with a kind (`approval`, `review`, `input`, recorded on the suspension beside the `human_approval` / `human_input` reason it maps to), a deadline, and a cancel (FIX-2129). One predicate, `isUserSuspension` in `contracts`, says whether a suspension waits for a user; a raw `ctx.suspend` with either reason is one too. Every way such a stop ends resolves its single pending state under the request's lease, so the first wins and the rest are told `already-resolved`: +`ctx.waitForUser({ kind, prompt, deadline? })` is `ctx.suspend` with a kind (`approval`, `review`, `input`, recorded on the suspension beside the `user_approval` / `user_input` reason it maps to), a deadline, and a cancel (FIX-2129). One predicate, `isUserSuspension` in `contracts`, says whether a suspension waits for a user; a raw `ctx.suspend` with either reason is one too. Every way such a stop ends resolves its single pending state under the request's lease, so the first wins and the rest are told `already-resolved`: - **Answered** through the answer route (`POST /:flowKind/requests/:requestId/answer`, `routes/answer-routes.ts`). Unlike resume, it is open to every source, `task` included, because the caller sends only where the stop is and the answer. It runs resume's ownership checks (`ownsRecord`, `callerReachesRequest`) on the stop's request before it reads the stop, answers a stop that isn't the caller's, or isn't a user's, as a missing one, checks the answer against the stop's `allow` and `resumeSchema`, and records the signed-in caller as `resolvedBy`. - **Its deadline**: the call's `deadline`, else the host's `userDeadlineMs` (`RequestHost.userDeadlineMs`), else none; a raw `ctx.suspend` keeps its own `timeoutMs`. The sweeper expires it and re-drives the request: an approval reads as a no, a review or an input throws `SuspensionTimeoutError`. A stop with no deadline is never expired. diff --git a/docs/architecture/items.md b/docs/architecture/items.md index 5217aff709..ad5ff1e590 100644 --- a/docs/architecture/items.md +++ b/docs/architecture/items.md @@ -214,7 +214,7 @@ One shared algorithm in `@flow-state-dev/core/items` (`attributeItemsToTasks` / `suspension` items are consumer-renderable. The `suspension` item carries an `allow: ResumeAction[]` field (`"approve" | "reject" | "submit" | "skip"`) recording which resolutions the gate permits — the resume route gates inbound actions against it (`409` otherwise), and renderers read it to decide which controls to show (e.g. a Skip button appears iff `"skip"` is present). `resolution` on the `suspension_resume` item, and the resolved status more broadly, now includes `submitted` and `skipped` alongside `approved` / `rejected` / `timed_out` / `expired`. -`ItemRenderer` dispatches `type === "suspension"` items to a built-in default by `render.component` hint → `reason` → `resumeSchema` shape: a registered `render.component` wins; otherwise `human_approval` → `ApprovalRenderer` (Approve / Reject), and `human_input` → a free-text question, an enum selection, or a flat-object form depending on the schema. Register a custom component under the `suspension` slot of `RendererRegistry` to replace the default entirely, or set `suspension: false` to suppress it (headless layouts use `useSuspensions` and render the resolution UI in a modal or sidebar instead). +`ItemRenderer` dispatches `type === "suspension"` items to a built-in default by `render.component` hint → `reason` → `resumeSchema` shape: a registered `render.component` wins; otherwise `user_approval` → `ApprovalRenderer` (Approve / Reject), and `user_input` → a free-text question, an enum selection, or a flat-object form depending on the schema. Register a custom component under the `suspension` slot of `RendererRegistry` to replace the default entirely, or set `suspension: false` to suppress it (headless layouts use `useSuspensions` and render the resolution UI in a modal or sidebar instead). `suspension_resume` items are not rendered. They carry the audit record of a resolved suspension and are used by `useSuspensions` to flip a suspension from `pending` to resolved. Apps derive resume state from the item log, not from the `suspension` item's `suspensionStatus` field. diff --git a/docs/atlas/conductor.html b/docs/atlas/conductor.html index 6811cff0a3..8ba275de8a 100644 --- a/docs/atlas/conductor.html +++ b/docs/atlas/conductor.html @@ -793,7 +793,7 @@
Runs
bounded, disposable

Where a gate lives

-

ctx.suspend(options) durably pauses a flow pending external human action: request status becomes "suspended", a SuspensionRecord persists the whole context (suspensionId, requestId, flowKind, actionName, sessionId, userId, reason, message, data, resumeSchema, render, allow, status, blockInstanceId, stepIndex), and an HTTP resume route re-enters the action with completed steps replayed from the durable log rather than re-executed. reason: "human_approval" defaults allow to ["approve","reject"]; "human_input" to ["submit"]. It needs durable: true on the action and on the runtime. Four working shapes live in apps/kitchen-sink/flows/chat-agent/: requestApproval, askQuestion, collectForm, chooseOption.

+

ctx.suspend(options) durably pauses a flow pending external human action: request status becomes "suspended", a SuspensionRecord persists the whole context (suspensionId, requestId, flowKind, actionName, sessionId, userId, reason, message, data, resumeSchema, render, allow, status, blockInstanceId, stepIndex), and an HTTP resume route re-enters the action with completed steps replayed from the durable log rather than re-executed. reason: "user_approval" defaults allow to ["approve","reject"]; "user_input" to ["submit"]. It needs durable: true on the action and on the runtime. Four working shapes live in apps/kitchen-sink/flows/chat-agent/: requestApproval, askQuestion, collectForm, chooseOption.

All of that belongs to the main session, and it stays exactly as described. It is not the mechanism for anything a spawned run is involved in — and today nothing stops one reaching for it anyway. A run that calls ctx.suspend gets a suspension: its request parks, the row reads as a job still going, and nobody upstream is told. A fence making the call an error inside a run was filed as FIX-1247 and has since been cancelled. cancelled It is not built, and nothing on the tracker will build it.

diff --git a/goals/client/does-every-job-with-one-client/fixtures/flows.mts b/goals/client/does-every-job-with-one-client/fixtures/flows.mts index ac9ff2b4f0..c623d64d25 100644 --- a/goals/client/does-every-job-with-one-client/fixtures/flows.mts +++ b/goals/client/does-every-job-with-one-client/fixtures/flows.mts @@ -58,11 +58,11 @@ const gate = handler({ outputSchema: z.object({ answer: z.string() }), execute: async (input, ctx) => { if (input.kind === "approval") { - await ctx.suspend!({ reason: "human_approval", message: `Approve "${input.subject}"?` }); + await ctx.suspend!({ reason: "user_approval", message: `Approve "${input.subject}"?` }); return { answer: "approved" }; } const answer = (await ctx.suspend!({ - reason: "human_input", + reason: "user_input", message: `What should "${input.subject}" say?`, resumeSchema: z.string().min(1), })) as string; diff --git a/goals/continue-interrupted-run/continues-not-restarts/run.mts b/goals/continue-interrupted-run/continues-not-restarts/run.mts index 759d5a8728..99464c3e57 100644 --- a/goals/continue-interrupted-run/continues-not-restarts/run.mts +++ b/goals/continue-interrupted-run/continues-not-restarts/run.mts @@ -90,7 +90,7 @@ await runGoal(async (failures) => { inputSchema: z.any(), outputSchema: z.unknown(), execute: async (_i: unknown, ctx: { suspend?: (payload: unknown) => unknown }) => - ctx.suspend!({ reason: "human_approval", message: "Approve?" }), + ctx.suspend!({ reason: "user_approval", message: "Approve?" }), }); const finish = handler({ diff --git a/goals/continue-interrupted-run/two-interrupted-requests-continue-independently/run.mts b/goals/continue-interrupted-run/two-interrupted-requests-continue-independently/run.mts index f46d1339db..f84d270a88 100644 --- a/goals/continue-interrupted-run/two-interrupted-requests-continue-independently/run.mts +++ b/goals/continue-interrupted-run/two-interrupted-requests-continue-independently/run.mts @@ -56,7 +56,7 @@ function buildFlow(kind: string, counter: { runs: number }): FlowInstance { inputSchema: z.any(), outputSchema: z.unknown(), execute: async (_i: unknown, ctx: { suspend?: (payload: unknown) => unknown }) => - ctx.suspend!({ reason: "human_approval", message: "Approve?" }), + ctx.suspend!({ reason: "user_approval", message: "Approve?" }), }); return defineFlow({ kind, diff --git a/goals/design-system/skins-reused-components-from-one-token-set/host/fixtures.ts b/goals/design-system/skins-reused-components-from-one-token-set/host/fixtures.ts index 1ab33207b8..80de8d2b0d 100644 --- a/goals/design-system/skins-reused-components-from-one-token-set/host/fixtures.ts +++ b/goals/design-system/skins-reused-components-from-one-token-set/host/fixtures.ts @@ -89,7 +89,7 @@ export function container(component: string, requestId: string, blockInstanceId: export function suspension(options: { suspensionId: string; message: string; - reason?: "human_approval" | "human_input"; + reason?: "user_approval" | "user_input"; resumeSchema?: Record; allow?: string[]; }): SuspensionItem { @@ -98,7 +98,7 @@ export function suspension(options: { type: "suspension", suspensionId: options.suspensionId, suspensionStatus: "pending", - reason: options.reason ?? "human_approval", + reason: options.reason ?? "user_approval", message: options.message, ...(options.resumeSchema ? { resumeSchema: options.resumeSchema } : {}), ...(options.allow ? { allow: options.allow } : {}), diff --git a/goals/design-system/skins-reused-components-from-one-token-set/host/main.tsx b/goals/design-system/skins-reused-components-from-one-token-set/host/main.tsx index 26440d7afb..79dd261af3 100644 --- a/goals/design-system/skins-reused-components-from-one-token-set/host/main.tsx +++ b/goals/design-system/skins-reused-components-from-one-token-set/host/main.tsx @@ -59,7 +59,7 @@ const approvedItem = f.suspension({ suspensionId: "s-approved", message: "Refund const rejectedItem = f.suspension({ suspensionId: "s-rejected", message: "Delete the account?" }); const formItem = f.suspension({ suspensionId: "s-form", - reason: "human_input", + reason: "user_input", message: "Before we route this ticket:", resumeSchema: { type: "object", @@ -74,14 +74,14 @@ const formItem = f.suspension({ const formDoneItem = f.suspension({ ...formItem, suspensionId: "s-form-done" } as never); const questionItem = f.suspension({ suspensionId: "s-question", - reason: "human_input", + reason: "user_input", message: "What is the deadline?", resumeSchema: { type: "string", minLength: 1 }, allow: ["submit"], }); const questionDoneItem = f.suspension({ suspensionId: "s-question-done", - reason: "human_input", + reason: "user_input", message: "Which region?", resumeSchema: { type: "string", minLength: 1 }, allow: ["submit"], diff --git a/goals/devforce-lab/it-waits-for-a-person-before-it-files/goal.md b/goals/devforce-lab/it-waits-for-a-person-before-it-files/goal.md index 94d4833a91..99ec17377f 100644 --- a/goals/devforce-lab/it-waits-for-a-person-before-it-files/goal.md +++ b/goals/devforce-lab/it-waits-for-a-person-before-it-files/goal.md @@ -20,7 +20,7 @@ different valid feature still passes a correct implementation. lab code; the run is keyless *(AR-1, AR-7)*; 1. opened with the ask: the session listing, read as Inbox reads it (`GET /sessions?include=dispatch-runs` through the lab's door with its verified bearer), returns the EM seat's own session `s_eng_em`; - its requests hold exactly one pending `human_approval` naming both held-out strings and allowing + its requests hold exactly one pending `user_approval` naming both held-out strings and allowing approve and reject; the EM's file names the coder among its `delegates:`; the board holds **no row**; nothing dispatched; the coder not reached *(AR-2, AR-3, AR-4)*; 2. Approve, through `POST /eng.em/requests/:id/resume`: first a resume with no bearer (401) and one diff --git a/goals/devforce-lab/it-waits-for-a-person-before-it-files/run.mts b/goals/devforce-lab/it-waits-for-a-person-before-it-files/run.mts index 972b62c82f..e7efaae1fc 100644 --- a/goals/devforce-lab/it-waits-for-a-person-before-it-files/run.mts +++ b/goals/devforce-lab/it-waits-for-a-person-before-it-files/run.mts @@ -7,7 +7,7 @@ * pending approval in the EM seat's own session. Approve files the row and the * coder seat's run starts; Deny files nothing and the EM says so. * - * Model-free, and keyless: the ask is handlers and the stock `human_approval` + * Model-free, and keyless: the ask is handlers and the stock `user_approval` * suspension, and the coder runs the scripted stub. A miss here is a finding * about the lab or the shell, never about what a model chose to do. * @@ -276,7 +276,7 @@ await runGoal(async (failures) => { } ask = seen.pending[0]; if (ask !== undefined) { - if (ask.reason !== "human_approval") note("1", `the ask's reason is "${ask.reason}"`); + if (ask.reason !== "user_approval") note("1", `the ask's reason is "${ask.reason}"`); for (const token of [feature.issue, feature.goal]) { if (!ask.message.includes(token)) note("1", `the ask does not name "${token}": ${ask.message}`); } @@ -298,7 +298,7 @@ await runGoal(async (failures) => { await lab.dispose(); } evidence.push( - `opening with the ask left one pending human_approval in ${EM_SESSION}, listed as Inbox lists it and naming the feature, with no row and no dispatch`, + `opening with the ask left one pending user_approval in ${EM_SESSION}, listed as Inbox lists it and naming the feature, with no row and no dispatch`, ); } diff --git a/goals/devtool-workforce-visibility/reads-a-row-actions-result/fixtures/flow.mts b/goals/devtool-workforce-visibility/reads-a-row-actions-result/fixtures/flow.mts index b0ae728fe9..5aeaa12fb7 100644 --- a/goals/devtool-workforce-visibility/reads-a-row-actions-result/fixtures/flow.mts +++ b/goals/devtool-workforce-visibility/reads-a-row-actions-result/fixtures/flow.mts @@ -62,7 +62,7 @@ export function rowResultsFlow(answers: RowAnswers) { inputSchema: z.unknown(), execute: async (_input, ctx) => { const decision = (await ctx.suspend!({ - reason: "human_input", + reason: "user_input", message: "Answer this row", resumeSchema: { type: "object", properties: { answer: { type: "string" } } }, })) as { answer?: string } | undefined; diff --git a/goals/durable-by-default/a-local-stop-is-held-and-answered/fixtures/flows/review/flow.ts b/goals/durable-by-default/a-local-stop-is-held-and-answered/fixtures/flows/review/flow.ts index c7b3cf284f..06443bb97b 100644 --- a/goals/durable-by-default/a-local-stop-is-held-and-answered/fixtures/flows/review/flow.ts +++ b/goals/durable-by-default/a-local-stop-is-held-and-answered/fixtures/flows/review/flow.ts @@ -35,7 +35,7 @@ const approve = handler({ outputSchema: input, execute: async (value: Input, ctx) => { await ctx.suspend!({ - reason: "human_approval", + reason: "user_approval", message: `Publish "${value.title}"?`, ...(value.deadlineMs === undefined ? {} : { timeoutMs: value.deadlineMs }), }); @@ -49,7 +49,7 @@ const question = handler({ outputSchema: z.object({ title: z.string(), answer: z.string() }), execute: async (value: Input, ctx) => { const answer = (await ctx.suspend!({ - reason: "human_input", + reason: "user_input", message: `What should "${value.title}" say?`, resumeSchema: z.string().min(1), })) as string; diff --git a/goals/lib/shift-manager.mts b/goals/lib/shift-manager.mts index 5ddfaf5344..999cd29697 100644 --- a/goals/lib/shift-manager.mts +++ b/goals/lib/shift-manager.mts @@ -276,7 +276,7 @@ export async function pickShift(page: Page, shift: "day" | "evening" | "night"): } /** Suspension reasons that are a person being asked something. */ -const PERSON_REASONS = new Set(["human_approval", "human_input"]); +const PERSON_REASONS = new Set(["user_approval", "user_input"]); /** The worker a listed session runs, as its state names it (`workerId`), or `null` when it names none. */ export function workerOf(session: Readonly>): string | null { diff --git a/goals/oversized-output/stays-out-of-the-record/run.mts b/goals/oversized-output/stays-out-of-the-record/run.mts index 41ec54af0f..d31fa7f025 100644 --- a/goals/oversized-output/stays-out-of-the-record/run.mts +++ b/goals/oversized-output/stays-out-of-the-record/run.mts @@ -58,7 +58,7 @@ const approve = handler({ inputSchema: z.any(), outputSchema: z.any(), execute: async (input, ctx) => { - await ctx.suspend!({ reason: "human_approval", message: "Approve?" }); + await ctx.suspend!({ reason: "user_approval", message: "Approve?" }); return input; } }); diff --git a/goals/shift-manager/a-lab-is-worked-through-one-skinned-shell/parts.mts b/goals/shift-manager/a-lab-is-worked-through-one-skinned-shell/parts.mts index e3fdc1c0e3..72d6440402 100644 --- a/goals/shift-manager/a-lab-is-worked-through-one-skinned-shell/parts.mts +++ b/goals/shift-manager/a-lab-is-worked-through-one-skinned-shell/parts.mts @@ -85,7 +85,7 @@ import "./app/globals.css"; const ask = { id: "s1", type: "suspension", status: "completed", requestId: "r1", itemIndex: 0, ts: 0, provenance: { blockName: "gen", blockInstanceId: "b1", phase: "main" }, - suspensionId: "s1", suspensionStatus: "pending", reason: "human_approval", message: "Ship it?" } as never; + suspensionId: "s1", suspensionStatus: "pending", reason: "user_approval", message: "Ship it?" } as never; const failed = { id: "t1", type: "tool_output", status: "failed", requestId: "r1", itemIndex: 1, ts: 0, blockName: "deploy", provenance: { blockName: "gen", blockInstanceId: "b1", phase: "main" }, output: "exit 1", toolCall: { callId: "c1", name: "deploy", arguments: "{}", generatorBlock: "gen" } } as never; diff --git a/goals/shift-manager/it-draws-v2s-look/run.mts b/goals/shift-manager/it-draws-v2s-look/run.mts index 5ac8c1a8f9..57af8b78cd 100644 --- a/goals/shift-manager/it-draws-v2s-look/run.mts +++ b/goals/shift-manager/it-draws-v2s-look/run.mts @@ -647,7 +647,7 @@ function grade(read: Sweep, where: Where, tag: string, failures: Failures, lab: // ---- the store, read by this check ---------------------------------------------- /** Suspension reasons that are a person being asked something. */ -const PERSON_REASONS = new Set(["human_approval", "human_input"]); +const PERSON_REASONS = new Set(["user_approval", "user_input"]); async function readStore(api: LabApi, userId: string, boards: readonly string[] = []): Promise { const listing = await api.get(`/sessions?userId=${encodeURIComponent(userId)}&include=dispatch-runs&limit=500`); diff --git a/goals/shift-manager/it-draws-v2s-look/screens-inbox-tasks-roster.mts b/goals/shift-manager/it-draws-v2s-look/screens-inbox-tasks-roster.mts index b9a7d213b6..afd9f0cada 100644 --- a/goals/shift-manager/it-draws-v2s-look/screens-inbox-tasks-roster.mts +++ b/goals/shift-manager/it-draws-v2s-look/screens-inbox-tasks-roster.mts @@ -45,7 +45,7 @@ export type StoreScreens = { // ---- the store --------------------------------------------------------------------- /** Suspension reasons that are a person being asked something. */ -const PERSON_REASONS = new Set(["human_approval", "human_input"]); +const PERSON_REASONS = new Set(["user_approval", "user_input"]); const DONE = new Set(["completed", "cancelled"]); const RUNNING = "in_progress"; /** A row waiting on the person: running, held on a question no steer answers yet (FIX-2131; it was `parked`). */ @@ -59,12 +59,12 @@ const isQueued = (status: string) => !DONE.has(status) && status !== RUNNING && /** * The shape the registry's cards decide an approval by: anything but a - * `human_input` that takes a submission. Must match the approval branch of + * `user_input` that takes a submission. Must match the approval branch of * `suspensionShape` in `@flow-state-dev/react`; it is written out here because * that package's only entry loads React, which goals don't depend on. */ function workerFlowOf(item: Record): "approval" | "question" { - return item.reason !== "human_input" || !Array.isArray(item.allow) || !item.allow.includes("submit") ? "approval" : "question"; + return item.reason !== "user_input" || !Array.isArray(item.allow) || !item.allow.includes("submit") ? "approval" : "question"; } /** diff --git a/goals/shift-manager/it-opens-a-lab/run.mts b/goals/shift-manager/it-opens-a-lab/run.mts index 4f5978b8e5..e5a5bc189a 100644 --- a/goals/shift-manager/it-opens-a-lab/run.mts +++ b/goals/shift-manager/it-opens-a-lab/run.mts @@ -119,7 +119,7 @@ function emptyInbox(store: Store): string { return `Nothing needs you. ${n(running, "session is", "sessions are")} still running.`; } /** Suspension reasons that are a person being asked something. */ -const PERSON_REASONS = new Set(["human_approval", "human_input"]); +const PERSON_REASONS = new Set(["user_approval", "user_input"]); const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)); const sorted = (values: Iterable) => [...values].sort(); diff --git a/goals/shift-manager/it-sends-a-turn-into-a-seat-session/lab/asker/asker.mts b/goals/shift-manager/it-sends-a-turn-into-a-seat-session/lab/asker/asker.mts index 57d2f38539..44fe3d3149 100644 --- a/goals/shift-manager/it-sends-a-turn-into-a-seat-session/lab/asker/asker.mts +++ b/goals/shift-manager/it-sends-a-turn-into-a-seat-session/lab/asker/asker.mts @@ -2,7 +2,7 @@ * The goal's fixture seat kind: a seat that asks a person, and a door that * hears them. * - * - `ask`, durable: suspends on the framework's stock `human_approval`, so + * - `ask`, durable: suspends on the framework's stock `user_approval`, so * Inbox lists it. * - `message`, the door: a person's line into the seat's session. The engine * stores the line as a user item before the step runs; the step then says @@ -40,7 +40,7 @@ const gate = handler({ outputSchema: z.object({ what: z.string(), approved: z.boolean() }), execute: async (input, ctx) => { try { - await ctx.suspend!({ reason: "human_approval", message: `Approve: ${input.what}` }); + await ctx.suspend!({ reason: "user_approval", message: `Approve: ${input.what}` }); return { what: input.what, approved: true }; } catch (error) { if (error instanceof SuspensionRejectedError) return { what: input.what, approved: false }; diff --git a/goals/shift-manager/it-shows-who-is-on-shift/lab/lab.mts b/goals/shift-manager/it-shows-who-is-on-shift/lab/lab.mts index c39440d079..b6ed204c37 100644 --- a/goals/shift-manager/it-shows-who-is-on-shift/lab/lab.mts +++ b/goals/shift-manager/it-shows-who-is-on-shift/lab/lab.mts @@ -171,7 +171,7 @@ export async function openShiftLab(spread: Spread = spreadFromEnv()) { outputSchema: z.object({ approved: z.boolean() }), execute: async (input, ctx) => { try { - await ctx.suspend!({ reason: "human_approval", message: `Approve: ${input.what}` }); + await ctx.suspend!({ reason: "user_approval", message: `Approve: ${input.what}` }); return { approved: true }; } catch (error) { if (error instanceof SuspensionRejectedError) return { approved: false }; diff --git a/goals/shift-manager/one-person-runs-a-labs-projects-and-people/goal.md b/goals/shift-manager/one-person-runs-a-labs-projects-and-people/goal.md index d2236e0720..a2cd275366 100644 --- a/goals/shift-manager/one-person-runs-a-labs-projects-and-people/goal.md +++ b/goals/shift-manager/one-person-runs-a-labs-projects-and-people/goal.md @@ -17,15 +17,15 @@ FIX-1792 took the DevTeam off mailboxes, and a project lists none. Retired under - **a3** Brief, Workstreams (its progress, and no mailbox workstream listed), Board (its named no-board state) and Stream for each. The Stream is the person's project coordinator: the conversation it draws names a session of the person's own, on the project coordinator's flow, naming the worker the Lab's `projectSetup` names as its worker and the project as its project. No gap copy on any tab. - **a4** The second member's Stream on the first project is their own project coordinator, graded as in a3, and not the person's session; the outsider's PROJECTS lists both projects. - **a5** a2 to a4 again on a new process over the same store; the rows unchanged, and each Stream draws the same coordinator session as before the restart. -- **b1** Asked for a coder seat like the team's own (the ask names its flow and brief, read from the tree, so a chief of staff that asks which brief isn't graded on it), CoS's `hire` is ok, no `human_approval` is raised, the person's roster holds the new worker's row, Roster lists it as theirs, and the organization's seat inventory doesn't list it: a worker the person hires is theirs (FIX-1788). -- **b2** Asked to fire it, the turn suspends on one `human_approval` whose message names `fire` and whose data names the worker; Inbox lists it with the worker on its card; nothing changes. After a restart the worker and the ask are both still there. +- **b1** Asked for a coder seat like the team's own (the ask names its flow and brief, read from the tree, so a chief of staff that asks which brief isn't graded on it), CoS's `hire` is ok, no `user_approval` is raised, the person's roster holds the new worker's row, Roster lists it as theirs, and the organization's seat inventory doesn't list it: a worker the person hires is theirs (FIX-1788). +- **b2** Asked to fire it, the turn suspends on one `user_approval` whose message names `fire` and whose data names the worker; Inbox lists it with the worker on its card; nothing changes. After a restart the worker and the ask are both still there. - **b3** Approve in Inbox: the worker leaves the person's roster and Roster, and is still gone after a restart. - **b4** Asked in a `feature` workstream the EM leads, through its entry page, the EM hires nothing: no such worker on the person's roster, in Roster or in the inventory. The ask must be kept first: the workstream's session holds the line once, or b4 fails, since a line never sent hires nothing either. - **c1** On boot 1 (`extra-flow`: one more worker flow), CoS hires a worker on the scratch flow; the person's roster row names that flow and Roster lists it as theirs; a turn in the person's session with it, created on that flow naming it, runs as that worker. - **c2** On boot 2 (as shipped: the flow is cut), a turn in that session is refused, naming the flow (FIX-1788 BR-19a); the worker's roster row is unchanged and Roster still lists it. -- **c3** Asked to fire it, the turn suspends on one `human_approval` naming the worker; Approve in Inbox. +- **c3** Asked to fire it, the turn suspends on one `user_approval` naming the worker; Approve in Inbox. - **c4** Boot 3: the person's roster has no row for it, and Roster doesn't list it. -- **J4** A docs-only writer adds CoS, its `hire` and `fire` tools from `createWorkerHireBlocks` with the fire asking first, the projects collection and the project tools (`createProject` and `openWorkstream`, which the task names, as it names the chief of staff's flow, `coordinator` with no delegates, and its model) to a scratch copy of the pentest Lab. The task also states what the Lab's other checks need of it, which neither the docs nor the copy show: every start fresh, and `probe`, `probe-desk` and `coordinator` run only declared workers. What to do about those is still the docs' to say. Shift Manager over the copy boots, PROJECTS lists the project CoS created, and the worker CoS hired is a row on the person's own roster, on the flow the ask named, that Roster lists as theirs. The hire ask names the built-in `agent` flow, read from the writer's files, not from the model: a Lab whose files never call `createWorkerHireBlocks`, or that mark `agent` `standardOnly`, fails J4. Asked to fire that worker, CoS's turn suspends on one `human_approval` whose message names `fire` and whose data names the worker, read from the store's items and left unanswered, while the worker is still on the person's roster. Each step the writer logs as *doc silent* goes to a judge: Jev (`typesafe-ai/jev`) reads it beside the task and the sections of the writer's docs that share the most words with it, and answers whether those sections answer the step, the step is a gap, or it is outside what the task asked for, citing the section it read (`j4-judge.mts`). A line fails J4 when Jev says *gap*. A line Jev says *answered* or *outside* below 0.6 still drops when Jev gives *gap* 0.2 or less: Jev is sure the step is no gap and only splits between the two drops, as it does for a step answered from the Lab's own files. Otherwise Jev is unsure, and the line is judged again, up to three times in all, stopping once two calls agree: it fails J4 when at least two of the three calls are not *answered* or *outside* at 0.6 or more, so a line Jev is unsure about every time still fails. Dropped lines are reported in the notes, with every call's verdict when the line was judged again. Control `J4_CUT=store` cuts the Shift Manager README's stores and restarts from the writer's docs, and must fail J4 on that step. +- **J4** A docs-only writer adds CoS, its `hire` and `fire` tools from `createWorkerHireBlocks` with the fire asking first, the projects collection and the project tools (`createProject` and `openWorkstream`, which the task names, as it names the chief of staff's flow, `coordinator` with no delegates, and its model) to a scratch copy of the pentest Lab. The task also states what the Lab's other checks need of it, which neither the docs nor the copy show: every start fresh, and `probe`, `probe-desk` and `coordinator` run only declared workers. What to do about those is still the docs' to say. Shift Manager over the copy boots, PROJECTS lists the project CoS created, and the worker CoS hired is a row on the person's own roster, on the flow the ask named, that Roster lists as theirs. The hire ask names the built-in `agent` flow, read from the writer's files, not from the model: a Lab whose files never call `createWorkerHireBlocks`, or that mark `agent` `standardOnly`, fails J4. Asked to fire that worker, CoS's turn suspends on one `user_approval` whose message names `fire` and whose data names the worker, read from the store's items and left unanswered, while the worker is still on the person's roster. Each step the writer logs as *doc silent* goes to a judge: Jev (`typesafe-ai/jev`) reads it beside the task and the sections of the writer's docs that share the most words with it, and answers whether those sections answer the step, the step is a gap, or it is outside what the task asked for, citing the section it read (`j4-judge.mts`). A line fails J4 when Jev says *gap*. A line Jev says *answered* or *outside* below 0.6 still drops when Jev gives *gap* 0.2 or less: Jev is sure the step is no gap and only splits between the two drops, as it does for a step answered from the Lab's own files. Otherwise Jev is unsure, and the line is judged again, up to three times in all, stopping once two calls agree: it fails J4 when at least two of the three calls are not *answered* or *outside* at 0.6 or more, so a line Jev is unsure about every time still fails. Dropped lines are reported in the notes, with every call's verdict when the line was judged again. Control `J4_CUT=store` cuts the Shift Manager README's stores and restarts from the writer's docs, and must fail J4 on that step. - **P3.3 and P3.4** every child's check on its green path, with the controls part 1 hasn't already failed (`manifest.mts`). A child's control counts as red only when it exits with a FAIL list naming the assertions its own goal.md names for it, and nothing else where that goal says "only" (`EXPECTED` in `manifest.mts`). A timeout, a crash or a red at another assertion is a finding. - `goals/shift-manager/a-lab-is-worked-through-one-skinned-shell` is excluded from P3.4: it is FIX-1737's closure goal, matched only because it serves DevTeam, and its part 3 reruns checks P3 already runs. - **Part 4** the seam rows, each a scripted assertion (`seams.mts`). Since FIX-1788, ER-19 holds when a person's worker row is deleted only by Workforce's fire block, and ER-5 when every refusal of a turn's worker is thrown where the turn loads it, through the same mint a hire's check uses. diff --git a/goals/shift-manager/one-person-runs-a-labs-projects-and-people/j4.mts b/goals/shift-manager/one-person-runs-a-labs-projects-and-people/j4.mts index d90d098cc3..7c7910ae87 100644 --- a/goals/shift-manager/one-person-runs-a-labs-projects-and-people/j4.mts +++ b/goals/shift-manager/one-person-runs-a-labs-projects-and-people/j4.mts @@ -24,7 +24,7 @@ * for a project and a worker in the Chief of Staff view: PROJECTS must list * the project; the person's roster must hold the worker it hired, and Roster * list it as theirs; and a fire of that worker must suspend on one - * `human_approval` in the store naming it. The copy is deleted after the run; + * `user_approval` in the store naming it. The copy is deleted after the run; * `packages/shift-manager` is left untouched. */ import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs"; @@ -289,13 +289,13 @@ export async function j4(browser: Browser, scratch: string, pages: string, shots const fire = await askCos(world, "J4", `Please fire the worker "${worker}".`); if (fire === undefined || fire.sessionId === null || fire.requestId === null) failures.push(`J4: the fire was not asked: ${quote(fire)}`); else { - const asks = (await asksOf(world.routes.owner, fire.sessionId, fire.requestId)).filter((a) => a.reason === "human_approval"); + const asks = (await asksOf(world.routes.owner, fire.sessionId, fire.requestId)).filter((a) => a.reason === "user_approval"); const named = (asks[0]?.data as { worker?: string } | undefined)?.worker; - if (fire.status !== "suspended" || asks.length !== 1) failures.push(`J4: asked to fire "${worker}", the turn ended ${fire.status} with ${asks.length} human_approval ask(s), not suspended on one: ${quote(fire)}`); + if (fire.status !== "suspended" || asks.length !== 1) failures.push(`J4: asked to fire "${worker}", the turn ended ${fire.status} with ${asks.length} user_approval ask(s), not suspended on one: ${quote(fire)}`); else if (named !== worker || !/fire/i.test(asks[0]!.message ?? "")) failures.push(`J4: the fire's ask says "${asks[0]!.message}" naming ${JSON.stringify(asks[0]!.data)}, not a fire of "${worker}"`); // Nothing is removed before the person answers: a fire that writes first and asks after still raises the same ask. else if (!(await readWorkers(world.routes.owner)).some((w) => w.id === worker)) failures.push(`J4: asked to fire "${worker}", the turn suspended on its ask, but the person's roster no longer holds it: the fire ran before anyone approved`); - else notes.push(`J4: asked to fire "${worker}", the turn suspended on one human_approval "${asks[0]!.message}" ${JSON.stringify(asks[0]!.data)}; left unanswered, and the worker is still on the roster`); + else notes.push(`J4: asked to fire "${worker}", the turn suspended on one user_approval "${asks[0]!.message}" ${JSON.stringify(asks[0]!.data)}; left unanswered, and the worker is still on the roster`); } } } diff --git a/goals/shift-manager/one-person-runs-a-labs-projects-and-people/legs/b.mts b/goals/shift-manager/one-person-runs-a-labs-projects-and-people/legs/b.mts index 5b8edeedb9..2e7ce1de38 100644 --- a/goals/shift-manager/one-person-runs-a-labs-projects-and-people/legs/b.mts +++ b/goals/shift-manager/one-person-runs-a-labs-projects-and-people/legs/b.mts @@ -147,8 +147,8 @@ export async function legB(world: World, restart: (label: string) => Promise h.ok).length} ok: ${quote(hire)}`); - const raised = cosSession === null || hire.requestId === null ? [] : (await asksOf(world.routes.owner, cosSession, hire.requestId)).filter((a) => a.reason === "human_approval"); - if (raised.length > 0) r.fail("b1", `the hire raised ${raised.length} human_approval ask(s)`); + const raised = cosSession === null || hire.requestId === null ? [] : (await asksOf(world.routes.owner, cosSession, hire.requestId)).filter((a) => a.reason === "user_approval"); + if (raised.length > 0) r.fail("b1", `the hire raised ${raised.length} user_approval ask(s)`); if (hire.status !== "completed") r.fail("b1", `the hire turn ended ${hire.status}`); const hired = await where(world, seat); if (hired.rosterRow === undefined) r.fail("b1", `seat appears: the person's roster has no row for "${seat}"`); @@ -164,10 +164,10 @@ export async function legB(world: World, restart: (label: string) => Promise a.reason === "human_approval"); + const asks = (await asksOf(world.routes.owner, fire.sessionId, fire.requestId)).filter((a) => a.reason === "user_approval"); ask = asks[0]; const named = (ask?.data as { worker?: string } | undefined)?.worker; - if (fire.status !== "suspended" || asks.length !== 1) r.fail("b2", `the fire turn ended ${fire.status} with ${asks.length} human_approval ask(s): ${quote(fire)}`); + if (fire.status !== "suspended" || asks.length !== 1) r.fail("b2", `the fire turn ended ${fire.status} with ${asks.length} user_approval ask(s): ${quote(fire)}`); else if (named !== seat || !/fire/i.test(ask!.message ?? "")) r.fail("b2", `the ask says "${ask!.message}" naming ${JSON.stringify(ask!.data)}, not a fire of "${seat}"`); const inbox = await inboxAsks(world); if (ask?.suspensionId === undefined || !inbox.includes(ask.suspensionId)) r.fail("b2", `Inbox doesn't list the ask ${ask?.suspensionId} (lists [${inbox.join(", ")}])`); diff --git a/goals/shift-manager/one-person-runs-a-labs-projects-and-people/legs/c.mts b/goals/shift-manager/one-person-runs-a-labs-projects-and-people/legs/c.mts index 92e65a7e05..4ba6d8b1fd 100644 --- a/goals/shift-manager/one-person-runs-a-labs-projects-and-people/legs/c.mts +++ b/goals/shift-manager/one-person-runs-a-labs-projects-and-people/legs/c.mts @@ -81,9 +81,9 @@ export async function legC(world: World, opts: { worker: string; flow: string; p if (fire === undefined || fire.requestId === null || fire.sessionId === null) { r.fail("c3", `the fire was not asked: ${quote(fire)}`); } else { - const asks = (await asksOf(owner(), fire.sessionId, fire.requestId)).filter((a) => a.reason === "human_approval"); + const asks = (await asksOf(owner(), fire.sessionId, fire.requestId)).filter((a) => a.reason === "user_approval"); const named = (asks[0]?.data as { worker?: string } | undefined)?.worker; - if (fire.status !== "suspended" || asks.length !== 1) r.fail("c3", `the fire turn ended ${fire.status} with ${asks.length} human_approval ask(s): ${quote(fire)}`); + if (fire.status !== "suspended" || asks.length !== 1) r.fail("c3", `the fire turn ended ${fire.status} with ${asks.length} user_approval ask(s): ${quote(fire)}`); else if (named !== worker || !/fire/i.test(asks[0]!.message ?? "")) r.fail("c3", `the ask says "${asks[0]!.message}" naming ${JSON.stringify(asks[0]!.data)}, not a fire of "${worker}"`); else { const answered = await answerInInbox(world, asks[0]!.suspensionId!, "Approve"); diff --git a/goals/shift-manager/one-person-runs-a-labs-projects-and-people/seams.mts b/goals/shift-manager/one-person-runs-a-labs-projects-and-people/seams.mts index 3ad82014ea..299e0a5b6c 100644 --- a/goals/shift-manager/one-person-runs-a-labs-projects-and-people/seams.mts +++ b/goals/shift-manager/one-person-runs-a-labs-projects-and-people/seams.mts @@ -237,7 +237,7 @@ export function seams(base: string): SeamRow[] { ["the shared section, org seat and mailbox (FIX-1719)", "apps/docs/docs/workforce/overview.md", /^## Projects and the Shift Coordinator\n[\s\S]*?Shift Coordinator[\s\S]*?(approve)/im], ["Asking CoS for a project (FIX-1718)", "apps/docs/docs/workforce/projects.md", /^# Projects$[\s\S]*Shift Coordinator/m], ["Shift Manager's PROJECTS (FIX-1718)", "packages/shift-manager/README.md", /^## What you see$[\s\S]*?PROJECTS/m], - ["The CoS page (FIX-1719)", "apps/docs/docs/workforce/shift-coordinator.md", /^# The Shift Coordinator$[\s\S]*?^## Adding one$[\s\S]*?^## What asks first$[\s\S]*?"reason": "human_approval"/m], + ["The CoS page (FIX-1719)", "apps/docs/docs/workforce/shift-coordinator.md", /^# The Shift Coordinator$[\s\S]*?^## Adding one$[\s\S]*?^## What asks first$[\s\S]*?"reason": "user_approval"/m], // Each person talks to a project through their own project coordinator; the project rooms are gone (FIX-1793). ["Talking to a project (FIX-1793)", "apps/docs/docs/workforce/projects.md", /^## Talking to a project$[\s\S]*?\*\*project coordinator\*\*[\s\S]*?^### How its delegates follow your workstreams$/m], // FIX-1621's repair of a seat whose kind is gone was retired by FIX-1788: a worker is a row its owner fires or edits. diff --git a/goals/shift-manager/workers-message-each-other/legs-calls.mts b/goals/shift-manager/workers-message-each-other/legs-calls.mts index adf6fb789a..02f59f9ca7 100644 --- a/goals/shift-manager/workers-message-each-other/legs-calls.mts +++ b/goals/shift-manager/workers-message-each-other/legs-calls.mts @@ -165,7 +165,7 @@ export async function leg10b(world: World): Promise { message: `Before anything else, call waitForUser with kind "approval" and prompt "May I publish the ${fyi} report?", and wait for my answer.`, }); const stop = await until(async () => { - const stops = (await alice.routes.items(researcher.id, "suspension")).filter((i) => i.requestId === stopTurn.requestId && i.reason === "human_approval"); + const stops = (await alice.routes.items(researcher.id, "suspension")).filter((i) => i.requestId === stopTurn.requestId && i.reason === "user_approval"); return stops.at(-1); }, 30_000, 1_000); if (stop === undefined) { diff --git a/goals/task-board/holds-a-task-waiting-on-a-person/run.mts b/goals/task-board/holds-a-task-waiting-on-a-person/run.mts index e3ed80d4bb..157282ba25 100644 --- a/goals/task-board/holds-a-task-waiting-on-a-person/run.mts +++ b/goals/task-board/holds-a-task-waiting-on-a-person/run.mts @@ -769,8 +769,8 @@ async function legE(run: Run, dbFile: string, restart: () => Promise): Prom /** f. The host's setting: waitForUser with none reads it; a raw ctx.suspend keeps its own. */ async function legF(run: Run): Promise { const own = await file(run, word("[ask:input] the host's deadline")); - const rawTimed = await file(run, word(`[raw:human_input:${RAW_TIMEOUT_MS}] a raw stop with its own`)); - const rawNone = await file(run, word("[raw:human_input] a raw stop with none")); + const rawTimed = await file(run, word(`[raw:user_input:${RAW_TIMEOUT_MS}] a raw stop with its own`)); + const rawNone = await file(run, word("[raw:user_input] a raw stop with none")); for (const id of [own, rawTimed, rawNone]) if (!(await untilWaiting(run, id, "f"))) return; const deadlineOf = async (id: string) => { const row = await run.h.byId(id); diff --git a/goals/task-board/settles-when-its-work-is-over/goal.md b/goals/task-board/settles-when-its-work-is-over/goal.md index 0e2360f39d..08943d8640 100644 --- a/goals/task-board/settles-when-its-work-is-over/goal.md +++ b/goals/task-board/settles-when-its-work-is-over/goal.md @@ -11,7 +11,7 @@ - `a` (background work): `a:after-the-side-chains` the task completed after the last write of its request's side chain and of the one `onFinished` started. `a:once` one ending, heard once, with the work's answer. - `b` (pieces): `b:waiting-while-open` while a piece is open the task is `in_progress`, `keptOpenBy: "filed"`, with no lease. `b:last-turns-answer` completed once with the answer of the last turn a piece's ending woke (its worker never checkpoints). `b:once` heard once, no running row left. Variant, the last piece ending during the task's own request: `b:piece-ends-during-request` it did, and `b:settles-after-woken-turn` that request's check left it running, and it completed with the woken turn's answer, not its own. - `c` (a message queued mid-task): for each of `[message]` and `[message-checkpoint]`, `c:settles-first` the task completed when its work ended, before the message's turn began; `c:outside-the-task` the message's turn held no claim, saw the task completed, and reported no checkpoint; `c:output` completed on attempt 1 with the work's answer, no checkpoint; `c:once` heard once. -- `d` (a wait and a person's stop): `d:keeps-its-claim` a `human_input` stop and an `external_event` stop are each `in_progress`, waiting on `"user"` and `"wait"`, with no lease; `d:not-run-twice` past the lease the claim committed to (two minutes) and a pass of the board, each is still running on attempt 1 and its work never ran again; `d:resumes` and `d:done-after-resume` each resumed and completed on attempt 1 with the resumed answer. +- `d` (a wait and a person's stop): `d:keeps-its-claim` a `user_input` stop and an `external_event` stop are each `in_progress`, waiting on `"user"` and `"wait"`, with no lease; `d:not-run-twice` past the lease the claim committed to (two minutes) and a pass of the board, each is still running on attempt 1 and its work never ran again; `d:resumes` and `d:done-after-resume` each resumed and completed on attempt 1 with the resumed answer. **Anti-game:** no grade reads a call the gate made or a stub. It reads the stored rows (status, `keptOpenBy`, lease, attempts, output, timestamps), the requests the engine stored, the notices the desk acted on, and the proofs each worker wrote from inside its own run. A task's request arrived on the `task` source, which no public route re-enters, so leg d resolves the stop and continues the request through the engine, as a host's own answer surface does; the claim and the attempt it grades are the stored row's. diff --git a/goals/task-board/settles-when-its-work-is-over/run.mts b/goals/task-board/settles-when-its-work-is-over/run.mts index 76dcc2fda4..6bbcfd5af7 100644 --- a/goals/task-board/settles-when-its-work-is-over/run.mts +++ b/goals/task-board/settles-when-its-work-is-over/run.mts @@ -559,7 +559,7 @@ async function legC(run: Run): Promise { } const STOPS = [ - ["human_input", "user"], + ["user_input", "user"], ["external_event", "wait"] ] as const; @@ -577,7 +577,7 @@ async function resumeStop(run: Run, taskId: string, reason: string): Promise { - await ctx.suspend!({ reason: "human_approval", message: `Send "${input.message}"?` }); + await ctx.suspend!({ reason: "user_approval", message: `Send "${input.message}"?` }); return { reply: `sent: ${input.message}` }; }, }); diff --git a/packages/cli/test/fixtures/durable/flows/review/flow.ts b/packages/cli/test/fixtures/durable/flows/review/flow.ts index 5cf7fe766b..e03b11c7b1 100644 --- a/packages/cli/test/fixtures/durable/flows/review/flow.ts +++ b/packages/cli/test/fixtures/durable/flows/review/flow.ts @@ -24,7 +24,7 @@ const approve = handler({ inputSchema: z.object({ title: z.string() }), outputSchema: z.object({ title: z.string() }), execute: async (input, ctx) => { - await ctx.suspend!({ reason: "human_approval", message: `Publish "${input.title}"?` }); + await ctx.suspend!({ reason: "user_approval", message: `Publish "${input.title}"?` }); return input; }, }); diff --git a/packages/client/README.md b/packages/client/README.md index 1ea5665e9d..e1ef494b81 100644 --- a/packages/client/README.md +++ b/packages/client/README.md @@ -120,7 +120,7 @@ the suspension's `resumeSchema` (an invalid payload is a 400 with path-keyed suspension's `allow` set is a 409. To answer a stop that waits for a user from an inbox (a `ctx.waitForUser`, or a -`human_approval` / `human_input` stop), use `answer`. The server checks the +`user_approval` / `user_input` stop), use `answer`. The server checks the caller owns the stop's request before it reads the stop, and records the signed-in caller as who answered, so there is no `resumedBy`: diff --git a/packages/client/src/client.ts b/packages/client/src/client.ts index 118cf7238b..18a0349a47 100644 --- a/packages/client/src/client.ts +++ b/packages/client/src/client.ts @@ -317,7 +317,7 @@ export interface RequestHandle { resume(body: ResumeSuspensionBody, options: StreamOption): Promise; /** * Answer a suspension of this request that waits for a user - * (`ctx.waitForUser`, or a raw `human_approval` / `human_input` stop), + * (`ctx.waitForUser`, or a raw `user_approval` / `user_input` stop), * whatever started its run, a task's included, which `resume` refuses. * The server checks the caller owns the request before it reads the stop, * resolves it once, and continues the same request; this resolves to its diff --git a/packages/client/test/sessions.test.ts b/packages/client/test/sessions.test.ts index c67d21d4f8..817509499e 100644 --- a/packages/client/test/sessions.test.ts +++ b/packages/client/test/sessions.test.ts @@ -197,7 +197,7 @@ describe("client.sessions", () => { flowKind: "demo", actionName: "run", userId: "devuser", - reason: "human_approval", + reason: "user_approval", message: "Approve?", status: "pending", blockInstanceId: "b1", diff --git a/packages/contracts/src/types/suspension.ts b/packages/contracts/src/types/suspension.ts index c895363310..4de97583c8 100644 --- a/packages/contracts/src/types/suspension.ts +++ b/packages/contracts/src/types/suspension.ts @@ -32,8 +32,8 @@ export type SuspensionStatus = * autocomplete on the known set. */ export type SuspensionReason = - | "human_approval" - | "human_input" + | "user_approval" + | "user_input" | "external_event" | (string & {}); @@ -58,13 +58,13 @@ export type ResumeAction = "approve" | "reject" | "submit" | "skip"; export type WaitForUserKind = "approval" | "review" | "input"; /** The suspension reasons that wait for a user. */ -const USER_REASONS: ReadonlySet = new Set(["human_approval", "human_input"]); +const USER_REASONS: ReadonlySet = new Set(["user_approval", "user_input"]); /** * Whether a suspension waits for a user: the one predicate every reader keys * on (the claim gate, the answer route, the Inbox). True for a - * `ctx.waitForUser` stop and for a raw `ctx.suspend` with `human_approval` or - * `human_input`. `external_event` and a custom reason (the open `string & {}` + * `ctx.waitForUser` stop and for a raw `ctx.suspend` with `user_approval` or + * `user_input`. `external_event` and a custom reason (the open `string & {}` * arm of {@link SuspensionReason}) are never a user's. */ export function isUserSuspension(suspension: { readonly reason: string }): boolean { @@ -73,8 +73,8 @@ export function isUserSuspension(suspension: { readonly reason: string }): boole /** * The kind of a user's suspension: its own `kind`, or, on a record that - * carries none (a raw `ctx.suspend`), read from its reason: `human_approval` - * an approval, `human_input` input. `undefined` for a suspension that does + * carries none (a raw `ctx.suspend`), read from its reason: `user_approval` + * an approval, `user_input` input. `undefined` for a suspension that does * not wait for a user. */ export function waitForUserKindOf(suspension: { @@ -83,5 +83,5 @@ export function waitForUserKindOf(suspension: { }): WaitForUserKind | undefined { if (!isUserSuspension(suspension)) return undefined; if (suspension.kind !== undefined) return suspension.kind; - return suspension.reason === "human_approval" ? "approval" : "input"; + return suspension.reason === "user_approval" ? "approval" : "input"; } diff --git a/packages/core/README.md b/packages/core/README.md index b71fbcaea2..8ebd797da0 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -167,7 +167,7 @@ const region = asked.answer; - At a deadline an approval reads as a no with `deadline: true`. A review or an input throws `SuspensionTimeoutError`: catch it to go ahead, end or ask again, or leave it and the try fails. - When the task the request works is cancelled while it waits, the call returns `{ cancelled: true }`, and any later `waitForUser` in that run returns it at once. -A raw `ctx.suspend({ reason: "human_approval" | "human_input" })` is the same kind of stop, read by its reason, with its own `timeoutMs` as its only deadline: an input that passes it throws `SuspensionTimeoutError`, and a cancel throws `SuspensionRejectedError` with `cancelled: true`. `isUserSuspension(suspension)` and `waitForUserKindOf(suspension)` (from `@flow-state-dev/core/types`) say whether a suspension waits for a user, and for what. +A raw `ctx.suspend({ reason: "user_approval" | "user_input" })` is the same kind of stop, read by its reason, with its own `timeoutMs` as its only deadline: an input that passes it throws `SuspensionTimeoutError`, and a cancel throws `SuspensionRejectedError` with `cancelled: true`. `isUserSuspension(suspension)` and `waitForUserKindOf(suspension)` (from `@flow-state-dev/core/types`) say whether a suspension waits for a user, and for what. **Flow:** - `defineFlow(definition)` — Create a flow type with actions, `internal` and `task` entries, scopes, resources, and per-scope `client` blocks. See [Dispatches, entries, and `dispatcher()`](#dispatches-entries-and-dispatcher) diff --git a/packages/core/src/errors/suspension-error.ts b/packages/core/src/errors/suspension-error.ts index 8284aa8845..3138fd8f5a 100644 --- a/packages/core/src/errors/suspension-error.ts +++ b/packages/core/src/errors/suspension-error.ts @@ -43,8 +43,8 @@ export interface SuspendOptions { render?: { component: string; props?: Record }; /** * Which resolution actions this suspension permits. Omit to take the default - * for the `reason`: `human_input` → `["submit"]`; everything else (including - * `human_approval`) → `["approve", "reject"]`. Add `"skip"` to make the step + * for the `reason`: `user_input` → `["submit"]`; everything else (including + * `user_approval`) → `["approve", "reject"]`. Add `"skip"` to make the step * optional — a skipped resume returns the `SUSPENSION_SKIPPED` sentinel from * `ctx.suspend()` instead of aborting. The resume route enforces this set. */ @@ -67,7 +67,7 @@ export function resolveAllowedActions( allow: ResumeAction[] | undefined ): ResumeAction[] { if (allow !== undefined) return allow; - return reason === "human_input" ? ["submit"] : ["approve", "reject"]; + return reason === "user_input" ? ["submit"] : ["approve", "reject"]; } /** diff --git a/packages/core/src/types/request-end.ts b/packages/core/src/types/request-end.ts index da080271fd..b194eff946 100644 --- a/packages/core/src/types/request-end.ts +++ b/packages/core/src/types/request-end.ts @@ -32,7 +32,7 @@ export interface RequestEnding { readonly status: RequestEndStatus; /** * On `suspended`: the suspension it parked on. `reason` is why - * (`human_approval`, `human_input`, `external_event`, or a flow's own); the + * (`user_approval`, `user_input`, `external_event`, or a flow's own); the * rest is what a reader of a task waiting on it shows (FIX-2129): its id, * its kind when `waitForUser` set one, what it asks (`title`, `message`), * and its deadline (`expiresAt`), absent when it has none. diff --git a/packages/core/src/types/wait-for-user.ts b/packages/core/src/types/wait-for-user.ts index 4da7d64f82..84863f86d7 100644 --- a/packages/core/src/types/wait-for-user.ts +++ b/packages/core/src/types/wait-for-user.ts @@ -89,7 +89,7 @@ export interface WaitForUserContext { function suspendOptionsOf(options: WaitForUserOptions, deadline: number | undefined): SuspendOptions { const approval = options.kind === "approval"; return { - reason: approval ? "human_approval" : "human_input", + reason: approval ? "user_approval" : "user_input", kind: options.kind, message: options.prompt, ...(options.title !== undefined ? { title: options.title } : {}), diff --git a/packages/core/test/blocks/replay-log.test.ts b/packages/core/test/blocks/replay-log.test.ts index dfd9d2ed0b..fe8527e37c 100644 --- a/packages/core/test/blocks/replay-log.test.ts +++ b/packages/core/test/blocks/replay-log.test.ts @@ -73,7 +73,7 @@ function suspensionItem( status: "completed", suspensionId, suspensionStatus: "pending", - reason: "human_approval", + reason: "user_approval", message: "approve?", blockInstanceId: `${REQ}:${path}:0`, requestId: REQ, @@ -240,7 +240,7 @@ describe("buildReplayLog", () => { suspensionItem("root/step[3]", "susp_b", 2), ]); expect(log.resolvedResumes(`${REQ}:root/step[2]`)).toEqual([ - { data: { observed: "In Spec Review" }, rejected: false, expired: false, cancelled: false, stopped: false, skipped: false, resolution: "approved", reason: "human_approval", suspensionId: "susp_a", resolvedBy: undefined }, + { data: { observed: "In Spec Review" }, rejected: false, expired: false, cancelled: false, stopped: false, skipped: false, resolution: "approved", reason: "user_approval", suspensionId: "susp_a", resolvedBy: undefined }, ]); expect(log.resolvedResumes(`${REQ}:root/step[3]`)).toEqual([]); }); @@ -265,7 +265,7 @@ describe("buildReplayLog", () => { }), ]); expect(log.resolvedResumes(`${REQ}:root/step[2]`)).toEqual([ - { data: { note: "no" }, rejected: true, expired: false, cancelled: false, stopped: false, skipped: false, resolution: "rejected", reason: "human_approval", suspensionId: "susp_a", resolvedBy: "reviewer" }, + { data: { note: "no" }, rejected: true, expired: false, cancelled: false, stopped: false, skipped: false, resolution: "rejected", reason: "user_approval", suspensionId: "susp_a", resolvedBy: "reviewer" }, ]); }); @@ -280,7 +280,7 @@ describe("buildReplayLog", () => { }), ]); expect(log.resolvedResumes(`${REQ}:root/step[2]`)).toEqual([ - { data: undefined, rejected: true, expired: true, cancelled: false, stopped: false, skipped: false, resolution: "expired", reason: "human_approval", suspensionId: "susp_a", resolvedBy: "durability-sweeper" }, + { data: undefined, rejected: true, expired: true, cancelled: false, stopped: false, skipped: false, resolution: "expired", reason: "user_approval", suspensionId: "susp_a", resolvedBy: "durability-sweeper" }, ]); }); @@ -292,7 +292,7 @@ describe("buildReplayLog", () => { suspensionResumeItem("root/step[2]", "susp_a", 1, { resolution: "cancelled", resolvedBy: "cancel" }), ]); expect(log.resolvedResumes(`${REQ}:root/step[2]`)).toEqual([ - { data: undefined, rejected: true, expired: false, cancelled: true, stopped: false, skipped: false, resolution: "cancelled", reason: "human_approval", suspensionId: "susp_a", resolvedBy: "cancel" }, + { data: undefined, rejected: true, expired: false, cancelled: true, stopped: false, skipped: false, resolution: "cancelled", reason: "user_approval", suspensionId: "susp_a", resolvedBy: "cancel" }, ]); }); @@ -306,7 +306,7 @@ describe("buildReplayLog", () => { suspensionResumeItem("root/step[2]", "susp_b", 3, { resolution: "stopped", resolvedBy: "stop" }), ]); expect(log.resolvedResumes(`${REQ}:root/step[2]`)).toMatchObject([ - { rejected: false, stopped: true, resolution: "stopped", reason: "human_approval", suspensionId: "susp_b" }, + { rejected: false, stopped: true, resolution: "stopped", reason: "user_approval", suspensionId: "susp_b" }, ]); expect(log.resolvedInOrder().map((r) => [r.suspensionId, r.resolution])).toEqual([ ["susp_a", "approved"], diff --git a/packages/core/test/items/suspension-guards.test.ts b/packages/core/test/items/suspension-guards.test.ts index ff2be81086..4e6bcd5e40 100644 --- a/packages/core/test/items/suspension-guards.test.ts +++ b/packages/core/test/items/suspension-guards.test.ts @@ -26,7 +26,7 @@ describe("isSuspensionItem", () => { type: "suspension", suspensionId: "susp-1", suspensionStatus: "pending", - reason: "human_approval", + reason: "user_approval", message: "Approve this?" }; @@ -76,7 +76,7 @@ describe("isSuspensionResumeItem", () => { type: "suspension", suspensionId: "susp-1", suspensionStatus: "pending", - reason: "human_approval", + reason: "user_approval", message: "Approve this?" }; diff --git a/packages/core/test/step-abort-signal.test.ts b/packages/core/test/step-abort-signal.test.ts index 753918eaec..c0c456a074 100644 --- a/packages/core/test/step-abort-signal.test.ts +++ b/packages/core/test/step-abort-signal.test.ts @@ -151,7 +151,7 @@ const suspends = handler({ inputSchema: z.unknown(), outputSchema: z.unknown(), execute: async () => { - throw new SuspensionError({ suspensionId: "sus", reason: "human_approval" }); + throw new SuspensionError({ suspensionId: "sus", reason: "user_approval" }); }, }); diff --git a/packages/core/test/suspension-types.test.ts b/packages/core/test/suspension-types.test.ts index eb2acb0610..8624ae7327 100644 --- a/packages/core/test/suspension-types.test.ts +++ b/packages/core/test/suspension-types.test.ts @@ -44,7 +44,7 @@ describe("SuspensionRecord", () => { flowKind: "chat", actionName: "ask", userId: "user_1", - reason: "human_approval" as SuspensionReason, + reason: "user_approval" as SuspensionReason, message: "Please approve this action", status: "pending" as SuspensionStatus, blockInstanceId: "block_1", @@ -103,7 +103,7 @@ describe("SuspensionError", () => { it("is instanceof Error", () => { const err = new SuspensionError({ suspensionId: "sus_1", - reason: "human_approval" + reason: "user_approval" }); expect(err).toBeInstanceOf(Error); }); @@ -111,7 +111,7 @@ describe("SuspensionError", () => { it("carries suspension metadata", () => { const err = new SuspensionError({ suspensionId: "sus_42", - reason: "human_input", + reason: "user_input", message: "Enter the code", data: { field: "otp" }, resumeSchema: { type: "object" }, @@ -121,7 +121,7 @@ describe("SuspensionError", () => { expect(err.name).toBe("SuspensionError"); expect(err.suspensionId).toBe("sus_42"); - expect(err.reason).toBe("human_input"); + expect(err.reason).toBe("user_input"); expect(err.message).toBe("Enter the code"); expect(err.data).toEqual({ field: "otp" }); expect(err.resumeSchema).toEqual({ type: "object" }); diff --git a/packages/core/test/suspension-vocabulary.test.ts b/packages/core/test/suspension-vocabulary.test.ts index 80a02d31a6..c90f36f330 100644 --- a/packages/core/test/suspension-vocabulary.test.ts +++ b/packages/core/test/suspension-vocabulary.test.ts @@ -64,30 +64,30 @@ describe("RESUME_ACTION_STATUS", () => { }); describe("resolveAllowedActions", () => { - it("defaults human_input to submit-only", () => { - expect(resolveAllowedActions("human_input", undefined)).toEqual(["submit"]); + it("defaults user_input to submit-only", () => { + expect(resolveAllowedActions("user_input", undefined)).toEqual(["submit"]); }); - it("defaults human_approval (and any other reason) to binary approve/reject", () => { - expect(resolveAllowedActions("human_approval", undefined)).toEqual(["approve", "reject"]); + it("defaults user_approval (and any other reason) to binary approve/reject", () => { + expect(resolveAllowedActions("user_approval", undefined)).toEqual(["approve", "reject"]); expect(resolveAllowedActions("external_event", undefined)).toEqual(["approve", "reject"]); }); it("honours an explicit allow set over the reason default", () => { - expect(resolveAllowedActions("human_input", ["submit", "skip"])).toEqual(["submit", "skip"]); + expect(resolveAllowedActions("user_input", ["submit", "skip"])).toEqual(["submit", "skip"]); }); }); describe("SuspensionError.allow", () => { it("resolves the default allow set from the reason", () => { - const err = new SuspensionError({ suspensionId: "s1", reason: "human_input" }); + const err = new SuspensionError({ suspensionId: "s1", reason: "user_input" }); expect(err.allow).toEqual(["submit"]); }); it("carries an explicit allow set verbatim", () => { const err = new SuspensionError({ suspensionId: "s1", - reason: "human_input", + reason: "user_input", allow: ["submit", "skip"] }); expect(err.allow).toEqual(["submit", "skip"]); diff --git a/packages/core/test/wait-for-user.test.ts b/packages/core/test/wait-for-user.test.ts index 47d3f8cdee..e9f5ec8a3c 100644 --- a/packages/core/test/wait-for-user.test.ts +++ b/packages/core/test/wait-for-user.test.ts @@ -25,11 +25,11 @@ function ctxThat(answer: { returns: unknown } | { throws: Error }, host?: { user } describe("waitForUser: what it asks for", () => { - it("an approval is a human_approval with approve and reject; review and input are human_input with submit", async () => { + it("an approval is a user_approval with approve and reject; review and input are user_input with submit", async () => { for (const [kind, reason, allow] of [ - ["approval", "human_approval", ["approve", "reject"]], - ["review", "human_input", ["submit"]], - ["input", "human_input", ["submit"]], + ["approval", "user_approval", ["approve", "reject"]], + ["review", "user_input", ["submit"]], + ["input", "user_input", ["submit"]], ] as const) { const { ctx, asked } = ctxThat({ returns: "ok" }); await waitForUserOn(ctx, { kind, prompt: "Which region?" }); @@ -115,12 +115,12 @@ describe("waitForUser: how it comes back", () => { describe("isUserSuspension", () => { it("is a user's for the two person reasons only: never a wait, an external event or a custom reason", () => { - expect(isUserSuspension({ reason: "human_approval" })).toBe(true); - expect(isUserSuspension({ reason: "human_input" })).toBe(true); + expect(isUserSuspension({ reason: "user_approval" })).toBe(true); + expect(isUserSuspension({ reason: "user_input" })).toBe(true); for (const reason of ["external_event", "wait", "ask", "my_own_reason"]) expect(isUserSuspension({ reason })).toBe(false); // A raw suspension with no kind reads its kind from its reason. - expect(waitForUserKindOf({ reason: "human_approval" })).toBe("approval"); - expect(waitForUserKindOf({ reason: "human_input" })).toBe("input"); + expect(waitForUserKindOf({ reason: "user_approval" })).toBe("approval"); + expect(waitForUserKindOf({ reason: "user_input" })).toBe("input"); expect(waitForUserKindOf({ reason: "external_event", kind: "input" })).toBeUndefined(); }); }); diff --git a/packages/devtool/test/suspensions.test.tsx b/packages/devtool/test/suspensions.test.tsx index 5028400f0a..2ac7596ce9 100644 --- a/packages/devtool/test/suspensions.test.tsx +++ b/packages/devtool/test/suspensions.test.tsx @@ -43,7 +43,7 @@ function pendingRecord(overrides: Partial = {}): SuspensionRec flowKind: "chat", actionName: "ask", userId: "user_1", - reason: "human_approval", + reason: "user_approval", message: "Approve this draft?", status: "pending", blockInstanceId: "b1", @@ -184,13 +184,13 @@ describe("SuspensionItemView", () => { }, suspensionId: "sus_1", suspensionStatus: "pending", - reason: "human_approval", + reason: "user_approval", message: "Approve this draft?", } as unknown as SuspensionItem; render(); expect(screen.getByText("Approve this draft?")).toBeInTheDocument(); - expect(screen.getByText("human_approval")).toBeInTheDocument(); + expect(screen.getByText("user_approval")).toBeInTheDocument(); expect(screen.getByText("pending")).toBeInTheDocument(); }); }); diff --git a/packages/engine/README.md b/packages/engine/README.md index 59333f2452..0e37849838 100644 --- a/packages/engine/README.md +++ b/packages/engine/README.md @@ -1159,7 +1159,7 @@ Each tick takes a single-holder sentinel lease (co-located hosts serialize), enf **Stopping a suspended request.** The abort route and `ctx.session.stopRequest` also stop a `suspended` request when the host has durable execution: the stop resolves its pending gate `stopped` through the gate's single pending state. A wait gate continues the request with a stop outcome, so the parked call (`parkOnWait` returns `{ answered: false, stopped: true }`) can end the task it waits on and end its turn; any other gate continues the request with the stop recorded, so it ends `aborted` through its own lifecycle (its `onFinished` hook runs) without running past the gate. A gate a person already resolved (approved, say) whose request has not run again yet, so it waits on the sweep's re-drive, is stopped the same way: the gate is recorded `stopped`, the request ends `aborted`, and the approved step never runs. The person's answer, and any form data they sent, is replaced by the stop and not kept. A stop that finds the gate already resolved, with the request running again or about to, answers `409` on the route and `"already-resolved"` from `stopRequest`. A run a task board started (the `task` source) that is parked on a user's stop ends at that stop instead: it continues through the board's claim gate, which cancels the task, and ends `aborted` at the stop itself, with nothing after it run. Checkpoints of `in_progress` or `suspended` requests are never age-pruned — they are the resume points an active or paused run needs. -**Answering a user's stop.** `POST /api/flows/:flowKind/requests/:requestId/answer` with `{ suspensionId, action, data? }` answers a suspension that waits for a user (`ctx.waitForUser`, or a `human_approval` / `human_input` stop), whatever started its run, a task board included, which the resume route refuses. It runs the resume path's ownership checks on the stop's request (flow instance, user, tenant, organization) before it reads the stop, and answers a stop that isn't the caller's, or isn't a user's, as one that doesn't exist (`404`). The answer is checked against the stop's own `allow` and `resumeSchema`; who answered is the signed-in caller, never a body field. It resolves the stop through its single pending state, so of an answer, a cancel, a deadline and a stop, the first wins and the rest are told `already-resolved` (`409`). The client call is a request handle's `answer`. +**Answering a user's stop.** `POST /api/flows/:flowKind/requests/:requestId/answer` with `{ suspensionId, action, data? }` answers a suspension that waits for a user (`ctx.waitForUser`, or a `user_approval` / `user_input` stop), whatever started its run, a task board included, which the resume route refuses. It runs the resume path's ownership checks on the stop's request (flow instance, user, tenant, organization) before it reads the stop, and answers a stop that isn't the caller's, or isn't a user's, as one that doesn't exist (`404`). The answer is checked against the stop's own `allow` and `resumeSchema`; who answered is the signed-in caller, never a body field. It resolves the stop through its single pending state, so of an answer, a cancel, a deadline and a stop, the first wins and the rest are told `already-resolved` (`409`). The client call is a request handle's `answer`. **A user's stop's deadline.** A `waitForUser` call's `deadline`, else `createFlowState({ userDeadlineMs })` (unset by default, one second to 365 days), else none: a stop with no deadline waits until it is answered, stopped or cancelled, and the sweeper never ends it. A raw `ctx.suspend` keeps its own `timeoutMs`. At a deadline the sweeper continues the request: an approval reads as a no, and a review or an input throws `SuspensionTimeoutError` into the block. diff --git a/packages/engine/src/stores/testing/parked-gate-conformance.ts b/packages/engine/src/stores/testing/parked-gate-conformance.ts index 13dc19b75b..b63eb17b9e 100644 --- a/packages/engine/src/stores/testing/parked-gate-conformance.ts +++ b/packages/engine/src/stores/testing/parked-gate-conformance.ts @@ -58,7 +58,7 @@ export function createParkedGateConformanceTests(options: CreateParkedGateConfor name: suspensionId, inputSchema: z.any(), outputSchema: z.any(), - execute: async (_i, ctx) => ctx.suspend!({ reason: "human_approval", suspensionId }) + execute: async (_i, ctx) => ctx.suspend!({ reason: "user_approval", suspensionId }) }); const flow = defineFlow({ kind: "parked-gate-conformance", diff --git a/packages/engine/test/abort.test.ts b/packages/engine/test/abort.test.ts index f6f94de086..dbcf6a5892 100644 --- a/packages/engine/test/abort.test.ts +++ b/packages/engine/test/abort.test.ts @@ -1895,7 +1895,7 @@ describe("cross-process abort accepted in the teardown window", () => { inputSchema: z.any(), outputSchema: z.unknown(), execute: async (_input, ctx) => - ctx.suspend!({ reason: "human_approval", message: "Approve?" }) + ctx.suspend!({ reason: "user_approval", message: "Approve?" }) }); const after = handler({ name: "after", @@ -2017,7 +2017,7 @@ describe("a stop accepted in the window before the turn is written parked (FIX-1 name: "gate", inputSchema: z.any(), outputSchema: z.unknown(), - execute: async (_input, ctx) => ctx.suspend!({ reason: "human_approval", message: "Approve?" }) + execute: async (_input, ctx) => ctx.suspend!({ reason: "user_approval", message: "Approve?" }) }); const flow = defineFlow({ kind: "teardown-window-stop", diff --git a/packages/engine/test/background-work-recovery.test.ts b/packages/engine/test/background-work-recovery.test.ts index 58ac65eed6..76c8617f85 100644 --- a/packages/engine/test/background-work-recovery.test.ts +++ b/packages/engine/test/background-work-recovery.test.ts @@ -100,7 +100,7 @@ describe("attached durable background-work recovery", () => { outputSchema: z.unknown(), execute: async (_i, ctx) => ctx.suspend!({ - reason: "human_approval", + reason: "user_approval", message: "Approve?", data: { observed: ctx.getBlockOutput!(bg) } }) @@ -183,7 +183,7 @@ describe("attached durable background-work recovery", () => { outputSchema: z.unknown(), execute: async (_i, ctx) => ctx.suspend!({ - reason: "human_approval", + reason: "user_approval", message: "Approve?", // All iterations share the element block name, so getBlockOutput // resolves to the most recent completed one — non-undefined proves @@ -323,7 +323,7 @@ describe("attached durable background-work recovery — mid-drain fan-out", () = outputSchema: z.unknown(), execute: async (_input, ctx) => { await readyToSuspend.promise; - return ctx.suspend!({ reason: "human_approval", message: "Approve?" }); + return ctx.suspend!({ reason: "user_approval", message: "Approve?" }); } }); diff --git a/packages/engine/test/block-as.test.ts b/packages/engine/test/block-as.test.ts index 9a6cc1a388..6a97c51562 100644 --- a/packages/engine/test/block-as.test.ts +++ b/packages/engine/test/block-as.test.ts @@ -183,7 +183,7 @@ function routerFixture(rename: Rename) { name: "gate", inputSchema: z.any(), outputSchema: z.unknown(), - execute: async (_input, ctx) => ctx.suspend!({ reason: "human_approval", message: "go on?" }), + execute: async (_input, ctx) => ctx.suspend!({ reason: "user_approval", message: "go on?" }), }); const after = handler({ name: "after", @@ -410,7 +410,7 @@ describe("state, routes and lookups by the copy (BR-11, BR-12)", () => { name: "gate", inputSchema: z.any(), outputSchema: z.unknown(), - execute: async (_input, ctx) => ctx.suspend!({ reason: "human_approval", message: "go on?" }), + execute: async (_input, ctx) => ctx.suspend!({ reason: "user_approval", message: "go on?" }), }); const after = handler({ name: "after", diff --git a/packages/engine/test/cascading-router.test.ts b/packages/engine/test/cascading-router.test.ts index 54e3ca8f94..09ec5f2055 100644 --- a/packages/engine/test/cascading-router.test.ts +++ b/packages/engine/test/cascading-router.test.ts @@ -69,7 +69,7 @@ function tree(options: TreeOptions = {}) { execute: async (input, ctx) => { (received[name] ??= []).push(input); if (suspend && received[name]!.length === 1) { - return ctx.suspend!({ reason: "human_approval", message: "page on-call?" }); + return ctx.suspend!({ reason: "user_approval", message: "page on-call?" }); } return { handledBy: name, input }; }, diff --git a/packages/engine/test/checkpoint-durability-provider.test.ts b/packages/engine/test/checkpoint-durability-provider.test.ts index d0a7828e57..de34d700e5 100644 --- a/packages/engine/test/checkpoint-durability-provider.test.ts +++ b/packages/engine/test/checkpoint-durability-provider.test.ts @@ -63,7 +63,7 @@ function makeRecord(overrides?: Partial): SuspensionRecord { flowKind: "chat", actionName: "ask", userId: "user_1", - reason: "human_approval", + reason: "user_approval", message: "Approve?", status: "pending", blockInstanceId: "block_1", diff --git a/packages/engine/test/continuation-item.test.ts b/packages/engine/test/continuation-item.test.ts index e0b95443dc..03e8c06f3c 100644 --- a/packages/engine/test/continuation-item.test.ts +++ b/packages/engine/test/continuation-item.test.ts @@ -51,7 +51,7 @@ function buildCrashFlow(kind: string) { name: "gate", inputSchema: z.any(), outputSchema: z.unknown(), - execute: async (_i, ctx) => ctx.suspend!({ reason: "human_approval", message: "Approve?" }) + execute: async (_i, ctx) => ctx.suspend!({ reason: "user_approval", message: "Approve?" }) }); return defineFlow({ kind, diff --git a/packages/engine/test/debug-suspensions-route.test.ts b/packages/engine/test/debug-suspensions-route.test.ts index 825b980415..1f8677f73b 100644 --- a/packages/engine/test/debug-suspensions-route.test.ts +++ b/packages/engine/test/debug-suspensions-route.test.ts @@ -28,7 +28,7 @@ function makeRecord(overrides: Partial): SuspensionRecord { actionName: "ask", sessionId: SESSION_ID, userId: "user_1", - reason: "human_approval", + reason: "user_approval", message: "Approve?", status: "pending", blockInstanceId: "block_1", diff --git a/packages/engine/test/durability-stores.test.ts b/packages/engine/test/durability-stores.test.ts index 83c3f6ebc1..5bf3496022 100644 --- a/packages/engine/test/durability-stores.test.ts +++ b/packages/engine/test/durability-stores.test.ts @@ -20,7 +20,7 @@ function makeRecord(overrides?: Partial): SuspensionRecord { flowKind: "chat", actionName: "ask", userId: "user_1", - reason: "human_approval", + reason: "user_approval", message: "Approve?", status: "pending", blockInstanceId: "block_1", diff --git a/packages/engine/test/durability-sweeper-person-deadline.test.ts b/packages/engine/test/durability-sweeper-person-deadline.test.ts index b1e3adb5d5..1a0b37c74f 100644 --- a/packages/engine/test/durability-sweeper-person-deadline.test.ts +++ b/packages/engine/test/durability-sweeper-person-deadline.test.ts @@ -24,7 +24,7 @@ function approval(id: string, expiresAt: number): SuspensionRecord { flowKind: "review", actionName: "submit", userId: "devuser", - reason: "human_approval", + reason: "user_approval", message: "Publish?", status: "pending", blockInstanceId: "seq_1", @@ -81,7 +81,7 @@ describe("durability sweeper: a person's deadline", () => { name: "gated", inputSchema: z.any(), outputSchema: z.any(), - execute: async (_i, ctx) => ctx.suspend!({ reason: "human_approval", message: "Publish?", timeoutMs: 500 }) + execute: async (_i, ctx) => ctx.suspend!({ reason: "user_approval", message: "Publish?", timeoutMs: 500 }) }); const flow = defineFlow({ kind: "review", actions: { submit: { block: sequencer({ name: "seq" }).step(gated) } } })({ id: "review" diff --git a/packages/engine/test/durability-sweeper.test.ts b/packages/engine/test/durability-sweeper.test.ts index fd518486be..7d80586af7 100644 --- a/packages/engine/test/durability-sweeper.test.ts +++ b/packages/engine/test/durability-sweeper.test.ts @@ -29,7 +29,7 @@ function makeSuspension( flowKind: "chat", actionName: "run", userId: "user_1", - reason: "human_approval", + reason: "user_approval", message: "approve?", status: "pending", blockInstanceId: "seq_1", diff --git a/packages/engine/test/durable-by-default.test.ts b/packages/engine/test/durable-by-default.test.ts index edda979136..78a458f174 100644 --- a/packages/engine/test/durable-by-default.test.ts +++ b/packages/engine/test/durable-by-default.test.ts @@ -35,7 +35,7 @@ function stoppingFlow() { name: "approve", inputSchema: z.any(), outputSchema: z.any(), - execute: async (_input, ctx) => ctx.suspend!({ reason: "human_approval", message: "Ship it?" }) + execute: async (_input, ctx) => ctx.suspend!({ reason: "user_approval", message: "Ship it?" }) }); const flow = defineFlow({ kind: "durable-default", diff --git a/packages/engine/test/durable-completion-cleanup.test.ts b/packages/engine/test/durable-completion-cleanup.test.ts index dc813733eb..2a4fa73f76 100644 --- a/packages/engine/test/durable-completion-cleanup.test.ts +++ b/packages/engine/test/durable-completion-cleanup.test.ts @@ -27,7 +27,7 @@ function seededSuspension(requestId: string): SuspensionRecord { flowKind: "cleanup-test", actionName: "run", userId: "u1", - reason: "human_approval", + reason: "user_approval", message: "stale gate", status: "approved", blockInstanceId: "seq", diff --git a/packages/engine/test/filesystem-suspension-store.test.ts b/packages/engine/test/filesystem-suspension-store.test.ts index 1cd87bd6eb..7918e3990f 100644 --- a/packages/engine/test/filesystem-suspension-store.test.ts +++ b/packages/engine/test/filesystem-suspension-store.test.ts @@ -22,7 +22,7 @@ function makeRecord(overrides?: Partial): SuspensionRecord { flowKind: "chat", actionName: "ask", userId: "user_1", - reason: "human_approval", + reason: "user_approval", message: "Approve?", status: "pending", blockInstanceId: "block_1", diff --git a/packages/engine/test/flow-instance-ownership.test.ts b/packages/engine/test/flow-instance-ownership.test.ts index d17cee07d1..97be535ac4 100644 --- a/packages/engine/test/flow-instance-ownership.test.ts +++ b/packages/engine/test/flow-instance-ownership.test.ts @@ -587,7 +587,7 @@ describe("record-backed routes read the stored owner", () => { inputSchema: z.object({}), outputSchema: z.unknown(), execute: async (_input, ctx) => - ctx.suspend!({ reason: "human_approval", message: "Approve?" }) + ctx.suspend!({ reason: "user_approval", message: "Approve?" }) }) ) } diff --git a/packages/engine/test/flowstate/durable-createflowstate.test.ts b/packages/engine/test/flowstate/durable-createflowstate.test.ts index 203c6a9bc6..6be93d7843 100644 --- a/packages/engine/test/flowstate/durable-createflowstate.test.ts +++ b/packages/engine/test/flowstate/durable-createflowstate.test.ts @@ -17,7 +17,7 @@ const approvalStep = handler({ outputSchema: z.string(), execute: async (input, ctx) => { const decision = (await ctx.suspend!({ - reason: "human_approval", + reason: "user_approval", message: `Approve ${input.request}?`, resumeSchema: z.object({ approved: z.boolean() }) })) as { approved: boolean }; diff --git a/packages/engine/test/generator-suspension-resume.test.ts b/packages/engine/test/generator-suspension-resume.test.ts index 21aac75822..04cd0981c3 100644 --- a/packages/engine/test/generator-suspension-resume.test.ts +++ b/packages/engine/test/generator-suspension-resume.test.ts @@ -1142,7 +1142,7 @@ describe("generator turn-boundary suspension + resume (FIX-814 PR3)", () => { inputSchema: z.object({ repository: z.string() }), outputSchema: z.object({ repository: z.string() }), execute: async (input, ctx) => { - await ctx.suspend!({ reason: "human_approval", message: `Set the repository to ${input.repository}?` }); + await ctx.suspend!({ reason: "user_approval", message: `Set the repository to ${input.repository}?` }); return { repository: input.repository }; }, }); diff --git a/packages/engine/test/history-interrupted-turn.test.ts b/packages/engine/test/history-interrupted-turn.test.ts index f018854d1b..55b785d50c 100644 --- a/packages/engine/test/history-interrupted-turn.test.ts +++ b/packages/engine/test/history-interrupted-turn.test.ts @@ -154,7 +154,7 @@ describe("history across a turn the host died in", () => { actionName: "run", sessionId: SESSION, userId: "alice", - reason: "human_approval" as const, + reason: "user_approval" as const, message: "Approve?", status, blockInstanceId: "gen_1", diff --git a/packages/engine/test/recorded-value-limit.test.ts b/packages/engine/test/recorded-value-limit.test.ts index 016e2d357d..b6013dc423 100644 --- a/packages/engine/test/recorded-value-limit.test.ts +++ b/packages/engine/test/recorded-value-limit.test.ts @@ -319,7 +319,7 @@ const approve = handler({ inputSchema: z.any(), outputSchema: z.any(), execute: async (input, ctx) => { - await ctx.suspend!({ reason: "human_approval", message: "Approve?" }); + await ctx.suspend!({ reason: "user_approval", message: "Approve?" }); return input; } }); diff --git a/packages/engine/test/request-action-result.test.ts b/packages/engine/test/request-action-result.test.ts index 78b5a4fc5a..307543cb77 100644 --- a/packages/engine/test/request-action-result.test.ts +++ b/packages/engine/test/request-action-result.test.ts @@ -329,7 +329,7 @@ describe("the request record's action result", () => { inputSchema: z.unknown(), outputSchema: z.unknown(), execute: async (_input, ctx) => { - const decision = (await ctx.suspend!({ reason: "human_approval", message: "Approve?" })) as { + const decision = (await ctx.suspend!({ reason: "user_approval", message: "Approve?" })) as { note?: string; }; return { ok: true, note: decision?.note ?? null }; diff --git a/packages/engine/test/request-end-background-failures.test.ts b/packages/engine/test/request-end-background-failures.test.ts index 6295c35510..ce0280a640 100644 --- a/packages/engine/test/request-end-background-failures.test.ts +++ b/packages/engine/test/request-end-background-failures.test.ts @@ -385,7 +385,7 @@ describe("request-end seam · background failures", () => { name: "ask", inputSchema: z.any(), outputSchema: z.unknown(), - execute: (_input, ctx) => ctx.suspend!({ reason: "human_input", message: "Which one?" }) + execute: (_input, ctx) => ctx.suspend!({ reason: "user_input", message: "Which one?" }) }) ) } @@ -409,7 +409,7 @@ describe("request-end seam · background failures", () => { runtimeConfig: { durabilityProvider: provider } }); - expect(endings).toEqual([{ status: "suspended", suspension: expect.objectContaining({ reason: "human_input", suspensionId: expect.any(String) }) }]); + expect(endings).toEqual([{ status: "suspended", suspension: expect.objectContaining({ reason: "user_input", suspensionId: expect.any(String) }) }]); }); it("hands on nothing for a request whose background work succeeded", async () => { diff --git a/packages/engine/test/request-end-seam.test.ts b/packages/engine/test/request-end-seam.test.ts index 3aa248727a..22c08413fd 100644 --- a/packages/engine/test/request-end-seam.test.ts +++ b/packages/engine/test/request-end-seam.test.ts @@ -139,7 +139,7 @@ describe("request-end seam", () => { name: "ask", inputSchema: z.any(), outputSchema: z.unknown(), - execute: (_input, ctx) => ctx.suspend!({ reason: "human_input", message: "Which one?" }) + execute: (_input, ctx) => ctx.suspend!({ reason: "user_input", message: "Which one?" }) }) ) } @@ -163,7 +163,7 @@ describe("request-end seam", () => { runtimeConfig: { durabilityProvider: provider } }); - expect(endings).toEqual([{ status: "suspended", suspension: expect.objectContaining({ reason: "human_input", suspensionId: expect.any(String) }) }]); + expect(endings).toEqual([{ status: "suspended", suspension: expect.objectContaining({ reason: "user_input", suspensionId: expect.any(String) }) }]); }); it("runs on a suspended request before the request can be resumed", async () => { @@ -194,7 +194,7 @@ describe("request-end seam", () => { name: "ask", inputSchema: z.any(), outputSchema: z.unknown(), - execute: (_input, ctx) => ctx.suspend!({ reason: "human_input", message: "Which one?" }) + execute: (_input, ctx) => ctx.suspend!({ reason: "user_input", message: "Which one?" }) }) ) } @@ -254,7 +254,7 @@ describe("request-end seam", () => { name: "ask", inputSchema: z.any(), outputSchema: z.unknown(), - execute: (_input, ctx) => ctx.suspend!({ reason: "human_input", message: "Which one?" }) + execute: (_input, ctx) => ctx.suspend!({ reason: "user_input", message: "Which one?" }) }) ) } diff --git a/packages/engine/test/resume-after-as-tool.test.ts b/packages/engine/test/resume-after-as-tool.test.ts index 6203005f6c..89c4a29c02 100644 --- a/packages/engine/test/resume-after-as-tool.test.ts +++ b/packages/engine/test/resume-after-as-tool.test.ts @@ -19,7 +19,7 @@ const approve = handler({ inputSchema: z.any(), outputSchema: z.any(), execute: async (input, ctx) => { - await ctx.suspend!({ reason: "human_approval", message: "Approve?" }); + await ctx.suspend!({ reason: "user_approval", message: "Approve?" }); return input; } }); diff --git a/packages/engine/test/resume-background-work-containment.test.ts b/packages/engine/test/resume-background-work-containment.test.ts index 6172137b39..0c127590e3 100644 --- a/packages/engine/test/resume-background-work-containment.test.ts +++ b/packages/engine/test/resume-background-work-containment.test.ts @@ -55,7 +55,7 @@ function setup(afterGate: () => void) { outputSchema: z.unknown(), execute: async (input, ctx) => await ctx.suspend!({ - reason: "human_approval", + reason: "user_approval", message: `Approve ${input.amount}?`, data: { amount: input.amount } }) diff --git a/packages/engine/test/resume-expiry.test.ts b/packages/engine/test/resume-expiry.test.ts index 6856e395f4..14d6415915 100644 --- a/packages/engine/test/resume-expiry.test.ts +++ b/packages/engine/test/resume-expiry.test.ts @@ -67,7 +67,7 @@ async function seedSuspended( flowKind: "resume-exp", actionName: "go", userId: "u1", - reason: "human_approval", + reason: "user_approval", message: "Approve?", status: "pending", blockInstanceId: "b1", diff --git a/packages/engine/test/resume-metadata-ingress.test.ts b/packages/engine/test/resume-metadata-ingress.test.ts index cae18da16b..104f425cc7 100644 --- a/packages/engine/test/resume-metadata-ingress.test.ts +++ b/packages/engine/test/resume-metadata-ingress.test.ts @@ -38,7 +38,7 @@ function payoutFlow(kind: string, paid: string[]) { inputSchema: z.any(), outputSchema: z.unknown(), execute: async (_input, ctx) => - ctx.suspend!({ reason: "human_approval", message: "Release the payout?" }) + ctx.suspend!({ reason: "user_approval", message: "Release the payout?" }) }); const pay = handler({ name: "pay", @@ -71,7 +71,7 @@ function rootGateFlow(kind: string, paid: string[]) { inputSchema: z.any(), outputSchema: z.unknown(), execute: async (_input, ctx) => { - await ctx.suspend!({ reason: "human_approval", message: "Release the payout?" }); + await ctx.suspend!({ reason: "user_approval", message: "Release the payout?" }); paid.push(kind); return "paid"; } diff --git a/packages/engine/test/resume-replay-traces-off.test.ts b/packages/engine/test/resume-replay-traces-off.test.ts index aa89971d58..00fffbcb17 100644 --- a/packages/engine/test/resume-replay-traces-off.test.ts +++ b/packages/engine/test/resume-replay-traces-off.test.ts @@ -48,7 +48,7 @@ function buildFlow(): FlowInstance { execute: async (input: { asked: string | null }, ctx) => { if (input.asked === null) return ctx.sequencer!.state; const answer = (await ctx.suspend!({ - reason: "human_input", + reason: "user_input", message: input.asked, allow: ["submit"], })) as string; @@ -194,7 +194,7 @@ describe("resume replay with trace observability off", () => { inputSchema: z.any(), outputSchema: z.any(), execute: async (input: unknown, ctx) => { - const verdict = await ctx.suspend!({ reason: "human_approval", message: "Approve?" }); + const verdict = await ctx.suspend!({ reason: "user_approval", message: "Approve?" }); return { draft: input, verdict }; }, }); @@ -423,7 +423,7 @@ describe("resume replay with trace observability off", () => { outputSchema: z.any(), execute: async (_input, ctx) => { seen.push(ctx.wasRescued(safe)); - await ctx.suspend!({ reason: "human_approval", message: "Approve?" }); + await ctx.suspend!({ reason: "user_approval", message: "Approve?" }); return { rescued: ctx.wasRescued(safe) }; }, }); diff --git a/packages/engine/test/resume-route-refusal.test.ts b/packages/engine/test/resume-route-refusal.test.ts index 8fd86f6a34..f51ca36982 100644 --- a/packages/engine/test/resume-route-refusal.test.ts +++ b/packages/engine/test/resume-route-refusal.test.ts @@ -67,7 +67,7 @@ async function resume( flowKind: "resume-refusal", actionName: "go", userId: "u1", - reason: "human_approval", + reason: "user_approval", message: "Approve?", status: "pending", blockInstanceId: "b1", diff --git a/packages/engine/test/retention.test.ts b/packages/engine/test/retention.test.ts index 72a198d873..a3f393c338 100644 --- a/packages/engine/test/retention.test.ts +++ b/packages/engine/test/retention.test.ts @@ -604,7 +604,7 @@ describe("applyRetentionPolicy", () => { actionName: "run", sessionId: SESSION_ID, userId: "user1", - reason: "human_approval" as const, + reason: "user_approval" as const, message: "Approve?", status, blockInstanceId: "inst", diff --git a/packages/engine/test/retry-p-retry.test.ts b/packages/engine/test/retry-p-retry.test.ts index 206b364b40..da48ca42c5 100644 --- a/packages/engine/test/retry-p-retry.test.ts +++ b/packages/engine/test/retry-p-retry.test.ts @@ -38,7 +38,7 @@ describe("retryWithPolicy (p-retry backed)", () => { // It also must not be relabeled "Retry aborted". let attempts = 0; const suspension = new SuspensionError({ - reason: "human_approval", + reason: "user_approval", suspensionId: "susp_1" }); await expect( @@ -55,7 +55,7 @@ describe("retryWithPolicy (p-retry backed)", () => { it("classifies SuspensionError as non-retryable regardless of policy", () => { const suspension = new SuspensionError({ - reason: "human_approval", + reason: "user_approval", suspensionId: "susp_2" }); expect( diff --git a/packages/engine/test/router-resume.test.ts b/packages/engine/test/router-resume.test.ts index 37f98232d3..7c6af407a2 100644 --- a/packages/engine/test/router-resume.test.ts +++ b/packages/engine/test/router-resume.test.ts @@ -81,7 +81,7 @@ function buildSuspendingBranchFixture() { outputSchema: z.unknown(), execute: async (_input, ctx) => { runs.gate += 1; - return ctx.suspend!({ reason: "human_approval", message: "continue branch A?" }); + return ctx.suspend!({ reason: "user_approval", message: "continue branch A?" }); } }); const after = handler({ @@ -171,7 +171,7 @@ describe("router branch suspends → resume continues the same branch (FIX-814)" inputSchema: z.any(), outputSchema: z.unknown(), execute: async (_input, ctx) => - ctx.suspend!({ reason: "human_approval", message: "proceed?" }) + ctx.suspend!({ reason: "user_approval", message: "proceed?" }) }); const other = handler({ name: "other", @@ -231,7 +231,7 @@ describe("router branch suspends → resume continues the same branch (FIX-814)" inputSchema: z.object({ doubled: z.number() }), outputSchema: z.any(), execute: async (input, ctx) => { - const decision = await ctx.suspend!({ reason: "human_approval", message: "ok?" }); + const decision = await ctx.suspend!({ reason: "user_approval", message: "ok?" }); return { seen: input.doubled, decision }; } }); @@ -339,7 +339,7 @@ describe("router decision cannot be honored on resume (FIX-814)", () => { outputSchema: z.unknown(), execute: async (_input, ctx) => { runs.a += 1; - return ctx.suspend!({ reason: "human_approval", message: "A?" }); + return ctx.suspend!({ reason: "user_approval", message: "A?" }); } }); const branchB = handler({ diff --git a/packages/engine/test/side-chain-rename-continuation.test.ts b/packages/engine/test/side-chain-rename-continuation.test.ts index b6671fa62a..2ce95b831c 100644 --- a/packages/engine/test/side-chain-rename-continuation.test.ts +++ b/packages/engine/test/side-chain-rename-continuation.test.ts @@ -74,7 +74,7 @@ function buildFlow(kind: string, onRun: () => void) { name: "gate", inputSchema: z.any(), outputSchema: z.unknown(), - execute: async (_i, ctx) => ctx.suspend!({ reason: "human_approval", message: "Approve?" }) + execute: async (_i, ctx) => ctx.suspend!({ reason: "user_approval", message: "Approve?" }) }); return defineFlow({ diff --git a/packages/engine/test/stop-suspended.test.ts b/packages/engine/test/stop-suspended.test.ts index 1a9ea7048b..4054cfed85 100644 --- a/packages/engine/test/stop-suspended.test.ts +++ b/packages/engine/test/stop-suspended.test.ts @@ -41,7 +41,7 @@ function parkingFlow( inputSchema: z.any(), outputSchema: z.any(), execute: async (_i, ctx) => { - const answer = await ctx.suspend!({ reason: "human_approval", message: "Approve?" }); + const answer = await ctx.suspend!({ reason: "user_approval", message: "Approve?" }); seen.push("after-approval"); return answer; } @@ -686,7 +686,7 @@ describe("the sweep re-drives a request left parked behind a resolved gate (BR-1 ...gate, requestId: "req_approval", suspensionId: "susp_approval", - reason: "human_approval", + reason: "user_approval", data: undefined, createdAt: gate.createdAt + 2_000, status: "submitted", @@ -926,7 +926,7 @@ describe("the sweep re-drives a gate a person resolved whose turn never continue inputSchema: z.any(), outputSchema: z.any(), execute: async (_i, ctx) => { - const answer = await ctx.suspend!({ reason: "human_approval", message: "Approve?", ...(allow ? { allow } : {}) }); + const answer = await ctx.suspend!({ reason: "user_approval", message: "Approve?", ...(allow ? { allow } : {}) }); answers.push(answer); seen.push("after-gate"); return { answer: answer === SUSPENSION_SKIPPED ? "skipped" : answer }; @@ -1516,7 +1516,7 @@ describe("an approval past its deadline: the turn carries on as if it is no long flowKind: "parking", actionName: "approve", userId: USER, - reason: "human_input", + reason: "user_input", message: "Fill this in", allow: ["submit"], status: "pending", diff --git a/packages/engine/test/stream-routes-external-dispatch.test.ts b/packages/engine/test/stream-routes-external-dispatch.test.ts index 9d974a504f..150a9cb75d 100644 --- a/packages/engine/test/stream-routes-external-dispatch.test.ts +++ b/packages/engine/test/stream-routes-external-dispatch.test.ts @@ -290,7 +290,7 @@ describe("external dispatch — enqueue failure at the route boundary (FIX-828)" flowKind: FLOW_KIND, actionName: "run", userId: "u_1", - reason: "human_approval", + reason: "user_approval", message: "Approve?", status: "pending", blockInstanceId: "b1", diff --git a/packages/engine/test/suspension-resume-generalized.test.ts b/packages/engine/test/suspension-resume-generalized.test.ts index 18093d203b..00e8499185 100644 --- a/packages/engine/test/suspension-resume-generalized.test.ts +++ b/packages/engine/test/suspension-resume-generalized.test.ts @@ -79,7 +79,7 @@ describe("submit resolution", () => { outputSchema: z.unknown(), execute: async (_input, ctx) => { const answer = await ctx.suspend!({ - reason: "human_input", + reason: "user_input", message: "What is your name?", resumeSchema: { type: "object", properties: { name: { type: "string" } } }, allow: ["submit"] @@ -129,7 +129,7 @@ describe("skip resolution", () => { outputSchema: z.unknown(), execute: async (_input, ctx) => { const answer = await ctx.suspend!({ - reason: "human_input", + reason: "user_input", message: "Optional feedback?", allow: ["submit", "skip"] }); @@ -172,7 +172,7 @@ describe("skip resolution", () => { outputSchema: z.object({ ok: z.boolean() }), execute: async (_input, ctx) => { const answer = await ctx.suspend!({ - reason: "human_input", + reason: "user_input", message: "Gate A (optional)?", allow: ["submit", "skip"] }); @@ -185,7 +185,7 @@ describe("skip resolution", () => { inputSchema: z.any(), outputSchema: z.object({ ok: z.boolean() }), execute: async (_input, ctx) => { - await ctx.suspend!({ reason: "human_approval", message: "Gate B?" }); + await ctx.suspend!({ reason: "user_approval", message: "Gate B?" }); return { ok: true }; } }); @@ -253,7 +253,7 @@ describe("resume route — allow enforcement & payload validation", () => { flowKind: "gen", actionName: "go", userId: "u1", - reason: "human_input", + reason: "user_input", message: "Provide input", status: "pending", blockInstanceId: "b1", @@ -370,7 +370,7 @@ describe("resume route — allow enforcement & payload validation", () => { // must still resolve — validation only runs when the resumer sends data. const { stores, provider } = createDurableStores(); const requestId = await seedSuspended(stores, provider, { - reason: "human_approval", + reason: "user_approval", allow: ["approve", "reject"], resumeSchema: { type: "object", properties: { note: { type: "string" } } } }); diff --git a/packages/engine/test/suspension-resume.test.ts b/packages/engine/test/suspension-resume.test.ts index 0393e84d21..540478f2a1 100644 --- a/packages/engine/test/suspension-resume.test.ts +++ b/packages/engine/test/suspension-resume.test.ts @@ -34,7 +34,7 @@ describe("ctx.suspend() — initial suspension", () => { outputSchema: z.unknown(), execute: async (input, ctx) => { const decision = await ctx.suspend!({ - reason: "human_approval", + reason: "user_approval", message: `Approve transfer of $${input.amount}?`, data: { amount: input.amount } }); @@ -74,7 +74,7 @@ describe("ctx.suspend() — initial suspension", () => { const suspensions = await provider.listSuspended({ status: "pending" }); expect(suspensions.length).toBe(1); - expect(suspensions[0].reason).toBe("human_approval"); + expect(suspensions[0].reason).toBe("user_approval"); expect(suspensions[0].requestId).toBe(result.requestId); const suspItem = result.items.find((i) => i.type === "suspension"); @@ -88,7 +88,7 @@ describe("ctx.suspend() — initial suspension", () => { outputSchema: z.unknown(), execute: async (_input, ctx) => { return ctx.suspend!({ - reason: "human_input", + reason: "user_input", message: "Please provide feedback", resumeSchema: { type: "object", properties: { feedback: { type: "string" } } } }); @@ -119,7 +119,7 @@ describe("ctx.suspend() — initial suspension", () => { const suspItem = result.items.find((i) => i.type === "suspension") as any; expect(suspItem).toBeDefined(); - expect(suspItem.reason).toBe("human_input"); + expect(suspItem.reason).toBe("user_input"); expect(suspItem.message).toBe("Please provide feedback"); expect(suspItem.resumeSchema).toBeDefined(); }); @@ -130,7 +130,7 @@ describe("ctx.suspend() — initial suspension", () => { inputSchema: z.any(), outputSchema: z.unknown(), execute: async (_input, ctx) => - ctx.suspend!({ reason: "human_input", title: "Deploy failed", message: "It failed twice.\n\n- Retry it?" }) + ctx.suspend!({ reason: "user_input", title: "Deploy failed", message: "It failed twice.\n\n- Retry it?" }) }); const flow = defineFlow({ kind: "suspend-title-test", @@ -152,7 +152,7 @@ describe("ctx.suspend() — initial suspension", () => { inputSchema: z.any(), outputSchema: z.unknown(), execute: async (_input, ctx) => - ctx.suspend!({ reason: "human_approval", message: "Approve?" }) + ctx.suspend!({ reason: "user_approval", message: "Approve?" }) }); const flow = defineFlow({ @@ -208,7 +208,7 @@ describe("resume after suspension", () => { execute: async (input, ctx) => { suspendCallCount++; const decision = await ctx.suspend!({ - reason: "human_approval", + reason: "user_approval", message: `Approve $${input.amount}?` }); return { approved: true, decision }; @@ -295,7 +295,7 @@ describe("resume after suspension", () => { outputSchema: z.unknown(), execute: async (_input, ctx) => { return ctx.suspend!({ - reason: "human_approval", + reason: "user_approval", message: "Approve?" }); } @@ -361,7 +361,7 @@ describe("suspension without durability provider", () => { outputSchema: z.unknown(), execute: async (_input, ctx) => { return ctx.suspend!({ - reason: "human_input", + reason: "user_input", message: "Provide input" }); } @@ -443,7 +443,7 @@ describe("same-request continuation (FIX-811)", () => { inputSchema: z.object({ amount: z.number(), prepared: z.boolean() }), outputSchema: z.unknown(), execute: async (_input, ctx) => - ctx.suspend!({ reason: "human_approval", message: "Approve?" }) + ctx.suspend!({ reason: "user_approval", message: "Approve?" }) }); const confirmStep = handler({ name: "confirmStep", @@ -548,7 +548,7 @@ describe("same-request continuation (FIX-811)", () => { inputSchema: z.any(), outputSchema: z.unknown(), execute: async (_input, ctx) => - ctx.suspend!({ reason: "human_approval", message: "Approve?" }) + ctx.suspend!({ reason: "user_approval", message: "Approve?" }) }); const flow = defineFlow({ kind: "fix811-resume-item", @@ -608,7 +608,7 @@ describe("same-request continuation (FIX-811)", () => { inputSchema: z.object({ doubled: z.number() }), outputSchema: z.unknown(), execute: async (_input, ctx) => - ctx.suspend!({ reason: "human_approval", message: "Approve?" }) + ctx.suspend!({ reason: "user_approval", message: "Approve?" }) }); const readerStep = handler({ name: "readerStep", @@ -663,14 +663,14 @@ describe("same-request continuation (FIX-811)", () => { inputSchema: z.any(), outputSchema: z.unknown(), execute: async (_input, ctx) => - ctx.suspend!({ reason: "human_approval", message: "Gate A?" }) + ctx.suspend!({ reason: "user_approval", message: "Gate A?" }) }); const gateB = handler({ name: "gateB", inputSchema: z.any(), outputSchema: z.unknown(), execute: async (_input, ctx) => - ctx.suspend!({ reason: "human_approval", message: "Gate B?" }) + ctx.suspend!({ reason: "user_approval", message: "Gate B?" }) }); const done = handler({ name: "done", @@ -732,8 +732,8 @@ describe("same-request continuation (FIX-811)", () => { inputSchema: z.any(), outputSchema: z.unknown(), execute: async (_input, ctx) => { - const first = await ctx.suspend!({ reason: "human_approval", message: "first?", suspensionId: "gate-1" }); - const second = await ctx.suspend!({ reason: "human_approval", message: "second?", suspensionId: "gate-2" }); + const first = await ctx.suspend!({ reason: "user_approval", message: "first?", suspensionId: "gate-1" }); + const second = await ctx.suspend!({ reason: "user_approval", message: "second?", suspensionId: "gate-2" }); return { first, second }; } }); @@ -774,8 +774,8 @@ describe("same-request continuation (FIX-811)", () => { inputSchema: z.any(), outputSchema: z.unknown(), execute: async (_input, ctx) => { - const first = await ctx.suspend!({ reason: "human_approval", message: "first?" }); - const second = await ctx.suspend!({ reason: "human_approval", message: "second?" }); + const first = await ctx.suspend!({ reason: "user_approval", message: "first?" }); + const second = await ctx.suspend!({ reason: "user_approval", message: "second?" }); return { first, second }; } }); @@ -828,7 +828,7 @@ describe("same-request continuation (FIX-811)", () => { name: "gate", inputSchema: z.any(), outputSchema: z.unknown(), - execute: async (_i, ctx) => ctx.suspend!({ reason: "human_approval", message: "Approve?" }) + execute: async (_i, ctx) => ctx.suspend!({ reason: "user_approval", message: "Approve?" }) }); const flow = defineFlow({ kind: "fix811-crash", @@ -898,7 +898,7 @@ describe("same-request continuation (FIX-811)", () => { charges += 1; return { charged: true }; }); - return ctx.suspend!({ reason: "human_approval", message: "Approve?" }); + return ctx.suspend!({ reason: "user_approval", message: "Approve?" }); } }); const flow = defineFlow({ @@ -954,7 +954,7 @@ describe("same-request continuation (FIX-811)", () => { outputSchema: z.unknown(), execute: async (_input, ctx) => ctx.suspend!({ - reason: "human_approval", + reason: "user_approval", message: "Approve?", data: { tally: (ctx.sequencer!.state as { tally: number }).tally } }) @@ -1015,7 +1015,7 @@ describe("same-request continuation (FIX-811)", () => { inputSchema: z.object({ request: z.string() }), outputSchema: z.string(), execute: async (_input, ctx) => { - await ctx.suspend!({ reason: "human_approval", message: "Approve?" }); + await ctx.suspend!({ reason: "user_approval", message: "Approve?" }); return "done"; } }); @@ -1069,7 +1069,7 @@ describe("same-request continuation (FIX-811)", () => { name: "gate", inputSchema: z.object({ request: z.string() }), outputSchema: z.unknown(), - execute: async (_input, ctx) => ctx.suspend!({ reason: "human_approval", message: "Approve?" }) + execute: async (_input, ctx) => ctx.suspend!({ reason: "user_approval", message: "Approve?" }) }); const flow = defineFlow({ kind: "fix811-usermsg-crash", @@ -1125,7 +1125,7 @@ describe("same-request continuation (FIX-811)", () => { outputSchema: z.unknown(), execute: async (_i, ctx) => { ctx.emit.message("Please approve"); - return ctx.suspend!({ reason: "human_approval", message: "Approve?" }); + return ctx.suspend!({ reason: "user_approval", message: "Approve?" }); } }); const done = handler({ @@ -1187,13 +1187,13 @@ describe("same-request continuation (FIX-811)", () => { name: "gateA", inputSchema: z.any(), outputSchema: z.unknown(), - execute: async (_input, ctx) => ctx.suspend!({ reason: "human_approval", message: "Gate A?" }) + execute: async (_input, ctx) => ctx.suspend!({ reason: "user_approval", message: "Gate A?" }) }); const gateB = handler({ name: "gateB", inputSchema: z.any(), outputSchema: z.unknown(), - execute: async (_input, ctx) => ctx.suspend!({ reason: "human_approval", message: "Gate B?" }) + execute: async (_input, ctx) => ctx.suspend!({ reason: "user_approval", message: "Gate B?" }) }); const done = handler({ name: "done", @@ -1270,7 +1270,7 @@ describe("same-request continuation (FIX-811)", () => { inputSchema: z.any(), outputSchema: z.unknown(), execute: async (_input, ctx) => - ctx.suspend!({ reason: "human_approval", message: "Approve?" }) + ctx.suspend!({ reason: "user_approval", message: "Approve?" }) }); const report = handler({ name: "report", @@ -1318,7 +1318,7 @@ describe("same-request continuation (FIX-811)", () => { inputSchema: z.any(), outputSchema: z.unknown(), execute: async (_input, ctx) => - ctx.suspend!({ reason: "human_approval", message: "Approve?" }) + ctx.suspend!({ reason: "user_approval", message: "Approve?" }) }); const flow = defineFlow({ kind: "fix811-ponr", @@ -1374,7 +1374,7 @@ describe("same-request continuation (FIX-811)", () => { name: "approvalStep", inputSchema: z.any(), outputSchema: z.unknown(), - execute: async (_input, ctx) => ctx.suspend!({ reason: "human_approval", message: "Approve?" }) + execute: async (_input, ctx) => ctx.suspend!({ reason: "user_approval", message: "Approve?" }) }); const flow = defineFlow({ kind: "fix811-ponr-lease", @@ -1442,7 +1442,7 @@ describe("same-request continuation (FIX-811)", () => { name: "gate", inputSchema: z.any(), outputSchema: z.unknown(), - execute: async (_i, ctx) => ctx.suspend!({ reason: "human_approval", message: "Approve?" }) + execute: async (_i, ctx) => ctx.suspend!({ reason: "user_approval", message: "Approve?" }) }); const flow = defineFlow({ kind: "fix811-crash-lease", @@ -1516,7 +1516,7 @@ describe("same-request continuation (FIX-811)", () => { outputSchema: z.unknown(), execute: async (_i, ctx) => { ctx.emit.message("Working on it"); - return ctx.suspend!({ reason: "human_approval", message: "Approve?" }); + return ctx.suspend!({ reason: "user_approval", message: "Approve?" }); } }); const flow = defineFlow({ @@ -1585,7 +1585,7 @@ describe("same-request continuation (FIX-811)", () => { outputSchema: z.unknown(), execute: async (_input, ctx) => { const decision = await ctx.suspend!({ - reason: "human_approval", + reason: "user_approval", message: "Approve?" }); return { approved: true, decision }; @@ -1642,7 +1642,7 @@ describe("same-request continuation (FIX-811)", () => { inputSchema: z.any(), outputSchema: z.unknown(), execute: async (_input, ctx) => - ctx.suspend!({ reason: "human_approval", message: "Approve?" }) + ctx.suspend!({ reason: "user_approval", message: "Approve?" }) }); const flow = defineFlow({ kind: "fix811-seq-continuity", @@ -1696,7 +1696,7 @@ describe("same-request continuation (FIX-811)", () => { inputSchema: z.any(), outputSchema: z.unknown(), execute: async (_input, ctx) => - ctx.suspend!({ reason: "human_approval", message: "Approve?" }) + ctx.suspend!({ reason: "user_approval", message: "Approve?" }) }); const flow = defineFlow({ kind: "fix811-pretransition-revert", diff --git a/packages/engine/test/transports/host.test.ts b/packages/engine/test/transports/host.test.ts index 7bc5eb18f5..8fdb670147 100644 --- a/packages/engine/test/transports/host.test.ts +++ b/packages/engine/test/transports/host.test.ts @@ -92,7 +92,7 @@ describe("createInboundTransportHost", () => { const gate = handler({ name: "gate", execute: async (_input: { value: string }, ctx): Promise => - ctx.suspend!({ reason: "human_approval", message: "approve?" }) + ctx.suspend!({ reason: "user_approval", message: "approve?" }) }); registry.register( defineFlow({ diff --git a/packages/engine/test/transports/resume-concurrency.test.ts b/packages/engine/test/transports/resume-concurrency.test.ts index 790fd779ff..ac5e870d38 100644 --- a/packages/engine/test/transports/resume-concurrency.test.ts +++ b/packages/engine/test/transports/resume-concurrency.test.ts @@ -93,7 +93,7 @@ function buildHost( name: "approve", inputSchema: z.any(), outputSchema: z.unknown(), - execute: async (_input, ctx) => ctx.suspend!({ reason: "human_approval", message: "Go?" }) + execute: async (_input, ctx) => ctx.suspend!({ reason: "user_approval", message: "Go?" }) }) ) .step(handler({ name: "afterApproval", inputSchema: z.any(), outputSchema: z.any(), execute: block("resumed") })) diff --git a/packages/engine/test/wait-for-user.test.ts b/packages/engine/test/wait-for-user.test.ts index 8d7dcbe349..e17778a2e4 100644 --- a/packages/engine/test/wait-for-user.test.ts +++ b/packages/engine/test/wait-for-user.test.ts @@ -146,14 +146,14 @@ describe("waitForUser: what the stop records", () => { const flow = askingFlow(seen); const h = harness(flow); const none = await park(h, flow, { options: { kind: "review", prompt: "Look at this." } }); - expect(none.gate).toMatchObject({ reason: "human_input", kind: "review", message: "Look at this.", allow: ["submit"] }); + expect(none.gate).toMatchObject({ reason: "user_input", kind: "review", message: "Look at this.", allow: ["submit"] }); expect(none.gate.expiresAt).toBeUndefined(); const host = harness(flow); host.runtimeConfig.userDeadlineMs = 60_000; // The host's setting reaches the request through its request host. const set = await park(host, flow, { options: { kind: "approval", prompt: "Ship?" } }); - expect(set.gate).toMatchObject({ reason: "human_approval", kind: "approval" }); + expect(set.gate).toMatchObject({ reason: "user_approval", kind: "approval" }); expect(set.gate.expiresAt! - set.gate.createdAt).toBeGreaterThanOrEqual(59_000); // A caller that runs the action directly, with no request host wired, keeps the deadline it set. @@ -523,8 +523,8 @@ describe("a stop of a task's run waiting on a user", () => { await h.drain(); expect((await h.stores.request.get(requestId))?.status).toBe("aborted"); expect(seen).toEqual(["work"]); - expect(stopsAtItsGate({ source: "http" }, { reason: "human_input" })).toBe(false); + expect(stopsAtItsGate({ source: "http" }, { reason: "user_input" })).toBe(false); expect(stopsAtItsGate({ source: "task" }, { reason: "external_event" })).toBe(false); - expect(stopsAtItsGate({ source: "task" }, { reason: "human_approval" })).toBe(true); + expect(stopsAtItsGate({ source: "task" }, { reason: "user_approval" })).toBe(true); }); }); diff --git a/packages/engine/test/wait-own-session.test.ts b/packages/engine/test/wait-own-session.test.ts index 9aa97f61ea..fca5be38a4 100644 --- a/packages/engine/test/wait-own-session.test.ts +++ b/packages/engine/test/wait-own-session.test.ts @@ -84,7 +84,7 @@ describe("a session's open stop for a person", () => { }); it("is the request parked on a person, and never a wait, another session's stop, or the asking request's own", async () => { - const person: Gate = { requestId: "r_stopped", sessionId: "s1", suspensionId: "ask", reason: "human_input" }; + const person: Gate = { requestId: "r_stopped", sessionId: "s1", suspensionId: "ask", reason: "user_input" }; expect(await waits([queued, person]).userStop!()).toEqual({ requestId: "r_stopped" }); // A wait parked in the session is no person's stop: a queued message never holds another. expect(await waits([queued]).userStop!()).toBeUndefined(); diff --git a/packages/engine/test/wait-resume.test.ts b/packages/engine/test/wait-resume.test.ts index bf5ff4e85b..79b014f681 100644 --- a/packages/engine/test/wait-resume.test.ts +++ b/packages/engine/test/wait-resume.test.ts @@ -506,7 +506,7 @@ describe("wait gate: park, and resume from the waiting turn's own conversation", inputSchema: z.object({}).passthrough(), outputSchema: z.any(), execute: async (_input, ctx) => - ctx.suspend!({ reason: "human_approval", suspensionId: GATE_ID }) + ctx.suspend!({ reason: "user_approval", suspensionId: GATE_ID }) }); const touchBlock = handler({ name: "touch", diff --git a/packages/integration-tests/src/scenarios/request-action-result.test.ts b/packages/integration-tests/src/scenarios/request-action-result.test.ts index a13e147705..33c39f395d 100644 --- a/packages/integration-tests/src/scenarios/request-action-result.test.ts +++ b/packages/integration-tests/src/scenarios/request-action-result.test.ts @@ -32,7 +32,7 @@ const gate = handler({ inputSchema: z.unknown(), outputSchema: z.unknown(), execute: async (_input, ctx) => { - const decision = (await ctx.suspend!({ reason: "human_input", message: "Answer?" })) as { answer?: string }; + const decision = (await ctx.suspend!({ reason: "user_input", message: "Answer?" })) as { answer?: string }; return { ok: true, answer: decision?.answer ?? null }; } }); diff --git a/packages/integration-tests/src/scenarios/resume-takes-its-turn.test.ts b/packages/integration-tests/src/scenarios/resume-takes-its-turn.test.ts index 8b663530be..ebd79264e4 100644 --- a/packages/integration-tests/src/scenarios/resume-takes-its-turn.test.ts +++ b/packages/integration-tests/src/scenarios/resume-takes-its-turn.test.ts @@ -52,7 +52,7 @@ function harness() { name: "approve", inputSchema: z.any(), outputSchema: z.unknown(), - execute: async (_input, ctx) => ctx.suspend!({ reason: "human_approval", message: "Send it?" }) + execute: async (_input, ctx) => ctx.suspend!({ reason: "user_approval", message: "Send it?" }) }) ) .step( diff --git a/packages/orchestration/README.md b/packages/orchestration/README.md index 024f1a4e59..5e8938db6e 100644 --- a/packages/orchestration/README.md +++ b/packages/orchestration/README.md @@ -751,7 +751,7 @@ session. Until then the row stays `in_progress`, and `keptOpenBy` says why: A row with no lease is never reclaimed, so a waiting task isn't run twice. A resume continues the same attempt. A stop for a person (a `ctx.waitForUser()`, or a `ctx.suspend()` -for `human_approval` or `human_input`) is also mirrored on the row as a question. +for `user_approval` or `user_input`) is also mirrored on the row as a question. **A task waiting on a user.** `getTask` and `listTasks` show `keptOpenBy` on a running task, and its `questions`. A stop for a person is one with `source.kind: "suspension"`: its diff --git a/packages/orchestration/test/inbox.test.ts b/packages/orchestration/test/inbox.test.ts index 3112b88dc3..349ef654d5 100644 --- a/packages/orchestration/test/inbox.test.ts +++ b/packages/orchestration/test/inbox.test.ts @@ -403,13 +403,13 @@ describe("suspensionTruthOf: what a session's suspended requests record", () => it("keeps a user's pending stop, marks a task run's, and drops a resumed one, another reason and another status", () => { const requests = [ request("r1", "task", [ - { type: "suspension", suspensionId: "a", reason: "human_approval" }, - { type: "suspension", suspensionId: "b", reason: "human_input" }, + { type: "suspension", suspensionId: "a", reason: "user_approval" }, + { type: "suspension", suspensionId: "b", reason: "user_input" }, { type: "suspension_resume", suspensionId: "b" }, { type: "suspension", suspensionId: "c", reason: "external_event" }, ]), - request("r2", "http", [{ type: "suspension", suspensionId: "d", reason: "human_input" }]), - request("r3", "http", [{ type: "suspension", suspensionId: "e", reason: "human_input" }], "completed"), + request("r2", "http", [{ type: "suspension", suspensionId: "d", reason: "user_input" }]), + request("r3", "http", [{ type: "suspension", suspensionId: "e", reason: "user_input" }], "completed"), ]; expect(suspensionTruthOf("s", requests)).toEqual([ { suspensionId: "a", sessionId: "s", requestId: "r1", taskRun: true }, diff --git a/packages/orchestration/test/task-board/lease-recovery.test.ts b/packages/orchestration/test/task-board/lease-recovery.test.ts index 3bb22f7f9c..2bee63c562 100644 --- a/packages/orchestration/test/task-board/lease-recovery.test.ts +++ b/packages/orchestration/test/task-board/lease-recovery.test.ts @@ -231,7 +231,7 @@ describe("a worker that parks on a suspension stops holding its task", () => { execute: async () => { throw new SuspensionError({ suspensionId: "needs-a-human", - reason: "human_approval", + reason: "user_approval", }); }, }) as TaskWorker; diff --git a/packages/orchestration/test/task-board/settles-when-its-work-is-over.test.ts b/packages/orchestration/test/task-board/settles-when-its-work-is-over.test.ts index 49fbb03fb2..fdbf1784b1 100644 --- a/packages/orchestration/test/task-board/settles-when-its-work-is-over.test.ts +++ b/packages/orchestration/test/task-board/settles-when-its-work-is-over.test.ts @@ -423,7 +423,7 @@ describe("the claim gate settles a task when its work is over", () => { it("a resume keeps the attempt's start on its run link", async () => { // The gate links the run again on a resume: the same attempt, started when it was. const h = await harness(); - h.setBehaviour(async (ctx) => ({ resumedWith: await ctx.suspend!({ reason: "human_input", message: "waiting" }) })); + h.setBehaviour(async (ctx) => ({ resumedWith: await ctx.suspend!({ reason: "user_input", message: "waiting" }) })); const first = await h.run(); const startedAt = (await h.row())!.run!.startedAt; expect(startedAt).toEqual(expect.any(Number)); @@ -439,7 +439,7 @@ describe("the claim gate settles a task when its work is over", () => { async (later) => { const h = await harness(); h.setBehaviour(async (ctx) => { - const resolution = await ctx.suspend!({ reason: "human_input", message: "which one?" }); + const resolution = await ctx.suspend!({ reason: "user_input", message: "which one?" }); return { resumedWith: resolution }; }); const first = await h.run(); @@ -462,7 +462,7 @@ describe("the claim gate settles a task when its work is over", () => { it("a parked request stopped while it waits for a user cancels its task on that attempt (FIX-2129): never left waiting, never asked again", async () => { const h = await harness(); - h.setBehaviour(async (ctx) => ctx.suspend!({ reason: "human_input", message: "which one?" })); + h.setBehaviour(async (ctx) => ctx.suspend!({ reason: "user_input", message: "which one?" })); const first = await h.run(); expect(await h.row()).toMatchObject({ status: "in_progress", keptOpenBy: "wait", questions: [{ ask: { kind: "input", prompt: "which one?" } }] }); @@ -475,8 +475,8 @@ describe("the claim gate settles a task when its work is over", () => { }); it.each([ - ["human_input", true], - ["human_approval", true], + ["user_input", true], + ["user_approval", true], ["external_event", false], ] as const)("a %s stop keeps its claim with no lease, and the resume settles it on attempt 1", async (reason, forPerson) => { const h = await harness(); diff --git a/packages/orchestration/test/tasks/notice-defer.test.ts b/packages/orchestration/test/tasks/notice-defer.test.ts index 1a2a2aa75f..927ff2224b 100644 --- a/packages/orchestration/test/tasks/notice-defer.test.ts +++ b/packages/orchestration/test/tasks/notice-defer.test.ts @@ -83,7 +83,7 @@ function host(defer: () => boolean, options: HostOptions = {}) { } heard.push(notice); await options.gate; - if (options.park === true) await ctx.suspend!({ reason: "human_approval", message: "Tell the customer?" }); + if (options.park === true) await ctx.suspend!({ reason: "user_approval", message: "Tell the customer?" }); return {}; } }), diff --git a/packages/orchestration/test/tasks/wait-fixture.ts b/packages/orchestration/test/tasks/wait-fixture.ts index c5ad7f97b1..a7caad9447 100644 --- a/packages/orchestration/test/tasks/wait-fixture.ts +++ b/packages/orchestration/test/tasks/wait-fixture.ts @@ -265,7 +265,7 @@ export function waitFlow( name: "await_approval", inputSchema: z.object({}).passthrough(), outputSchema: z.any(), - execute: async (_input, ctx) => ({ answer: await ctx.suspend!({ reason: "human_approval", message: "Go ahead?" }) }) + execute: async (_input, ctx) => ({ answer: await ctx.suspend!({ reason: "user_approval", message: "Go ahead?" }) }) }); const finishTaskTool = handler({ name: "finish_task", diff --git a/packages/react/README.md b/packages/react/README.md index b4dde48c6b..764468cdad 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -267,7 +267,7 @@ Derives pending and resolved suspensions from `session.items`. Pairs each `suspe ```tsx const { pending, approve, reject, error } = useSuspensions(session, { - reasons: ["human_approval"], // optional filter + reasons: ["user_approval"], // optional filter }); // Render headless approval UI @@ -309,7 +309,7 @@ Returns `{ kind, value, setValue, setField, fields, options, errors, canSubmit, ### ``, ``, `` -The default cards for `human_input` suspensions, all thin views over `useSuspensionForm`: `QuestionRenderer` (free-text answer), `SelectionRenderer` (single choice from a `z.enum`, or multi from `z.array(z.enum)`), and `SchemaFormRenderer` (a flat object of scalars and enums, one control per property). `ItemRenderer` auto-picks one for a `human_input` suspension by `render.component` hint → reason → `resumeSchema` shape; `human_approval` suspensions get `ApprovalRenderer`. A registered `renderers.suspension` overrides this, and `renderers.suspension: false` suppresses inline cards. +The default cards for `user_input` suspensions, all thin views over `useSuspensionForm`: `QuestionRenderer` (free-text answer), `SelectionRenderer` (single choice from a `z.enum`, or multi from `z.array(z.enum)`), and `SchemaFormRenderer` (a flat object of scalars and enums, one control per property). `ItemRenderer` auto-picks one for a `user_input` suspension by `render.component` hint → reason → `resumeSchema` shape; `user_approval` suspensions get `ApprovalRenderer`. A registered `renderers.suspension` overrides this, and `renderers.suspension: false` suppresses inline cards. ### `useApproval(item, options?)` diff --git a/packages/react/src/components/ItemRenderer.ts b/packages/react/src/components/ItemRenderer.ts index d5cf16fe6d..daeeae73d1 100644 --- a/packages/react/src/components/ItemRenderer.ts +++ b/packages/react/src/components/ItemRenderer.ts @@ -162,7 +162,7 @@ function renderBlockToolOutputFallback(item: ToolOutputItem): ReactNode { * 1. `item.render.component` — if it names a registered `renderers.component` * entry, the author's custom component wins (the escape hatch for schemas * richer than the bounded default can handle). - * 2. by `reason`: `human_approval` → the approve/reject card; `human_input` → + * 2. by `reason`: `user_approval` → the approve/reject card; `user_input` → * by `resumeSchema` shape (free-text question, enum selection, or flat form). * 3. fallback to the approval card. * diff --git a/packages/react/src/components/QuestionRenderer.ts b/packages/react/src/components/QuestionRenderer.ts index ffa98fd0ea..44805ea9a2 100644 --- a/packages/react/src/components/QuestionRenderer.ts +++ b/packages/react/src/components/QuestionRenderer.ts @@ -1,7 +1,7 @@ /** * Built-in default card for a clarifying-question suspension (FIX-849). * - * Chosen by `ItemRenderer` for a `human_input` suspension whose `resumeSchema` is + * Chosen by `ItemRenderer` for a `user_input` suspension whose `resumeSchema` is * a single string (or absent). Renders the question and a free-text box; submit * sends the raw string back as the resume payload. Logic is delegated to * `useSuspensionForm`. Once resolved it collapses to a one-line receipt. diff --git a/packages/react/src/components/SchemaFormRenderer.ts b/packages/react/src/components/SchemaFormRenderer.ts index 6749790c67..3b78b9af11 100644 --- a/packages/react/src/components/SchemaFormRenderer.ts +++ b/packages/react/src/components/SchemaFormRenderer.ts @@ -1,7 +1,7 @@ /** * Built-in default card for a flat-form suspension (FIX-849). * - * Chosen by `ItemRenderer` for a `human_input` suspension whose `resumeSchema` is + * Chosen by `ItemRenderer` for a `user_input` suspension whose `resumeSchema` is * a flat object of scalars and enums. Renders one control per property (text / * number / checkbox / select), validates via `useSuspensionForm`, and submits the * collected object. A single flat object can mix a free-text field, a selection, diff --git a/packages/react/src/components/SelectionRenderer.ts b/packages/react/src/components/SelectionRenderer.ts index 2b574ff341..0073c1efae 100644 --- a/packages/react/src/components/SelectionRenderer.ts +++ b/packages/react/src/components/SelectionRenderer.ts @@ -1,7 +1,7 @@ /** * Built-in default card for a selection suspension (FIX-849). * - * Chosen by `ItemRenderer` for a `human_input` suspension whose `resumeSchema` is + * Chosen by `ItemRenderer` for a `user_input` suspension whose `resumeSchema` is * a top-level enum (single choice → radio buttons) or an array of an enum (multi * choice → checkboxes). Submit sends the chosen value(s). Logic is delegated to * `useSuspensionForm`; once resolved it collapses to a one-line receipt. diff --git a/packages/react/src/hooks/useSuspensionForm.ts b/packages/react/src/hooks/useSuspensionForm.ts index 4ec40d6ace..fc53966478 100644 --- a/packages/react/src/hooks/useSuspensionForm.ts +++ b/packages/react/src/hooks/useSuspensionForm.ts @@ -120,13 +120,13 @@ export type SuspensionShape = "approval" | "question" | "selection" | "form"; * Pick the default card shape for a suspension from its `reason`, `allow`, and * `resumeSchema`. Shared by the built-in `ItemRenderer` dispatch and the polished * UI dispatcher so the two surfaces never diverge: - * - `human_approval` → approval. - * - `human_input` whose permitted actions don't include `submit` → approval. + * - `user_approval` → approval. + * - `user_input` whose permitted actions don't include `submit` → approval. * This covers a legacy record persisted before `allow` existed (the resume * route treats a missing `allow` as binary approve/reject) and an explicitly - * binary `human_input` gate — rendering a submit-only card for either would + * binary `user_input` gate — rendering a submit-only card for either would * show a button the server 409s. - * - otherwise `human_input` → form (flat object) / selection (enum) / question + * - otherwise `user_input` → form (flat object) / selection (enum) / question * (everything else, including a schema richer than the bounded set). * Pure — no hooks. */ @@ -135,7 +135,7 @@ export function suspensionShape(item: { resumeSchema?: Record; allow?: ResumeAction[]; }): SuspensionShape { - if (item.reason !== "human_input") return "approval"; + if (item.reason !== "user_input") return "approval"; // No submit path → render the binary approval card so the gate stays resolvable. if (item.allow === undefined || !item.allow.includes("submit")) return "approval"; const analysis = analyzeResumeSchema(item.resumeSchema); diff --git a/packages/react/src/hooks/useSuspensions.ts b/packages/react/src/hooks/useSuspensions.ts index 3079a516be..59dbb79866 100644 --- a/packages/react/src/hooks/useSuspensions.ts +++ b/packages/react/src/hooks/useSuspensions.ts @@ -31,7 +31,7 @@ import type { SessionView } from "./useSession"; export interface UseSuspensionsOptions { /** Restrict to a single request's suspensions. Default: all in session.items. */ requestId?: string; - /** Restrict to specific reasons (e.g. ["human_approval"]). Default: all reasons. */ + /** Restrict to specific reasons (e.g. ["user_approval"]). Default: all reasons. */ reasons?: SuspensionReason[]; } @@ -213,7 +213,7 @@ export function useSuspensions( const { requestId, reasons } = options; // Key the reasons array by value, not reference: an inline literal - // (`useSuspensions(session, { reasons: ["human_approval"] })`) is a new array + // (`useSuspensions(session, { reasons: ["user_approval"] })`) is a new array // every render, which would force deriveSuspensions to recompute each time. const reasonsKey = reasons === undefined ? undefined : reasons.join(" "); const { suspensions, pending } = useMemo( diff --git a/packages/react/test/suspension-dispatch.test.ts b/packages/react/test/suspension-dispatch.test.ts index 2075498684..43806ae8bc 100644 --- a/packages/react/test/suspension-dispatch.test.ts +++ b/packages/react/test/suspension-dispatch.test.ts @@ -2,7 +2,7 @@ /** * ItemRenderer dispatch for suspension items (FIX-849). * - * Verifies the default-renderer selection: a `human_input` suspension routes to + * Verifies the default-renderer selection: a `user_input` suspension routes to * the form/selection/question card by schema shape; a registered * `render.component` wins over the reason default; and a registered * `renderers.suspension` (or `false`) still overrides everything. @@ -27,7 +27,7 @@ function suspension(overrides: Partial = {}): SuspensionItem { provenance, ts: 0, suspensionId: "sus_1", - reason: "human_input", + reason: "user_input", message: "Tell us more", ...overrides } as SuspensionItem; @@ -58,22 +58,22 @@ describe("ItemRenderer suspension dispatch", () => { expect(container.querySelector('input[type="radio"]')).not.toBeNull(); }); - it("renders the question card for a free-text human_input", () => { + it("renders the question card for a free-text user_input", () => { const { container } = renderItem(suspension({ allow: ["submit"] })); expect(container.querySelector('[data-suspension-input="question"]')).not.toBeNull(); }); - it("renders the approval card for a human_approval suspension", () => { - const { getByText } = renderItem(suspension({ reason: "human_approval", allow: ["approve", "reject"] })); + it("renders the approval card for a user_approval suspension", () => { + const { getByText } = renderItem(suspension({ reason: "user_approval", allow: ["approve", "reject"] })); expect(getByText("Approve")).not.toBeNull(); expect(getByText("Reject")).not.toBeNull(); }); - it("renders the approval card for a legacy human_input with no allow set", () => { - // A human_input gate persisted before `allow` existed has no submit path + it("renders the approval card for a legacy user_input with no allow set", () => { + // A user_input gate persisted before `allow` existed has no submit path // (the route treats missing allow as binary), so it must render approve/reject // rather than a submit-only card the server would 409. - const { getByText, container } = renderItem(suspension({ reason: "human_input", allow: undefined })); + const { getByText, container } = renderItem(suspension({ reason: "user_input", allow: undefined })); expect(getByText("Approve")).not.toBeNull(); expect(container.querySelector('[data-suspension-input="question"]')).toBeNull(); }); diff --git a/packages/react/test/useSuspensionForm.test.ts b/packages/react/test/useSuspensionForm.test.ts index 004003f5c8..7941e3fcad 100644 --- a/packages/react/test/useSuspensionForm.test.ts +++ b/packages/react/test/useSuspensionForm.test.ts @@ -32,7 +32,7 @@ function suspension(overrides: Partial = {}): SuspensionItem { provenance, ts: 0, suspensionId: "sus_1", - reason: "human_input", + reason: "user_input", message: "Tell us more", ...overrides } as SuspensionItem; @@ -96,26 +96,26 @@ describe("analyzeResumeSchema", () => { }); describe("suspensionShape", () => { - it("routes human_input to a card by schema shape when submit is allowed", () => { - expect(suspensionShape({ reason: "human_input", allow: ["submit"] })).toBe("question"); + it("routes user_input to a card by schema shape when submit is allowed", () => { + expect(suspensionShape({ reason: "user_input", allow: ["submit"] })).toBe("question"); expect( - suspensionShape({ reason: "human_input", allow: ["submit"], resumeSchema: { type: "string", enum: ["a"] } }) + suspensionShape({ reason: "user_input", allow: ["submit"], resumeSchema: { type: "string", enum: ["a"] } }) ).toBe("selection"); expect( suspensionShape({ - reason: "human_input", + reason: "user_input", allow: ["submit"], resumeSchema: { type: "object", properties: { a: { type: "string" } } } }) ).toBe("form"); }); - it("falls back to the approval card for human_approval and for binary/legacy human_input", () => { - expect(suspensionShape({ reason: "human_approval", allow: ["approve", "reject"] })).toBe("approval"); - // Legacy human_input with no allow (route treats as binary) → approval. - expect(suspensionShape({ reason: "human_input" })).toBe("approval"); - // Explicitly binary human_input (no submit path) → approval, not a submit card. - expect(suspensionShape({ reason: "human_input", allow: ["approve", "reject"] })).toBe("approval"); + it("falls back to the approval card for user_approval and for binary/legacy user_input", () => { + expect(suspensionShape({ reason: "user_approval", allow: ["approve", "reject"] })).toBe("approval"); + // Legacy user_input with no allow (route treats as binary) → approval. + expect(suspensionShape({ reason: "user_input" })).toBe("approval"); + // Explicitly binary user_input (no submit path) → approval, not a submit card. + expect(suspensionShape({ reason: "user_input", allow: ["approve", "reject"] })).toBe("approval"); }); }); diff --git a/packages/react/test/useSuspensions.test.ts b/packages/react/test/useSuspensions.test.ts index d76b310b19..8165019b21 100644 --- a/packages/react/test/useSuspensions.test.ts +++ b/packages/react/test/useSuspensions.test.ts @@ -33,7 +33,7 @@ function suspension(overrides: Partial = {}): SuspensionItem { provenance, ts: 0, suspensionId: "sus_1", - reason: "human_approval", + reason: "user_approval", message: "Approve this draft?", ...overrides } as SuspensionItem; @@ -110,14 +110,14 @@ describe("deriveSuspensions", () => { it("filters by reasons", () => { const items = [ - suspension({ id: "a", suspensionId: "sus_a", reason: "human_approval" }), - suspension({ id: "b", suspensionId: "sus_b", reason: "human_input" }) + suspension({ id: "a", suspensionId: "sus_a", reason: "user_approval" }), + suspension({ id: "b", suspensionId: "sus_b", reason: "user_input" }) ]; - const result = deriveSuspensions(items, { reasons: ["human_input"] }); + const result = deriveSuspensions(items, { reasons: ["user_input"] }); expect(result.suspensions).toHaveLength(1); - expect(result.suspensions[0].item.reason).toBe("human_input"); + expect(result.suspensions[0].item.reason).toBe("user_input"); }); it("preserves stream order", () => { @@ -144,7 +144,7 @@ describe("deriveSuspensions", () => { it("surfaces the suspension's allow set, defaulting to binary for older items (FIX-849)", () => { const withAllow = deriveSuspensions([ - suspension({ reason: "human_input", allow: ["submit", "skip"] }) + suspension({ reason: "user_input", allow: ["submit", "skip"] }) ]); expect(withAllow.suspensions[0].allow).toEqual(["submit", "skip"]); diff --git a/packages/shift-manager/src/components/flow-state/suspension-card.tsx b/packages/shift-manager/src/components/flow-state/suspension-card.tsx index 7b39b359d1..5b8aa13075 100644 --- a/packages/shift-manager/src/components/flow-state/suspension-card.tsx +++ b/packages/shift-manager/src/components/flow-state/suspension-card.tsx @@ -22,8 +22,8 @@ import { useSuspensionResolution } from "./suspension-resolution"; * author-supplied component (for schemas richer than the bounded defaults) * before any shape dispatch. * - * `human_approval` keeps the existing `Approval` card (which derives its own - * resolved state). For `human_input`, this derives resolved state once from the + * `user_approval` keeps the existing `Approval` card (which derives its own + * resolved state). For `user_input`, this derives resolved state once from the * session stream and passes it to the chosen non-binary card. */ export function SuspensionCard({ item }: { item: SuspensionItem }) { diff --git a/packages/shift-manager/src/surfaces/Inbox.tsx b/packages/shift-manager/src/surfaces/Inbox.tsx index b88bf058c4..7720302ce1 100644 --- a/packages/shift-manager/src/surfaces/Inbox.tsx +++ b/packages/shift-manager/src/surfaces/Inbox.tsx @@ -92,7 +92,7 @@ function askOfItem(item: InboxItem): Ask { suspensionId: hold.source.suspensionId, requestId: hold.source.requestId, suspensionStatus: "pending", - reason: approval ? "human_approval" : "human_input", + reason: approval ? "user_approval" : "user_input", message: hold.ask.prompt, ...(hold.ask.title !== undefined ? { title: hold.ask.title } : {}), allow: approval ? ["approve", "reject"] : ["submit"], diff --git a/packages/shift-manager/teams/devteam/ask.mts b/packages/shift-manager/teams/devteam/ask.mts index 60250cd425..22c925c7a3 100644 --- a/packages/shift-manager/teams/devteam/ask.mts +++ b/packages/shift-manager/teams/devteam/ask.mts @@ -11,7 +11,7 @@ * the one `file` and `drain` run in, and which a session listing returns), * opened naming the EM worker if it isn't there yet ({@link openWorkerSession}), * run the asking door as the given user until it suspends on a stock - * `human_approval`. The answer is not this module's business: it arrives + * `user_approval`. The answer is not this module's business: it arrives * through the engine's resume route, the one Shift Manager's Inbox uses. * * **Once per feature, per store, claimed atomically.** Before it runs anything diff --git a/packages/shift-manager/teams/devteam/host.mts b/packages/shift-manager/teams/devteam/host.mts index e606518674..85e06bd28a 100644 --- a/packages/shift-manager/teams/devteam/host.mts +++ b/packages/shift-manager/teams/devteam/host.mts @@ -359,7 +359,7 @@ const forCoding = handler({ * * **A repository waits for the user.** Which remote a project's code is * cloned from is the user's to say, so `setRepository`, and `createProject` - * with a `repository`, pause on a stock `human_approval` before the write. + * with a `repository`, pause on a stock `user_approval` before the write. * Approve writes it; Deny throws out of the tool before the write runs, and * nothing changes. Without durable execution the tool refuses rather than * writing unasked. @@ -432,7 +432,7 @@ export function chiefOfStaffProjectTools(blocks: ProjectBlocks, workstreams: Wor * is the block under `.as()`; `fire` is a sequencer, because it waits for an * approval first. * - * **A fire waits for the user.** It pauses on a stock `human_approval` + * **A fire waits for the user.** It pauses on a stock `user_approval` * naming the worker before the write; Deny throws out of the tool before the * write runs, and nothing changes. Without durable execution the tool refuses * rather than firing unasked. @@ -458,7 +458,7 @@ export function chiefOfStaffRosterTools(installation: WorkerInstallation) { }; } -/** The approval a fire waits on: a stock `human_approval` naming the worker. Returns on Approve; on Deny the runtime throws out of it. */ +/** The approval a fire waits on: a stock `user_approval` naming the worker. Returns on Approve; on Deny the runtime throws out of it. */ const askFire = handler({ name: "devforce-cos-ask-fire", inputSchema: z.object({ id: z.string() }).passthrough(), @@ -466,7 +466,7 @@ const askFire = handler({ execute: async (input: { id: string }, ctx: BlockContext) => { // A host without durable execution refuses at the stop itself (FIX-2063). await ctx.suspend!({ - reason: "human_approval", + reason: "user_approval", message: `Fire worker "${input.id}"?`, data: { worker: input.id }, allow: ["approve", "reject"], @@ -484,7 +484,7 @@ const repositoryAskInputSchema = z .passthrough(); /** - * The approval a repository write waits on: a stock `human_approval` naming + * The approval a repository write waits on: a stock `user_approval` naming * the project and the remote, with any user or password left out of what * Inbox shows. Returns on Approve; on Deny the runtime throws out of it. */ @@ -502,7 +502,7 @@ function askRepository( const repository = input.repository == null ? null : redactRemote(input.repository); // A host without durable execution refuses at the stop itself (FIX-2063). await ctx.suspend!({ - reason: "human_approval", + reason: "user_approval", message: repository === null ? `Clear the repository of project "${project}"? Its coding work will run on its files.` diff --git a/packages/shift-manager/teams/devteam/workforce/flows/workers/em.mts b/packages/shift-manager/teams/devteam/workforce/flows/workers/em.mts index 4077c169c7..2809f61c2b 100644 --- a/packages/shift-manager/teams/devteam/workforce/flows/workers/em.mts +++ b/packages/shift-manager/teams/devteam/workforce/flows/workers/em.mts @@ -266,7 +266,7 @@ export function defineEmWorkerFlow(options: EmWorkerFlowOptions) { }); /** - * The stock `human_approval` suspension, naming the feature. + * The stock `user_approval` suspension, naming the feature. * * Approve makes `ctx.suspend` return; reject makes it throw * `SuspensionRejectedError`. Either way the gate returns a decision the @@ -279,7 +279,7 @@ export function defineEmWorkerFlow(options: EmWorkerFlowOptions) { execute: async (input: z.infer, ctx: BlockContext) => { try { await ctx.suspend!({ - reason: "human_approval", + reason: "user_approval", message: `File ${input.issue}: ${input.goal} and start the coder on it?`, allow: ["approve", "reject"], }); diff --git a/packages/shift-manager/test/devteam-repository-ask.test.ts b/packages/shift-manager/test/devteam-repository-ask.test.ts index 970f294737..9abccab462 100644 --- a/packages/shift-manager/test/devteam-repository-ask.test.ts +++ b/packages/shift-manager/test/devteam-repository-ask.test.ts @@ -132,7 +132,7 @@ async function ask( expect((await runtime.stores.request.get(started.requestId!))?.status).toBe("suspended"); const pending = (await runtime.stores.suspensions.list({ status: "pending" })) as SuspensionRecord[]; expect(pending).toHaveLength(1); - expect(pending[0]!.reason).toBe("human_approval"); + expect(pending[0]!.reason).toBe("user_approval"); return { requestId: started.requestId!, suspension: pending[0]! }; } diff --git a/packages/shift-manager/test/fixtures/ask-lab/asker.mts b/packages/shift-manager/test/fixtures/ask-lab/asker.mts index b78e71e8d5..595df956cf 100644 --- a/packages/shift-manager/test/fixtures/ask-lab/asker.mts +++ b/packages/shift-manager/test/fixtures/ask-lab/asker.mts @@ -3,7 +3,7 @@ * anything. * * Two doors, both durable, both ending in the framework's stock - * `human_approval` suspension: + * `user_approval` suspension: * * - `work` — the task entry a coordinator's routed task is handed to * (Workforce's `workerTaskEntry`), in the delegate's own session for that @@ -90,7 +90,7 @@ const hear = handler({ execute: async (input, ctx) => { if (input.message === ASKER_REFUSED_LINE) throw new Error("This worker won't take that line."); if (input.message === ASKER_SLOW_LINE) await slow; - if (input.message === ASKER_GATED_LINE) await ctx.suspend!({ reason: "human_approval", message: `Approve: ${input.message}` }); + if (input.message === ASKER_GATED_LINE) await ctx.suspend!({ reason: "user_approval", message: `Approve: ${input.message}` }); ctx.emit.message(heardLine(input.message)); return { heard: input.message }; }, @@ -105,8 +105,8 @@ const gate = handler({ try { await ctx.suspend!( input.detail === undefined - ? { reason: "human_approval", message: `Approve: ${input.what}` } - : { reason: "human_approval", title: `Approve: ${input.what}`, message: input.detail }, + ? { reason: "user_approval", message: `Approve: ${input.what}` } + : { reason: "user_approval", title: `Approve: ${input.what}`, message: input.detail }, ); return { what: input.what, approved: true }; } catch (error) { diff --git a/packages/shift-manager/test/fixtures/run-lab/lab.mts b/packages/shift-manager/test/fixtures/run-lab/lab.mts index 35ede454af..78a47afdb0 100644 --- a/packages/shift-manager/test/fixtures/run-lab/lab.mts +++ b/packages/shift-manager/test/fixtures/run-lab/lab.mts @@ -194,7 +194,7 @@ const scriptedRun = handler({ }), ]); } - if (script.ask !== undefined) await ctx.suspend!({ reason: "human_approval", message: script.ask }); + if (script.ask !== undefined) await ctx.suspend!({ reason: "user_approval", message: script.ask }); const resources = (ctx as { resources?: Record }).resources ?? {}; const plan = resources[OBSERVED_PLAN] as Upsertable | undefined; diff --git a/packages/shift-manager/test/inbox-tasks.test.ts b/packages/shift-manager/test/inbox-tasks.test.ts index bafeb86613..8ee6ed7942 100644 --- a/packages/shift-manager/test/inbox-tasks.test.ts +++ b/packages/shift-manager/test/inbox-tasks.test.ts @@ -28,7 +28,7 @@ describe("FROM THE SESSION and the replies (BR-18, I17, I18)", () => { const early = tool("Read", { path: "a.ts" }, "12 lines"); const calls = [tool("Bash", { command: "pnpm test" }, "31 passed"), tool("Edit", { path: "b.ts" }, { ok: true }), tool("Write", { path: "c.ts" }, "")]; const before = user("before the ask"); - const ask = item({ type: "suspension", suspensionId: "s1", reason: "human_approval", message: "Ship it?" }); + const ask = item({ type: "suspension", suspensionId: "s1", reason: "user_approval", message: "Ship it?" }); const after = tool("Read", { path: "after.ts" }, "not before the ask"); const reply = user("go ahead"); // The read hands items back out of order; the derivation must not care. @@ -46,12 +46,12 @@ describe("FROM THE SESSION and the replies (BR-18, I17, I18)", () => { it("an ask with nothing before it has no calls, and its session's earlier lines are not replies", () => { const earlier = user("filed this"); - const ask = item({ type: "suspension", suspensionId: "s2", reason: "human_approval" }); + const ask = item({ type: "suspension", suspensionId: "s2", reason: "user_approval" }); expect(askSessionOf([ask, earlier], ask)).toEqual({ calls: [], replies: [] }); }); it("an ask its session's read doesn't hold places nothing, rather than reading every item as before it", () => { - const ask = item({ type: "suspension", suspensionId: "s3", reason: "human_approval" }); + const ask = item({ type: "suspension", suspensionId: "s3", reason: "user_approval" }); expect(askSessionOf([tool("Read", { path: "x" }, "1"), user("hi")], ask)).toBeNull(); }); }); diff --git a/packages/shift-manager/test/roster-screen.test.tsx b/packages/shift-manager/test/roster-screen.test.tsx index bca19c3b43..ed7483741a 100644 --- a/packages/shift-manager/test/roster-screen.test.tsx +++ b/packages/shift-manager/test/roster-screen.test.tsx @@ -52,7 +52,7 @@ const ask = (workerId: string, suspensionId: string, message: string): Ask => flowId: workerId, parentSessionId: null, kind: "approval", - item: { suspensionId, requestId: `r_${suspensionId}`, reason: "human_approval", message }, + item: { suspensionId, requestId: `r_${suspensionId}`, reason: "user_approval", message }, since: 0, unanswerable: null, }) as unknown as Ask; diff --git a/packages/shift-manager/test/send.test.ts b/packages/shift-manager/test/send.test.ts index ab82154d53..c4b04e8fd5 100644 --- a/packages/shift-manager/test/send.test.ts +++ b/packages/shift-manager/test/send.test.ts @@ -112,7 +112,7 @@ describe("sendTurn", () => { status: "suspended", items: [ { requestId: "req_door", role: "user", type: "message" }, - { requestId: "req_door", type: "suspension", reason: "human_approval", suspensionId: "susp_fire" }, + { requestId: "req_door", type: "suspension", reason: "user_approval", suspensionId: "susp_fire" }, ], }); await expect(sendTurn(client, TARGET, "fire eng.coder", { pollMs: 1 })).resolves.toEqual({ requestId: "req_door", suspended: true, stopped: "ask" }); @@ -124,7 +124,7 @@ describe("sendTurn", () => { status: "suspended", items: [ { requestId: "req_door", role: "user", type: "message" }, - { requestId: "req_other", type: "suspension", reason: "human_approval", suspensionId: "susp_other" }, + { requestId: "req_other", type: "suspension", reason: "user_approval", suspensionId: "susp_other" }, { requestId: "req_door", type: "suspension", reason: "external_event", suspensionId: "susp_deploy" }, ], }); @@ -137,7 +137,7 @@ describe("sendTurn", () => { status: "suspended", items: [ { requestId: "req_door", role: "user", type: "message" }, - { requestId: "req_door", type: "suspension", reason: "human_approval", suspensionId: "susp_fire" }, + { requestId: "req_door", type: "suspension", reason: "user_approval", suspensionId: "susp_fire" }, { requestId: "req_door", type: "suspension_resume", suspensionId: "susp_fire" }, { requestId: "req_door", type: "suspension", reason: "external_event", suspensionId: "susp_deploy" }, ], @@ -148,12 +148,12 @@ describe("sendTurn", () => { // Every state a suspended poll can be followed by, and what the composer is told for each. describe("what a suspended turn is still stopped on, once the session is read", () => { const line = { requestId: "req_door", role: "user", type: "message" }; - const ask = (id: string, reason = "human_approval") => ({ requestId: "req_door", type: "suspension", reason, suspensionId: id }); + const ask = (id: string, reason = "user_approval") => ({ requestId: "req_door", type: "suspension", reason, suspensionId: id }); const resume = (id: string) => ({ requestId: "req_door", type: "suspension_resume", suspensionId: id }); const cases: Array<[string, Item[], "ask" | "wait" | null]> = [ ["answered between the poll and the read, nothing pending: plain delivered", [line, ask("s1"), resume("s1")], null], ["a wait answered, then a user's ask pending: in Inbox", [line, ask("s1", "external_event"), resume("s1"), ask("s2")], "ask"], - ["a user's input pending: in Inbox", [line, ask("s1", "human_input")], "ask"], + ["a user's input pending: in Inbox", [line, ask("s1", "user_input")], "ask"], ["another request's ask pending, this one's answered: not this line's", [line, ask("s1"), resume("s1"), { ...ask("s9"), requestId: "req_other" }], null], ]; for (const [what, items, stopped] of cases) { @@ -173,7 +173,7 @@ describe("sendTurn", () => { // Inbox pages every suspension item; so does this, or an older pending ask is missed. it("a pending ask older than a page of later suspension events: still in Inbox", async () => { const others = Array.from({ length: 250 }, (_, i) => [ - { requestId: `req_${i}`, type: "suspension", reason: "human_approval", suspensionId: `o${i}` }, + { requestId: `req_${i}`, type: "suspension", reason: "user_approval", suspensionId: `o${i}` }, { requestId: `req_${i}`, type: "suspension_resume", suspensionId: `o${i}` }, ]).flat(); const { client } = stubClients({ status: "suspended", items: [line, ask("s1"), ...others] }); @@ -190,7 +190,7 @@ describe("sendTurn", () => { // The read is the request's own: one call, however long the session's history. it("classifies from the request's own items in one read, not by paging the session's history", async () => { const others = Array.from({ length: 2_000 }, (_, i) => [ - { requestId: `req_${i}`, type: "suspension", reason: "human_approval", suspensionId: `o${i}` }, + { requestId: `req_${i}`, type: "suspension", reason: "user_approval", suspensionId: `o${i}` }, { requestId: `req_${i}`, type: "suspension_resume", suspensionId: `o${i}` }, ]).flat(); const { client, reads } = stubClients({ status: "suspended", items: [line, ...others, ask("s1")] }); diff --git a/packages/store-postgres/test/background-work-recovery.test.ts b/packages/store-postgres/test/background-work-recovery.test.ts index 5ec0c74e08..cc252b742b 100644 --- a/packages/store-postgres/test/background-work-recovery.test.ts +++ b/packages/store-postgres/test/background-work-recovery.test.ts @@ -116,7 +116,7 @@ describe("completed background `.sideChain()` trace replays across a cold restar inputSchema: z.any(), outputSchema: z.unknown(), execute: async (_input, ctx) => - ctx.suspend!({ reason: "human_approval", message: "approve?" }) + ctx.suspend!({ reason: "user_approval", message: "approve?" }) }); const flow = defineFlow({ diff --git a/packages/store-postgres/test/stores.test.ts b/packages/store-postgres/test/stores.test.ts index 942891f6b5..68d2854975 100644 --- a/packages/store-postgres/test/stores.test.ts +++ b/packages/store-postgres/test/stores.test.ts @@ -1375,7 +1375,7 @@ describe("PostgreSQL store adapter", () => { flowKind: "chat", actionName: "ask", userId: "user_1", - reason: "human_approval", + reason: "user_approval", message: "Approve?", status: "pending", blockInstanceId: "block_1", diff --git a/packages/store-sqlite/test/background-work-recovery.test.ts b/packages/store-sqlite/test/background-work-recovery.test.ts index 713322f2aa..2a01e4720c 100644 --- a/packages/store-sqlite/test/background-work-recovery.test.ts +++ b/packages/store-sqlite/test/background-work-recovery.test.ts @@ -115,7 +115,7 @@ describe("completed background `.sideChain()` trace replays across a cold restar inputSchema: z.any(), outputSchema: z.unknown(), execute: async (_input, ctx) => - ctx.suspend!({ reason: "human_approval", message: "approve?" }) + ctx.suspend!({ reason: "user_approval", message: "approve?" }) }); const flow = defineFlow({ diff --git a/packages/store-sqlite/test/completed-trace-persistence.test.ts b/packages/store-sqlite/test/completed-trace-persistence.test.ts index e748eee016..7e247c0bfd 100644 --- a/packages/store-sqlite/test/completed-trace-persistence.test.ts +++ b/packages/store-sqlite/test/completed-trace-persistence.test.ts @@ -76,7 +76,7 @@ describe("completed block traces persist on a suspended request (FIX-839)", () = inputSchema: z.any(), outputSchema: z.unknown(), execute: async (_input, ctx) => - ctx.suspend!({ reason: "human_approval", message: "approve?" }) + ctx.suspend!({ reason: "user_approval", message: "approve?" }) }); const flow = defineFlow({ kind: "trace-persist", diff --git a/packages/store-sqlite/test/continuation-item-persistence.test.ts b/packages/store-sqlite/test/continuation-item-persistence.test.ts index de8fe5a09c..a3a4f8a84f 100644 --- a/packages/store-sqlite/test/continuation-item-persistence.test.ts +++ b/packages/store-sqlite/test/continuation-item-persistence.test.ts @@ -59,7 +59,7 @@ describe("continuation item persists and round-trips through SQLite (FIX-865)", name: "gate", inputSchema: z.any(), outputSchema: z.unknown(), - execute: async (_i, ctx) => ctx.suspend!({ reason: "human_approval", message: "Approve?" }) + execute: async (_i, ctx) => ctx.suspend!({ reason: "user_approval", message: "Approve?" }) }); const flow = defineFlow({ kind: "sqlite-continuation-item", diff --git a/packages/store-sqlite/test/multigate-cold-restart.test.ts b/packages/store-sqlite/test/multigate-cold-restart.test.ts index 77f7d6aed8..ce117b7b47 100644 --- a/packages/store-sqlite/test/multigate-cold-restart.test.ts +++ b/packages/store-sqlite/test/multigate-cold-restart.test.ts @@ -84,13 +84,13 @@ describe("multi-gate sequencer resume across a cold restart", () => { name: "gateA", inputSchema: z.any(), outputSchema: z.unknown(), - execute: async (_input, ctx) => ctx.suspend!({ reason: "human_approval", message: "Gate A?" }) + execute: async (_input, ctx) => ctx.suspend!({ reason: "user_approval", message: "Gate A?" }) }); const gateB = handler({ name: "gateB", inputSchema: z.any(), outputSchema: z.unknown(), - execute: async (_input, ctx) => ctx.suspend!({ reason: "human_approval", message: "Gate B?" }) + execute: async (_input, ctx) => ctx.suspend!({ reason: "user_approval", message: "Gate B?" }) }); const done = handler({ name: "done", diff --git a/packages/store-sqlite/test/router-resume-cold-restart.test.ts b/packages/store-sqlite/test/router-resume-cold-restart.test.ts index e384ef55ac..4856cd2a5d 100644 --- a/packages/store-sqlite/test/router-resume-cold-restart.test.ts +++ b/packages/store-sqlite/test/router-resume-cold-restart.test.ts @@ -96,7 +96,7 @@ describe("router branch resume across a cold restart (SQLite)", () => { inputSchema: z.any(), outputSchema: z.unknown(), execute: async (_input, ctx) => - ctx.suspend!({ reason: "human_approval", message: "continue branch A?" }) + ctx.suspend!({ reason: "user_approval", message: "continue branch A?" }) }); const after = handler({ name: "after", diff --git a/packages/store-sqlite/test/stores.test.ts b/packages/store-sqlite/test/stores.test.ts index a76fac6ea5..3ca899f746 100644 --- a/packages/store-sqlite/test/stores.test.ts +++ b/packages/store-sqlite/test/stores.test.ts @@ -1301,7 +1301,7 @@ describe("SQLite store adapter", () => { flowKind: "chat", actionName: "ask", userId: "user_1", - reason: "human_approval", + reason: "user_approval", message: "Approve?", status: "pending", blockInstanceId: "block_1", diff --git a/packages/ui/README.md b/packages/ui/README.md index 6836b39c10..4412344596 100644 --- a/packages/ui/README.md +++ b/packages/ui/README.md @@ -52,10 +52,10 @@ Generic, framework-agnostic components. No dependency on `@flow-state-dev/*`. | `sandbox` | Source/preview tab wrapper for JSX artifacts using JSXPreview and CodeBlock | | `info-card` | Generative-UI info card: title, optional image, fact rows. Pairs with `emitInfoCard` | | `link-card` | Generative-UI link card: rich preview for an external URL. Pairs with `emitLinkCard` | -| `approval` | Polished Approve / Reject card for a `human_approval` suspension. Collapses to a receipt on resolve | -| `question` | Free-text answer card for a `human_input` suspension | -| `selection` | Single (enum) or multi (array of enum) choice card for a `human_input` suspension | -| `form` | Flat-object form card for a `human_input` suspension — one control per scalar/enum property | +| `approval` | Polished Approve / Reject card for a `user_approval` suspension. Collapses to a receipt on resolve | +| `question` | Free-text answer card for a `user_input` suspension | +| `selection` | Single (enum) or multi (array of enum) choice card for a `user_input` suspension | +| `form` | Flat-object form card for a `user_input` suspension — one control per scalar/enum property | | `model-badge` | Small pill showing the `ModelIdentity` that answered. Renders nothing when the model is undefined | | `audit-annotation` | Compact card for `responseAuditor` findings: severity indicators, per-analyzer scores, evidence. Fed by the `audit-annotation` component item | @@ -80,7 +80,7 @@ import { chatAssistantRenderers } from "@/components/flow-state/chat-assistant"; Sources are excluded from the renderer map (`source: false`) — render them grouped separately via `` to display as a collapsed list after the message thread. -`chatAssistantRenderers` maps the `suspension` slot to a `SuspensionCard` that picks the right card by the suspension's reason and `resumeSchema` shape: the `Approval` card for `human_approval`, and the `Question` / `Selection` / `Form` cards for `human_input` (free text, a choice from an enum, or a flat-object form). All four are thin views over `useSuspensionForm` / `useApproval`. Nested or union schemas fall outside the flat-form boundary — name your own component via the suspension's `render.component` hint for those. +`chatAssistantRenderers` maps the `suspension` slot to a `SuspensionCard` that picks the right card by the suspension's reason and `resumeSchema` shape: the `Approval` card for `user_approval`, and the `Question` / `Selection` / `Form` cards for `user_input` (free text, a choice from an enum, or a flat-object form). All four are thin views over `useSuspensionForm` / `useApproval`. Nested or union schemas fall outside the flat-form boundary — name your own component via the suspension's `render.component` hint for those. When a `task-board-meta` item includes a `collectionId`, the default registry renders `TaskPlan` for that collection. `task-change` items are not rendered on their own. `planAndExecute` and `supervisor` emit `task-change` and `task-board-meta`. diff --git a/packages/ui/registry/components/form.stories.tsx b/packages/ui/registry/components/form.stories.tsx index ff5e69ced2..bcd7c5b0a2 100644 --- a/packages/ui/registry/components/form.stories.tsx +++ b/packages/ui/registry/components/form.stories.tsx @@ -13,7 +13,7 @@ const SUSPENSION_ID = "susp-form"; // under its label, not just a bare name. const item = suspensionItem({ suspensionId: SUSPENSION_ID, - reason: "human_input", + reason: "user_input", message: "Before we route this ticket, a couple of quick questions.", resumeSchema: { type: "object", diff --git a/packages/ui/registry/components/question.stories.tsx b/packages/ui/registry/components/question.stories.tsx index f6961c1982..9ac263e8b2 100644 --- a/packages/ui/registry/components/question.stories.tsx +++ b/packages/ui/registry/components/question.stories.tsx @@ -9,7 +9,7 @@ const SUSPENSION_ID = "susp-question"; const item = suspensionItem({ suspensionId: SUSPENSION_ID, - reason: "human_input", + reason: "user_input", message: "What should we know about the launch deadline?", resumeSchema: { type: "string", minLength: 1 }, allow: ["submit"], @@ -52,7 +52,7 @@ export const Skippable: Story = { ; requestId?: string; - /** Defaults to `"human_approval"`; pass `"human_input"` for the non-binary cards. */ + /** Defaults to `"user_approval"`; pass `"user_input"` for the non-binary cards. */ reason?: SuspensionReason; /** JSON Schema describing the expected resume payload (drives question/form/selection). */ resumeSchema?: Record; @@ -174,7 +174,7 @@ export function suspensionItem( message = "Approve this action?", data, requestId = "req-1", - reason = "human_approval", + reason = "user_approval", resumeSchema, allow, } = options; diff --git a/packages/workforce/README.md b/packages/workforce/README.md index b5be7da584..16f0ff5594 100644 --- a/packages/workforce/README.md +++ b/packages/workforce/README.md @@ -1394,7 +1394,7 @@ const { hire, fire } = createWorkerHireBlocks(installation); const rosterTools = { hire: hire.as({ name: "hire", description: "Hire a worker of the user's own." }), fire: sequencer({ name: "fire", description: "Fire one of the user's own workers.", inputSchema: fire.inputSchema, outputSchema: fire.outputSchema }) - .tap(askFire) // your own `human_approval` suspension, if a fire should wait for the user + .tap(askFire) // your own `user_approval` suspension, if a fire should wait for the user .step(fire), }; @@ -2443,7 +2443,7 @@ await reporter.bind(host); // after the runtime exists; restarts owed work - **One report per fingerprint** (flow, action, error code, normalized message). A repeat raises the count; a redelivered occurrence counts once. At most `limits.newPerWindow` (5) new reports per `limits.windowMs` (1 hour); the rest go into one storm report. - **Secrets are redacted at intake**, before a row, a held request or a storm entry is written: the environment's keys, `secrets()`, and the operator's stored MCP keys. - **The draft run has no tracker tools.** A separate filing run gets the tracker project's MCP servers, and a failed filing is tried again. -- **Preview.** The draft waits on a `human_input` suspension (so the runtime needs `durable: true`) until the operator files or dismisses it, unless `preview.autoFile` or `preview.autoFileAfterMs` say otherwise. +- **Preview.** The draft waits on a `user_input` suspension (so the runtime needs `durable: true`) until the operator files or dismisses it, unless `preview.autoFile` or `preview.autoFileAfterMs` say otherwise. - **A filed report's repeats** add a comment at most every `limits.commentEveryMs`. - **It never reports its own failures**, and runs on its own flow, never through a coordinator. diff --git a/packages/workforce/src/error-reporter/flow.ts b/packages/workforce/src/error-reporter/flow.ts index dfa9b1476f..58a805f3aa 100644 --- a/packages/workforce/src/error-reporter/flow.ts +++ b/packages/workforce/src/error-reporter/flow.ts @@ -421,7 +421,7 @@ export function defineErrorReporterFlow(options: ErrorReporterFlowOptions) { const questions = draft.questions.length === 0 ? "" : `\n\n**Questions**\n\n${draft.questions.map((q) => `- ${q}`).join("\n")}`; try { const answer = await ctx.suspend!({ - reason: "human_input", + reason: "user_input", // The question's heading in Inbox; `data.title` is the issue title it files under. title: `Error report: ${draft.title}`, message: `Seen ${seen} time${seen === 1 ? "" : "s"}. File it?${questions}`, diff --git a/packages/workforce/test/agent-resumed-turn-worker.test.ts b/packages/workforce/test/agent-resumed-turn-worker.test.ts index 50be2a00cf..11e86cbf46 100644 --- a/packages/workforce/test/agent-resumed-turn-worker.test.ts +++ b/packages/workforce/test/agent-resumed-turn-worker.test.ts @@ -25,7 +25,7 @@ const approveRefund = handler({ inputSchema: z.object({ order: z.string() }), outputSchema: z.object({ refunded: z.string() }), execute: async (input, ctx) => { - await ctx.suspend!({ reason: "human_approval", message: `Refund ${input.order}?`, allow: ["approve", "reject"] }); + await ctx.suspend!({ reason: "user_approval", message: `Refund ${input.order}?`, allow: ["approve", "reject"] }); return { refunded: input.order }; } }); diff --git a/packages/workforce/test/error-reporter.test.ts b/packages/workforce/test/error-reporter.test.ts index 074fcb6253..bcd67ec11c 100644 --- a/packages/workforce/test/error-reporter.test.ts +++ b/packages/workforce/test/error-reporter.test.ts @@ -287,7 +287,7 @@ describe("a request that settled failed", () => { expect(lab.prompts.map((p) => p.kind)).toEqual(["draft"]); const asks = await lab.asks(); expect(asks).toHaveLength(1); - expect(asks[0]!.reason).toBe("human_input"); + expect(asks[0]!.reason).toBe("user_input"); expect(asks[0]!.title).toBe("Error report: Coordinator fails on a project with no repository"); expect(asks[0]!.message).toBe("Seen 1 time. File it?\n\n**Questions**\n\n- Which team?"); diff --git a/packages/workforce/test/upgrade-entry-names.test.ts b/packages/workforce/test/upgrade-entry-names.test.ts index 06d416e518..e6d7f938f9 100644 --- a/packages/workforce/test/upgrade-entry-names.test.ts +++ b/packages/workforce/test/upgrade-entry-names.test.ts @@ -231,7 +231,7 @@ describe("a reply an older host parked under `run`", () => { name: "upgrade-ask", inputSchema: z.object({ message: z.string() }), outputSchema: z.unknown(), - execute: async (input, ctx) => ({ asked: input.message, decision: await ctx.suspend!({ reason: "human_approval", message: "Go?" }) }) + execute: async (input, ctx) => ({ asked: input.message, decision: await ctx.suspend!({ reason: "user_approval", message: "Go?" }) }) }); const answer = handler({ name: "upgrade-answer", inputSchema: z.any(), outputSchema: z.string(), execute: async () => "answered" }); const flow = defineFlow({ diff --git a/scripts/codemod/README.md b/scripts/codemod/README.md index fcbd3456d7..692d595662 100644 --- a/scripts/codemod/README.md +++ b/scripts/codemod/README.md @@ -31,3 +31,15 @@ FIX-595 spec §4.5): Both live in `packages/memory/src/memory-system-blocks.ts`. After running the codemod, grep the memory package for any remaining sequencer-shaped `.then(` calls and rewrite them manually. + +## `rename-human-reasons.ts` + +FIX-2151: renames the suspension reasons `"human_approval"` / `"human_input"` to +`"user_approval"` / `"user_input"`. Unlike the codemod above it is textual, +not type-aware: both strings are unique, so it is a word-bounded replace over every tracked file under `packages`, `apps`, `goals`, +`docs` and `.changeset`, leaving history alone (`CHANGELOG.md`, blog posts, +`docs/internal/`, a goal's dated verdict rows, its own release note): + +```bash +pnpm tsx scripts/codemod/rename-human-reasons.ts +``` diff --git a/scripts/codemod/rename-human-reasons.ts b/scripts/codemod/rename-human-reasons.ts new file mode 100644 index 0000000000..3a98bca3ad --- /dev/null +++ b/scripts/codemod/rename-human-reasons.ts @@ -0,0 +1,78 @@ +/** + * Codemod: FIX-2151, the suspension reasons say *user*. + * + * `"human_approval"` → `"user_approval"` and `"human_input"` → `"user_input"`, + * the framework's one word for the person on the other end (`userId`, + * `waitForUser`). The head names are the contract in + * `specs/epics/FIX-2071/renames.md`. + * + * Both strings are unique, so a word-bounded replace over every tracked file + * under `ROOTS` below is the whole rename; no type checker is needed. It has + * to be total under `ROOTS`: `SuspensionReason`'s open `string & {}` arm means + * a missed call site still compiles and silently becomes a custom reason. + * + * History is left alone: `CHANGELOG.md` files, dated blog posts, + * `docs/internal/`, a goal's dated verdict rows (`| 2026-10-06 | …`), and + * this rename's own release note, which names the old values on purpose. + * `specs/` is retained design history and is not a root. + * + * Usage: `pnpm tsx scripts/codemod/rename-human-reasons.ts`. Re-run on a fresh + * `main` to regenerate a conflicting PR (FIX-2071 ER-2). + */ + +import { execFileSync } from "node:child_process"; +import { readFileSync, writeFileSync } from "node:fs"; +import { fileURLToPath } from "node:url"; +import { dirname, resolve } from "node:path"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const repoRoot = resolve(__dirname, "..", ".."); + +const RENAMES: Record = { + human_approval: "user_approval", + human_input: "user_input", +}; + +const ROOTS = ["packages", "apps", "goals", "docs", ".changeset"]; + +const HISTORY = /(^|\/)CHANGELOG\.md$|^apps\/docs\/blog\/|^docs\/internal\/|^\.changeset\/user-suspension-reasons\.md$/; + +/** A goal's dated verdict row records a past run under the names it ran with. */ +const VERDICT_ROW = /^\| \d{4}-\d{2}-\d{2} \|/; + +const PATTERN = new RegExp(`\\b(${Object.keys(RENAMES).join("|")})\\b`, "g"); + +const files = execFileSync("git", ["ls-files", "--", ...ROOTS], { cwd: repoRoot, encoding: "utf8" }) + .split("\n") + .filter((path) => path && !HISTORY.test(path)); + +let changedFiles = 0; +let changedLines = 0; +for (const path of files) { + const abs = resolve(repoRoot, path); + let text: string; + try { + text = readFileSync(abs, "utf8"); + } catch { + continue; // a tracked path deleted in the working tree + } + if (!PATTERN.test(text)) continue; + PATTERN.lastIndex = 0; + const lines = text.split("\n"); + let touched = false; + for (let i = 0; i < lines.length; i++) { + if (VERDICT_ROW.test(lines[i])) continue; + const next = lines[i].replace(PATTERN, (word) => RENAMES[word]); + if (next !== lines[i]) { + lines[i] = next; + touched = true; + changedLines++; + } + } + if (touched) { + writeFileSync(abs, lines.join("\n")); + changedFiles++; + } +} + +console.log(`rename-human-reasons: ${changedLines} lines in ${changedFiles} files`);