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
8 changes: 8 additions & 0 deletions .changeset/request-action-result.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
"@flow-state-dev/engine": patch
"@flow-state-dev/client": patch
"@flow-state-dev/devtool": patch
"@flow-state-dev/fsdev": patch
---

Each request's record now stores its action result (`output` as JSON, and/or `error`) with its final status, `listSessionRequests` returns it (the output with `includeResultOutput`), the DevTool task row reads it instead of reconstructing it from traces, and a run a completion hook failed after the action answered now reports that answer as `output` (including `fsdev run`'s result, where it was `null`) (FIX-1661).
16 changes: 16 additions & 0 deletions apps/docs/docs/advanced/manual-flow-execution.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,22 @@ run time exactly as it would through the HTTP layer.
produced, a `durationMs`, an `error` when the run failed, and the `requestId` —
the id of the run, for correlating logs or attaching a stream.

`output` and `error` can both be set. When the action returns and a completion
hook such as `onCompleted` then throws, the run fails with the hook's error, and
`output` still holds what the action returned.

The same `output` and `error` are saved to the request's record in your
`stores`, as `result`, when the run ends. A client can read them later from [`listSessionRequests`](/docs/api/client#sessionslistsessionrequestssessionid-options)
without attaching a stream; pass `includeResultOutput: true` to get the output.
The record keeps a JSON copy of the output, so a `Date` is stored as its ISO
string. A value that doesn't survive a JSON round trip, such as a `BigInt`,
`NaN` or a `Map`, isn't stored. Aborted and interrupted runs save no
result.

The output is saved for an action whose block is marked `transient` too:
`transient` keeps the block's trace items out of storage, not the action's
return value.

To fire-and-forget, don't await: drop the `await` and let the run proceed. The
run is durable either way — items and events persist to the `stores` you passed.
One caveat: an un-awaited run that fails produces an unhandled promise
Expand Down
35 changes: 35 additions & 0 deletions apps/docs/docs/api/client.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,41 @@ There is no counterpart that starts one. Whether work is dispatched at all is de

Full walkthrough: [Client > Overview](/docs/client/overview#dispatched-runs).

### `sessions.listSessionRequests(sessionId, options?)`
Comment thread
jhoffner marked this conversation as resolved.
Resolved

List the requests a session has run. Each entry is a `SessionRequestSummary`: the action name, the status, the timings, and, once the request has ended, a `result` saying what the action came to.

```ts
const requests = await sessions.listSessionRequests("sess_1", { includeResultOutput: true });

for (const req of requests) {
const { result } = req;
if (result == null) continue; // still running, aborted, or no result recorded
if (result.error) console.log(req.actionName, "failed:", result.error.message);
else if (result.outputNotRecorded) console.log(req.actionName, "finished, output not recorded");
else console.log(req.actionName, "returned", result.output);
}
```

| Option | Type | Notes |
|--------|------|-------|
| `status` | `RequestStatus` | Only requests with this status. |
| `limit` / `offset` | `number` | Paging. |
| `includeItems` | `boolean` | Add each request's item log as `items`. |
| `includeResultOutput` | `boolean` | Add the action's return value as `result.output`. |

Without `includeResultOutput`, `result` carries `error` and a `hasOutput` flag but not the value itself.

| Request status | `result` |
|---|---|
| `completed` or `incomplete` | `{ hasOutput: true }`, plus `output` with `includeResultOutput`. `{ hasOutput: false }` when the action returned nothing. |
| `failed` | `{ error: { code, message }, hasOutput: false }`. When the action had returned before a completion hook failed the request, `hasOutput` is `true` and `output` is there with `includeResultOutput`. |
| `in_progress`, `suspended`, `aborted` or `interrupted` | absent |

`output` is a JSON copy of what the action returned, so a `Date` is stored as its ISO string and an object key set to `undefined` is left out. A value that doesn't survive a JSON round trip (a `BigInt`, an object that refers to itself, `NaN` or `Infinity`, a function or symbol, an `undefined` array slot, a `Map`, `Set` or `Error`) isn't stored. Those requests carry `outputNotRecorded: true` and `hasOutput: false` in place of the output, and their status is unaffected.

A finished request written by a server version that didn't store results has no `result`. Check `result == null` rather than inferring the outcome from `status`.

## SSE Clients

### `createSSEClient(options)`
Expand Down
11 changes: 10 additions & 1 deletion apps/docs/docs/devtool/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,16 @@ A note is not an error. A failure with no retries left writes the task's `error`

An open row lists the flow's actions that take a `taskId`. Pick one and its form opens in the row with the task's id filled in and locked. Run it and the DevTool sends the action the same way the action bar would, in the session you're looking at. The row updates when the task changes.

If the task can't move that way, say you cancel a task that already finished, the action refuses and the row shows why in the action's own words. Nothing is written. The row reads that answer from the request's trace, so with trace observability off it can only tell you the action was sent.
If the task can't move that way, say you cancel a task that already finished, the action refuses and the row shows why in the action's own words. Nothing is written. The row shows the request's outcome:

| The row reads | When |
|---|---|
| `Running…` | The request hasn't finished. |
| `Done`, with the return value | The request completed. |
| `Refused:` and the reason | The request completed, and the action returned `{ ok: false }` or `{ outcome: "declined" }`. |
| `Failed:` and the error | The request ended any other way. |
| `No result recorded for this request.` | The request completed but has no saved result, as with history written by an older server. |
| `Finished, but its return value couldn't be recorded.` | The return value wasn't saved because JSON can't hold it. See [`listSessionRequests`](/docs/api/client#sessionslistsessionrequestssessionid-options). |

The DevTool changes tasks only through your flow's actions. There is no way to edit a task's record directly, so every change is a transition the task can legally make. The action doesn't claim the task. It acts as a coordinator would, so it can settle a task a worker is still running: your change lands, and the worker's result is dropped when it arrives. If a row says the flow has no actions that take a `taskId`, see [changing tasks from outside a run](/docs/orchestration/task-board#changing-tasks-from-outside-a-run).

Expand Down
6 changes: 5 additions & 1 deletion apps/docs/docs/server/background-work.md
Original file line number Diff line number Diff line change
Expand Up @@ -388,7 +388,11 @@ GET /api/flows/sessions/dsx_9f2c1a/requests
```

That returns the run's own requests, with the item log for each when you ask for
it (`?include_items=true`).
it (`?include_items=true`). A finished request also carries a `result` with its
error, if any, and the action's return value when you ask for that too
(`?include_result_output=true`). See
[`listSessionRequests`](/docs/api/client#sessionslistsessionrequestssessionid-options)
for the shape.

A run a `dispatcher()` started reads `source: "internal"`, or `source: "task"`
when a task-board seat handed the work off, and carries a `metadata.dispatch`
Expand Down
1 change: 1 addition & 0 deletions docs/architecture/server-and-client.md
Original file line number Diff line number Diff line change
Expand Up @@ -400,6 +400,7 @@ Client Server
- Framework examples use `userId: "devuser"` as local default
- POST returns `202 Accepted` immediately — execution is async
- Client can pre-generate `requestId` and pass it in the POST body
- The action's result is stored on the request record as `result` (`output`, and/or `error`) in the same write as the final status. `GET /sessions/:id/requests` returns it, with `result.output` only on `include_result_output=true` (every entry carries `hasOutput`). A missing `result` means unfinished, aborted/interrupted, or a legacy record (BP-030)

## Canonical Authority

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
/**
* The fixture flow: one durable task board, its task tools as actions, and
* five app actions shaped as the goal's row legs.
*
* Every leg action takes a `taskId`, so the DevTool offers it on each row, and
* answers with a value the goal check fixes through `ROW_RESULT_ANSWERS` (the
* fixture's `answers`, held out). Each is shaped as one of the cases a trace
* reading could not see:
*
* - `handover` — a transient block refuses. Nothing it traced is persisted.
* - `hook` — a refusal, with the flow's completion hooks running after it
* as root blocks of the same request.
* - `ref` — a success whose value a sequencer holds by reference to its
* step's trace.
* - `suspend` — suspends for a person, and answers with what they resumed it
* with.
* - `hookFails` — refuses, then the action's own completion hook throws, so the
* request fails after the action answered.
*
* No model anywhere: every block is a deterministic handler.
*/
import { defineFlow, handler, sequencer } from "@flow-state-dev/core";
import { taskBoard, taskToolActions } from "@flow-state-dev/orchestration/task-board";
import { defineTaskCollection, type TaskWorker } from "@flow-state-dev/orchestration/tasks";
import { z } from "zod";

/** The flow kind the goal check addresses, and the board its rows are on. */
export const ROW_RESULTS_KIND = "row-results";
export const ROW_BOARD = "rows";

/** The answers each leg returns, fixed by the goal check. */
export type RowAnswers = {
handover: string;
hook: string;
ref: unknown;
suspend: string;
hookFails: { refusal: string; error: string };
};

const taskInput = z.object({ taskId: z.string() });

const noopWorker = handler({
name: "row-results-noop-worker",
inputSchema: z.unknown(),
outputSchema: z.null(),
execute: () => null,
}) as TaskWorker;

/** Build the flow for one set of answers. */
export function rowResultsFlow(answers: RowAnswers) {
const rows = defineTaskCollection({ id: ROW_BOARD, scope: "session" });
const board = taskBoard({ name: ROW_BOARD, collection: rows, workers: noopWorker });

const refStep = handler({
name: "row-results-ref-step",
inputSchema: taskInput,
execute: () => answers.ref,
});

const gate = handler({
name: "row-results-gate",
inputSchema: z.unknown(),
execute: async (_input, ctx) => {
const decision = (await ctx.suspend!({
reason: "human_input",
message: "Answer this row",
resumeSchema: { type: "object", properties: { answer: { type: "string" } } },
})) as { answer?: string } | undefined;
return { ok: true, answer: decision?.answer ?? null };
},
});

// Root blocks of every request, before and after its action, taking the
// request's own id as input: what a trace reading had to tell apart.
const hookBlock = (name: string) =>
handler({ name, inputSchema: z.unknown(), execute: () => ({ observed: name }) });

return defineFlow({
kind: ROW_RESULTS_KIND,
request: {
onStarted: hookBlock("row-results-on-started"),
onCompleted: hookBlock("row-results-on-completed"),
onFinished: hookBlock("row-results-on-finished"),
},
actions: {
...taskToolActions(board),
handover: {
inputSchema: taskInput,
block: handler({
name: "row-results-handover",
transient: true,
inputSchema: taskInput,
execute: () => ({ ok: false, error: answers.handover }),
}),
},
hook: {
inputSchema: taskInput,
block: handler({
name: "row-results-hook",
inputSchema: taskInput,
execute: () => ({ ok: false, error: answers.hook }),
}),
},
ref: {
inputSchema: taskInput,
block: sequencer({ name: "row-results-ref", inputSchema: taskInput }).step(refStep),
},
suspend: {
inputSchema: taskInput,
durable: true,
block: sequencer({ name: "row-results-suspend", durable: true, inputSchema: taskInput }).step(gate),
},
hookFails: {
inputSchema: taskInput,
block: handler({
name: "row-results-hook-fails",
inputSchema: taskInput,
execute: () => ({ ok: false, error: answers.hookFails.refusal }),
}),
onCompleted: handler({
name: "row-results-failing-hook",
inputSchema: z.unknown(),
execute: () => {
throw new Error(answers.hookFails.error);
},
}),
},
},
} as never);
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
/**
* What `fsdev dev` serves for this goal: the fixture flow, durable, on SQLite
* under the server's working directory, with the debug endpoints on so the
* check can find the suspension it resumes.
*
* ROW_RESULT_ANSWERS='<json>' fsdev dev --config <this file>
*
* The answers come from the goal check (its fixture, held out); a person
* running the server by hand gets placeholder ones.
*/
import { mkdirSync } from "node:fs";
import { createFlowState } from "@flow-state-dev/engine";
import { sqliteStores } from "@flow-state-dev/store-sqlite";
import { ROW_RESULTS_KIND, rowResultsFlow, type RowAnswers } from "./flow.mts";

/** The user the DevTool's navigator lists sessions for. */
export const ROW_RESULTS_USER = "u_row_results";

const answers: RowAnswers = process.env.ROW_RESULT_ANSWERS
? (JSON.parse(process.env.ROW_RESULT_ANSWERS) as RowAnswers)
: {
handover: "refused (handover)",
hook: "refused (hook)",
ref: { ok: true, value: "ref" },
suspend: "approved",
hookFails: { refusal: "refused (hook fails)", error: "the hook failed" },
};

mkdirSync(".fsdev/data", { recursive: true });

const flow = rowResultsFlow(answers)();

export default createFlowState({
flows: { [ROW_RESULTS_KIND]: flow },
stores: { default: { primary: sqliteStores({ filename: ".fsdev/data/row-results.db" }) } },
durable: true,
debugEndpointsEnabled: true,
devtool: { userId: ROW_RESULTS_USER },
} as never);
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
{
"rows": {
"handover": "a transient row that the handover leg refuses",
"hook": "a row the hook leg refuses under the flow's completion hooks",
"ref": "a row the ref leg answers with a value held by reference",
"suspend": "a row the suspend leg answers after a person resumes it",
"hookFails": "a row whose action answers before a hook fails the request"
},
"answers": {
"handover": "handover: task is cancelled, which is terminal",
"hook": "hook: task is not claimable while it is parked",
"ref": { "ok": true, "value": "ref: priority raised to 7" },
"suspend": "suspend: approved by the on-call reviewer",
"hookFails": {
"refusal": "hook-fails: the task was already settled",
"error": "hook-fails: the notification service is down"
}
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# devtool-workforce-visibility › it reads a row action's result

**Issue:** FIX-1661. The spec's goal check.

**Outcome:** A developer runs an action from a task's row in the DevTool and the row shows what that action came to: refused with the action's own words, done with its answer, or failed with the error, even when the answer only ever existed in a transient block, behind completion hooks, by reference inside a sequencer, after a person resumed it, or before a hook failed the request. The row reads it from the result the engine recorded for the request, never from traces or the live stream.

**Input:** The fixture flow (`fixtures/flow.mts`), served by the ordinary `fsdev dev --config fixtures/fsdev.config.mts` on SQLite, durable, with no model. `fixtures/input.json` holds one row goal per leg and the answer each leg's action returns. Both are **held out**: the server gets the answers through `ROW_RESULT_ANSWERS`, and rows are filed through the board's own `addTask_rows` action and found by the ids it returned. Different answers must pass too.

**Signal:** Chromium on the shipped DevTool bundle, rebuilt at the start of the run, at **1280×800**. The page talks to the server through a pass-through proxy the check runs. Each leg runs its action from the row's own Actions strip, with the task id locked in the form. Every failure line names its leg.

- **handover.** A transient block refuses. Then the hook leg's dispatch takes the one live stream, and the handover row is graded again: it still reads `refused` with the fixture's words.
- **hook.** A refusal with the flow's `onStarted`/`onCompleted`/`onFinished` hooks running as root blocks of the same request. The row reads `refused` with the fixture's words.
- **ref.** A sequencer whose step returns the answer. The row reads `ok` and shows that value.
- **suspend.** A durable sequencer suspends for a person. While suspended the row reads pending (checked after 4.5s). The check resumes it over HTTP with the fixture's answer, and the same row then reads `ok` with it.
- **hook-fails.** The action refuses, then its own `onCompleted` hook throws. The row reads `failed` with the hook's error and the action's refusal.
- **api.** Through the proxy, `GET /sessions/:id/requests?include_result_output=true` lists each leg's request with its recorded result and output. Without the flag it lists the status, `result.error` and `hasOutput` only.
- The page loads once. Any further main-frame navigation fails the run.

**Anti-game:** The hollow pass is a row that still reconstructs the answer from traces or the stream, and happens to get these cases right. The `no-result` control rules it out: with `result` stripped from the listing, every row leg must go red, so nothing but the recorded result can turn a row green. Rows are found by `data-task-id`, never by text. The check never reads the store to decide what is on screen.

**Model:** n/a. Every block is a deterministic handler.

**Run:** `PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers pnpm tsx goals/devtool-workforce-visibility/reads-a-row-actions-result/run.mts`. The run builds the DevTool bundle first. On a clean checkout, run `pnpm packages:build` once before it.

**Controls:** Each control must FAIL at exactly the legs named, and the run checks that itself.

- `GOAL_CONTROL=no-result`: the proxy strips `result` from the session request list, which is what a server that does not record results sends. Must fail **every leg**: handover, hook, ref, suspend, hook-fails and api.

## Verdict log

| Date | Commit | Model | Verdict | Notes |
|------|--------|-------|---------|-------|
| 2026-09-30 | `2013d34f6` + this goal (on `fix/fix-1661`) | n/a | FAIL (expected) | Control `no-result`: **every leg**, and no other. The handover, hook, ref and suspend rows read *"No result recorded for this request."*; hook-fails read *"Failed: The request ended failed. No result recorded for this request."*; api reported each leg listing no result. |
| 2026-09-30 | `2013d34f6` + this goal (on `fix/fix-1661`) | n/a | **PASS** | handover: *"Refused: handover: task is cancelled, which is terminal"*, still so after hook's dispatch. hook: *"Refused: hook: task is not claimable while it is parked"*. ref: *"Done: {"ok":true,"value":"ref: priority raised to 7"}"*. suspend: pending while suspended, then *"Done: {"ok":true,"answer":"suspend: approved by the on-call reviewer"}"*. hook-fails: *"Failed: hook-fails: the notification service is down (the action itself refused: hook-fails: the task was already settled)"*. api: all five results with the flag; status, error and `hasOutput` only without. One page load. |
Loading
Loading