Skip to content
Merged
Show file tree
Hide file tree
Changes from all 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 @@ -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.

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'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

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