From 2013d34f63081741338be413786a7beb51939ca9 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 30 Sep 2026 01:52:14 +0000 Subject: [PATCH 1/7] feat(engine,client,devtool): record each request's action result; the DevTool row reads it (FIX-1661) The engine writes the action's result on the request record in the same write as the final status, through one typed settlement, and the session request list returns it (output only with include_result_output). The DevTool's Tasks-tab row reads status + result from the polled list; the trace reconstruction and the stream-log cache are deleted. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_014LohgYyHsXCYQd6kABH11N --- packages/client/src/index.ts | 1 + .../client/src/session-client/sessions.ts | 9 +- packages/client/src/types/index.ts | 35 +++ packages/client/test/sessions.test.ts | 18 ++ packages/devtool/src/react/DevToolPanel.tsx | 41 +-- .../components/workspace/task-row-actions.tsx | 24 +- .../src/react/hooks/use-session-requests.ts | 6 +- .../devtool/src/react/lib/request-status.ts | 19 -- .../devtool/src/react/lib/task-actions.ts | 176 +++-------- .../test/devtool-panel-session-reset.test.tsx | 63 ++-- packages/devtool/test/request-status.test.ts | 19 +- packages/devtool/test/task-actions.test.ts | 260 +++++----------- .../devtool/test/task-row-actions.test.tsx | 60 ++-- .../devtool/test/use-session-requests.test.ts | 4 +- .../src/execution/request-action-result.ts | 77 +++++ packages/engine/src/execution/runAction.ts | 86 ++++-- packages/engine/src/index.ts | 1 + packages/engine/src/routes/session-routes.ts | 28 +- packages/engine/src/stores/index.ts | 1 + .../testing/request-store-conformance.ts | 35 +++ packages/engine/src/stores/types.ts | 46 +++ .../host/createInboundTransportHost.ts | 25 +- .../engine/test/request-action-result.test.ts | 285 ++++++++++++++++++ .../engine/test/served-setup-failure.test.ts | 4 + .../test/session-requests-result.test.ts | 119 ++++++++ packages/engine/test/transports/host.test.ts | 5 +- .../scenarios/request-action-result.test.ts | 148 +++++++++ 27 files changed, 1125 insertions(+), 470 deletions(-) create mode 100644 packages/engine/src/execution/request-action-result.ts create mode 100644 packages/engine/test/request-action-result.test.ts create mode 100644 packages/engine/test/session-requests-result.test.ts create mode 100644 packages/integration-tests/src/scenarios/request-action-result.test.ts 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 07f284711e..e359f6d1a0 100644 --- a/packages/devtool/src/react/DevToolPanel.tsx +++ b/packages/devtool/src/react/DevToolPanel.tsx @@ -53,7 +53,7 @@ import { useFocusRevalidate } from "./hooks/use-focus-revalidate"; import { useDispatchRuns } from "./hooks/use-dispatch-runs"; import { useReadFence } from "@flow-state-dev/react"; import { flattenTaskItems } from "./lib/task-collection-state"; -import { isRequestOpen, mergeRawItems, pickFurthestStatus, snapshotSupersedesLive } from "./lib/request-status"; +import { isRequestOpen, pickFurthestStatus, snapshotSupersedesLive } from "./lib/request-status"; const NAV_EXPANDED_WIDTH = 300; const NAV_COLLAPSED_WIDTH = 64; @@ -188,11 +188,6 @@ function PanelContent({ className }: { className?: string }) { // Raw (uncollapsed) counterpart of `liveItems`, populated only by the // per-row Continue action (FIX-865) — see `handleContinueItems` below. 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). - 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 // streamed one learns it finished only from a re-read of the list; see the @@ -238,7 +233,6 @@ function PanelContent({ className }: { className?: string }) { setDispatchedRequestId(null); setLiveItems(new Map()); setLiveRawItems(new Map()); - setStreamRawItems(new Map()); setRowRequestIds(new Set()); clearReplay(); } @@ -370,17 +364,6 @@ function PanelContent({ className }: { className?: string }) { setActiveRequestId(null); }, [liveMode, activeRequestId, dispatchedRequestId, replayState.requestId]); - useEffect(() => { - if (streamState === null || streamState.rawItems.length === 0) return; - const { requestId, rawItems } = streamState; - setStreamRawItems((prev) => { - if (prev.get(requestId) === rawItems) return prev; - const next = new Map(prev); - next.set(requestId, rawItems); - return next; - }); - }, [streamState]); - useEffect(() => { if (streamRequestId && streamItems.length > 0) { setLiveItems((prev) => { @@ -431,12 +414,8 @@ function PanelContent({ className }: { className?: string }) { // per-row Continue action's own stream (`liveRawItems`) takes // priority; for the watched main-stream request, fall back to the // live `streamState.rawItems` (trace-inclusive) before the polled list. - // A finished request's polled log, plus what only a stream saw of it. rawItems: settled - ? mergeRawItems( - req.items!, - liveRawItems.get(req.id) ?? streamFor(req.id)?.rawItems ?? streamRawItems.get(req.id), - ) + ? req.items! : (liveRawItems.get(req.id) ?? streamFor(req.id)?.rawItems ?? req.items ?? []), source: req.source, metadata: req.metadata, @@ -453,7 +432,7 @@ function PanelContent({ className }: { className?: string }) { }); } return groups; - }, [requests, liveItems, liveRawItems, streamRawItems, activeRequestId, lastResponse, streamState, streamStatus, streamRequestId]); + }, [requests, liveItems, liveRawItems, activeRequestId, lastResponse, streamState, streamStatus, streamRequestId]); // The flat item stream the Tasks tab and the block tree fold. Derived here // rather than in the JSX because `flatMap` returns a NEW array on every @@ -582,8 +561,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); @@ -595,14 +576,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..c1b1e6c4f2 100644 --- a/packages/devtool/src/react/lib/request-status.ts +++ b/packages/devtool/src/react/lib/request-status.ts @@ -70,22 +70,3 @@ export function snapshotSupersedesLive( if (storeItems === undefined || storeItems.length === 0) return false; return REQUEST_STATUS_RANK[storeStatus] === 2; } - -/** - * A finished request's raw log for reading its outcome: 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. - * - * @param polled The request's polled raw log. - * @param streamed What a stream delivered for the same request, if any. - */ -export function mergeRawItems(polled: T[], streamed: readonly T[] | undefined): T[] { - if (streamed === undefined || streamed.length === 0) return polled; - const seen = new Set(polled.map((item) => item.id)); - const extra = streamed.filter((item) => !seen.has(item.id)); - return extra.length === 0 ? polled : [...polled, ...extra]; -} 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 1f9aac56a3..a2d113f65e 100644 --- a/packages/devtool/test/devtool-panel-session-reset.test.tsx +++ b/packages/devtool/test/devtool-panel-session-reset.test.tsx @@ -196,23 +196,28 @@ vi.mock("../src/react/components/workspace/stream-view", () => ({ // 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 ( - ), + 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 @@ -246,6 +255,7 @@ describe("DevToolPanel — session switch releases the dispatched request", () = streamMock.streamState = null; lastRowRequests = []; lastTaskItems = []; + lastStreamGroups = []; devToolState.activeSessionId = "sess_1"; devToolState.workspaceToken = 0; sendAction.mockReset().mockResolvedValue(null); @@ -641,8 +651,9 @@ describe("DevToolPanel — session switch releases the dispatched request", () = }); const recorded = { output: { ok: false, error: "task is cancelled, which is terminal" } }; + const polled = [{ id: "a_hook", type: "block_trace" }]; requestsState.requests = [ - { id: "req_a", status: "completed", items: [], result: recorded }, + { id: "req_a", status: "completed", items: polled, result: recorded }, { id: "req_b", status: "in_progress", items: [] }, ]; await act(async () => view.rerender()); @@ -650,6 +661,15 @@ describe("DevToolPanel — session switch releases the dispatched request", () = state: "refused", message: "task is cancelled, which is terminal", }); + // The inspector views still show the transient trace only the stream saw: + // the polled log lacks it, and a finished request keeps what streamed. + await act(async () => { + fireEvent.mouseDown(screen.getByRole("tab", { name: "Stream" })); + }); + expect(lastStreamGroups.find((group) => group.requestId === "req_a")?.rawItems).toEqual([...polled, streamedRefusal]); + await act(async () => { + fireEvent.mouseDown(screen.getByRole("tab", { name: "Tasks" })); + }); // A listing that recorded nothing for A reads as nothing recorded, even // with A's refusal sitting in what the stream saw. diff --git a/packages/devtool/test/request-status.test.ts b/packages/devtool/test/request-status.test.ts index 98350f0937..78912753fd 100644 --- a/packages/devtool/test/request-status.test.ts +++ b/packages/devtool/test/request-status.test.ts @@ -6,7 +6,7 @@ * catches up. */ import { describe, expect, it } from "vitest"; -import { pickFurthestStatus, snapshotSupersedesLive } from "../src/react/lib/request-status"; +import { mergeRawItems, pickFurthestStatus, snapshotSupersedesLive } from "../src/react/lib/request-status"; describe("pickFurthestStatus", () => { it("prefers a mid-flight suspend the snapshot hasn't caught up to", () => { @@ -62,3 +62,19 @@ describe("snapshotSupersedesLive", () => { expect(snapshotSupersedesLive("completed", undefined, false)).toBe(false); }); }); + +describe("mergeRawItems", () => { + // A transient trace streams live but is never persisted, so the polled log + // of a finished request lacks it. Replacing the stream's log with the polled + // one would drop an observed block from the Stream and Trace tabs. + it("keeps the polled log and adds what only the stream saw", () => { + const polled = [{ id: "a", v: "polled" }, { id: "b" }]; + const streamed = [{ id: "a", v: "stream" }, { id: "t", transient: true }]; + expect(mergeRawItems(polled, streamed)).toEqual([{ id: "a", v: "polled" }, { id: "b" }, { id: "t", transient: true }]); + }); + + it("is the polled log when nothing was streamed", () => { + const polled = [{ id: "a" }]; + expect(mergeRawItems(polled, undefined)).toBe(polled); + }); +}); From b9fdfeafa7e44c3e12fad8e9d6fc91778b5ce7e2 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 30 Sep 2026 02:56:21 +0000 Subject: [PATCH 7/7] fix(engine): snapshot the recorded output when the action answers, before completion hooks (FIX-1661) Review round 5: the record's JSON copy was taken at settle time, after the completion hooks, so a hook that mutated the returned object changed the recorded answer (PLAN S3 captures before hooks). recordOutput() now takes the snapshot when the action answers; RequestSettlement carries that RecordedOutput for both the completed and the answered-then-failed settlements. The new test goes red with the snapshot taken at settle. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_014LohgYyHsXCYQd6kABH11N --- .../src/execution/request-action-result.ts | 29 +++++++++--- packages/engine/src/execution/runAction.ts | 12 +++-- .../engine/test/request-action-result.test.ts | 46 ++++++++++++++++--- 3 files changed, 68 insertions(+), 19 deletions(-) diff --git a/packages/engine/src/execution/request-action-result.ts b/packages/engine/src/execution/request-action-result.ts index 28daab6e92..e0f1851826 100644 --- a/packages/engine/src/execution/request-action-result.ts +++ b/packages/engine/src/execution/request-action-result.ts @@ -18,19 +18,34 @@ import type { RequestActionResult } from "../stores/types"; */ export type SettlementError = { code?: string; message: string }; +/** + * The action's output as the record stores it, taken by {@link recordOutput} + * the moment the action answers: before the completion hooks run, so a hook + * that mutates the returned object cannot change the recorded answer. + */ +export type RecordedOutput = Pick; + +/** + * Snapshot an action's return value for its record. See + * {@link RecordedOutput} for when to call it. + */ +export function recordOutput(output: unknown): RecordedOutput { + return recordableOutput(output); +} + /** * How a request ended, with what its record's `result` is built from. * - * - `completed` / `incomplete` — the action's own return value (`undefined` - * when it returned nothing). + * - `completed` / `incomplete` — the action's own return value, recorded when + * it answered. * - `failed` — the cause, when the writer has one, and `answered` when the * action had returned before something after it (a completion hook) failed * the request. * - `aborted` / `interrupted` / `suspended` — no result, by design. */ export type RequestSettlement = - | { status: "completed" | "incomplete"; output: unknown } - | { status: "failed"; error?: SettlementError; answered?: { output: unknown } } + | { status: "completed" | "incomplete"; recorded: RecordedOutput } + | { status: "failed"; error?: SettlementError; answered?: RecordedOutput } | { status: "aborted" } | { status: "interrupted" } | { status: "suspended" }; @@ -43,10 +58,10 @@ export function buildRequestActionResult(settlement: RequestSettlement): Request switch (settlement.status) { case "completed": case "incomplete": - return recordableOutput(settlement.output); + return { ...settlement.recorded }; case "failed": return { - ...(settlement.answered !== undefined ? recordableOutput(settlement.answered.output) : {}), + ...(settlement.answered ?? {}), ...(settlement.error !== undefined ? { error: { code: settlement.error.code ?? "execution_error", message: settlement.error.message } } : {}) @@ -84,7 +99,7 @@ export function settledRecordFields(settlement: RequestSettlement): { * an object key whose value is `undefined` is left out, which reads back the * same. */ -function recordableOutput(output: unknown): RequestActionResult { +function recordableOutput(output: unknown): RecordedOutput { if (output === undefined) return {}; let text: string | undefined; let lossy = false; diff --git a/packages/engine/src/execution/runAction.ts b/packages/engine/src/execution/runAction.ts index 90948d4c30..562954cfcc 100644 --- a/packages/engine/src/execution/runAction.ts +++ b/packages/engine/src/execution/runAction.ts @@ -37,7 +37,7 @@ import { normalizeError, displayCause } from "../errors/normalize-error"; import type { RequestRecord, StoreRegistry } from "../stores/types"; import { createInternalResponseEmitter } from "../streaming/response-emitter"; import { executeBlock } from "./executeBlock"; -import { settledRecordFields, type RequestSettlement } from "./request-action-result"; +import { recordOutput, settledRecordFields, type RecordedOutput, type RequestSettlement } from "./request-action-result"; import { getResponseItems, getResponseItemCount } from "./internal/response"; import { applyNormalizedErrorSeam, @@ -1841,7 +1841,9 @@ export async function runActionInternal< // What the action block returned, once it has. Set before the completion // hooks run, so a hook that fails the request leaves it on the record. - let actionAnswer: { output: unknown } | undefined; + // `recorded` is the record's snapshot, taken then too, so a hook that + // mutates the returned object cannot change the recorded answer. + let actionAnswer: { output: unknown; recorded: RecordedOutput } | undefined; try { // Re-throw deferred parse error now that we have ctx for error handling. @@ -2007,7 +2009,7 @@ export async function runActionInternal< // The action has answered. Anything that fails the request from here on // (a completion hook, the token budget) keeps this answer on the failed // record beside its own error (FIX-1661). - actionAnswer = { output: result.output }; + actionAnswer = { output: result.output, recorded: recordOutput(result.output) }; const tokenBudget = getActionTokenBudget(action); let terminalStatus: "completed" | "incomplete" = "completed"; @@ -2142,7 +2144,7 @@ export async function runActionInternal< await settleRequestRecord( options.stores, requestId, - { status: terminalStatus, output: result.output }, + { status: terminalStatus, recorded: actionAnswer.recorded }, { completedAtMs: completedAt, items } ); @@ -2477,7 +2479,7 @@ export async function runActionInternal< await settleRequestRecord( options.stores, requestId, - { status: "failed", error: normalized, answered: actionAnswer }, + { status: "failed", error: normalized, answered: actionAnswer?.recorded }, { failedAtMs: failedAt, items: itemsToPersist() } ); diff --git a/packages/engine/test/request-action-result.test.ts b/packages/engine/test/request-action-result.test.ts index 0ec33d0a1f..786dd773fd 100644 --- a/packages/engine/test/request-action-result.test.ts +++ b/packages/engine/test/request-action-result.test.ts @@ -13,7 +13,7 @@ import { z } from "zod"; import { describe, expect, it } from "vitest"; import { continueRequest, createFlowRegistry, createInMemoryStores, runAction } from "../src"; import { createCheckpointDurabilityProvider } from "../src/durability/checkpoint-durability-provider"; -import { buildRequestActionResult } from "../src/execution/request-action-result"; +import { buildRequestActionResult, recordOutput } from "../src/execution/request-action-result"; const answer = { ok: false, error: "task is cancelled, which is terminal" }; @@ -191,12 +191,12 @@ describe("the request record's action result", () => { throw new Error("not serializable"); } }; - expect(buildRequestActionResult({ status: "completed", output: hostile })).toEqual({ outputNotRecorded: true }); - expect(buildRequestActionResult({ status: "failed", answered: { output: hostile } })).toEqual({ + expect(buildRequestActionResult({ status: "completed", recorded: recordOutput(hostile) })).toEqual({ outputNotRecorded: true }); + expect(buildRequestActionResult({ status: "failed", answered: recordOutput(hostile) })).toEqual({ outputNotRecorded: true }); // A toJSON that returns undefined stringifies to `undefined` rather than throwing. - expect(buildRequestActionResult({ status: "completed", output: { toJSON: () => undefined } })).toEqual({ + expect(buildRequestActionResult({ status: "completed", recorded: recordOutput({ toJSON: () => undefined }) })).toEqual({ outputNotRecorded: true }); }); @@ -222,25 +222,57 @@ describe("the request record's action result", () => { ["a typed array", new Uint8Array([1, 2])] ]; for (const [label, output] of lossy) { - expect(buildRequestActionResult({ status: "completed", output }), label).toEqual({ outputNotRecorded: true }); + expect(buildRequestActionResult({ status: "completed", recorded: recordOutput(output) }), label).toEqual({ outputNotRecorded: true }); } // What JSON keeps faithfully is stored as JSON: a Date as its ISO string, // an undefined-valued key left out (it reads back undefined either way). const at = new Date("2026-09-30T00:00:00.000Z"); expect( - buildRequestActionResult({ status: "completed", output: { at, ok: false, detail: undefined } }) + buildRequestActionResult({ status: "completed", recorded: recordOutput({ at, ok: false, detail: undefined }) }) ).toEqual({ output: { at: "2026-09-30T00:00:00.000Z", ok: false } }); // A class instance's own fields and a boxed primitive survive JSON. class Verdict { constructor(readonly ok: boolean) {} } expect( - buildRequestActionResult({ status: "completed", output: { v: new Verdict(true), n: Object(3) } }) + buildRequestActionResult({ status: "completed", recorded: recordOutput({ v: new Verdict(true), n: Object(3) }) }) ).toEqual({ output: { v: { ok: true }, n: 3 } }); }); // Storage is uncapped by design (D1): a large answer is still the answer, // and only a listing that opts into outputs pays to carry it. + // The record holds the action's answer, not what a completion hook later + // did to the object the action returned. + it("records the answer as the action returned it, before a completion hook mutates it (BR-1)", async () => { + const returned = { ok: true, note: "as answered" }; + const hookFails = { ok: true, note: "as answered" }; + const { record } = await run( + oneAction({ + execute: () => returned, + flowOnCompleted: () => { + returned.note = "changed by a hook"; + } + }), + "req_hook_mutates" + ); + expect(record?.status).toBe("completed"); + expect(record?.result).toEqual({ output: { ok: true, note: "as answered" } }); + + // The same holds when the mutating hook then fails the request. + const failed = await run( + oneAction({ + execute: () => hookFails, + onCompleted: () => { + hookFails.note = "changed by a hook"; + throw new Error("hook failed after mutating"); + } + }), + "req_hook_mutates_fails" + ); + expect(failed.record?.status).toBe("failed"); + expect(failed.record?.result?.output).toEqual({ ok: true, note: "as answered" }); + }); + it("stores a large output whole", async () => { const blob = "é".repeat(256 * 1024); const { record, returned } = await run(oneAction({ execute: () => ({ blob }) }), "req_large");