Skip to content
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .changeset/user-suspension-reasons.md
Original file line number Diff line number Diff line change
@@ -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).
2 changes: 1 addition & 1 deletion .changeset/wait-for-user.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
4 changes: 2 additions & 2 deletions apps/docs/docs/advanced/block-memoization-and-replay.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 };
Expand All @@ -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 };
Expand Down
10 changes: 5 additions & 5 deletions apps/docs/docs/advanced/durable-execution.md
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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<string, unknown>` | Arbitrary metadata attached to the suspension record |
| `resumeSchema` | `Record<string, unknown>` | 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<string, unknown> }` | 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

Expand Down Expand Up @@ -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" }
Expand Down Expand Up @@ -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"],
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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() }),
});
Expand Down
2 changes: 1 addition & 1 deletion apps/docs/docs/api/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
2 changes: 1 addition & 1 deletion apps/docs/docs/api/client.md
Original file line number Diff line number Diff line change
Expand Up @@ -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({
Expand Down
6 changes: 3 additions & 3 deletions apps/docs/docs/api/react.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
});
```

Expand Down Expand Up @@ -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";
Expand Down
14 changes: 7 additions & 7 deletions apps/docs/docs/client/react.md
Original file line number Diff line number Diff line change
Expand Up @@ -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",
});
```
Expand Down Expand Up @@ -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.

`<ItemsRenderer>` 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.
`<ItemsRenderer>` 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";
Expand All @@ -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"]),
Expand All @@ -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.
<SuspensionResolverProvider resolve={session.resumeSuspension}>
<ItemsRenderer items={session.items} />
</SuspensionResolverProvider>
Expand Down
2 changes: 1 addition & 1 deletion apps/docs/docs/orchestration/task-board.md
Original file line number Diff line number Diff line change
Expand Up @@ -817,7 +817,7 @@ Until then the task stays `in_progress`, and its row's `waitingOn` 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 `holds`.
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 `holds`.

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.

Expand Down
2 changes: 1 addition & 1 deletion apps/docs/docs/streaming/items.md
Original file line number Diff line number Diff line change
Expand Up @@ -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" }
```

Expand Down
8 changes: 4 additions & 4 deletions apps/docs/docs/workforce/shift-coordinator.md
Original file line number Diff line number Diff line change
Expand Up @@ -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(),
Expand All @@ -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"] });
},
});

Expand Down Expand Up @@ -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"]
Expand Down
18 changes: 9 additions & 9 deletions apps/docs/guides/human-in-the-loop.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 held on questions](/docs/orchestration/task-board#a-task-held-on-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 held on questions](/docs/orchestration/task-board#a-task-held-on-questions).

## How a pause works

Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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() }),
});
Expand All @@ -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
Expand All @@ -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"])),
Expand All @@ -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"],
Expand Down Expand Up @@ -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() }),
});
Expand Down Expand Up @@ -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 (
Expand Down
Loading
Loading