diff --git a/.changeset/request-action-result.md b/.changeset/request-action-result.md new file mode 100644 index 0000000000..5a19c6d513 --- /dev/null +++ b/.changeset/request-action-result.md @@ -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). diff --git a/apps/docs/docs/advanced/manual-flow-execution.md b/apps/docs/docs/advanced/manual-flow-execution.md index 4d4bcf0b14..02bba7f72b 100644 --- a/apps/docs/docs/advanced/manual-flow-execution.md +++ b/apps/docs/docs/advanced/manual-flow-execution.md @@ -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 diff --git a/apps/docs/docs/api/client.md b/apps/docs/docs/api/client.md index 971009d16d..ebfaf0d710 100644 --- a/apps/docs/docs/api/client.md +++ b/apps/docs/docs/api/client.md @@ -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?)` + +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)` diff --git a/apps/docs/docs/devtool/overview.md b/apps/docs/docs/devtool/overview.md index 107d3f5fa3..629e177425 100644 --- a/apps/docs/docs/devtool/overview.md +++ b/apps/docs/docs/devtool/overview.md @@ -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). diff --git a/apps/docs/docs/server/background-work.md b/apps/docs/docs/server/background-work.md index 8f30c70fec..457338621c 100644 --- a/apps/docs/docs/server/background-work.md +++ b/apps/docs/docs/server/background-work.md @@ -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` diff --git a/docs/architecture/server-and-client.md b/docs/architecture/server-and-client.md index 05fcf13880..2fad40e0b4 100644 --- a/docs/architecture/server-and-client.md +++ b/docs/architecture/server-and-client.md @@ -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 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 new file mode 100644 index 0000000000..b0ae728fe9 --- /dev/null +++ b/goals/devtool-workforce-visibility/reads-a-row-actions-result/fixtures/flow.mts @@ -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); +} diff --git a/goals/devtool-workforce-visibility/reads-a-row-actions-result/fixtures/fsdev.config.mts b/goals/devtool-workforce-visibility/reads-a-row-actions-result/fixtures/fsdev.config.mts new file mode 100644 index 0000000000..d14791293a --- /dev/null +++ b/goals/devtool-workforce-visibility/reads-a-row-actions-result/fixtures/fsdev.config.mts @@ -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='' fsdev dev --config + * + * 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); diff --git a/goals/devtool-workforce-visibility/reads-a-row-actions-result/fixtures/input.json b/goals/devtool-workforce-visibility/reads-a-row-actions-result/fixtures/input.json new file mode 100644 index 0000000000..b2d2349cfb --- /dev/null +++ b/goals/devtool-workforce-visibility/reads-a-row-actions-result/fixtures/input.json @@ -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" + } + } +} diff --git a/goals/devtool-workforce-visibility/reads-a-row-actions-result/goal.md b/goals/devtool-workforce-visibility/reads-a-row-actions-result/goal.md new file mode 100644 index 0000000000..54c458d615 --- /dev/null +++ b/goals/devtool-workforce-visibility/reads-a-row-actions-result/goal.md @@ -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. | diff --git a/goals/devtool-workforce-visibility/reads-a-row-actions-result/run.mts b/goals/devtool-workforce-visibility/reads-a-row-actions-result/run.mts new file mode 100644 index 0000000000..33330c6323 --- /dev/null +++ b/goals/devtool-workforce-visibility/reads-a-row-actions-result/run.mts @@ -0,0 +1,479 @@ +/** + * Goal check: a Tasks-tab row shows what its action actually came to, from + * what the engine recorded for the request, in every case that broke reading + * it back from traces and the live stream. + * + * Real path, no model, out of CI. See goal.md for the contract. + * + * The subject is the fixture flow (`fixtures/flow.mts`) served by the ordinary + * `fsdev dev` over `fixtures/fsdev.config.mts`, and read in Chromium on the + * shipped DevTool bundle. The page talks to the server through a pass-through + * proxy this file runs; the `no-result` control makes that proxy strip + * `result` from the session request list, which is what a server that does + * not record results sends. + * + * Legs (every failure line is tagged with its leg): + * + * handover a transient action refuses; another row's dispatch then takes + * the one live stream; the first row still shows the refusal + * hook a refusal with the flow's completion hooks running after it + * ref a success whose value a sequencer holds by reference + * suspend pending while suspended, then the answer the resume gave + * hook-fails the action refused, then its completion hook failed the request + * api the session's request list carries each leg's result, output + * only with include_result_output + * + * Run: PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers pnpm tsx goals/devtool-workforce-visibility/reads-a-row-actions-result/run.mts + * Controls: GOAL_CONTROL=no-result (must FAIL every leg) + */ +import { execFileSync, spawn, type ChildProcess } from "node:child_process"; +import { createServer, request as httpRequest, type Server } from "node:http"; +import { mkdirSync } from "node:fs"; +import { join } from "node:path"; +import { fileURLToPath } from "node:url"; +import type { Browser, Locator, Page } from "playwright"; +import { REPO_ROOT, goalTmpDir, intentFreeEnv, loadFixture, runGoal } from "../../lib/index.mts"; +import { launchChromium } from "../../lib/playwright.mts"; + +type Answers = { + handover: string; + hook: string; + ref: unknown; + suspend: string; + hookFails: { refusal: string; error: string }; +}; +type Fixture = { + rows: { handover: string; hook: string; ref: string; suspend: string; hookFails: string }; + answers: Answers; +}; + +const fixture = loadFixture(import.meta.url); +const CONTROL = process.env.GOAL_CONTROL ?? ""; +const SHOTS = goalTmpDir("reads-a-row-actions-result"); +const CONFIG = fileURLToPath(new URL("./fixtures/fsdev.config.mts", import.meta.url)); +const KIND = "row-results"; +const BOARD = "rows"; +const USER = "u_row_results"; +const SESSION = `s_row_results_${Date.now()}`; + +/** Every leg, in the order the check runs them. */ +const LEGS = ["handover", "hook", "ref", "suspend", "hook-fails", "api"] as const; +type Leg = (typeof LEGS)[number]; + +/** The legs each control must redden: all of them. */ +const EXPECTED: Record = { + "no-result": LEGS, +}; + +const NO_RESULT = "No result recorded for this request."; +/** How long an answer gets to reach the row. The row poll re-reads every 2s. */ +const SETTLE_MS = 20_000; + +const failures: string[] = []; +const evidence: string[] = []; +function fail(leg: Leg, line: string): void { + failures.push(`[${leg}] ${line}`); +} + +// --------------------------------------------------------------------------- +// The server, and the proxy the page reads it through +// --------------------------------------------------------------------------- + +async function waitForHealth(origin: string, child: ChildProcess, log: () => string): Promise { + let exited = false; + child.on("exit", () => (exited = true)); + for (let i = 0; i < 240 && !exited; i += 1) { + try { + if ((await fetch(`${origin}/healthz`)).status === 200) return; + } catch { + /* not listening yet */ + } + await new Promise((r) => setTimeout(r, 250)); + } + throw new Error(`the dev server never became ready on ${origin}. Log tail:\n${log().slice(-2000)}`); +} + +async function serve(port: number): Promise<{ origin: string; stop: () => void }> { + const workDir = join(SHOTS, "server"); + mkdirSync(workDir, { recursive: true }); + let log = ""; + const child = spawn( + join(REPO_ROOT, "node_modules", ".bin", "tsx"), + [join(REPO_ROOT, "packages", "cli", "bin", "fsdev.ts"), "dev", "--config", CONFIG, "--no-open", "--port", String(port)], + { + cwd: workDir, + env: intentFreeEnv(process.env, { + ROW_RESULT_ANSWERS: JSON.stringify(fixture.answers), + FSDEV_DEBUG_ENDPOINTS: "1", + }), + stdio: ["ignore", "pipe", "pipe"], + }, + ); + child.stdout?.on("data", (chunk) => (log += String(chunk))); + child.stderr?.on("data", (chunk) => (log += String(chunk))); + const origin = `http://127.0.0.1:${port}`; + await waitForHealth(origin, child, () => log); + return { origin, stop: () => child.kill("SIGTERM") }; +} + +/** The session request list, which the `no-result` control rewrites. */ +const LIST_PATH = /^\/api\/flows\/sessions\/[^/]+\/requests(\?|$)/; + +/** + * A pass-through proxy in front of the server. Everything streams through + * untouched, except that under `no-result` the session request list loses + * every `result`: what a server that does not record results sends. + */ +function proxy(target: string, port: number): Promise<{ origin: string; server: Server }> { + const upstream = new URL(target); + const server = createServer((req, res) => { + const rewrite = CONTROL === "no-result" && req.method === "GET" && LIST_PATH.test(req.url ?? ""); + const out = httpRequest( + { host: upstream.hostname, port: upstream.port, method: req.method, path: req.url, headers: req.headers }, + (answer) => { + if (!rewrite) { + res.writeHead(answer.statusCode ?? 502, answer.headers); + answer.pipe(res); + return; + } + const chunks: Buffer[] = []; + answer.on("data", (chunk: Buffer) => chunks.push(chunk)); + answer.on("end", () => { + let text = Buffer.concat(chunks).toString("utf8"); + try { + const body = JSON.parse(text) as { requests?: Array> }; + for (const entry of body.requests ?? []) delete entry.result; + text = JSON.stringify(body); + } catch { + /* not JSON: pass it on as it came */ + } + const headers = { ...answer.headers }; + delete headers["content-length"]; + delete headers["content-encoding"]; + res.writeHead(answer.statusCode ?? 502, headers); + res.end(text); + }); + }, + ); + out.on("error", () => { + res.writeHead(502); + res.end(); + }); + req.pipe(out); + }); + return new Promise((resolve) => server.listen(port, "127.0.0.1", () => resolve({ origin: `http://127.0.0.1:${port}`, server }))); +} + +// --------------------------------------------------------------------------- +// The driver's own HTTP: filing rows, finding a request, resuming one +// --------------------------------------------------------------------------- + +async function json(origin: string, path: string, init?: RequestInit): Promise<{ status: number; body: any }> { + const response = await fetch(`${origin}/api/flows${path}`, { + ...init, + headers: { "content-type": "application/json", ...(init?.headers ?? {}) }, + }); + const text = await response.text(); + try { + return { status: response.status, body: text.length === 0 ? null : JSON.parse(text) }; + } catch { + return { status: response.status, body: text }; + } +} + +type Listed = { id: string; actionName: string; status: string; result?: Record; items?: any[] }; + +async function listRequests(origin: string, query: string): Promise { + const { status, body } = await json(origin, `/sessions/${SESSION}/requests${query}`); + if (status !== 200) throw new Error(`listing the session's requests answered ${status}`); + return body.requests as Listed[]; +} + +/** File one row with the board's own `addTask`, and read its id off the task-change item it logged. */ +async function fileRow(origin: string, goal: string): Promise { + const posted = await json(origin, `/${KIND}/${SESSION}/actions/addTask_${BOARD}`, { + method: "POST", + body: JSON.stringify({ userId: USER, input: { goal } }), + }); + if (posted.status !== 202) throw new Error(`filing "${goal}" answered ${posted.status}: ${JSON.stringify(posted.body)}`); + const requestId = String(posted.body?.request?.id); + for (let waited = 0; waited < 15_000; waited += 100) { + const entry = (await listRequests(origin, "?include_items=true")).find((request) => request.id === requestId); + const change = (entry?.items ?? []).find( + (item) => item?.type === "component" && item?.data?.task?.goal === goal && typeof item?.data?.task?.id === "string", + ); + if (entry?.status === "completed" && change !== undefined) return String(change.data.task.id); + await new Promise((r) => setTimeout(r, 100)); + } + throw new Error(`the row "${goal}" was never filed`); +} + +/** The newest request of one action on the session, once it is listed. */ +async function requestOf(origin: string, action: string, until: (status: string) => boolean): Promise { + for (let waited = 0; waited < SETTLE_MS; waited += 100) { + const found = (await listRequests(origin, "")).find((request) => request.actionName === action); + if (found !== undefined && until(found.status)) return found; + await new Promise((r) => setTimeout(r, 100)); + } + return undefined; +} + +// --------------------------------------------------------------------------- +// The DevTool's own navigation and the row's Actions strip +// --------------------------------------------------------------------------- + +async function openSession(page: Page): Promise { + const kindRow = page.locator(`[data-kind="${KIND}"]`); + if ((await kindRow.getAttribute("aria-expanded")) !== "true") await kindRow.click(); + const instanceRow = page.locator(`[data-instance-id="${KIND}"]`); + if ((await instanceRow.count()) > 0 && (await instanceRow.getAttribute("aria-expanded")) !== "true") { + await instanceRow.click(); + } + await page.locator(`[data-session-id="${SESSION}"]`).click(); + await page.waitForFunction( + (id) => [...document.querySelectorAll("[title^='Session ID: ']")].some((el) => el.getAttribute("title")?.includes(id)), + SESSION, + { timeout: 15_000 }, + ); + await page.getByRole("tab", { name: "Tasks" }).click(); +} + +/** The row for one task in the active Tasks panel, by its id and nothing else. */ +function rowLocator(page: Page, taskId: string): Locator { + return page.locator(`main [role='tabpanel'][data-state='active'] [data-task-id="${taskId}"]`).first(); +} + +async function openRow(page: Page, taskId: string): Promise { + const row = rowLocator(page, taskId); + try { + await row.waitFor({ timeout: 15_000 }); + } catch { + return false; + } + const toggle = row.locator("button[aria-expanded]").first(); + if ((await toggle.count()) === 0) return false; + if ((await toggle.getAttribute("aria-expanded")) !== "true") await toggle.click(); + return true; +} + +/** Pick the action on the row, check its form carries the row's locked id, and run it. */ +async function startFromRow(page: Page, taskId: string, action: string): Promise { + if (!(await openRow(page, taskId))) return `row ${taskId} is not on screen, found by its task id`; + const row = rowLocator(page, taskId); + const button = row.getByRole("group", { name: "Actions" }).getByRole("button", { name: action, exact: true }); + if ((await button.count()) === 0) return `the row does not offer "${action}"`; + if ((await button.getAttribute("aria-pressed")) !== "true") await button.click(); + const idField = row.locator('[data-field="taskId"] input').first(); + const locked = (await idField.getAttribute("readonly")) !== null || (await idField.isDisabled()); + if ((await idField.inputValue()) !== taskId || !locked) return `"${action}"'s form does not carry the row's id, locked`; + await row.getByRole("button", { name: /^run$/i }).click(); + return undefined; +} + +type Shown = { state: string; text: string }; + +/** What the row's outcome for `action` reads, once `until` holds (or the last read). */ +async function readOutcome( + page: Page, + taskId: string, + action: string, + until: (shown: Shown) => boolean, + ms = SETTLE_MS, +): Promise { + const line = rowLocator(page, taskId).locator(`[data-submission="${action}"] [data-outcome]`).first(); + let last: Shown | undefined; + for (let waited = 0; waited <= ms; waited += 250) { + if ((await line.count()) > 0) { + last = { state: (await line.getAttribute("data-outcome")) ?? "", text: ((await line.textContent()) ?? "").trim() }; + if (until(last)) return last; + } + await page.waitForTimeout(250); + } + return last; +} + +const settled = (shown: Shown) => shown.state !== "pending"; + +/** Grade one row's settled answer against the one the fixture fixed. */ +function grade(leg: Leg, shown: Shown | undefined, want: { state: string; contains: string[] }): void { + if (shown === undefined) { + fail(leg, "the row never showed an outcome"); + return; + } + if (shown.state !== want.state) { + fail(leg, `the row reads ${shown.state}: "${shown.text}", not ${want.state}`); + return; + } + const missing = want.contains.filter((part) => !shown.text.includes(part)); + if (missing.length > 0) { + fail(leg, `the row reads "${shown.text}", without ${missing.map((part) => JSON.stringify(part)).join(", ")}`); + return; + } + if (shown.text.includes(NO_RESULT)) { + fail(leg, `the row reads "${shown.text}"`); + return; + } + evidence.push(`${leg}: ${shown.state} "${shown.text}"`); +} + +// --------------------------------------------------------------------------- +// The run +// --------------------------------------------------------------------------- + +async function main(): Promise<{ failures: string[]; evidence: string }> { + if (CONTROL !== "" && EXPECTED[CONTROL] === undefined) throw new Error(`unknown control "${CONTROL}"`); + // The bundle the shell serves, built here so a stale one cannot be graded. + execFileSync("pnpm", ["--filter", "@flow-state-dev/devtool", "build:assets"], { cwd: REPO_ROOT, stdio: "inherit" }); + + const base = 4300 + Math.floor(Math.random() * 600); + const server = await serve(base); + const front = await proxy(server.origin, base + 1); + let browser: Browser | undefined; + const answers = fixture.answers; + try { + // ---- the subject: five rows on the board, one per leg -------------------- + const ids: Record = {} as never; + for (const [leg, goal] of Object.entries(fixture.rows) as Array<[keyof Fixture["rows"], string]>) { + ids[leg] = await fileRow(server.origin, goal); + } + + browser = await launchChromium(); + const page = await browser.newPage({ viewport: { width: 1280, height: 800 } }); + let navigations = 0; + page.on("framenavigated", (frame) => { + if (frame === page.mainFrame()) navigations += 1; + }); + await page.goto(front.origin, { waitUntil: "networkidle" }); + await openSession(page); + + // ---- handover, then hook: the second dispatch takes the one stream -------- + const handoverProblem = await startFromRow(page, ids.handover, "handover"); + if (handoverProblem !== undefined) fail("handover", handoverProblem); + const handoverFirst = await readOutcome(page, ids.handover, "handover", settled); + const hookProblem = await startFromRow(page, ids.hook, "hook"); + if (hookProblem !== undefined) fail("hook", hookProblem); + const hookShown = await readOutcome(page, ids.hook, "hook", settled); + // Graded after the hook leg's dispatch took the stream from it. + const handoverShown = await readOutcome(page, ids.handover, "handover", settled); + if (handoverProblem === undefined) { + if (handoverFirst !== undefined && handoverShown !== undefined && handoverFirst.text !== handoverShown.text) { + fail("handover", `the row read "${handoverFirst.text}", then "${handoverShown.text}" once the stream moved on`); + } + grade("handover", handoverShown, { state: "refused", contains: [answers.handover] }); + } + if (hookProblem === undefined) grade("hook", hookShown, { state: "refused", contains: [answers.hook] }); + + // ---- ref: a success held by reference ----------------------------------- + const refProblem = await startFromRow(page, ids.ref, "ref"); + if (refProblem !== undefined) fail("ref", refProblem); + else grade("ref", await readOutcome(page, ids.ref, "ref", settled), { state: "ok", contains: [JSON.stringify(answers.ref)] }); + + // ---- suspend: pending while suspended, then the resume's answer ---------- + const suspendProblem = await startFromRow(page, ids.suspend, "suspend"); + if (suspendProblem !== undefined) { + fail("suspend", suspendProblem); + } else { + const suspended = await requestOf(server.origin, "suspend", (status) => status === "suspended"); + if (suspended === undefined) { + fail("suspend", "the action never suspended"); + } else { + // Give the row two poll cycles to read the suspended request; it must stay pending. + await page.waitForTimeout(4_500); + const whileSuspended = await readOutcome(page, ids.suspend, "suspend", () => true, 0); + if (whileSuspended?.state !== "pending") { + fail("suspend", `while suspended the row reads ${whileSuspended?.state}: "${whileSuspended?.text}", not pending`); + } + const pending = await json(server.origin, `/sessions/${SESSION}/debug/suspensions`); + const list = Array.isArray(pending.body) ? pending.body : (pending.body?.suspensions ?? []); + const suspension = list.find((entry: { requestId?: string }) => entry.requestId === suspended.id); + const resumed = await json(server.origin, `/${KIND}/requests/${suspended.id}/resume`, { + method: "POST", + body: JSON.stringify({ + suspensionId: suspension?.suspensionId, + action: "submit", + data: { answer: answers.suspend }, + resumedBy: USER, + }), + }); + if (resumed.status >= 300) { + fail("suspend", `the resume answered ${resumed.status}: ${JSON.stringify(resumed.body)}`); + } else if (whileSuspended?.state === "pending") { + grade("suspend", await readOutcome(page, ids.suspend, "suspend", settled), { + state: "ok", + contains: [answers.suspend], + }); + } + } + } + + // ---- hook-fails: the action refused, then its hook failed the request ---- + const failsProblem = await startFromRow(page, ids.hookFails, "hookFails"); + if (failsProblem !== undefined) fail("hook-fails", failsProblem); + else { + grade("hook-fails", await readOutcome(page, ids.hookFails, "hookFails", settled), { + state: "failed", + contains: [answers.hookFails.error, answers.hookFails.refusal], + }); + } + await page.screenshot({ path: join(SHOTS, "rows.png"), fullPage: true }); + + // ---- api: the list the DevTool reads, through the same proxy ------------- + const expected: Record = { + handover: { output: { ok: false, error: answers.handover }, status: "completed" }, + hook: { output: { ok: false, error: answers.hook }, status: "completed" }, + ref: { output: answers.ref, status: "completed" }, + suspend: { output: { ok: true, answer: answers.suspend }, status: "completed" }, + hookFails: { output: { ok: false, error: answers.hookFails.refusal }, error: answers.hookFails.error, status: "failed" }, + }; + const withOutput = await listRequests(front.origin, "?include_result_output=true"); + const summaries = await listRequests(front.origin, ""); + for (const [action, want] of Object.entries(expected)) { + const full = withOutput.find((request) => request.actionName === action); + const summary = summaries.find((request) => request.actionName === action); + if (full === undefined || summary === undefined) { + fail("api", `the list has no ${action} request`); + continue; + } + const result = full.result as { output?: unknown; error?: { message?: string }; hasOutput?: boolean } | undefined; + if (full.status !== want.status) fail("api", `${action} lists ${full.status}, not ${want.status}`); + if (result == null) { + fail("api", `${action} lists no result`); + continue; + } + if (JSON.stringify(result.output) !== JSON.stringify(want.output)) { + fail("api", `${action} lists output ${JSON.stringify(result.output)}, not ${JSON.stringify(want.output)}`); + } + if (want.error !== undefined && !String(result.error?.message ?? "").includes(want.error)) { + fail("api", `${action} lists error ${JSON.stringify(result.error)}, not "${want.error}"`); + } + const brief = summary.result as { output?: unknown; error?: { message?: string }; hasOutput?: boolean } | undefined; + if (brief == null || "output" in brief || brief.hasOutput !== true) { + fail("api", `without the flag, ${action} lists ${JSON.stringify(brief)}: want hasOutput and no output`); + } else if (want.error !== undefined && !String(brief.error?.message ?? "").includes(want.error)) { + fail("api", `without the flag, ${action} lists no error`); + } + } + if (!failures.some((line) => line.startsWith("[api]"))) { + evidence.push("api: all five results listed with include_result_output; without it, status, error and hasOutput only"); + } + + if (navigations !== 1) fail("handover", `the page navigated ${navigations} times; it loads once`); + } finally { + await browser?.close(); + front.server.close(); + server.stop(); + } + + if (CONTROL !== "") { + const red = new Set(failures.map((line) => /^\[([^\]]+)\]/.exec(line)?.[1])); + const missed = EXPECTED[CONTROL]!.filter((leg) => !red.has(leg)); + const extra = [...red].filter((leg) => leg !== undefined && !EXPECTED[CONTROL]!.includes(leg as Leg)); + const expectedOk = missed.length === 0 && extra.length === 0; + console.log( + `control ${CONTROL}: ${expectedOk ? "every expected leg failed, and no other" : `missed ${missed.join(", ") || "none"}; unexpected ${extra.join(", ") || "none"}`}`, + ); + } + return { failures, evidence: evidence.join("; ") }; +} + +await runGoal(main); diff --git a/packages/cli/test/fixtures/flows/throwing-flow/flow.ts b/packages/cli/test/fixtures/flows/throwing-flow/flow.ts index e099862003..20f4cb816a 100644 --- a/packages/cli/test/fixtures/flows/throwing-flow/flow.ts +++ b/packages/cli/test/fixtures/flows/throwing-flow/flow.ts @@ -1,5 +1,7 @@ /** - * Test fixture: a flow whose action always throws, for error handling tests. + * Test fixture: a flow whose actions fail, for error handling tests. + * `fail` throws in its block; `answerThenHookFails` answers, then its + * completion hook throws, so the run fails after the action answered. */ import { defineFlow, handler } from "@flow-state-dev/core"; import { z } from "zod"; @@ -13,6 +15,19 @@ const throwingHandler = handler({ }, }); +const answeringHandler = handler({ + name: "answering-handler", + inputSchema: z.object({ message: z.string() }), + execute: async () => ({ ok: false, error: "already settled" }), +}); + +const throwingHook = handler({ + name: "throwing-hook", + execute: async () => { + throw new Error("Intentional completion hook error"); + }, +}); + const throwingFlow = defineFlow({ kind: "throwing", actions: { @@ -20,6 +35,11 @@ const throwingFlow = defineFlow({ inputSchema: z.object({ message: z.string() }), block: throwingHandler, }, + answerThenHookFails: { + inputSchema: z.object({ message: z.string() }), + block: answeringHandler, + onCompleted: throwingHook, + }, }, }); diff --git a/packages/cli/test/run-command.integration.test.ts b/packages/cli/test/run-command.integration.test.ts index ab1a84ce8f..460e950677 100644 --- a/packages/cli/test/run-command.integration.test.ts +++ b/packages/cli/test/run-command.integration.test.ts @@ -99,6 +99,22 @@ describe("fsdev run integration", () => { expect(errorEvent).toBeDefined(); }); + // A run a completion hook failed after the action answered reports the + // failure AND the answer: `output` is what the action returned, not null. + it("reports the action's answer on a run a completion hook failed", async () => { + const result = await executeRunCommand("throwing", "answerThenHookFails", { + input: '{"message": "test"}', + cwd: fixturesDir, + stores: createInMemoryStores(), + }); + + expect(result.success).toBe(false); + expect(result.error!.message).toContain("Intentional completion hook error"); + expect(result.output).toEqual({ ok: false, error: "already settled" }); + expect(process.exitCode).toBe(1); + expect(parsedEvents().find((e) => e.type === "error")).toBeDefined(); + }); + it("throws CliError for unknown flow kind", async () => { await expect( executeRunCommand("nonexistent", "action", { diff --git a/packages/client/README.md b/packages/client/README.md index 4da9b78b62..2eb8a52c1e 100644 --- a/packages/client/README.md +++ b/packages/client/README.md @@ -118,10 +118,13 @@ const snapshot = await sessions.getSessionState("sess_1", { // the first page's `at` and `sessionCreatedAt` to `createSessionSSEClient` // (`since`, `sessionCreatedAt`), so it follows the session you read. -// List a session's requests. Returns summaries only by default; pass -// `includeItems` to back-fill each request's item log — useful for inspecting -// requests that already completed (e.g. the DevTool's trace view). +// List a session's requests. A finished request carries `result`: `error` when +// it failed, and `hasOutput`. Pass `includeResultOutput` for the action's return +// value as `result.output`, and `includeItems` for each request's item log. +// `result` is absent while a request runs, on aborted or interrupted requests, +// and on history from a server that didn't save results: guard with `== null`. const requests = await sessions.listSessionRequests("sess_1", { + includeResultOutput: true, includeItems: true, }); ``` diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts index 3b56dc2b50..f8ca807a80 100644 --- a/packages/client/src/index.ts +++ b/packages/client/src/index.ts @@ -106,6 +106,7 @@ export type { ResourceSnapshotEntry, SendActionOptions, SessionDetail, + SessionRequestResult, SessionRequestSummary, SessionSSECallbacks, SessionStreamHandle, diff --git a/packages/client/src/session-client/sessions.ts b/packages/client/src/session-client/sessions.ts index 511fb71885..3c4ff33d56 100644 --- a/packages/client/src/session-client/sessions.ts +++ b/packages/client/src/session-client/sessions.ts @@ -65,6 +65,12 @@ export type ListSessionRequestsOptions = { * requests. */ includeItems?: boolean; + /** + * Request each finished request's `result.output` + * (`include_result_output=true`). Off by default: the summaries carry + * `result.error` and `result.hasOutput`, not the value the action returned. + */ + includeResultOutput?: boolean; }; /** @@ -227,7 +233,8 @@ export function createSessionClient(options: CreateSessionClientOptions = {}): S status: listOptions?.status, limit: listOptions?.limit, offset: listOptions?.offset, - include_items: listOptions?.includeItems + include_items: listOptions?.includeItems, + include_result_output: listOptions?.includeResultOutput }) }) }); diff --git a/packages/client/src/types/index.ts b/packages/client/src/types/index.ts index 9838ecbc54..9c03bd301b 100644 --- a/packages/client/src/types/index.ts +++ b/packages/client/src/types/index.ts @@ -272,10 +272,45 @@ export type SessionRequestSummary = { * via the state endpoint. Present on responses that carry full records. */ items?: OutputItem[]; + /** + * What the action came to, once the request has ended. See + * {@link SessionRequestResult}. + * + * Absent while the request runs or is suspended, and on `aborted` or + * `interrupted` requests. Absent on a `completed`, `incomplete` or `failed` + * request means no result was recorded (a server, or history, from before + * results were stored). Guard with `== null` (BP-030). + */ + result?: SessionRequestResult; createdAt: number; updatedAt: number; }; +/** + * A request's action result, as `GET /sessions/:id/requests` lists it. + * + * | Request ended | `result` | + * |---|---| + * | `completed` / `incomplete` | `{ output }`, the value the action returned; no `output` when it returned nothing | + * | `failed` | `{ error }`, plus `output` when the action answered before a completion hook failed the request | + * + * `output` is listed only when the caller passes `includeResultOutput: true`; + * `hasOutput` says whether there is one either way. + */ +export type SessionRequestResult = { + /** The action's return value. Listed only with `includeResultOutput`. */ + output?: unknown; + /** Whether the action's return value is stored, listed or not. */ + hasOutput?: boolean; + /** + * The action returned a value that could not be stored as JSON. The request + * still finished; its return value is unknown. + */ + outputNotRecorded?: true; + /** Why the request failed. */ + error?: { code: string; message: string }; +}; + /** * Client-visible metadata for a single resource in the snapshot. */ diff --git a/packages/client/test/sessions.test.ts b/packages/client/test/sessions.test.ts index bfa5ba8cc3..d41b9d304f 100644 --- a/packages/client/test/sessions.test.ts +++ b/packages/client/test/sessions.test.ts @@ -150,6 +150,24 @@ describe("createSessionClient", () => { ); }); + it("asks for each request's action output only with includeResultOutput", async () => { + // The list carries `result.error` and `hasOutput` either way; the output + // itself is opt-in, so a caller that polls pays for it only on request. + const fetcher = vi.fn(async () => + createJsonResponse({ + requests: [{ ...REQUESTS[0], result: { output: { ok: false, error: "no" }, hasOutput: true } }] + }) + ); + const client = createSessionClient({ fetcher }); + + const [listed] = await client.listSessionRequests("sess_1", { includeItems: true, includeResultOutput: true }); + + expect(fetcher.mock.calls[0]?.[0]).toBe( + "/api/flows/sessions/sess_1/requests?include_items=true&include_result_output=true" + ); + expect(listed?.result).toEqual({ output: { ok: false, error: "no" }, hasOutput: true }); + }); + it("lists debug suspensions with status filter and parses the response", async () => { const suspensions = [ { diff --git a/packages/devtool/src/react/DevToolPanel.tsx b/packages/devtool/src/react/DevToolPanel.tsx index 456678ec37..e802823c31 100644 --- a/packages/devtool/src/react/DevToolPanel.tsx +++ b/packages/devtool/src/react/DevToolPanel.tsx @@ -190,8 +190,8 @@ function PanelContent({ className }: { className?: string }) { const [liveRawItems, setLiveRawItems] = useState>(new Map()); // The last raw log each streamed request's stream delivered, kept after the // stream moves on. Read only once a request has finished, to add the traces - // its polled log lacks (a transient block's are never persisted), so a - // Tasks-tab row can still read its outcome (FIX-1629). + // its polled log lacks (a transient block's are never persisted), so the + // Stream and Trace tabs keep what they showed live. const [streamRawItems, setStreamRawItems] = useState>(new Map()); // The requests Tasks-tab rows dispatched in this workspace (FIX-1629). Only // one request is streamed at a time, so a row whose request is not the @@ -586,8 +586,10 @@ function PanelContent({ className }: { className?: string }) { ); // The Tasks tab changes a task only through the viewed flow's own actions, - // on this same dispatch path, and reads each outcome from the session's - // requests (FIX-1629). + // on this same dispatch path (FIX-1629), and reads each outcome from what + // the engine recorded for the request: its status and action result on the + // polled list (FIX-1661). Never from the stream, which holds one request at + // a time, or from traces, which a transient block never keeps. const runRowAction = useCallback( async (action: string, input: unknown): Promise => { const answer = await handleSendAction(action, input); @@ -599,14 +601,18 @@ function PanelContent({ className }: { className?: string }) { }, [handleSendAction], ); + const rowOutcomeSources = useMemo( + () => requests.map((req) => ({ requestId: req.id, status: req.status, result: req.result })), + [requests], + ); const rowActions = useMemo( () => ({ names: activeFlow?.actions ?? [], schemas: activeFlow?.actionSchemas, run: runRowAction, - requests: requestGroups, + requests: rowOutcomeSources, }), - [activeFlow?.actions, activeFlow?.actionSchemas, runRowAction, requestGroups], + [activeFlow?.actions, activeFlow?.actionSchemas, runRowAction, rowOutcomeSources], ); // Re-read the list while any row's request is still running (or not listed diff --git a/packages/devtool/src/react/components/workspace/task-row-actions.tsx b/packages/devtool/src/react/components/workspace/task-row-actions.tsx index 555b47bc72..5e65499744 100644 --- a/packages/devtool/src/react/components/workspace/task-row-actions.tsx +++ b/packages/devtool/src/react/components/workspace/task-row-actions.tsx @@ -7,7 +7,8 @@ * the panel's own action path, the one the action bar uses. There is no other * write here, and no record editor: what a row can do is what the flow exposes. * - * The answer is read from the request the row dispatched, on its root trace + * The answer is read from what the engine recorded for the request the row + * dispatched: its status and action result on the session's request list * (`outcomeOf`). A refusal is shown as a refusal, in the tool's own words. * * There is no client-side lock: a second submit while the first is in flight @@ -20,6 +21,7 @@ import { Button } from "../ui/button"; import { SchemaForm } from "./schema-form"; import { buildInputFromForm, getDefaults } from "./action-bar"; import { + NO_RESULT_RECORDED, outcomeOf, type RequestOutcomeSource, type RowActionOutcome, @@ -172,8 +174,8 @@ function Outcome({ outcome }: { outcome: RowActionOutcome }) { ); case "ok": return ( - - Done. The row updates when the task changes. + + {outcome.output === undefined ? "Done." : `Done: ${describeOutput(outcome.output)}`} ); case "refused": @@ -191,10 +193,20 @@ function Outcome({ outcome }: { outcome: RowActionOutcome }) { case "unknown": return ( - {outcome.reason === "no-trace" - ? "Sent. The outcome isn't visible: this request left no trace (trace observability is off)." - : "Sent. The outcome isn't visible: part of the result was not retained."} + {outcome.reason === "not-reported" + ? NO_RESULT_RECORDED + : "Finished, but its return value couldn't be recorded."} ); } } + +/** An action's return value as one line of text. */ +function describeOutput(output: unknown): string { + if (typeof output === "string") return output; + try { + return JSON.stringify(output) ?? String(output); + } catch { + return String(output); + } +} diff --git a/packages/devtool/src/react/hooks/use-session-requests.ts b/packages/devtool/src/react/hooks/use-session-requests.ts index 0a605d940a..a6c616f75f 100644 --- a/packages/devtool/src/react/hooks/use-session-requests.ts +++ b/packages/devtool/src/react/hooks/use-session-requests.ts @@ -71,9 +71,11 @@ export function useSessionRequests(sessionId: string | null) { }); } // Request full item logs so requests that completed before this view - // opened still render their trace tree (FIX-733). + // opened still render their trace tree (FIX-733), and each request's + // action output, which a Tasks-tab row reads its answer from (FIX-1661). const result = await sessionClient.listSessionRequests(sessionId, { - includeItems: true + includeItems: true, + includeResultOutput: true }); if (!stillCurrent()) return; setRequests(result); diff --git a/packages/devtool/src/react/lib/request-status.ts b/packages/devtool/src/react/lib/request-status.ts index ddedbc54f9..b17ffbc6e0 100644 --- a/packages/devtool/src/react/lib/request-status.ts +++ b/packages/devtool/src/react/lib/request-status.ts @@ -72,13 +72,13 @@ export function snapshotSupersedesLive( } /** - * A finished request's raw log for reading its outcome: the polled log, plus - * any item only its stream saw. + * A finished request's raw log for the trace views: the polled log, plus any + * item only its stream saw. * - * A transient block's traces (an action's root among them, when its block is - * transient) stream live and are never persisted, so the polled log lacks - * them. The polled entry wins for an item both carry; stream-only items are - * appended in the order the stream saw them. + * A transient block's traces stream live and are never persisted, so the + * polled log lacks them. The polled entry wins for an item both carry; + * stream-only items are appended in the order the stream saw them. A Tasks + * row never reads this: its answer is the request's recorded result. * * @param polled The request's polled raw log. * @param streamed What a stream delivered for the same request, if any. diff --git a/packages/devtool/src/react/lib/task-actions.ts b/packages/devtool/src/react/lib/task-actions.ts index 98b96d57b3..b75736de71 100644 --- a/packages/devtool/src/react/lib/task-actions.ts +++ b/packages/devtool/src/react/lib/task-actions.ts @@ -14,10 +14,7 @@ * the DevTool depends on client, core and react only, as it mirrors the other * wire shapes it reads (see `task-collection-state`). */ -import type { ActionInputSchema } from "@flow-state-dev/client"; -import { buildItemLookup, type ItemLookup } from "@flow-state-dev/core/items"; -import type { BlockValueInternal } from "@flow-state-dev/core/items/internal"; -import { resolveBlockValueInternal } from "@flow-state-dev/core/items/internal"; +import type { ActionInputSchema, SessionRequestResult } from "@flow-state-dev/client"; import { isRequestOpen } from "./request-status"; /** @@ -98,172 +95,89 @@ export function taskActionsFor( }); } -/** One request as the panel's request groups carry it: enough to read its outcome. */ +/** + * One request as the session's request list reports it: its status and the + * action result the engine recorded for it. + */ export type RequestOutcomeSource = { requestId: string; status: string; - /** The request's raw item log, traces included. */ - rawItems?: readonly unknown[]; + /** + * The stored action result. Absent (or `null`) while the request runs or is + * suspended, on an aborted or interrupted one, and on a finished request no + * result was recorded for (an older server, or history from before an + * upgrade). + */ + result?: SessionRequestResult | null; }; /** * What a row action came to, read from the request it dispatched. * * - `pending` — the request has not finished (or has not been listed yet). - * - `ok` — the root block returned something other than a refusal. - * - `refused` — the root block returned `{ ok: false }` (a guarded verb said - * no) or a declined task write (`{ outcome: "declined" }`), and wrote - * nothing. - * - `failed` — the request failed, or the dispatch itself threw. - * - `unknown` — the result cannot be told: the request finished with no root - * trace to read (`no-trace`, trace observability off), or part of the root's - * output is a reference whose target was not retained (`not-retained`). - * Never read as success: a refusal can hide in either. + * - `ok` — the action returned something other than a refusal. + * - `refused` — the action returned `{ ok: false }` (a guarded verb said no) + * or a declined task write (`{ outcome: "declined" }`), and wrote nothing. + * - `failed` — the request ended in anything but `completed`, or the dispatch + * itself threw. + * - `unknown` — the request completed, but no result was recorded for it + * (`not-reported`), or its return value could not be stored + * (`output-not-recorded`). Never read as success: a refusal can hide in + * either. */ export type RowActionOutcome = | { state: "pending" } | { state: "ok"; output: unknown } | { state: "refused"; message: string } | { state: "failed"; message: string } - | { state: "unknown"; reason: "no-trace" | "not-retained" }; + | { state: "unknown"; reason: "not-reported" | "output-not-recorded" }; -type TraceLike = { - id?: string; - type?: string; - status?: string; - provenance?: { parentBlockInstanceId?: string }; - input?: { source?: BlockValueInternal }; - output?: BlockValueInternal; - error?: { message?: string }; -}; +/** What the row says for a finished request no result was recorded for. */ +export const NO_RESULT_RECORDED = "No result recorded for this request."; /** - * Read a dispatched request's outcome off the action's own root `block_trace`. + * Read a dispatched request's outcome off its entry in the session's request + * list: the status the engine wrote, and the action result it wrote in the + * same write. * - * The dispatch response carries a request id and no output, and a refused - * verb emits no change item, so the action's root trace is the one place the - * tool's `{ ok, error }` can be read. - * - * It is not simply the last root trace. `runAction` runs the flow's and the - * action's lifecycle hooks (`onStarted`, `onCompleted`, `onErrored`, - * `onFinished`) as root blocks of the same request, before and after the - * action, all under the same block instance id. Each hook receives - * `{ requestId, actionName }` for this request, which the action's own input - * cannot carry (the id is minted when the request starts), so a root whose - * input is that is a hook. The action's trace is the last root that is not. - * The raw log keeps several entries per trace (`in_progress`, then the one - * with the result), so entries are merged by item id before they are read. - * - * An output held by reference (a `ref` to a step's trace, or a `structure` of - * them) is resolved against the request's own items first. If any reference - * in it, at any depth, has no target, the resolved value has a hole where the - * refusal may have been, so it reads as `unknown` rather than being - * classified. The request's own status is read before the action's answer: - * while it runs, a hook can still fail it, so the answer waits; a request that - * ended in anything but `completed` reads as failed, carrying the action's - * refusal when it had one. + * The status decides first. Until the request ends, a completion hook can + * still fail it, so an answer is not read yet. A request that ended in + * anything but `completed` reads as failed, with the recorded error, and names + * the action's refusal when it had one. Only a completed request's output is + * classified, and a completed request with no recorded result is never + * guessed at. */ export function outcomeOf( requests: readonly RequestOutcomeSource[], requestId: string ): RowActionOutcome { const request = requests.find((candidate) => candidate.requestId === requestId); - if (request === undefined) return { state: "pending" }; - const lookup = buildItemLookup((request.rawItems ?? []) as readonly { id: string; type: string }[]); - const roots = mergedRootTraces(request.rawItems ?? []); - const isHook = (trace: TraceLike) => isHookInput(resolveInput(trace, lookup), requestId); - const root = [...roots].reverse().find((trace) => !isHook(trace)); - - // Order matters. A failed action is failed whatever happens after it. Then - // the request's own verdict: until it ends, a hook can still fail it, so a - // completed action is not yet an answer; once it has ended in anything but - // `completed`, it failed (BR-15), even if the action itself answered. - if (root?.status === "failed") { - return { state: "failed", message: root.error?.message ?? "The action failed." }; - } - if (isRequestOpen(request.status)) return { state: "pending" }; + if (request === undefined || isRequestOpen(request.status)) return { state: "pending" }; + const result = request.result ?? undefined; if (request.status !== "completed") { - const failedHook = [...roots].reverse().find((trace) => trace.status === "failed"); - // A request that failed before its action ran has no trace to name the - // cause; the runtime records it as a failed `error` item instead. + const ended = `The request ended ${request.status}.`; + // Aborted and interrupted requests carry no result by design. + const expectsResult = request.status === "failed" || request.status === "incomplete"; const message = - failedHook?.error?.message ?? lastErrorItemMessage(request.rawItems ?? []) ?? `The request ended ${request.status}.`; - const answer = root?.status === "completed" ? classifyAnswer(root, lookup) : undefined; + result?.error?.message ?? (result === undefined && expectsResult ? `${ended} ${NO_RESULT_RECORDED}` : ended); + const answer = result !== undefined && "output" in result ? classify(result.output) : undefined; return { state: "failed", message: answer?.state === "refused" ? `${message} (the action itself refused: ${answer.message})` : message, }; } - if (root?.status !== "completed") return { state: "unknown", reason: "no-trace" }; - return classifyAnswer(root, lookup); -} - -/** The message of the latest failed `error` item in a request's log, if any. */ -function lastErrorItemMessage(rawItems: readonly unknown[]): string | undefined { - for (let i = rawItems.length - 1; i >= 0; i--) { - const item = rawItems[i] as { type?: unknown; status?: unknown; message?: unknown } | null; - if (item?.type === "error" && item.status === "failed" && typeof item.message === "string") return item.message; - } - return undefined; + if (result === undefined) return { state: "unknown", reason: "not-reported" }; + if (result.outputNotRecorded === true) return { state: "unknown", reason: "output-not-recorded" }; + return classify(result.output); } -/** What a completed action root answered: a refusal, success, or a hole where the answer was. */ -function classifyAnswer(root: TraceLike, lookup: ItemLookup): RowActionOutcome { - if (root.output !== undefined && hasUnresolvedRef(root.output, lookup, 0)) { - return { state: "unknown", reason: "not-retained" }; - } - const value = resolveBlockValueInternal(root.output, lookup); +/** What a completed action answered: a refusal, or success. */ +function classify(value: unknown): RowActionOutcome { if (isRefusal(value)) return { state: "refused", message: refusalMessage(value.error) }; if (isDeclined(value)) return { state: "refused", message: declinedMessage(value) }; return { state: "ok", output: value }; } -/** Every root `block_trace`, one per item id with its entries merged in log order. */ -function mergedRootTraces(rawItems: readonly unknown[]): TraceLike[] { - const byId = new Map(); - rawItems.forEach((item, index) => { - const trace = item as TraceLike; - if (trace.type !== "block_trace") return; - const key = trace.id ?? index; - byId.set(key, { ...byId.get(key), ...trace }); - }); - return [...byId.values()].filter((trace) => trace.provenance?.parentBlockInstanceId === undefined); -} - -function resolveInput(trace: TraceLike, lookup: ItemLookup): unknown { - const source = trace.input?.source; - return source === undefined ? undefined : resolveBlockValueInternal(source, lookup); -} - -/** A request lifecycle hook's input: `{ requestId, actionName, … }` for this request. */ -function isHookInput(input: unknown, requestId: string): boolean { - return ( - typeof input === "object" && - input !== null && - (input as { requestId?: unknown }).requestId === requestId && - typeof (input as { actionName?: unknown }).actionName === "string" - ); -} - -/** - * Does any `ref` in `value`, at any depth, fail to reach content? Walks the - * same hops `resolveBlockValueInternal` takes, which resolves a miss to - * `undefined` in place and so cannot say one happened. - */ -function hasUnresolvedRef(value: BlockValueInternal, lookup: ItemLookup, refHops: number): boolean { - if (value.kind === "inline") return false; - if (value.kind === "ref") { - if (refHops > 1) return true; - const target = lookup(value.sourceItemId); - if (target?.type === "message") return false; - if (target?.type !== "block_trace") return true; - const output = (target as { output?: BlockValueInternal }).output; - return output === undefined || hasUnresolvedRef(output, lookup, refHops + 1); - } - const entries = value.shape.container === "array" ? value.shape.entries : Object.values(value.shape.entries); - return entries.some((entry) => hasUnresolvedRef(entry, lookup, 0)); -} - /** `{ ok: false }` is a refusal whatever its `error` holds, or without one. */ function isRefusal(value: unknown): value is { ok: false; error?: unknown } { return typeof value === "object" && value !== null && (value as { ok?: unknown }).ok === false; diff --git a/packages/devtool/test/devtool-panel-session-reset.test.tsx b/packages/devtool/test/devtool-panel-session-reset.test.tsx index df3aa1f6f7..bc3e1e2b50 100644 --- a/packages/devtool/test/devtool-panel-session-reset.test.tsx +++ b/packages/devtool/test/devtool-panel-session-reset.test.tsx @@ -187,32 +187,46 @@ vi.mock("../src/react/components/workspace/action-bar", () => ({ // The third work-starting path: the per-row Continue action for an interrupted // request, which the panel hands to the stream view. +/** The request groups the panel last handed the Stream tab. */ +let lastStreamGroups: Array<{ requestId: string; rawItems: unknown[] }> = []; vi.mock("../src/react/components/workspace/stream-view", () => ({ - StreamView: ({ onContinue }: { onContinue: (requestId: string) => void }) => ( - - ), + StreamView: ({ + onContinue, + requestGroups, + }: { + onContinue: (requestId: string) => void; + requestGroups: Array<{ requestId: string; rawItems: unknown[] }>; + }) => { + lastStreamGroups = requestGroups; + return ; + }, })); // The Tasks tab, reduced to the row-action seam the panel hands it: each click // dispatches through `rowActions.run`, as an expanded row's form does. const rowAnswers: Array> = []; -/** The request groups the panel last handed the Tasks tab. */ -let lastRowRequests: Array<{ requestId: string; status?: string; items: unknown[]; rawItems: unknown[] }> = []; +/** What the panel last handed the Tasks tab's rows to read their answers from. */ +let lastRowRequests: RequestOutcomeSource[] = []; +/** The flat item stream the panel last handed the Tasks tab. */ +let lastTaskItems: unknown[] = []; /** How many times the Tasks tab has been mounted; its open rows live in that mount's state. */ let taskViewMounts = 0; vi.mock("../src/react/components/workspace/task-collections-view", async () => { const { useState } = await import("react"); return { TaskCollectionsView: ({ + items, rowActions, }: { + items: unknown[]; rowActions: { run: (action: string, input: unknown) => Promise; - requests: Array<{ requestId: string; items: unknown[]; rawItems: unknown[] }>; + requests: RequestOutcomeSource[]; }; }) => { const [mount] = useState(() => ++taskViewMounts); lastRowRequests = rowActions.requests; + lastTaskItems = items; return (