diff --git a/.changeset/durable-brunch-stop.md b/.changeset/durable-brunch-stop.md new file mode 100644 index 00000000000..fc8ff7e0628 --- /dev/null +++ b/.changeset/durable-brunch-stop.md @@ -0,0 +1,5 @@ +--- +"@hashintel/petrinaut": patch +--- + +Let hosts make the assistant's Stop action durable before Petrinaut cancels its local response stream, while preserving local-only cancellation for hosts that do not provide the new stop request. diff --git a/.changeset/flue-voice-safety.md b/.changeset/flue-voice-safety.md new file mode 100644 index 00000000000..5540dee7b70 --- /dev/null +++ b/.changeset/flue-voice-safety.md @@ -0,0 +1,5 @@ +--- +"@hashintel/petrinaut": patch +--- + +Add half-duplex Voice handoff, exact response and marked-question replay, live transcripts, compact Voice setup and playback controls, and persistent copyable errors. Keep the conversation busy through browser-tool continuations, withhold pending work on Stop, surface automatic-tool failures to Voice, and display stopped entries and surviving client-tool Voice origins supplied by canonical history. diff --git a/.changeset/resumable-petrinaut-workpiece.md b/.changeset/resumable-petrinaut-workpiece.md new file mode 100644 index 00000000000..90d39bf47f3 --- /dev/null +++ b/.changeset/resumable-petrinaut-workpiece.md @@ -0,0 +1,6 @@ +--- +"@hashintel/petrinaut": patch +"@hashintel/petrinaut-core": patch +--- + +Report an AI mutation that leaves the document unchanged as not applied, without claiming the requested state was already present, so hosts can distinguish an applied document change from an unchanged one, and reliably continue consecutive browser tool calls from live or rehydrated assistant messages. diff --git a/.changeset/voice-input-withdrawal-and-stop-correlation.md b/.changeset/voice-input-withdrawal-and-stop-correlation.md new file mode 100644 index 00000000000..7d371bd6dbe --- /dev/null +++ b/.changeset/voice-input-withdrawal-and-stop-correlation.md @@ -0,0 +1,5 @@ +--- +"@hashintel/petrinaut": patch +--- + +Let hosts withdraw a retained voice input through an `AbortSignal`, keep a late durable Stop result from cancelling a newer turn, replace all conversation-owned assistant state when the conversation identity changes, hydrate host-owned history only once it carries every locally streamed reply, keep the composer status busy across the automatic follow-up to a client-tool step, and let a Stop pressed during that step withhold the follow-up. diff --git a/apps/brunch-agent/README.md b/apps/brunch-agent/README.md index 7732125b788..f61a3324ea7 100644 --- a/apps/brunch-agent/README.md +++ b/apps/brunch-agent/README.md @@ -8,9 +8,7 @@ From the repository root, make `ANTHROPIC_API_KEY` available in the environment yarn dev:brunch ``` -The first step builds the Petrinaut libraries the panel imports (`dist/` and design-system -codegen). Then it starts the Brunch server at `http://127.0.0.1:4321` and the real Petrinaut -website at `http://127.0.0.1:4915`. The website proxies `/api/chat` to Brunch. The panel talks to one Flue chat agent composed from the context-independent core prompt in `@hashintel/brunch-agent/flue`, the SDCPN/Petrinaut instructions, modelling runbook skill, and `readPetrinautDoc` client tool in `@hashintel/brunch-agent-plugin-sdcpn`, and app-owned deployment/transport material. The skill is activated via `activate_skill`, with supporting resources disclosed via `read_skill_resource`; the app's only model-facing diagnostic tool is `ping`. There is no generalized elicitation loop, sweep tool, or `brunch_ask` on this path. Capture is a harness-side pipe: an explicit settled range of Flue history is applied into a JSON store beside the conversation database, not by the interviewer. +The first step builds the Petrinaut libraries the panel imports (`dist/` and design-system codegen). Then it starts the Brunch server at `http://127.0.0.1:4321` and the real Petrinaut website at `http://127.0.0.1:4915`. The website proxies `/agents/chat/*` to Brunch without changing the request origin or Flue protocol. The typed panel and Voice mode talk to one Flue chat agent composed from the context-independent core prompt in `@hashintel/brunch-agent/flue`, the SDCPN/Petrinaut instructions, modelling runbook skill, and `readPetrinautDoc` client tool in `@hashintel/brunch-agent-plugin-sdcpn`, and app-owned deployment material. The skill is activated via `activate_skill`, with supporting resources disclosed via `read_skill_resource`; the app's only model-facing diagnostic tool is `ping`. There is no generalized elicitation loop, sweep tool, or `brunch_ask` on this path. Capture is a harness-side pipe: an explicit settled range of Flue history is applied into a JSON store beside the conversation database, not by the interviewer. A headless Mission 3 drive (simulated expert, same `ChatAgent` door): @@ -18,38 +16,28 @@ A headless Mission 3 drive (simulated expert, same `ChatAgent` door): yarn workspace @apps/brunch-agent runbook:headless ``` -`ANTHROPIC_API_KEY` is required. `BRUNCH_CHAT_MODEL` selects the interviewer -(default `claude-sonnet-4-5` for this script only). Artifacts write under -`libs/@hashintel/brunch-agent/docs/evidence/evaluations/vestera-runbook-headless/` -unless `BRUNCH_RUNBOOK_OUTPUT_DIR` is set. +`ANTHROPIC_API_KEY` is required. `BRUNCH_CHAT_MODEL` selects the interviewer (default `claude-sonnet-4-5` for this script only). Artifacts write under `libs/@hashintel/brunch-agent/docs/evidence/evaluations/vestera-runbook-headless/` unless `BRUNCH_RUNBOOK_OUTPUT_DIR` is set. -Conversations persist in `apps/brunch-agent/.data-wipe-me/conversations.db`. `BRUNCH_DEV_DB_PATH` -overrides that local path. Capture envelopes for one Flue conversation sit beside that sqlite -file, named by the hashed instance id (`.json`). The hermetic `/api/chat` test uses -`BRUNCH_CHAT_DB_PATH` and writes the capture file in that same directory. Flue history is the -conversation log; the capture store is not a second transcript. The browser may cache messages -but reload hydrates from `GET /api/chat?id=`. +Conversations persist in `apps/brunch-agent/.data-wipe-me/conversations.db`. `BRUNCH_DEV_DB_PATH` overrides that local path. Capture envelopes for one Flue conversation sit beside that sqlite file, named by the hashed instance id (`.json`). The hermetic browser-transport test uses `BRUNCH_CHAT_DB_PATH` and writes the capture file in that same directory. Flue history is the conversation log; the capture store is not a second transcript. The panel rehydrates from the SDK's canonical conversation observation and does not resubmit or replay settled turns. -The mounted Flue URL `/agents/chat/:id` requires the same principal and conversation identity (`x-brunch-principal` and `x-brunch-conversation`) as `/api/chat`; the path id is the hash of those, not a bearer token. +The mounted Flue URL `/agents/chat/:instanceId` requires the principal and logical conversation identity in `x-brunch-principal` and `x-brunch-conversation`. The path id is the hash of those values, not a bearer token or trusted authentication. -Print a human-readable transcript of one conversation from that same Flue history (server already -running): +Print a human-readable transcript of one conversation from that same Flue history (server already running): ```sh yarn workspace @apps/brunch-agent transcript -- --principal --id ``` -## Voice dock +## Panel and Voice conversation route -A second input modality joins the same chat door. It is not a voice route and does not own -provider audio or session state. +Voice is a second input modality over the panel's conversation. It is not a Voice route and does not own provider audio or durable conversation state. -| | | -| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| URL | `POST /api/chat` (and `GET /api/chat?id=` to hydrate) | -| Identity | `x-brunch-principal` plus body `id` (the conversation id). The server hashes those into the Flue instance id. | -| Initial turn | JSON `{ id, trigger: "submit-message", messages }` whose last user text part is the utterance. | -| Client-tool follow-up | Same POST, with `messageId` of the assistant message and completed client-tool parts (`providerExecuted` not true). Correlated by `toolCallId`. | -| Response | AI SDK UI-message stream (SSE). | +| | | +| --------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| URL | `/agents/chat/:instanceId`, called through the public Flue browser client and the same-origin local proxy | +| Identity | `x-brunch-principal` plus `x-brunch-conversation`; the server verifies that their hash matches the mounted instance id | +| Initial turn | One `FlueClient.send()` carrying `{ kind: "user", body }` | +| Client-tool follow-up | One `FlueClient.send()` carrying the `client-tool-result` signal for completed client-tool parts, correlated by `toolCallId` | +| Response | `FlueClient.wait()` chunks projected into one finite AI SDK UI-message stream; observation/history provides canonical rehydration | -`OPTIONS /api/chat` is the CORS preflight for that same contract. +Typed and finalized spoken turns use this same route. The panel's explicit **Stop** requests a conversation-wide Flue abort before cancelling its local stream. Local Voice interruption stops playback only and leaves canonical history unchanged. diff --git a/apps/brunch-agent/package.json b/apps/brunch-agent/package.json index 60c6903cc7e..1e30bcc83a7 100644 --- a/apps/brunch-agent/package.json +++ b/apps/brunch-agent/package.json @@ -2,7 +2,7 @@ "name": "@apps/brunch-agent", "version": "0.0.0-private", "private": true, - "description": "Remote Brunch server, local development loop, and Petrinaut /api/chat door.", + "description": "Remote Brunch server and local Petrinaut development loop.", "license": "AGPL-3.0", "type": "module", "scripts": { diff --git a/apps/brunch-agent/petrinaut-local.vite.config.ts b/apps/brunch-agent/petrinaut-local.vite.config.ts index b265537076c..a4d4ff018cf 100644 --- a/apps/brunch-agent/petrinaut-local.vite.config.ts +++ b/apps/brunch-agent/petrinaut-local.vite.config.ts @@ -1,10 +1,10 @@ /** * Local FE-1436 panel launcher. * - * Loads the real hash Petrinaut website config, removes only its incumbent - * `/api/chat` dev handler, and sends that same-origin route to brunch's - * committed application server. The real panel, wrappers, and editor stay untouched; - * hash's tracked checkout stays clean. + * Loads the real hash Petrinaut website config and proxies Brunch's mounted + * Flue route to the committed application server. The real panel, API + * handlers, wrappers, and editor stay untouched; hash's tracked checkout + * stays clean. */ import { join, resolve } from "node:path"; @@ -13,7 +13,7 @@ import { defineConfig, loadConfigFromFile, mergeConfig, - type PluginOption, + type UserConfig, } from "vite"; import { @@ -21,21 +21,20 @@ import { petrinautLocalServer, } from "./src/http/local-origins.ts"; -const withoutIncumbentChatHandler = ( - plugins: readonly PluginOption[], -): PluginOption[] => - plugins.filter((plugin) => { - if ( - plugin === false || - plugin === null || - plugin === undefined || - Array.isArray(plugin) || - typeof plugin !== "object" || - !("name" in plugin) - ) { - return true; - } - return plugin.name !== "petrinaut-api-dev"; +interface PetrinautPanelConfigOptions { + readonly chatOrigin: string; + readonly loadedConfig: UserConfig; + readonly root: string; +} + +export const mergePetrinautPanelConfig = ({ + chatOrigin, + loadedConfig, + root, +}: PetrinautPanelConfigOptions): UserConfig => + mergeConfig(loadedConfig, { + root, + server: petrinautLocalServer(chatOrigin), }); export default defineConfig(async (environment) => { @@ -44,6 +43,7 @@ export default defineConfig(async (environment) => { throw new Error("PETRINAUT_WEBSITE_ROOT is required."); } const root = resolve(websiteRoot); + process.env.VITE_BRUNCH_CHAT_ENDPOINT ??= "/agents/chat"; // Babel resolves the React compiler plugin from the launched project's cwd, // not from the imported config file. Match a native hash launch before the // plugin begins transforming the real panel source. @@ -57,14 +57,9 @@ export default defineConfig(async (environment) => { throw new Error(`Could not load Petrinaut's Vite config from ${root}.`); const chatOrigin = process.env.BRUNCH_CHAT_ORIGIN ?? defaultChatOrigin; - return mergeConfig( - { - ...loaded.config, - plugins: withoutIncumbentChatHandler(loaded.config.plugins ?? []), - }, - { - root, - server: petrinautLocalServer(chatOrigin), - }, - ); + return mergePetrinautPanelConfig({ + chatOrigin, + loadedConfig: loaded.config, + root, + }); }); diff --git a/apps/brunch-agent/src/app.ts b/apps/brunch-agent/src/app.ts index 715b56c2130..bac01a99ca9 100644 --- a/apps/brunch-agent/src/app.ts +++ b/apps/brunch-agent/src/app.ts @@ -1,11 +1,4 @@ -/** - * The app's route map — one plain Flue chat agent plus Petrinaut's /api/chat door. - * - * Both doors require principal + conversation id. `/api/chat` takes the principal - * header and body `id`; `/agents/chat/:id` takes the same principal plus - * `x-brunch-conversation` and admits the request only when those re-derive the - * path id. The Flue instance id is derived, not a bearer token. - */ +/** The app's route map — one ownership-guarded Flue conversation door. */ import { readFile } from "node:fs/promises"; @@ -18,28 +11,16 @@ import { ChatAgent } from "./agents/chat-agent/agent.ts"; import { healthHandler } from "./health.ts"; import { assetHandler } from "./http/assets.ts"; import { agentOwnershipGuard } from "./http/ownership.ts"; -import { createPetrinautChatHandler } from "./http/petrinaut-chat.ts"; -import { - CHAT_AGENT_ROUTE, - HEALTH_ROUTE, - PETRINAUT_CHAT_ROUTE, -} from "./http/routes.ts"; +import { CHAT_AGENT_ROUTE, HEALTH_ROUTE } from "./http/routes.ts"; instrument(createOpenTelemetryInstrumentation({ content: false })); const app = new Hono(); -const appTransport: typeof fetch = async (input, init) => - app.fetch(input instanceof Request ? input : new Request(input, init)); -const petrinautChatHandler = createPetrinautChatHandler(appTransport); const chatAgentMount = `/agents/${CHAT_AGENT_ROUTE}`; app.use(`${chatAgentMount}/*`, agentOwnershipGuard(`${chatAgentMount}/`)); app.route(chatAgentMount, createAgentRouter(ChatAgent)); -app.on(["GET", "POST", "OPTIONS"], PETRINAUT_CHAT_ROUTE, (c) => - petrinautChatHandler(c.req.raw), -); - app.get(HEALTH_ROUTE, healthHandler); const uiRoot = new URL( diff --git a/apps/brunch-agent/src/conversation/client-tools.ts b/apps/brunch-agent/src/conversation/client-tools.ts index 2826f13f7f5..68b48d43b5d 100644 --- a/apps/brunch-agent/src/conversation/client-tools.ts +++ b/apps/brunch-agent/src/conversation/client-tools.ts @@ -1,14 +1,18 @@ /** Flue-side client-tool signal contract: awaiting sentinel, result signal, tool names. */ -import { READ_PETRINAUT_DOC_TOOL_NAME } from "@hashintel/brunch-agent-plugin-sdcpn/flue"; +import { + petrinautFixtureToolNames, + READ_PETRINAUT_DOC_TOOL_NAME, +} from "@hashintel/brunch-agent-plugin-sdcpn/flue"; +import { CLIENT_TOOL_RESULT_SIGNAL } from "@hashintel/brunch-agent-transport-aisdk"; import { AWAITING_CLIENT } from "@hashintel/brunch-agent/client-tools"; export { AWAITING_CLIENT }; - -export const CLIENT_TOOL_RESULT_SIGNAL = "client-tool-result"; +export { CLIENT_TOOL_RESULT_SIGNAL }; export const clientToolNames: ReadonlySet = new Set([ READ_PETRINAUT_DOC_TOOL_NAME, + ...petrinautFixtureToolNames, ]); const isRecord = (value: unknown): value is Record => diff --git a/apps/brunch-agent/src/conversation/identity-web.ts b/apps/brunch-agent/src/conversation/identity-web.ts deleted file mode 100644 index 68d7da8536d..00000000000 --- a/apps/brunch-agent/src/conversation/identity-web.ts +++ /dev/null @@ -1,14 +0,0 @@ -/** Browser-safe instance-id hash; must match `flueConversationId` byte-for-byte. */ - -import { hexFromDigest, identityPayload } from "./payload.ts"; - -export const flueConversationIdWeb = async ( - principalKey: string, - conversationId: string, -): Promise => { - const payload = identityPayload(principalKey, conversationId); - const bytes = new ArrayBuffer(payload.byteLength); - new Uint8Array(bytes).set(payload); - const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes); - return hexFromDigest(digest); -}; diff --git a/apps/brunch-agent/src/conversation/identity.ts b/apps/brunch-agent/src/conversation/identity.ts index ffaa4738819..da87b3a377c 100644 --- a/apps/brunch-agent/src/conversation/identity.ts +++ b/apps/brunch-agent/src/conversation/identity.ts @@ -3,47 +3,32 @@ import { createHash, timingSafeEqual } from "node:crypto"; import { - BRUNCH_CONVERSATION_HEADER, - BRUNCH_PRINCIPAL_HEADER, identityPayload, -} from "./payload.ts"; - -import type { ConversationIdentity } from "@hashintel/brunch-agent-transport-aisdk"; + type ConversationIdentity, +} from "@hashintel/brunch-agent-transport-aisdk"; export { + agentOwnershipHeaders, BRUNCH_CONVERSATION_HEADER, BRUNCH_PRINCIPAL_HEADER, - LOCAL_UI_PRINCIPAL, -} from "./payload.ts"; +} from "@hashintel/brunch-agent-transport-aisdk"; +export { LOCAL_UI_PRINCIPAL } from "./payload.ts"; export type { ConversationIdentity }; -export const flueConversationId = ( - principalKey: string, - conversationId: string, -): string => - createHash("sha256") - .update(identityPayload(principalKey, conversationId)) - .digest("hex"); +export const flueConversationId = (identity: ConversationIdentity): string => + createHash("sha256").update(identityPayload(identity)).digest("hex"); export const flueConversationIdFrom = ( identity: ConversationIdentity, -): string => flueConversationId(identity.principalKey, identity.conversationId); +): string => flueConversationId(identity); export const ownsFlueInstance = ( - principalKey: string, - conversationId: string, + identity: ConversationIdentity, instanceId: string, ): boolean => { - const expected = flueConversationId(principalKey, conversationId); + const expected = flueConversationId(identity); const expectedBytes = Buffer.from(expected); const presentedBytes = Buffer.from(instanceId); if (expectedBytes.length !== presentedBytes.length) return false; return timingSafeEqual(expectedBytes, presentedBytes); }; - -export const agentOwnershipHeaders = ( - identity: ConversationIdentity, -): Record => ({ - [BRUNCH_PRINCIPAL_HEADER]: identity.principalKey, - [BRUNCH_CONVERSATION_HEADER]: identity.conversationId, -}); diff --git a/apps/brunch-agent/src/conversation/payload.ts b/apps/brunch-agent/src/conversation/payload.ts index 2507070f3ed..20de535d2fe 100644 --- a/apps/brunch-agent/src/conversation/payload.ts +++ b/apps/brunch-agent/src/conversation/payload.ts @@ -1,29 +1,2 @@ -/** Identity headers and payload encoding shared by Node and the local Flue UI. */ - -export { BRUNCH_PRINCIPAL_HEADER } from "@hashintel/brunch-agent-transport-aisdk/headers"; - -export const BRUNCH_CONVERSATION_HEADER = "x-brunch-conversation"; - /** Principal for the stock Flue UI at `/`. Not a second ownership rule. */ export const LOCAL_UI_PRINCIPAL = "local"; - -export const identityPayload = ( - principalKey: string, - conversationId: string, -): Uint8Array => { - const encoder = new TextEncoder(); - const principalBytes = encoder.encode(principalKey); - const conversationBytes = encoder.encode(conversationId); - const payload = new Uint8Array( - principalBytes.length + 1 + conversationBytes.length, - ); - payload.set(principalBytes, 0); - payload[principalBytes.length] = 0; - payload.set(conversationBytes, principalBytes.length + 1); - return payload; -}; - -export const hexFromDigest = (digest: ArrayBuffer): string => - [...new Uint8Array(digest)] - .map((byte) => byte.toString(16).padStart(2, "0")) - .join(""); diff --git a/apps/brunch-agent/src/conversation/transcript.ts b/apps/brunch-agent/src/conversation/transcript.ts index cbaf34b0c33..23bfb5f8b18 100644 --- a/apps/brunch-agent/src/conversation/transcript.ts +++ b/apps/brunch-agent/src/conversation/transcript.ts @@ -1,4 +1,4 @@ -/** Human-readable and UI-message projections of Flue's public conversation snapshot. */ +/** Human-readable projection of Flue's public conversation snapshot. */ import { type FlueConversationMessage, @@ -6,38 +6,7 @@ import { type FlueConversationSnapshot, } from "@flue/sdk"; -import { - CLIENT_TOOL_RESULT_SIGNAL, - isAwaitingClient, - providerExecutedFor, -} from "./client-tools.ts"; - -type UiMessagePart = - | { readonly type: "text"; readonly text: string; readonly state: "done" } - | { - readonly type: "reasoning"; - readonly text: string; - readonly state: "done"; - } - | { - readonly type: `data-${string}`; - readonly data: unknown; - } - | { - readonly type: "file"; - readonly mediaType: string; - readonly url: string; - readonly filename?: string; - } - | { - readonly type: `tool-${string}`; - readonly toolCallId: string; - readonly state: "output-available" | "output-error" | "input-available"; - readonly input: unknown; - readonly output?: unknown; - readonly errorText?: string; - readonly providerExecuted?: boolean; - }; +import { CLIENT_TOOL_RESULT_SIGNAL, isAwaitingClient } from "./client-tools.ts"; const unhandledConversationPart = (part: never): never => { throw new Error(`Unhandled Flue conversation part: ${JSON.stringify(part)}`); @@ -48,12 +17,6 @@ const isFlueDataPart = ( ): part is Extract => part.type.startsWith("data-"); -export interface UiHistoryMessage { - readonly id: string; - readonly role: "user" | "assistant"; - readonly parts: readonly UiMessagePart[]; -} - const isRecord = (value: unknown): value is Record => typeof value === "object" && value !== null; @@ -108,95 +71,6 @@ const resolveToolOutput = ( return clientOutput; }; -const toolPartFrom = ( - part: Extract, - clientOutputs: ReadonlyMap, -): UiMessagePart => { - const output = resolveToolOutput(part, clientOutputs); - const providerExecuted = - part.state === "output-available" - ? providerExecutedFor(isAwaitingClient(part.output)) - : undefined; - if (part.state === "output-error") { - return { - type: `tool-${part.toolName}`, - toolCallId: part.toolCallId, - state: "output-error", - input: part.input, - errorText: part.errorText, - ...(providerExecuted === undefined ? {} : { providerExecuted }), - }; - } - if (output !== undefined) { - return { - type: `tool-${part.toolName}`, - toolCallId: part.toolCallId, - state: "output-available", - input: part.input, - output, - ...(providerExecuted === undefined ? {} : { providerExecuted }), - }; - } - return { - type: `tool-${part.toolName}`, - toolCallId: part.toolCallId, - state: "input-available", - input: part.input, - }; -}; - -const partsFrom = ( - message: FlueConversationMessage, - clientOutputs: ReadonlyMap, -): UiMessagePart[] => { - const parts: UiMessagePart[] = []; - for (const part of message.parts) { - if (part.type === "text") { - parts.push({ type: "text", text: part.text, state: "done" }); - continue; - } - if (part.type === "reasoning") { - parts.push({ type: "reasoning", text: part.text, state: "done" }); - continue; - } - if (part.type === "dynamic-tool") { - parts.push(toolPartFrom(part, clientOutputs)); - continue; - } - if (part.type === "file") { - parts.push({ - type: "file", - mediaType: part.mediaType, - url: part.url ?? "", - ...(part.filename === undefined ? {} : { filename: part.filename }), - }); - continue; - } - if (isFlueDataPart(part)) { - parts.push({ type: part.type, data: part.data }); - continue; - } - unhandledConversationPart(part); - } - return parts; -}; - -export const snapshotToUiMessages = ( - snapshot: FlueConversationSnapshot, -): UiHistoryMessage[] => { - const clientOutputs = clientToolResultsFrom(snapshot); - const messages: UiHistoryMessage[] = []; - for (const message of snapshot.messages) { - if (message.display !== "visible") continue; - if (message.purpose !== "user" && message.purpose !== "assistant") continue; - if (message.role !== "user" && message.role !== "assistant") continue; - const parts = partsFrom(message, clientOutputs); - if (parts.length === 0) continue; - messages.push({ id: message.id, role: message.role, parts }); - } - return messages; -}; - const textOf = (message: FlueConversationMessage): string => message.parts .filter( diff --git a/apps/brunch-agent/src/conversation/workpiece.ts b/apps/brunch-agent/src/conversation/workpiece.ts new file mode 100644 index 00000000000..d8ac8ae9b69 --- /dev/null +++ b/apps/brunch-agent/src/conversation/workpiece.ts @@ -0,0 +1,47 @@ +/** Recover the current Markdown workpiece from canonical Flue history. */ + +import { createHash } from "node:crypto"; + +import { selectRunbookWorkpiece } from "@hashintel/brunch-agent/workpiece"; + +import type { FlueConversationSnapshot } from "@flue/sdk"; + +const sha256 = (value: string): string => + createHash("sha256").update(value).digest("hex"); + +export interface RecoveredRunbookWorkpiece { + readonly authorship: "model-produced" | "test-authored"; + readonly content: string; + readonly fixtureId?: string; + readonly sha256: string; + readonly sourceKind: "assistant" | "prepared-signal"; + readonly sourceMessageId: string; + readonly sourceMessageSha256: string; + readonly sourceSubmissionId?: string; +} + +/** + * Add content and source hashes to the substrate-neutral current-workpiece + * selection used by both evaluations and the browser fixture. + */ +export const recoverRunbookWorkpiece = ( + snapshot: FlueConversationSnapshot, +): RecoveredRunbookWorkpiece | undefined => { + const selected = selectRunbookWorkpiece(snapshot); + if (selected === undefined) return undefined; + + return { + authorship: selected.authorship, + content: selected.content, + ...(selected.fixtureId === undefined + ? {} + : { fixtureId: selected.fixtureId }), + sha256: sha256(selected.content), + sourceKind: selected.sourceKind, + sourceMessageId: selected.sourceMessageId, + sourceMessageSha256: sha256(JSON.stringify(selected.sourceMessage)), + ...(selected.sourceSubmissionId === undefined + ? {} + : { sourceSubmissionId: selected.sourceSubmissionId }), + }; +}; diff --git a/apps/brunch-agent/src/diagnostics/transcript-cli.ts b/apps/brunch-agent/src/diagnostics/transcript-cli.ts index 9e2fabb3274..e38007c0999 100644 --- a/apps/brunch-agent/src/diagnostics/transcript-cli.ts +++ b/apps/brunch-agent/src/diagnostics/transcript-cli.ts @@ -5,9 +5,9 @@ * * yarn workspace @apps/brunch-agent transcript -- --principal --id * - * Identity matches POST /api/chat: principal + conversation id hash to the - * Flue instance. The mounted URL requires those same values as headers. This - * is a read of canonical Flue history, not a second log. + * Identity matches the mounted Flue route: principal + conversation id hash + * to the Flue instance, with those values also sent as ownership headers. + * This is a read of canonical Flue history, not a second log. */ import { createFlueClient } from "@flue/sdk"; diff --git a/apps/brunch-agent/src/evaluations/persona/proof-artifacts.ts b/apps/brunch-agent/src/evaluations/persona/proof-artifacts.ts index 0c3c71409e7..8d5d32c67a7 100644 --- a/apps/brunch-agent/src/evaluations/persona/proof-artifacts.ts +++ b/apps/brunch-agent/src/evaluations/persona/proof-artifacts.ts @@ -9,7 +9,7 @@ import { import { isAwaitingClient } from "../../conversation/client-tools.ts"; import { formatFlueTranscript } from "../../conversation/transcript.ts"; -import { recoverRunbookWorkpiece } from "../runbook/artifacts.ts"; +import { recoverRunbookWorkpiece } from "../../conversation/workpiece.ts"; interface ProofEventBase { readonly sequence: number; diff --git a/apps/brunch-agent/src/evaluations/runbook/artifacts.ts b/apps/brunch-agent/src/evaluations/runbook/artifacts.ts index 05a50b46847..fb1923706d2 100644 --- a/apps/brunch-agent/src/evaluations/runbook/artifacts.ts +++ b/apps/brunch-agent/src/evaluations/runbook/artifacts.ts @@ -2,56 +2,16 @@ import { basename } from "node:path"; -import { sha256 } from "./campaign-integrity.ts"; +import { runbookIrFence } from "@hashintel/brunch-agent/workpiece"; -import type { FlueConversationPart, FlueConversationSnapshot } from "@flue/sdk"; +import { recoverRunbookWorkpiece } from "../../conversation/workpiece.ts"; -export const RUNBOOK_IR_FENCE = "runbook-ir"; - -const runbookIrFencePattern = /```runbook-ir\s*\n([\s\S]*?)```/g; - -export const latestRunbookIrBlock = (text: string): string | undefined => { - const matches = [...text.matchAll(runbookIrFencePattern)]; - const last = matches.at(-1)?.[1]; - return last === undefined ? undefined : last.trim(); -}; +import type { FlueConversationSnapshot } from "@flue/sdk"; export const recoverRunbookIr = ( snapshot: FlueConversationSnapshot, ): string | undefined => recoverRunbookWorkpiece(snapshot)?.content; -export interface RecoveredRunbookWorkpiece { - readonly content: string; - readonly sha256: string; - readonly sourceMessageId: string; - readonly sourceMessageSha256: string; -} - -export const recoverRunbookWorkpiece = ( - snapshot: FlueConversationSnapshot, -): RecoveredRunbookWorkpiece | undefined => { - let recovered: RecoveredRunbookWorkpiece | undefined; - for (const message of snapshot.messages) { - if (message.purpose !== "assistant") continue; - const text = message.parts - .filter( - (part): part is Extract => - part.type === "text", - ) - .map((part) => part.text) - .join("\n"); - const content = latestRunbookIrBlock(text); - if (content === undefined) continue; - recovered = { - content, - sha256: sha256(content), - sourceMessageId: message.id, - sourceMessageSha256: sha256(JSON.stringify(message)), - }; - } - return recovered; -}; - export const interviewerToolNamesFrom = ( snapshot: FlueConversationSnapshot, ): readonly string[] => [ @@ -153,7 +113,7 @@ export const ordinaryElicitationViolationsFrom = ( } if ( firstWorkpiecePosition === undefined && - part.text.includes(`\`\`\`${RUNBOOK_IR_FENCE}`) + part.text.includes(`\`\`\`${runbookIrFence}`) ) { firstWorkpiecePosition = position; } diff --git a/apps/brunch-agent/src/evaluations/runbook/headless-petrinaut-client.ts b/apps/brunch-agent/src/evaluations/runbook/headless-petrinaut-client.ts index 54cce1b64ee..b654e17eebf 100644 --- a/apps/brunch-agent/src/evaluations/runbook/headless-petrinaut-client.ts +++ b/apps/brunch-agent/src/evaluations/runbook/headless-petrinaut-client.ts @@ -12,7 +12,7 @@ import { getLatestNetDefinitionToolName, } from "@hashintel/petrinaut-core/ai"; -import type { Petrinaut } from "@hashintel/petrinaut-core"; +import type { Petrinaut, SDCPN } from "@hashintel/petrinaut-core"; export interface HeadlessPetrinautToolCall { readonly toolCallId: string; @@ -45,15 +45,18 @@ const constructionToolNames = new Set( const errorMessageFrom = (error: unknown): string => error instanceof Error ? error.message : String(error); -export const createHeadlessPetrinautClient = (title: string) => { +export const createHeadlessPetrinautClient = ( + title: string, + initial: SDCPN = { + places: [], + transitions: [], + types: [], + parameters: [], + differentialEquations: [], + }, +) => { const handle = createJsonDocHandle({ - initial: { - places: [], - transitions: [], - types: [], - parameters: [], - differentialEquations: [], - }, + initial, }); const instance = createPetrinaut({ document: handle }); const writableCallbacks = createPetrinautAiWritableCallbacks( diff --git a/apps/brunch-agent/src/http/local-origins.ts b/apps/brunch-agent/src/http/local-origins.ts index 797fc52b346..ea299ed66c7 100644 --- a/apps/brunch-agent/src/http/local-origins.ts +++ b/apps/brunch-agent/src/http/local-origins.ts @@ -14,17 +14,12 @@ export const localPanelListen = { export const defaultChatOrigin = `http://${localChatListen.host}:${localChatListen.port}`; -export const defaultPanelOrigins = [ - `http://${localPanelListen.host}:${localPanelListen.port}`, - `http://localhost:${localPanelListen.port}`, -] as const; - export const petrinautLocalServer = (chatOrigin: string) => ({ ...localPanelListen, proxy: { - "/api/chat": { + "/agents/chat": { target: chatOrigin, - changeOrigin: true, + changeOrigin: false, }, }, }); diff --git a/apps/brunch-agent/src/http/ownership.ts b/apps/brunch-agent/src/http/ownership.ts index 277d83f2227..dbcb1463fdf 100644 --- a/apps/brunch-agent/src/http/ownership.ts +++ b/apps/brunch-agent/src/http/ownership.ts @@ -1,9 +1,11 @@ -/** Hono middleware: the mounted Flue route enforces the same ownership rule as `/api/chat`. */ +/** Hono middleware for the mounted Flue conversation route. */ -import { BRUNCH_PRINCIPAL_HEADER } from "@hashintel/brunch-agent-transport-aisdk/headers"; +import { + BRUNCH_CONVERSATION_HEADER, + BRUNCH_PRINCIPAL_HEADER, +} from "@hashintel/brunch-agent-transport-aisdk/headers"; import { ownsFlueInstance } from "../conversation/identity.ts"; -import { BRUNCH_CONVERSATION_HEADER } from "../conversation/payload.ts"; import type { MiddlewareHandler } from "hono"; @@ -27,7 +29,7 @@ export const agentOwnershipGuard = (mountPrefix: string): MiddlewareHandler => { .find((segment) => segment.length > 0); if ( instanceId === undefined || - !ownsFlueInstance(principalKey, conversationId, instanceId) + !ownsFlueInstance({ principalKey, conversationId }, instanceId) ) { return context.json({ error: "forbidden" }, 403); } diff --git a/apps/brunch-agent/src/http/petrinaut-chat.ts b/apps/brunch-agent/src/http/petrinaut-chat.ts deleted file mode 100644 index e76ba0fbbdd..00000000000 --- a/apps/brunch-agent/src/http/petrinaut-chat.ts +++ /dev/null @@ -1,123 +0,0 @@ -/** Application composition for Petrinaut's stock AI SDK chat transport. */ - -import { init } from "@flue/runtime"; -import { createFlueClient, type FlueConversationSnapshot } from "@flue/sdk"; - -import { - createAiSdkChatHandler, - type ChatResumeInput, - type ChatTurnInput, - type ConversationIdentity, - type TransportInspectionEvent, -} from "@hashintel/brunch-agent-transport-aisdk"; - -import { ChatAgent } from "../agents/chat-agent/agent.ts"; -import { - clientToolNames, - CLIENT_TOOL_RESULT_SIGNAL, -} from "../conversation/client-tools.ts"; -import { - agentOwnershipHeaders, - flueConversationIdFrom, -} from "../conversation/identity.ts"; -import { snapshotToUiMessages } from "../conversation/transcript.ts"; -import { createFlueUiStream } from "../conversation/ui-stream.ts"; -import { defaultPanelOrigins } from "./local-origins.ts"; -import { CHAT_AGENT_ROUTE } from "./routes.ts"; - -import type { UIMessageChunk } from "ai"; - -const inspect = - process.env.BRUNCH_TRANSPORT_AISDK_INSPECT === "1" - ? (event: TransportInspectionEvent): void => { - process.stdout.write(`TRANSPORT_AISDK ${JSON.stringify(event)}\n`); - } - : undefined; - -const conversationUrl = (instanceId: string): string => - `http://brunch.local/agents/${CHAT_AGENT_ROUTE}/${instanceId}`; - -const historyClient = ( - identity: ConversationIdentity, - appTransport: typeof fetch, -) => - createFlueClient({ - url: conversationUrl(flueConversationIdFrom(identity)), - fetch: appTransport, - headers: agentOwnershipHeaders(identity), - }); - -const streamTurn = async ( - instanceId: string, - dispatch: Parameters["dispatch"]>[0], - write: (chunk: UIMessageChunk) => void, -): Promise => { - const agent = init(ChatAgent, { id: instanceId }); - const receipt = await agent.dispatch(dispatch); - const projector = createFlueUiStream({ - submissionId: receipt.submissionId, - clientToolNames, - write, - }); - await agent.read(receipt, { onEvent: (chunk) => projector.accept(chunk) }); -}; - -const runUserTurn = ( - input: ChatTurnInput, - write: (chunk: UIMessageChunk) => void, -): Promise => - streamTurn( - flueConversationIdFrom(input), - { message: input.userMessage.text, idempotencyKey: input.idempotencyKey }, - write, - ); - -const runClientToolResume = ( - input: ChatResumeInput, - write: (chunk: UIMessageChunk) => void, -): Promise => - streamTurn( - flueConversationIdFrom(input), - { - message: { - kind: "signal", - type: CLIENT_TOOL_RESULT_SIGNAL, - tagName: CLIENT_TOOL_RESULT_SIGNAL, - body: JSON.stringify(input.toolResults), - attributes: { - toolCallIds: input.toolResults - .map((result) => result.toolCallId) - .join(","), - }, - }, - idempotencyKey: input.idempotencyKey, - }, - write, - ); - -export const createPetrinautChatHandler = (appTransport: typeof fetch) => { - const loadHistory = async ( - identity: ConversationIdentity, - ): Promise<{ readonly messages: readonly unknown[] }> => { - let snapshot: FlueConversationSnapshot; - try { - snapshot = await historyClient(identity, appTransport).history(); - } catch { - return { messages: [] }; - } - return { messages: snapshotToUiMessages(snapshot) }; - }; - - return createAiSdkChatHandler({ - allowedOrigins: ( - process.env.BRUNCH_PETRINAUT_ORIGINS ?? defaultPanelOrigins.join(",") - ) - .split(",") - .map((origin) => origin.trim()) - .filter((origin) => origin.length > 0), - inspect, - runTurn: runUserTurn, - resumeTurn: runClientToolResume, - loadHistory, - }); -}; diff --git a/apps/brunch-agent/src/http/routes.ts b/apps/brunch-agent/src/http/routes.ts index 008c73437ee..63637318d8f 100644 --- a/apps/brunch-agent/src/http/routes.ts +++ b/apps/brunch-agent/src/http/routes.ts @@ -4,6 +4,3 @@ export const CHAT_AGENT_ROUTE = "chat"; /** Cheap process-liveness probe; dependency readiness is established before listen. */ export const HEALTH_ROUTE = "/health"; - -/** Stock `DefaultChatTransport` endpoint used by Petrinaut's local panel. */ -export const PETRINAUT_CHAT_ROUTE = "/api/chat"; diff --git a/apps/brunch-agent/src/ui/chat.tsx b/apps/brunch-agent/src/ui/chat.tsx index e3581f59903..faf71094c85 100644 --- a/apps/brunch-agent/src/ui/chat.tsx +++ b/apps/brunch-agent/src/ui/chat.tsx @@ -6,12 +6,12 @@ import { } from "@flue/sdk"; import { useEffect, useMemo, useState, type FormEvent } from "react"; -import { flueConversationIdWeb } from "../conversation/identity-web.ts"; import { - BRUNCH_CONVERSATION_HEADER, - BRUNCH_PRINCIPAL_HEADER, - LOCAL_UI_PRINCIPAL, -} from "../conversation/payload.ts"; + agentOwnershipHeaders, + flueConversationIdWeb, +} from "@hashintel/brunch-agent-transport-aisdk"; + +import { LOCAL_UI_PRINCIPAL } from "../conversation/payload.ts"; import { CHAT_AGENT_ROUTE } from "../http/routes.ts"; type ChatConfiguration = @@ -165,18 +165,12 @@ export function Chat() { if (configuration.mode === "observer-error") return; let cancelled = false; - void flueConversationIdWeb( - configuration.principalKey, - configuration.conversationId, - ).then((instanceId) => { + void flueConversationIdWeb(configuration).then((instanceId) => { if (cancelled) return; setClient( createFlueClient({ url: `/agents/${CHAT_AGENT_ROUTE}/${instanceId}`, - headers: { - [BRUNCH_PRINCIPAL_HEADER]: configuration.principalKey, - [BRUNCH_CONVERSATION_HEADER]: configuration.conversationId, - }, + headers: agentOwnershipHeaders(configuration), }), ); }); diff --git a/apps/brunch-agent/test/agent-ownership.test.ts b/apps/brunch-agent/test/agent-ownership.test.ts index 9a2f19921ba..8c9143ce65e 100644 --- a/apps/brunch-agent/test/agent-ownership.test.ts +++ b/apps/brunch-agent/test/agent-ownership.test.ts @@ -9,9 +9,9 @@ import { expect, test } from "vitest"; import { agentOwnershipHeaders, + BRUNCH_CONVERSATION_HEADER, flueConversationIdFrom, } from "../src/conversation/identity.ts"; -import { BRUNCH_CONVERSATION_HEADER } from "../src/conversation/payload.ts"; import { agentOwnershipGuard } from "../src/http/ownership.ts"; import { CHAT_AGENT_ROUTE } from "../src/http/routes.ts"; diff --git a/apps/brunch-agent/test/architecture/boundaries.integration.ts b/apps/brunch-agent/test/architecture/boundaries.integration.ts index 85142865fb8..b3ad2048908 100644 --- a/apps/brunch-agent/test/architecture/boundaries.integration.ts +++ b/apps/brunch-agent/test/architecture/boundaries.integration.ts @@ -160,17 +160,20 @@ describe("dependency direction", () => { } }); - test("transports consume their wire encoder only — never core, a binding, or Flue", () => { + test("transports consume their wire encoder and the public Flue client only — never core, a binding, or the runtime", () => { const transports = byRole("transport"); expect(transports.length).toBeGreaterThan(0); for (const transport of transports) { - expect(runtimeDependencies(transport).sort()).toEqual(["ai", "valibot"]); + expect(runtimeDependencies(transport).sort()).toEqual([ + "@flue/sdk", + "ai", + ]); for (const file of sourceFiles(transport).filter((file) => file.path.startsWith(join(transport.path, "src")), )) { for (const specifier of importedPackages(file)) { if (specifier.startsWith("node:")) continue; - expect(["ai", "valibot"]).toContain(packageOf(specifier)); + expect(["@flue/sdk", "ai"]).toContain(packageOf(specifier)); } } } @@ -376,13 +379,15 @@ describe("recorded Flue constraints hold by construction (spec §10)", () => { }); describe("core auxiliary subpaths stay in their assigned lanes", () => { - test("core exposes Flue composition, browser contracts, and storage support as explicit subpaths", () => { + test("core exposes Flue composition, browser, storage, and workpiece contracts as explicit subpaths", () => { const core = PACKAGES.find((pkg) => pkg.name === CORE)!; expect(Object.keys(core.manifest.exports ?? {})).toEqual([ ".", "./client-tools", "./flue", + "./question-marker", "./storage", + "./workpiece", ]); }); @@ -420,14 +425,16 @@ describe("the HASH smoke is runnable without a model key or a network (spec §12 * path enters here by review only. */ const SUBSTRATE_INTEGRATION_ENTRY_POINTS: Readonly> = { + "libs/@hashintel/brunch-agent/packages/core/test/question-marker.test.ts": + "Types the Flue logger and calls the core marker tool with a mocked data-part writer and logger; no runtime boot, provider, key or socket.", "apps/brunch-agent/test/brunch-turn.test.ts": "Types Flue's client, admission, and conversation snapshot and constructs FlueExecutionError so the persona bridge can be unit-tested against a stubbed client — no provider key, no socket, no model call, no runtime boot.", "apps/brunch-agent/test/flue-transcript.test.ts": "Types Flue's public conversation snapshot so the transcript projector can be unit-tested; the import is type-only — no provider key, no socket, no model call, no runtime boot.", - "apps/brunch-agent/test/flue-ui-stream.test.ts": - "Types Flue conversation-stream chunks so the AI SDK projector can be unit-tested; the import is type-only — no provider key, no socket, no model call, no runtime boot.", "apps/brunch-agent/test/petrinaut-chat.integration.ts": - "Boots the plain Flue chat agent on Flue's node runtime with pi-ai's faux provider, drives the committed /api/chat door over app.fetch, and proves streamed reasoning/text, one server tool, one stub skill activation, one read-only client-tool resume, GET history ownership, SQLite restart, and harness-side idempotent apply-sweep into a capture store keyed by Flue conversation identity — no provider key, no socket, no extraction model call. Run as a child process by petrinaut-chat.test.ts.", + "Boots the plain Flue chat agent on Flue's node runtime with pi-ai's faux provider, drives the browser ChatTransport against the mounted Flue route over app.fetch, and proves streamed reasoning/text, server tools, client-tool resume, SDK history ownership, SQLite restart, and harness-side idempotent apply-sweep — no provider key, no socket, no extraction model call. Run as a child process by petrinaut-chat.test.ts.", + "apps/brunch-agent/test/prepared-workpiece.integration.ts": + "Boots the built Flue ChatAgent with pi-ai's faux provider, creates a prepared fixture through one tagged public signal with fixture-scoped initial data, retries its deterministic idempotency key, and proves prepared/model workpiece selection from canonical history — no provider key, socket, or network model call.", "apps/brunch-agent/test/proof-artifacts.test.ts": "Types Flue's public conversation snapshot so canonical trace derivation, workpiece binding, and atomic evidence retention can be unit-tested against an in-memory fixture — no provider key, no socket, no model call, no runtime boot.", "apps/brunch-agent/test/runbook-artifacts.test.ts": @@ -436,6 +443,14 @@ describe("the HASH smoke is runnable without a model key or a network (spec §12 "Defines the scripted pi-ai faux provider loaded only by the hermetic prospective-runner test — no provider key, no socket, and no network model call.", "apps/brunch-agent/test/runbook-headless.integration.ts": "Boots the built Flue ChatAgent with pi-ai's faux provider and a headless Petrinaut client to prove validated construct-only tool flow without a provider key, socket, or network model call.", + "apps/brunch-agent/test/workpiece.test.ts": + "Types Flue's public conversation snapshot so the substrate-neutral workpiece selector and app-owned SHA-256 projection can be unit-tested against in-memory messages — no provider key, no socket, no model call, no runtime boot.", + "libs/@hashintel/brunch-agent/packages/transport-aisdk/test/chat-transport.test.ts": + "Types a stubbed public Flue client and stream chunks to prove finite AI SDK projection and client-tool signal admission — no runtime boot, provider key, socket, or model call.", + "libs/@hashintel/brunch-agent/packages/transport-aisdk/test/transcript.test.ts": + "Types Flue's public conversation snapshot so history can be projected into AI SDK messages without a runtime boot, provider key, socket, or model call.", + "libs/@hashintel/brunch-agent/packages/transport-aisdk/test/ui-stream.test.ts": + "Types Flue conversation-stream chunks so the finite AI SDK projector can be unit-tested without a runtime boot, provider key, socket, or model call.", }; test("no test file carries a live model credential", () => { diff --git a/apps/brunch-agent/test/architecture/boundaries.test.ts b/apps/brunch-agent/test/architecture/boundaries.test.ts new file mode 100644 index 00000000000..712624bb2b6 --- /dev/null +++ b/apps/brunch-agent/test/architecture/boundaries.test.ts @@ -0,0 +1,5 @@ +/** + * Keep the filesystem-wide architecture suite runnable by Vitest while its + * implementation remains a non-test entry point for boundary self-inspection. + */ +import "./boundaries.integration.ts"; diff --git a/apps/brunch-agent/test/build-artifact.test.ts b/apps/brunch-agent/test/build-artifact.test.ts index a11f909b31d..ebb4a5558e9 100644 --- a/apps/brunch-agent/test/build-artifact.test.ts +++ b/apps/brunch-agent/test/build-artifact.test.ts @@ -19,6 +19,8 @@ import { fileURLToPath } from "node:url"; import { beforeAll, describe, expect, test } from "vitest"; +import { loadBuiltBrunchApplication } from "../src/evaluations/runbook/load-built-application"; + const DEV_APP = fileURLToPath(new URL("..", import.meta.url)).replace( /[/\\]$/u, "", @@ -108,6 +110,19 @@ describe("the emitted server bundle", () => { expect(bundle).toContain(".data-wipe-me"); // db.ts's default store path }); + test("serves only the guarded Flue conversation door", async () => { + const application = await loadBuiltBrunchApplication(); + const [legacyResponse, flueResponse] = await Promise.all([ + application.fetch(new Request("http://brunch.test/api/chat")), + application.fetch( + new Request("http://brunch.test/agents/chat/missing-identity"), + ), + ]); + + expect(legacyResponse.status).toBe(404); + expect(flueResponse.status).toBe(401); + }); + test("packages the authored skill without the retired filesystem loader", () => { expect(bundle).toContain("defineSkill"); expect(bundle).toContain("sdcpn-modelling"); diff --git a/apps/brunch-agent/test/conversation-identity.test.ts b/apps/brunch-agent/test/conversation-identity.test.ts index acf6d6c361b..aa78794f5a2 100644 --- a/apps/brunch-agent/test/conversation-identity.test.ts +++ b/apps/brunch-agent/test/conversation-identity.test.ts @@ -1,6 +1,7 @@ import { expect, test } from "vitest"; -import { flueConversationIdWeb } from "../src/conversation/identity-web.ts"; +import { flueConversationIdWeb } from "@hashintel/brunch-agent-transport-aisdk"; + import { flueConversationId, flueConversationIdFrom, @@ -8,14 +9,22 @@ import { } from "../src/conversation/identity.ts"; test("the same principal and conversation id always hash to the same Flue instance", () => { - expect(flueConversationId("principal-a", "conversation-1")).toBe( - flueConversationId("principal-a", "conversation-1"), - ); + const identity = { + principalKey: "principal-a", + conversationId: "conversation-1", + }; + expect(flueConversationId(identity)).toBe(flueConversationId(identity)); }); test("a different principal cannot address the same Flue instance", () => { - const owned = flueConversationId("principal-a", "conversation-1"); - const foreign = flueConversationId("principal-b", "conversation-1"); + const owned = flueConversationId({ + principalKey: "principal-a", + conversationId: "conversation-1", + }); + const foreign = flueConversationId({ + principalKey: "principal-b", + conversationId: "conversation-1", + }); expect(owned).not.toBe(foreign); expect(owned).toMatch(/^[0-9a-f]{64}$/); expect(foreign).toMatch(/^[0-9a-f]{64}$/); @@ -27,30 +36,25 @@ test("ownsFlueInstance admits only the principal and conversation that hashed th conversationId: "conversation-1", }; const instanceId = flueConversationIdFrom(identity); + expect(ownsFlueInstance(identity, instanceId)).toBe(true); expect( - ownsFlueInstance( - identity.principalKey, - identity.conversationId, - instanceId, - ), - ).toBe(true); - expect( - ownsFlueInstance("principal-b", identity.conversationId, instanceId), - ).toBe(false); - expect( - ownsFlueInstance(identity.principalKey, "conversation-2", instanceId), + ownsFlueInstance({ ...identity, principalKey: "principal-b" }, instanceId), ).toBe(false); expect( ownsFlueInstance( - identity.principalKey, - identity.conversationId, - "not-a-hash", + { ...identity, conversationId: "conversation-2" }, + instanceId, ), ).toBe(false); + expect(ownsFlueInstance(identity, "not-a-hash")).toBe(false); }); test("the browser hash matches the Node hash", async () => { - expect(await flueConversationIdWeb("principal-a", "conversation-1")).toBe( - flueConversationId("principal-a", "conversation-1"), + const identity = { + principalKey: "principal-a", + conversationId: "conversation-1", + }; + expect(await flueConversationIdWeb(identity)).toBe( + flueConversationId(identity), ); }); diff --git a/apps/brunch-agent/test/flue-transcript.test.ts b/apps/brunch-agent/test/flue-transcript.test.ts index 0b6827cfbe1..051e9792b3c 100644 --- a/apps/brunch-agent/test/flue-transcript.test.ts +++ b/apps/brunch-agent/test/flue-transcript.test.ts @@ -1,58 +1,9 @@ import { expect, test } from "vitest"; -import { - formatFlueTranscript, - snapshotToUiMessages, -} from "../src/conversation/transcript.ts"; +import { formatFlueTranscript } from "../src/conversation/transcript"; import type { FlueConversationSnapshot } from "@flue/sdk"; -const snapshotWithPendingClientTool: FlueConversationSnapshot = { - v: 1, - conversationId: "conversation-1", - offset: "0", - messages: [ - { - id: "assistant-1", - role: "assistant", - purpose: "assistant", - display: "visible", - parts: [ - { - type: "dynamic-tool", - toolCallId: "tool-doc-1", - toolName: "readPetrinautDoc", - state: "output-available", - input: { doc: "ai-assistant" }, - output: { awaiting: "client" }, - }, - ], - }, - ], - settlements: [], -}; - -const snapshotWithCompletedClientTool: FlueConversationSnapshot = { - ...snapshotWithPendingClientTool, - messages: [ - ...snapshotWithPendingClientTool.messages, - { - id: "signal-1", - role: "system", - purpose: "dispatch", - display: "hidden", - signal: { tagName: "client-tool-result" }, - parts: [ - { - type: "text", - text: '[{"toolCallId":"tool-doc-1","toolName":"readPetrinautDoc","output":null}]', - state: "done", - }, - ], - }, - ], -}; - const snapshotWithDataPart: FlueConversationSnapshot = { v: 1, conversationId: "conversation-1", @@ -72,49 +23,6 @@ const snapshotWithDataPart: FlueConversationSnapshot = { settlements: [], }; -test("history reconstruction leaves an unfinished client tool available to run", () => { - expect(snapshotToUiMessages(snapshotWithPendingClientTool)).toEqual([ - { - id: "assistant-1", - role: "assistant", - parts: [ - { - type: "tool-readPetrinautDoc", - toolCallId: "tool-doc-1", - state: "input-available", - input: { doc: "ai-assistant" }, - }, - ], - }, - ]); -}); - -test("history reconstruction uses the browser result even when it is null", () => { - const [message] = snapshotToUiMessages(snapshotWithCompletedClientTool); - expect(message?.parts).toEqual([ - { - type: "tool-readPetrinautDoc", - toolCallId: "tool-doc-1", - state: "output-available", - input: { doc: "ai-assistant" }, - output: null, - }, - ]); -}); - -test("history reconstruction keeps Flue data-* parts on the AI SDK message", () => { - expect(snapshotToUiMessages(snapshotWithDataPart)).toEqual([ - { - id: "assistant-1", - role: "assistant", - parts: [ - { type: "text", text: "Here is the order.", state: "done" }, - { type: "data-orderCard", data: { orderId: "42", status: "loaded" } }, - ], - }, - ]); -}); - test("the human transcript names Flue data parts instead of omitting them", () => { expect(formatFlueTranscript(snapshotWithDataPart)).toContain( '- data orderCard: {"orderId":"42","status":"loaded"}', diff --git a/apps/brunch-agent/test/flue-ui-stream.test.ts b/apps/brunch-agent/test/flue-ui-stream.test.ts deleted file mode 100644 index c151078e40a..00000000000 --- a/apps/brunch-agent/test/flue-ui-stream.test.ts +++ /dev/null @@ -1,141 +0,0 @@ -import { expect, test } from "vitest"; - -import { createFlueUiStream } from "../src/conversation/ui-stream.ts"; - -import type { ConversationStreamChunk } from "@flue/sdk"; -import type { UIMessageChunk } from "ai"; - -const position = (index: number) => ({ batch: 1, index }); - -const project = ( - chunks: readonly ConversationStreamChunk[], -): UIMessageChunk[] => { - const written: UIMessageChunk[] = []; - const projector = createFlueUiStream({ - submissionId: "submission-1", - clientToolNames: new Set(["readPetrinautDoc"]), - write: (chunk) => written.push(chunk), - }); - for (const chunk of chunks) projector.accept(chunk); - return written; -}; - -test("projects a Flue data-part onto the matching AI SDK data-* chunk", () => { - const written = project([ - { - type: "message-started", - conversationId: "conversation-1", - messageId: "message-1", - submissionId: "submission-1", - turnId: "turn-1", - position: position(0), - }, - { - type: "data-part", - conversationId: "conversation-1", - messageId: "message-1", - name: "orderCard", - data: { orderId: "42", status: "loaded" }, - position: position(1), - }, - { - type: "submission-settled", - conversationId: "conversation-1", - submissionId: "submission-1", - outcome: "completed", - position: position(2), - }, - ]); - - expect(written).toContainEqual({ - type: "data-orderCard", - data: { orderId: "42", status: "loaded" }, - }); -}); - -test("projects Flue message-metadata onto the AI SDK message-metadata chunk", () => { - const written = project([ - { - type: "message-started", - conversationId: "conversation-1", - messageId: "message-1", - submissionId: "submission-1", - turnId: "turn-1", - position: position(0), - }, - { - type: "message-metadata", - conversationId: "conversation-1", - messageId: "message-1", - metadata: { elapsedMs: 17 }, - position: position(1), - }, - { - type: "submission-settled", - conversationId: "conversation-1", - submissionId: "submission-1", - outcome: "completed", - position: position(2), - }, - ]); - - expect(written).toContainEqual({ - type: "message-metadata", - messageMetadata: { elapsedMs: 17 }, - }); -}); - -test("does not project Flue observe/reconnect chunks onto the AI SDK stream", () => { - const written = project([ - { - type: "message-started", - conversationId: "conversation-1", - messageId: "message-1", - submissionId: "submission-1", - turnId: "turn-1", - position: position(0), - }, - { - type: "stream-checkpoint", - incarnation: "incarnation-1", - }, - { - type: "conversation-reset", - conversationId: "conversation-1", - snapshot: { - v: 1, - conversationId: "conversation-1", - offset: "0", - messages: [], - settlements: [], - }, - position: position(1), - }, - { - type: "message-appended", - conversationId: "conversation-1", - message: { - id: "user-1", - role: "user", - purpose: "user", - display: "visible", - parts: [{ type: "text", text: "Hello.", state: "done" }], - }, - position: position(2), - }, - { - type: "submission-settled", - conversationId: "conversation-1", - submissionId: "submission-1", - outcome: "completed", - position: position(3), - }, - ]); - - expect(written.map((chunk) => chunk.type)).toEqual([ - "start", - "start-step", - "finish-step", - "finish", - ]); -}); diff --git a/apps/brunch-agent/test/local-dev-origins.test.ts b/apps/brunch-agent/test/local-dev-origins.test.ts index f85c76e97bb..8a20c937cae 100644 --- a/apps/brunch-agent/test/local-dev-origins.test.ts +++ b/apps/brunch-agent/test/local-dev-origins.test.ts @@ -2,9 +2,9 @@ import { readFileSync } from "node:fs"; import { expect, test } from "vitest"; +import { mergePetrinautPanelConfig } from "../petrinaut-local.vite.config.ts"; import { defaultChatOrigin, - defaultPanelOrigins, localChatListen, localPanelListen, petrinautLocalServer, @@ -22,7 +22,7 @@ test("one documented root command starts the Brunch server and Petrinaut panel", }; expect(rootPackage.scripts["dev:brunch"]).toBe( - "CARGO_TERM_PROGRESS_WHEN=never turbo run build --filter '@apps/petrinaut-website^...' && npm-run-all --parallel dev:brunch:server dev:brunch:panel", + "CARGO_TERM_PROGRESS_WHEN=never turbo run build --filter '@apps/brunch-agent^...' --filter '@apps/petrinaut-website^...' && npm-run-all --parallel dev:brunch:server dev:brunch:panel", ); expect(rootPackage.scripts["dev:brunch:server"]).toBe( "yarn workspace @apps/brunch-agent dev", @@ -43,11 +43,7 @@ test("dev listens on the chat origin the panel proxy already assumes", () => { expect(readAppFile("vite.config.ts")).toContain("localChatListen"); }); -test("petrinaut:dev listens on the panel origin chat CORS already assumes", () => { - expect(defaultPanelOrigins).toEqual([ - "http://127.0.0.1:4915", - "http://localhost:4915", - ]); +test("petrinaut:dev proxies the mounted Flue conversation route", () => { expect(localPanelListen).toEqual({ host: "127.0.0.1", port: 4915, @@ -56,16 +52,32 @@ test("petrinaut:dev listens on the panel origin chat CORS already assumes", () = expect(petrinautLocalServer(defaultChatOrigin)).toEqual({ ...localPanelListen, proxy: { - "/api/chat": { + "/agents/chat": { target: defaultChatOrigin, - changeOrigin: true, + changeOrigin: false, }, }, }); expect(readAppFile("petrinaut-local.vite.config.ts")).toContain( "petrinautLocalServer", ); - expect(readAppFile("src/http/petrinaut-chat.ts")).toContain( - "defaultPanelOrigins", + expect(readAppFile("petrinaut-local.vite.config.ts")).toContain( + 'VITE_BRUNCH_CHAT_ENDPOINT ??= "/agents/chat"', + ); +}); + +test("petrinaut:dev retains the website API handlers needed by Voice", () => { + const config = mergePetrinautPanelConfig({ + chatOrigin: defaultChatOrigin, + loadedConfig: { + plugins: [{ name: "petrinaut-api-dev" }], + }, + root: "/test/petrinaut-website", + }); + + expect(config.plugins).toEqual( + expect.arrayContaining([ + expect.objectContaining({ name: "petrinaut-api-dev" }), + ]), ); }); diff --git a/apps/brunch-agent/test/petrinaut-chat-result.ts b/apps/brunch-agent/test/petrinaut-chat-result.ts index 761d4fade07..b1a70cb413c 100644 --- a/apps/brunch-agent/test/petrinaut-chat-result.ts +++ b/apps/brunch-agent/test/petrinaut-chat-result.ts @@ -21,13 +21,15 @@ export interface PetrinautChatResult { readonly resumedStatus: number; readonly resumedText: string; readonly resumedFinish: UIMessageChunk | undefined; - readonly retriedStatus: number; - readonly retriedResumeStatus: number; + readonly questionMarkerLive: unknown; + readonly questionMarkerHistory: unknown; + readonly questionToolVisibleLive: boolean; + readonly questionToolVisibleHistory: boolean; readonly historyUserEntryCount: number; readonly historyClientToolResultCount: number; readonly historyGetStatus: number; readonly historyUserText: string; - readonly foreignHistoryMessages: number; + readonly legacyRouteStatus: number; readonly unauthenticatedHistoryStatus: number; readonly foreignAgentHistoryStatus: number; readonly transcript: string; @@ -53,5 +55,7 @@ export interface PetrinautChatResult { export interface PetrinautResumeResult { readonly historyGetStatus: number; readonly historyUserText: string; + readonly questionMarkerHistory: unknown; + readonly questionToolVisibleHistory: boolean; readonly transcript: string; } diff --git a/apps/brunch-agent/test/petrinaut-chat.integration.ts b/apps/brunch-agent/test/petrinaut-chat.integration.ts index 111f119aefa..253fc8ff4d3 100644 --- a/apps/brunch-agent/test/petrinaut-chat.integration.ts +++ b/apps/brunch-agent/test/petrinaut-chat.integration.ts @@ -1,7 +1,6 @@ import { mkdtemp } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; -import { fileURLToPath } from "node:url"; import { fauxAssistantMessage, @@ -14,11 +13,22 @@ import { setProvider } from "@flue/runtime"; import { createFlueClient, FlueApiError } from "@flue/sdk"; import { READ_PETRINAUT_DOC_TOOL_NAME } from "@hashintel/brunch-agent-plugin-sdcpn/flue"; +import { + createFlueChatTransport, + snapshotToUiMessages, +} from "@hashintel/brunch-agent-transport-aisdk"; import { ELICITATION_SKILL_NAME } from "@hashintel/brunch-agent/flue"; +import { + BRUNCH_QUESTION_DATA_NAME, + BRUNCH_QUESTION_TOOL_NAME, +} from "@hashintel/brunch-agent/question-marker"; import { PING_TOOL_NAME } from "../src/agents/chat-agent/tools/ping.ts"; import { applyCaptureSweep } from "../src/capture/apply-sweep.ts"; -import { CLIENT_TOOL_RESULT_SIGNAL } from "../src/conversation/client-tools.ts"; +import { + clientToolNames, + CLIENT_TOOL_RESULT_SIGNAL, +} from "../src/conversation/client-tools.ts"; import { agentOwnershipHeaders, flueConversationIdFrom, @@ -31,12 +41,13 @@ import type { PetrinautChatResult, PetrinautResumeResult, } from "./petrinaut-chat-result"; -import type { UIMessageChunk } from "ai"; +import type { UIMessage, UIMessageChunk } from "ai"; const ACTIVATE_SKILL_TOOL_NAME = "activate_skill"; const CHAT_MODEL_ID = "claude-haiku-4-5"; const RUNBOOK_SKILL_NAME = "sdcpn-modelling"; const READ_SKILL_RESOURCE_TOOL_NAME = "read_skill_resource"; +const question = "Which documentation page should we inspect next?"; const principalKey = "principal-mission-1"; const conversationId = "conversation-mission-1"; @@ -51,28 +62,57 @@ const dbFile = dbPath.endsWith(".db") process.env.BRUNCH_CHAT_MODEL = CHAT_MODEL_ID; process.env.BRUNCH_DEV_DB_PATH = dbFile; -process.env.BRUNCH_TRANSPORT_AISDK_INSPECT ??= "1"; - -const chunksFrom = (body: string): UIMessageChunk[] => - body - .trim() - .split("\n\n") - .slice(0, -1) - .map((frame) => JSON.parse(frame.slice("data: ".length)) as UIMessageChunk); +const chunksFrom = async ( + stream: ReadableStream, +): Promise => { + const chunks: UIMessageChunk[] = []; + const reader = stream.getReader(); + for (;;) { + const result = await reader.read(); + if (result.done) return chunks; + chunks.push(result.value); + } +}; const userTextFromHistory = ( - messages: readonly { - role?: string; - parts?: { type?: string; text?: string }[]; - }[], + messages: ReturnType, ): string => messages .filter((message) => message.role === "user") - .flatMap((message) => message.parts ?? []) + .flatMap((message) => message.parts) .filter((part) => part.type === "text") - .map((part) => part.text ?? "") + .map((part) => part.text) .join(""); +const questionMarkerFromHistory = ( + messages: ReturnType, +): unknown => { + const marker = messages + .flatMap((message) => message.parts) + .find( + (part) => + part.type === `data-${BRUNCH_QUESTION_DATA_NAME}` && "data" in part, + ); + return marker !== undefined && "data" in marker ? marker.data : undefined; +}; + +const questionMarkerFromChunks = ( + chunks: readonly UIMessageChunk[], +): unknown => { + const marker = chunks.find( + (chunk) => + chunk.type === `data-${BRUNCH_QUESTION_DATA_NAME}` && "data" in chunk, + ); + return marker !== undefined && "data" in marker ? marker.data : undefined; +}; + +const questionToolVisibleInHistory = ( + messages: ReturnType, +): boolean => + messages + .flatMap((message) => message.parts) + .some((part) => part.type === `tool-${BRUNCH_QUESTION_TOOL_NAME}`); + const faux = fauxProvider({ provider: "anthropic", models: [{ id: CHAT_MODEL_ID, reasoning: true }], @@ -89,27 +129,27 @@ try { fetch: appTransport, headers: agentOwnershipHeaders(identity), }); + const panelTransport = createFlueChatTransport({ + client: historyClient, + clientToolNames, + hiddenToolNames: new Set([BRUNCH_QUESTION_TOOL_NAME]), + }); + const projectHistory = ( + snapshot: Awaited>, + ) => + snapshotToUiMessages(snapshot, { + clientToolNames, + hiddenToolNames: new Set([BRUNCH_QUESTION_TOOL_NAME]), + }); if (process.env.BRUNCH_RESUME_PHASE === "1") { const snapshot = await historyClient.history(); - const historyGet = await app.fetch( - new Request( - `http://brunch.test/api/chat?id=${encodeURIComponent(conversationId)}`, - { - method: "GET", - headers: { "x-brunch-principal": principalKey }, - }, - ), - ); - const historyBody = (await historyGet.json()) as { - messages?: { - role?: string; - parts?: { type?: string; text?: string }[]; - }[]; - }; + const historyMessages = projectHistory(snapshot); const result: PetrinautResumeResult = { - historyGetStatus: historyGet.status, - historyUserText: userTextFromHistory(historyBody.messages ?? []), + historyGetStatus: 200, + historyUserText: userTextFromHistory(historyMessages), + questionMarkerHistory: questionMarkerFromHistory(historyMessages), + questionToolVisibleHistory: questionToolVisibleInHistory(historyMessages), transcript: formatFlueTranscript(snapshot), }; process.stdout.write(`PETRINAUT_RESUME_RESULT ${JSON.stringify(result)}\n`); @@ -195,9 +235,19 @@ try { ], { stopReason: "toolUse" }, ), + fauxAssistantMessage( + [ + fauxToolCall( + BRUNCH_QUESTION_TOOL_NAME, + { question }, + { id: "tool-question-1" }, + ), + ], + { stopReason: "toolUse" }, + ), fauxAssistantMessage([ fauxText( - "The guide says the assistant can read its own documentation pages.", + `The guide says the assistant can read its own documentation pages. ${question}`, ), ]), fauxAssistantMessage([ @@ -208,36 +258,21 @@ try { ]), ]); - const fixturePath = fileURLToPath( - new URL( - "../../../libs/@hashintel/brunch-agent/packages/transport-aisdk/test/fixtures/panel-initial.post.json", - import.meta.url, - ), - ); - const { readFile } = await import("node:fs/promises"); - const initialBody = JSON.parse(await readFile(fixturePath, "utf8")) as { - id: string; - messages: { id: string; role: string; parts: unknown[] }[]; - trigger: string; - }; - initialBody.id = conversationId; - const userMessage = initialBody.messages[0]; - if (userMessage === undefined) { - throw new Error("panel-initial.post.json is missing the user message"); - } + const userMessage = { + id: "user-mission-1", + role: "user", + parts: [{ type: "text", text: "Run the FE-1435 transport probe." }], + } satisfies UIMessage; - const initialResponse = await app.fetch( - new Request("http://brunch.test/api/chat", { - method: "POST", - headers: { - "content-type": "application/json", - "x-brunch-principal": principalKey, - "x-request-id": "request-mission-1", - }, - body: JSON.stringify(initialBody), + const initialChunks = await chunksFrom( + await panelTransport.sendMessages({ + trigger: "submit-message", + chatId: conversationId, + messageId: undefined, + messages: [userMessage], + abortSignal: undefined, }), ); - const initialChunks = chunksFrom(await initialResponse.text()); const startChunk = initialChunks.find((chunk) => chunk.type === "start"); const pingCall = initialChunks.find( @@ -277,82 +312,44 @@ try { chunk.toolName === READ_PETRINAUT_DOC_TOOL_NAME, ) ?? null; - const pendingHistoryResponse = await app.fetch( - new Request( - `http://brunch.test/api/chat?id=${encodeURIComponent(conversationId)}`, - { - method: "GET", - headers: { "x-brunch-principal": principalKey }, - }, - ), - ); - const pendingHistoryBody = (await pendingHistoryResponse.json()) as { - messages?: { - parts?: { toolCallId?: string; state?: string }[]; - }[]; - }; - const pendingHistoryClientToolState = pendingHistoryBody.messages - ?.flatMap((message) => message.parts ?? []) - .find((part) => part.toolCallId === clientToolCall?.toolCallId)?.state; + const pendingHistory = projectHistory(await historyClient.history()); + const pendingHistoryClientToolState = pendingHistory + .flatMap((message) => message.parts) + .find( + (part) => + "toolCallId" in part && + part.toolCallId === clientToolCall?.toolCallId, + ); - const resumeBody = { - id: conversationId, - trigger: "submit-message", - messageId: startChunk?.messageId, - messages: [ - userMessage, - { - id: startChunk?.messageId, - role: "assistant", - parts: [ - { - type: `tool-${READ_PETRINAUT_DOC_TOOL_NAME}`, - toolCallId: clientToolCall?.toolCallId, - state: "output-available", - input: { doc: "ai-assistant" }, - output: - "# AI Assistant\nThe assistant can read its own documentation pages.", - }, - ], - }, - ], - }; - const resumeResponse = await app.fetch( - new Request("http://brunch.test/api/chat", { - method: "POST", - headers: { - "content-type": "application/json", - "x-brunch-principal": principalKey, - "x-request-id": "request-mission-1-resume", - }, - body: JSON.stringify(resumeBody), - }), - ); - const resumedChunks = chunksFrom(await resumeResponse.text()); - const retriedResumeResponse = await app.fetch( - new Request("http://brunch.test/api/chat", { - method: "POST", - headers: { - "content-type": "application/json", - "x-brunch-principal": principalKey, - "x-request-id": "request-mission-1-resume-retry", - }, - body: JSON.stringify(resumeBody), - }), - ); - await retriedResumeResponse.text(); - const retriedResponse = await app.fetch( - new Request("http://brunch.test/api/chat", { - method: "POST", - headers: { - "content-type": "application/json", - "x-brunch-principal": principalKey, - "x-request-id": "request-mission-1-retry", - }, - body: JSON.stringify(initialBody), + if (startChunk?.type !== "start" || clientToolCall === null) { + throw new Error("initial stream did not reach the client-tool pause"); + } + const resumeMessages = [ + userMessage, + { + id: startChunk.messageId, + role: "assistant" as const, + parts: [ + { + type: `tool-${READ_PETRINAUT_DOC_TOOL_NAME}`, + toolCallId: clientToolCall.toolCallId, + state: "output-available", + input: { doc: "ai-assistant" }, + output: + "# AI Assistant\nThe assistant can read its own documentation pages.", + }, + ], + }, + ] as UIMessage[]; + const resumedChunks = await chunksFrom( + await panelTransport.sendMessages({ + trigger: "submit-message", + chatId: conversationId, + messageId: startChunk.messageId, + messages: resumeMessages, + abortSignal: undefined, }), ); - await retriedResponse.text(); const snapshot = await historyClient.history(); const userEntryIds = snapshot.messages .filter( @@ -407,37 +404,14 @@ try { foreignAgentHistoryStatus = error instanceof FlueApiError ? error.status : -1; } - const historyGet = await app.fetch( - new Request( - `http://brunch.test/api/chat?id=${encodeURIComponent(conversationId)}`, - { - method: "GET", - headers: { "x-brunch-principal": principalKey }, - }, - ), - ); - const historyBody = (await historyGet.json()) as { - messages?: { - role?: string; - parts?: { type?: string; text?: string }[]; - }[]; - }; - const foreignHistory = await app.fetch( - new Request( - `http://brunch.test/api/chat?id=${encodeURIComponent(conversationId)}`, - { - method: "GET", - headers: { "x-brunch-principal": "principal-other" }, - }, - ), + const historyMessages = projectHistory(snapshot); + const legacyRoute = await app.fetch( + new Request("http://brunch.test/api/chat"), ); - const foreignBody = (await foreignHistory.json()) as { - messages?: unknown[]; - }; const result: PetrinautChatResult = { - status: initialResponse.status, - messageId: startChunk?.messageId, + status: 200, + messageId: startChunk.messageId, partIds: initialChunks .filter( (chunk) => @@ -461,23 +435,33 @@ try { clientToolOutputsOnInitial: initialChunks.filter( (chunk) => chunk.type === "tool-output-available" && - chunk.toolCallId === clientToolCall?.toolCallId, + chunk.toolCallId === clientToolCall.toolCallId, ), initialFinish: initialChunks.at(-1), - pendingHistoryClientToolState, - resumedStatus: resumeResponse.status, + pendingHistoryClientToolState: + pendingHistoryClientToolState === undefined || + !("state" in pendingHistoryClientToolState) + ? undefined + : pendingHistoryClientToolState.state, + resumedStatus: 200, resumedText: resumedChunks .filter((chunk) => chunk.type === "text-delta") .map((chunk) => chunk.delta) .join(""), resumedFinish: resumedChunks.at(-1), - retriedStatus: retriedResponse.status, - retriedResumeStatus: retriedResumeResponse.status, + questionMarkerLive: questionMarkerFromChunks(resumedChunks), + questionMarkerHistory: questionMarkerFromHistory(historyMessages), + questionToolVisibleLive: resumedChunks.some( + (chunk) => + chunk.type === "tool-input-available" && + chunk.toolName === BRUNCH_QUESTION_TOOL_NAME, + ), + questionToolVisibleHistory: questionToolVisibleInHistory(historyMessages), historyUserEntryCount: userEntryIds.length, historyClientToolResultCount: clientToolResultCount, - historyGetStatus: historyGet.status, - historyUserText: userTextFromHistory(historyBody.messages ?? []), - foreignHistoryMessages: foreignBody.messages?.length ?? -1, + historyGetStatus: 200, + historyUserText: userTextFromHistory(historyMessages), + legacyRouteStatus: legacyRoute.status, unauthenticatedHistoryStatus, foreignAgentHistoryStatus, transcript: formatFlueTranscript(snapshot), @@ -486,12 +470,7 @@ try { activateSkillCall, readSkillResourceCall, interviewerToolNames, - captureUserText: userTextFromHistory( - snapshot.messages.map((message) => ({ - role: message.role, - parts: message.parts, - })), - ), + captureUserText: userTextFromHistory(historyMessages), captureIds: firstSweep.captures.map((capture) => capture.id), recaptureIds: secondSweep.captures.map((capture) => capture.id), skippedDedupKeys: secondSweep.skippedDedupKeys, diff --git a/apps/brunch-agent/test/petrinaut-chat.test.ts b/apps/brunch-agent/test/petrinaut-chat.test.ts index 712f5cac82d..2ee108a9ac0 100644 --- a/apps/brunch-agent/test/petrinaut-chat.test.ts +++ b/apps/brunch-agent/test/petrinaut-chat.test.ts @@ -10,11 +10,10 @@ import type { PetrinautChatResult, PetrinautResumeResult, } from "./petrinaut-chat-result"; -import type { TransportInspectionEvent } from "@hashintel/brunch-agent-transport-aisdk"; const testDirectory = import.meta.dirname; -test("the committed /api/chat door streams a plain Flue agent through server and client tools", async () => { +test("the browser transport streams the mounted Flue agent through server and client tools", async () => { const dbDirectory = await mkdtemp(join(tmpdir(), "brunch-chat-")); const dbPath = join(dbDirectory, "conversations.db"); @@ -26,15 +25,6 @@ test("the committed /api/chat door streams a plain Flue agent through server and ); expect(exitCode, stderr || stdout).toBe(0); - const inspectionLines = stdout - .split("\n") - .filter((line) => line.startsWith("TRANSPORT_AISDK ")) - .map( - (line) => - JSON.parse( - line.slice("TRANSPORT_AISDK ".length), - ) as TransportInspectionEvent, - ); const resultLine = stdout .split("\n") .find((line) => line.startsWith("PETRINAUT_CHAT_RESULT ")); @@ -82,8 +72,16 @@ test("the committed /api/chat door streams a plain Flue agent through server and type: "finish", finishReason: "stop", }); - expect(result.retriedStatus).toBe(200); - expect(result.retriedResumeStatus).toBe(200); + expect(result.questionMarkerLive).toEqual({ + question: "Which documentation page should we inspect next?", + toolCallId: "tool-question-1", + }); + expect(result.questionToolVisibleLive).toBe(false); + expect(result.questionMarkerHistory).toEqual({ + question: "Which documentation page should we inspect next?", + toolCallId: "tool-question-1", + }); + expect(result.questionToolVisibleHistory).toBe(false); expect(result.historyUserEntryCount).toBe(1); expect(result.historyClientToolResultCount).toBe(1); @@ -91,7 +89,7 @@ test("the committed /api/chat door streams a plain Flue agent through server and expect(result.historyUserText).toContain( "Run the FE-1435 transport probe.", ); - expect(result.foreignHistoryMessages).toBe(0); + expect(result.legacyRouteStatus).toBe(404); expect(result.unauthenticatedHistoryStatus).toBe(401); expect(result.foreignAgentHistoryStatus).toBe(403); expect(result.transcript).toContain("Run the FE-1435 transport probe."); @@ -119,6 +117,7 @@ test("the committed /api/chat door streams a plain Flue agent through server and expect(result.interviewerToolNames).toContain("read_skill_resource"); expect(result.interviewerToolNames).toContain("ping"); expect(result.interviewerToolNames).toContain("readPetrinautDoc"); + expect(result.interviewerToolNames).toContain("brunch_mark_question"); expect(result.interviewerToolNames).not.toContain("brunch_ask"); expect(result.interviewerToolNames).not.toContain("sweep"); expect(result.interviewerToolNames).not.toContain("brunch_sweep"); @@ -143,41 +142,6 @@ test("the committed /api/chat door streams a plain Flue agent through server and "Run the FE-1435 transport probe.", ); - expect(inspectionLines[0]).toMatchObject({ - type: "request-start", - requestId: "request-mission-1", - }); - expect(inspectionLines.some((event) => event.type === "resume-start")).toBe( - true, - ); - expect( - inspectionLines.filter((event) => event.type === "request-finish"), - ).toEqual([ - { - type: "request-finish", - requestId: "request-mission-1", - terminal: "completed", - }, - { - type: "request-finish", - requestId: "request-mission-1-resume", - terminal: "completed", - }, - { - type: "request-finish", - requestId: "request-mission-1-resume-retry", - terminal: "completed", - }, - { - type: "request-finish", - requestId: "request-mission-1-retry", - terminal: "completed", - }, - ]); - expect( - inspectionLines.filter((event) => event.type === "history-read"), - ).toHaveLength(3); - const resumed = await runNodeScript( join(testDirectory, "petrinaut-chat.integration.ts"), join(testDirectory, "../../.."), @@ -198,10 +162,16 @@ test("the committed /api/chat door streams a plain Flue agent through server and expect(resumeResult.historyUserText).toContain( "Run the FE-1435 transport probe.", ); + expect(resumeResult.questionMarkerHistory).toEqual({ + question: "Which documentation page should we inspect next?", + toolCallId: "tool-question-1", + }); + expect(resumeResult.questionToolVisibleHistory).toBe(false); expect(resumeResult.transcript).toContain("tool ping"); expect(resumeResult.transcript).toContain("tool readPetrinautDoc"); expect(resumeResult.transcript).toContain("tool activate_skill"); expect(resumeResult.transcript).toContain("tool read_skill_resource"); + expect(resumeResult.transcript).toContain("tool brunch_mark_question"); } finally { await rm(dbDirectory, { recursive: true, force: true }); } diff --git a/apps/brunch-agent/test/prepared-workpiece.integration.test.ts b/apps/brunch-agent/test/prepared-workpiece.integration.test.ts new file mode 100644 index 00000000000..25f523efb82 --- /dev/null +++ b/apps/brunch-agent/test/prepared-workpiece.integration.test.ts @@ -0,0 +1,70 @@ +import { mkdtemp, rm } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +import { expect, test } from "vitest"; + +import { runNodeScript } from "./run-node-script"; + +test("the built ChatAgent preserves prepared and model workpiece provenance", async () => { + const databaseDirectory = await mkdtemp( + join(tmpdir(), "brunch-prepared-workpiece-"), + ); + try { + const { exitCode, stdout, stderr } = await runNodeScript( + join(import.meta.dirname, "prepared-workpiece.integration.ts"), + join(import.meta.dirname, "../../.."), + { + BRUNCH_CHAT_DB_PATH: join(databaseDirectory, "conversations.db"), + }, + ); + expect(exitCode, stderr || stdout).toBe(0); + const resultLine = stdout + .split("\n") + .find((line) => line.startsWith("PREPARED_WORKPIECE_HERMETIC ")); + expect(resultLine, stdout).toBeDefined(); + const result = JSON.parse( + resultLine!.slice("PREPARED_WORKPIECE_HERMETIC ".length), + ) as { + readonly clientToolCallIds: string[]; + readonly messageCountStableAcrossRetry: boolean; + readonly prepared: { + readonly authorship: string; + readonly content: string; + readonly sourceKind: string; + }; + readonly preparedDispatchCount: number; + readonly preparationSubmissionId: string; + readonly retryDeduplicated: boolean; + readonly retrySubmissionId: string; + readonly targetArcAdded: boolean; + readonly revision: { + readonly authorship: string; + readonly content: string; + readonly sourceKind: string; + }; + }; + + expect(result.retryDeduplicated).toBe(true); + expect(result.retrySubmissionId).toBe(result.preparationSubmissionId); + expect(result.messageCountStableAcrossRetry).toBe(true); + expect(result.preparedDispatchCount).toBe(1); + expect(result.clientToolCallIds).toEqual([ + "fixture-read-before-mutation", + "fixture-add-reservation-arc", + ]); + expect(result.targetArcAdded).toBe(true); + expect(result.prepared).toMatchObject({ + authorship: "test-authored", + content: "# Prepared revision\n\nTiming and recovery remain unresolved.", + sourceKind: "prepared-signal", + }); + expect(result.revision).toMatchObject({ + authorship: "model-produced", + sourceKind: "assistant", + }); + expect(result.revision.content).toContain("# Model revision one"); + } finally { + await rm(databaseDirectory, { recursive: true, force: true }); + } +}); diff --git a/apps/brunch-agent/test/prepared-workpiece.integration.ts b/apps/brunch-agent/test/prepared-workpiece.integration.ts new file mode 100644 index 00000000000..3c6ea36699f --- /dev/null +++ b/apps/brunch-agent/test/prepared-workpiece.integration.ts @@ -0,0 +1,274 @@ +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +import { + fauxAssistantMessage, + fauxProvider, + fauxText, + fauxToolCall, +} from "@earendil-works/pi-ai"; +import { setProvider } from "@flue/runtime"; +import { createFlueClient } from "@flue/sdk"; + +import { + petrinautFixtureToolNames, + validatedFixtureMutationMode, +} from "@hashintel/brunch-agent-plugin-sdcpn/flue"; +import { createPreparedWorkpieceDelivery } from "@hashintel/brunch-agent/workpiece"; + +import { + CLIENT_TOOL_RESULT_SIGNAL, + isAwaitingClient, +} from "../src/conversation/client-tools.ts"; +import { + agentOwnershipHeaders, + flueConversationIdFrom, +} from "../src/conversation/identity.ts"; +import { recoverRunbookWorkpiece } from "../src/conversation/workpiece.ts"; +import { createHeadlessPetrinautClient } from "../src/evaluations/runbook/headless-petrinaut-client.ts"; +import { loadBuiltBrunchApplication } from "../src/evaluations/runbook/load-built-application.ts"; +import { CHAT_AGENT_ROUTE } from "../src/http/routes.ts"; + +const modelId = "claude-haiku-4-5"; +const dispatchCrewPlaceId = "dispatch_crew_available"; +const startFinalInspectionTransitionId = "start_final_inspection"; +const preparedBody = [ + "Fixture authorship: test-authored.", + "```runbook-ir", + "# Prepared revision", + "", + "Timing and recovery remain unresolved.", + "```", +].join("\n"); +const preparedDelivery = createPreparedWorkpieceDelivery({ + body: preparedBody, + fixtureId: "crew-reservation-v1", + revision: 0, +}); + +process.env.BRUNCH_CHAT_MODEL = modelId; +process.env.BRUNCH_DEV_DB_PATH = + process.env.BRUNCH_CHAT_DB_PATH ?? + join(tmpdir(), `brunch-prepared-workpiece-${crypto.randomUUID()}.db`); + +const provider = fauxProvider({ + provider: "anthropic", + models: [{ id: modelId, reasoning: true }], +}); +setProvider(provider.provider); +provider.setResponses([ + fauxAssistantMessage([ + fauxText( + [ + "Preparation acknowledged.", + "```runbook-ir", + "# Echo that must not become a model revision", + "```", + ].join("\n"), + ), + ]), + fauxAssistantMessage( + [ + fauxToolCall( + "getLatestNetDefinition", + {}, + { id: "fixture-read-before-mutation" }, + ), + ], + { stopReason: "toolUse" }, + ), + fauxAssistantMessage( + [ + fauxToolCall( + "addArc", + { + transitionId: startFinalInspectionTransitionId, + arcDirection: "input", + placeId: dispatchCrewPlaceId, + weight: 1, + }, + { id: "fixture-add-reservation-arc" }, + ), + ], + { stopReason: "toolUse" }, + ), + fauxAssistantMessage([ + fauxText( + [ + "Confirmation incorporated while retaining the unknown.", + "```runbook-ir", + "# Model revision one", + "", + "The sole crew is reserved for final inspection and returned by sign-off.", + "", + "Timing and recovery remain unresolved.", + "```", + ].join("\n"), + ), + ]), +]); + +const identity = { + principalKey: "prepared-workpiece-test", + conversationId: "prepared-workpiece-test", +}; +const application = await loadBuiltBrunchApplication(); +const petrinautClient = createHeadlessPetrinautClient( + "Prepared crew reservation", + { + types: [], + parameters: [], + places: [ + { + id: dispatchCrewPlaceId, + name: "Dispatch crew available", + colorId: null, + dynamicsEnabled: false, + differentialEquationId: null, + x: 0, + y: 0, + }, + ], + transitions: [ + { + id: startFinalInspectionTransitionId, + name: "Start final inspection", + inputArcs: [], + outputArcs: [], + lambdaType: "predicate", + lambdaCode: "", + transitionKernelCode: "", + x: 180, + y: 0, + }, + ], + differentialEquations: [], + }, +); + +try { + const transport: typeof fetch = async (input, init) => + application.fetch( + input instanceof Request ? input : new Request(input, init), + ); + const client = createFlueClient({ + url: `http://brunch.local/agents/${CHAT_AGENT_ROUTE}/${flueConversationIdFrom(identity)}`, + fetch: transport, + headers: agentOwnershipHeaders(identity), + }); + const preparationPrompt = { + uid: null, + initialData: { mode: validatedFixtureMutationMode }, + ...preparedDelivery, + } as const; + const preparation = await client.send(preparationPrompt); + await client.wait(preparation); + const preparedSnapshot = await client.history(); + const recoveredPrepared = recoverRunbookWorkpiece(preparedSnapshot); + + const retry = await client.send(preparationPrompt); + const afterRetry = await client.history(); + + const confirmation = await client.send({ + message: { + kind: "user", + body: "Final inspection consumes the sole crew; sign-off returns it.", + }, + }); + await client.wait(confirmation); + const completedCallIds = new Set(); + const serviceClientCalls = async (clientRound: number): Promise => { + if (clientRound >= 5) { + throw new Error("Prepared fixture exceeded five client-tool rounds."); + } + const snapshot = await client.history(); + const pendingCalls = snapshot.messages.flatMap((message) => + message.parts.flatMap((part) => { + if ( + part.type !== "dynamic-tool" || + !petrinautFixtureToolNames.includes( + part.toolName as (typeof petrinautFixtureToolNames)[number], + ) || + completedCallIds.has(part.toolCallId) || + part.state !== "output-available" || + !isAwaitingClient(part.output) + ) { + return []; + } + return [ + { + toolCallId: part.toolCallId, + toolName: part.toolName, + input: part.input, + }, + ]; + }), + ); + if (pendingCalls.length === 0) return; + + const results = await Promise.all( + pendingCalls.map((pendingCall) => petrinautClient.execute(pendingCall)), + ); + for (const result of results) completedCallIds.add(result.toolCallId); + const continuation = await client.send({ + message: { + kind: "signal", + type: CLIENT_TOOL_RESULT_SIGNAL, + tagName: CLIENT_TOOL_RESULT_SIGNAL, + body: JSON.stringify(results), + }, + }); + await client.wait(continuation); + await serviceClientCalls(clientRound + 1); + }; + await serviceClientCalls(0); + const revisedSnapshot = await client.history(); + const recoveredRevision = recoverRunbookWorkpiece(revisedSnapshot); + + process.stdout.write( + `PREPARED_WORKPIECE_HERMETIC ${JSON.stringify({ + preparationSubmissionId: preparation.submissionId, + retrySubmissionId: retry.submissionId, + retryDeduplicated: retry.deduplicated === true, + messageCountStableAcrossRetry: + preparedSnapshot.messages.length === afterRetry.messages.length, + prepared: recoveredPrepared, + revision: recoveredRevision, + clientToolCallIds: [...completedCallIds], + dynamicTools: revisedSnapshot.messages.flatMap((message) => + message.parts.flatMap((part) => + part.type === "dynamic-tool" + ? [ + { + toolCallId: part.toolCallId, + toolName: part.toolName, + state: part.state, + output: part.output, + errorText: part.errorText, + }, + ] + : [], + ), + ), + targetArcAdded: + petrinautClient + .definition() + .transitions.find(({ id }) => id === startFinalInspectionTransitionId) + ?.inputArcs.some( + (arc) => + arc.placeId === dispatchCrewPlaceId && + arc.type === "standard" && + arc.weight === 1, + ) === true, + preparedDispatchCount: revisedSnapshot.messages.filter( + (message) => + message.role === "system" && + message.purpose === "dispatch" && + message.signal?.tagName === "prepared-fixture", + ).length, + })}\n`, + ); +} finally { + petrinautClient.dispose(); + await application.stop(); +} diff --git a/apps/brunch-agent/test/runbook-artifacts.test.ts b/apps/brunch-agent/test/runbook-artifacts.test.ts index ec065240c0c..1203e25f189 100644 --- a/apps/brunch-agent/test/runbook-artifacts.test.ts +++ b/apps/brunch-agent/test/runbook-artifacts.test.ts @@ -2,10 +2,13 @@ import { describe, expect, test } from "vitest"; import { latestRunbookIrBlock, + runbookIrFence, +} from "@hashintel/brunch-agent/workpiece"; + +import { recoverRunbookWorkpiece } from "../src/conversation/workpiece.ts"; +import { ordinaryElicitationViolationsFrom, recoverRunbookIr, - recoverRunbookWorkpiece, - RUNBOOK_IR_FENCE, skillResourcePathsFrom, } from "../src/evaluations/runbook/artifacts.ts"; @@ -27,11 +30,11 @@ const snapshotWithAssistantText = (text: string): FlueConversationSnapshot => describe("runbook artifact recovery", () => { test("takes the last fenced IR block", () => { const text = [ - "```" + RUNBOOK_IR_FENCE, + "```" + runbookIrFence, "# first", "```", "later", - "```" + RUNBOOK_IR_FENCE, + "```" + runbookIrFence, "# second", "```", ].join("\n"); @@ -41,7 +44,7 @@ describe("runbook artifact recovery", () => { test("recovers an IR from assistant history", () => { const snapshot = snapshotWithAssistantText( [ - "```" + RUNBOOK_IR_FENCE, + "```" + runbookIrFence, "# Runbook IR", "## Purpose and outcome", "```", diff --git a/apps/brunch-agent/test/workpiece.test.ts b/apps/brunch-agent/test/workpiece.test.ts new file mode 100644 index 00000000000..490a18a7eec --- /dev/null +++ b/apps/brunch-agent/test/workpiece.test.ts @@ -0,0 +1,43 @@ +import { describe, expect, test } from "vitest"; + +import { recoverRunbookWorkpiece } from "../src/conversation/workpiece.ts"; + +import type { + FlueConversationMessage, + FlueConversationSnapshot, +} from "@flue/sdk"; + +const revisionMessage: FlueConversationMessage = { + id: "revision", + role: "assistant", + purpose: "assistant", + display: "visible", + submissionId: "turn-1", + parts: [ + { type: "text", text: "```runbook-ir\n# Revision\n```", state: "done" }, + ], +}; + +const snapshot: FlueConversationSnapshot = { + v: 1, + conversationId: "conversation", + offset: "1", + messages: [revisionMessage], + settlements: [], +}; + +describe("recoverRunbookWorkpiece", () => { + test("accepts a Flue snapshot and adds stable content and source hashes", () => { + expect(recoverRunbookWorkpiece(snapshot)).toEqual({ + authorship: "model-produced", + content: "# Revision", + sha256: + "330eeebe84d31400de2dad6ea1783ed1a0d0c5487ab32e63e58a6fffe201c4cb", + sourceKind: "assistant", + sourceMessageId: "revision", + sourceMessageSha256: + "eced072a0cecc954fa63a7f9664e1dffea1a685f71d2b835a9af971a115718e5", + sourceSubmissionId: "turn-1", + }); + }); +}); diff --git a/apps/brunch-agent/turbo.json b/apps/brunch-agent/turbo.json index 4d01ac0c4a7..e8122fd8fc4 100644 --- a/apps/brunch-agent/turbo.json +++ b/apps/brunch-agent/turbo.json @@ -12,7 +12,6 @@ "passThroughEnv": [ "ANTHROPIC_API_KEY", "BRUNCH_DEV_DB_PATH", - "BRUNCH_PETRINAUT_ORIGINS", "BRUNCH_TRANSPORT_AISDK_INSPECT" ] }, diff --git a/apps/petrinaut-website/README.md b/apps/petrinaut-website/README.md index 30cc5d6a7e3..ae357fc115d 100644 --- a/apps/petrinaut-website/README.md +++ b/apps/petrinaut-website/README.md @@ -76,7 +76,7 @@ provides a fake optimizer for isolated UI development. | `PETRINAUT_OPENAI_VOICE_ENABLED` | no | voice API | Set to `true` to enable voice outside production. | | `PETRINAUT_AI_MODEL` | no | `api/chat.ts` | Overrides the default OpenAI model id. | | `PETRINAUT_OPT_ORIGIN` | no | `vite.config.ts` | Overrides the local optimizer proxy target. | -| `VITE_BRUNCH_CHAT_ENDPOINT` | for voice input | website | Full Brunch Petrinaut chat endpoint used by the panel. | +| `VITE_BRUNCH_CHAT_ENDPOINT` | for Brunch | website | Base URL of the mounted Brunch Flue route. | | `VITE_PETRINAUT_OPT_PROVIDER` | no | website | Set to `service` to enable the optimization route. | | `SENTRY_DSN` | no | `vite.config.ts` | Wired into the bundle via `__SENTRY_DSN__` at build time. | @@ -97,6 +97,23 @@ disclosure before requesting microphone access. The disclosure also provides a microphone check and is remembered in browser storage only after Voice mode starts. +When Brunch is selected, typed turns and completed Voice transcripts both enter +the same mounted Flue conversation route. Each logical turn carries a stable +delivery key so a replayed request converges on the existing admission instead +of creating another turn. If admission cannot be confirmed, the UI reports the +ambiguity and does not retry automatically. **Stop** requests a durable Brunch +abort before the panel cancels its local response stream. Local playback +cancellation remains separate and does not alter canonical history. Canonical +Flue history is the source used when the same net is reopened. Automated +coverage guards a locally submitted turn from an older hydration snapshot and +does not resubmit turns or replay settled audio. The real hard-reload witness is +still pending, so reload parity is not yet claimed for this preview. +Voice-origin client-tool results retain their markers in Flue history. Direct +spoken user turns remain canonical text, but Flue 2.0.3 does not yet expose the +caller delivery metadata needed to restore their Voice chip after reopening. + +Browser execution and its continuation keep the shared composer busy; a local tool failure reaches Voice as an error rather than an apparently completed response. Durably aborted history entries retain their stopped label. If the Flue step has already completed, Stop can withhold not-yet-started browser work locally but cannot durably record that withholding: a reopen can recover those calls as pending. This cancellation/reopen limitation remains unresolved; the local guard is not a durable cancellation claim. + An active session stays at the end of the transcript. Its compact divider shows a waveform and **Connecting**, **Listening**, **Speaking**, **Paused**, or a recovery state. Listening levels follow microphone input; provisional words @@ -109,38 +126,45 @@ The text composer remains available. Sending typed text ends Voice mode first, then submits the draft exactly once through the same conversation; a failed handoff restores the draft. Closing the assistant pauses capture and speech before hiding it. Reopening preserves the mounted session in **Paused** state. -**Pause** and **End voice mode** live under **Voice mode actions**, while -**Resume** or **Reconnect** appears as the primary action when applicable. +The dock exposes **Your turn** while canonical audio owns the turn. That action +clears pending input and output, waits for the provider's matching +acknowledgements and response terminal event, and only then opens the +microphone for fresh capture. Its playback menu offers **Repeat question** and +**Read full response**. Full-response replay becomes available once the matching +response and audio output have both finished, enqueues all exact retained +canonical segments in order, and is disabled during capture, submission, +cancellation, pause, and errors. **Repeat question** has the same safety gates +and replays only exact question text carrying Brunch's non-interactive marker; +if the marker is missing, malformed, or does not match finalized prose, the +action stays disabled rather than guessing from the final segment. The browser sends its SDP offer to this app; the server initializes a trusted `gpt-realtime-2` audio-input/audio-output session through OpenAI's unified -Realtime call endpoint. The provider key, model, instructions, tools, language, -and vocabulary policy stay server-side. The session uses semantic VAD with low -eagerness so natural thinking pauses are less likely to end an answer early. - -Realtime is the disposable media plane: it carries continuous microphone and -remote audio, detects complete turns, and handles barge-in. Brunch remains the -control plane and sole authority for questions, captures, state, completion, -and durable history. The browser bridge accepts only the configured -`continue_interview` function, validates and serializes its arguments, rejects -duplicate or stale calls, and submits the answer through Petrinaut's shared -composer path with pending-`brunch_ask` correlation. +Realtime call endpoint. The provider key, model, instructions, language, and +vocabulary policy stay server-side. Realtime exposes no tools, uses +`tool_choice: "none"`, and configures semantic VAD to detect an input boundary +without creating a model response. + +Realtime is the disposable media plane: it carries microphone and remote audio, +detects complete turns, and transcribes input. Brunch remains the control plane +and sole authority for questions, captures, state, completion, and durable +history. The bridge accepts only +`conversation.item.input_audio_transcription.completed` as an answer, ignores +model function arguments, and submits the normalized transcript through +Petrinaut's shared composer path. Connection epoch, item id, and content index +form its stable identity. Duplicate, empty, failed, unavailable, and over-limit +transcripts never submit; recoverable failures leave a not-heard or too-long +notice in the dock. Provisional transcription remains display-only. The bridge waits for the correlated Brunch turn before returning canonical -speech segments to Realtime. It then requests audio with tools disabled and -instructs Realtime to speak only those segments. Generated audio is not a -verbatim record: canonical Brunch text remains visible and authoritative. The -microphone stays active while the interviewer speaks and while Brunch is -working. Speaking over assistant audio interrupts playback automatically; -WebRTC truncates provider-side unheard audio without changing Brunch history. - -The Brunch deployment must allow the website origin through its -`BRUNCH_PETRINAUT_ORIGINS` setting. Denying microphone permission leaves the -text composer available and submits nothing to Brunch. When Voice mode cannot -continue, the inline recovery state distinguishes microphone, connection, and -other Voice failures, explains the next action, and offers **Reconnect** where -appropriate. Sanitized error codes and diagnostic references remain collapsed -under **Technical details**. +speech segments to Realtime. It instructs Realtime to speak only those +segments. Generated audio is not a verbatim recording: canonical Brunch text +remains visible and authoritative. Voice is half-duplex: the physical +microphone is closed while the interviewer speaks, while Brunch is working, and +through cancellation. Audio captured before a **Your turn** handoff is +discarded and cannot become a later answer. + +The local Brunch preview reaches the mounted route through its same-origin, protocol-preserving proxy; this does not establish remote authentication or public ingress. Denying microphone permission leaves the text composer available and submits nothing to Brunch. When Voice mode cannot continue, the inline recovery state distinguishes microphone, connection, and other Voice failures, explains the next action, and offers **Reconnect** where appropriate. Sanitized error codes and diagnostic references remain collapsed under **Technical details**. Realtime connection, transcription, and canonical speech timings use random request IDs, and the existing Brunch transport provides its own request diff --git a/apps/petrinaut-website/package.json b/apps/petrinaut-website/package.json index ca2eb5ecde5..d90b45168e0 100644 --- a/apps/petrinaut-website/package.json +++ b/apps/petrinaut-website/package.json @@ -18,6 +18,7 @@ }, "dependencies": { "@ai-sdk/openai": "3.0.63", + "@flue/sdk": "2.0.3", "@hashintel/brunch-agent": "workspace:*", "@hashintel/brunch-agent-transport-aisdk": "workspace:*", "@hashintel/ds-components": "workspace:*", @@ -26,6 +27,7 @@ "@hashintel/petrinaut-core": "workspace:*", "@local/petrinaut-optimizer-client": "workspace:*", "@mantine/hooks": "8.3.5", + "@noble/hashes": "2.0.1", "@pandacss/dev": "1.11.1", "@sentry/react": "10.64.0", "@tanstack/react-router": "1.170.31", diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/brunch-client-tools.ts b/apps/petrinaut-website/src/main/app/local-storage-demo/brunch-client-tools.ts new file mode 100644 index 00000000000..e3226db07ec --- /dev/null +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/brunch-client-tools.ts @@ -0,0 +1,14 @@ +import { ASK_TOOL_NAME } from "@hashintel/brunch-agent/client-tools"; +import { readPetrinautDocToolName } from "@hashintel/petrinaut-core"; + +/** + * The one catalog of tools the browser answers on Brunch's behalf. The panel + * transport admits their results, the history projection leaves them runnable, + * and every interactive widget the demo registers must name one of them so a + * composer answer reaches Flue as a `client-tool-result` rather than an error. + * Kept free of React imports so the transport can load outside the DOM. + */ +export const brunchClientToolNames: ReadonlySet = new Set([ + readPetrinautDocToolName, + ASK_TOOL_NAME, +]); diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/brunch-panel-transport.test.ts b/apps/petrinaut-website/src/main/app/local-storage-demo/brunch-panel-transport.test.ts index fcf0482e253..2a77be95877 100644 --- a/apps/petrinaut-website/src/main/app/local-storage-demo/brunch-panel-transport.test.ts +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/brunch-panel-transport.test.ts @@ -1,34 +1,373 @@ -import { expect, test } from "vitest"; +import { FlueApiError } from "@flue/sdk"; +import { expect, test, vi } from "vitest"; -import { createBrunchPanelTransport } from "./brunch-panel-transport"; +import { + BrunchPanelConversationTracker, + createBrunchPanelTransport, + createUnavailableBrunchPanelTransport, +} from "./brunch-panel-transport"; -import type { PetrinautAiChatTransport } from "@hashintel/petrinaut/ui"; +import type { AgentSendResult, FlueClient } from "@flue/sdk"; -test("pins send and reconnect to the stable conversation id", async () => { - const seenChatIds: string[] = []; - const sourceTransport: PetrinautAiChatTransport = { - reconnectToStream: async (options) => { - seenChatIds.push(options.chatId); - return null; +test("delegates one typed message to the supplied Flue conversation", async () => { + const admission: AgentSendResult = { + streamUrl: "http://brunch.test/stream", + offset: "offset-1", + submissionId: "submission-1", + uid: "uid-1", + }; + const send = vi.fn(async () => admission); + const wait = vi.fn(async (_admission, options) => { + await options?.onEvent?.({ + type: "message-started", + conversationId: "conversation-stable", + messageId: "assistant-1", + submissionId: admission.submissionId, + turnId: "turn-1", + position: { batch: 1, index: 0 }, + }); + await options?.onEvent?.({ + type: "message-completed", + conversationId: "conversation-stable", + messageId: "assistant-1", + position: { batch: 1, index: 1 }, + }); + await options?.onEvent?.({ + type: "submission-settled", + conversationId: "conversation-stable", + submissionId: admission.submissionId, + outcome: "completed", + position: { batch: 1, index: 2 }, + }); + }); + const client = { + send, + wait, + } as Pick as FlueClient; + const tracker = new BrunchPanelConversationTracker(); + const admissionListener = vi.fn(); + tracker.subscribeToAdmission( + { kind: "user", messageId: "user-1" }, + admissionListener, + ); + const responseCompletedListener = vi.fn(); + tracker.subscribeToResponseMessageCompleted(responseCompletedListener); + const responseStartedListener = vi.fn(); + tracker.subscribeToResponseMessageStarted(responseStartedListener); + const onAdmission = vi.fn(); + const transport = createBrunchPanelTransport( + Promise.resolve(client), + tracker, + { onAdmission }, + ); + const stream = await transport.sendMessages({ + trigger: "submit-message", + chatId: "conversation-stable", + messageId: undefined, + messages: [ + { + id: "user-1", + role: "user", + parts: [{ type: "text", text: "Typed tracer." }], + }, + ], + abortSignal: undefined, + }); + expect(admissionListener).toHaveBeenCalledOnce(); + expect(admissionListener).toHaveBeenCalledWith({ + admission, + kind: "user", + messageId: "user-1", + }); + await stream.pipeTo(new WritableStream()); + + expect(send).toHaveBeenCalledOnce(); + expect(send).toHaveBeenCalledWith({ + idempotencyKey: "ai-sdk:user:user-1", + message: { kind: "user", body: "Typed tracer." }, + signal: undefined, + }); + expect(tracker.submissionForInput("user-1")).toBe("submission-1"); + expect(tracker.submissionsForResponse("assistant-1")).toEqual([ + "submission-1", + ]); + expect(responseStartedListener).toHaveBeenCalledOnce(); + expect(responseStartedListener).toHaveBeenCalledWith({ + messageId: "assistant-1", + position: { batch: 1, index: 0 }, + submissionId: "submission-1", + }); + expect(responseCompletedListener).toHaveBeenCalledOnce(); + expect(responseCompletedListener).toHaveBeenCalledWith({ + messageId: "assistant-1", + position: { batch: 1, index: 1 }, + submissionId: "submission-1", + }); + expect(onAdmission).toHaveBeenCalledOnce(); + expect(onAdmission).toHaveBeenCalledWith(admission); +}); + +test("matches client-tool admissions once and supports unsubscribe", () => { + const admission: AgentSendResult = { + streamUrl: "http://brunch.test/stream", + offset: "offset-1", + submissionId: "submission-1", + uid: "uid-1", + }; + const tracker = new BrunchPanelConversationTracker(); + const matchingListener = vi.fn(); + const unsubscribedListener = vi.fn(); + tracker.subscribeToAdmission( + { + kind: "client-tool-result", + messageId: "assistant-question", }, - sendMessages: async (options) => { - seenChatIds.push(options.chatId); - return new ReadableStream({ - start(controller) { - controller.close(); - }, - }); + matchingListener, + ); + const unsubscribe = tracker.subscribeToAdmission( + { + kind: "client-tool-result", + messageId: "assistant-question", }, + unsubscribedListener, + ); + unsubscribe(); + + tracker.recordAdmission({ + admission, + kind: "user", + messageId: "assistant-question", + }); + tracker.recordAdmission({ + admission, + kind: "client-tool-result", + messageId: "assistant-other", + }); + expect(matchingListener).not.toHaveBeenCalled(); + + const matchedAdmission = { + ...admission, + submissionId: "submission-tool-result", + }; + const event = { + admission: matchedAdmission, + kind: "client-tool-result" as const, + messageId: "assistant-question", }; + tracker.recordAdmission(event); + tracker.recordAdmission(event); + + expect(matchingListener).toHaveBeenCalledOnce(); + expect(matchingListener).toHaveBeenCalledWith(event); + expect(unsubscribedListener).not.toHaveBeenCalled(); +}); + +test("records every submission that wrote a resumed assistant message", () => { + const tracker = new BrunchPanelConversationTracker(); + const responseStartedListener = vi.fn(); + tracker.subscribeToResponseMessageStarted(responseStartedListener); + tracker.recordResponse({ + messageId: "assistant-1", + position: { batch: 1, index: 0 }, + submissionId: "submission-1", + }); + tracker.recordResponse({ + messageId: "assistant-1", + position: { batch: 2, index: 0 }, + submissionId: "submission-continuation", + }); + tracker.recordResponse({ + messageId: "assistant-1", + position: { batch: 2, index: 0 }, + submissionId: "submission-continuation", + }); + + expect(tracker.submissionsForResponse("assistant-1")).toEqual([ + "submission-1", + "submission-continuation", + ]); + expect(tracker.submissionsForResponse("assistant-2")).toBeUndefined(); + expect(responseStartedListener.mock.calls).toEqual([ + [ + { + messageId: "assistant-1", + position: { batch: 1, index: 0 }, + submissionId: "submission-1", + }, + ], + [ + { + messageId: "assistant-1", + position: { batch: 2, index: 0 }, + submissionId: "submission-continuation", + }, + ], + [ + { + messageId: "assistant-1", + position: { batch: 2, index: 0 }, + submissionId: "submission-continuation", + }, + ], + ]); +}); + +test("publishes Stop immediately and supports unsubscribe", () => { + const tracker = new BrunchPanelConversationTracker(); + const listener = vi.fn(); + const unsubscribedListener = vi.fn(); + tracker.subscribeToStopRequested(listener); + const unsubscribe = tracker.subscribeToStopRequested(unsubscribedListener); + unsubscribe(); + + tracker.recordStopRequested(); + + expect(listener).toHaveBeenCalledOnce(); + expect(unsubscribedListener).not.toHaveBeenCalled(); +}); +test("settles in-flight submissions before a durable abort can target them", async () => { + const tracker = new BrunchPanelConversationTracker(); + let admit: (() => void) | undefined; + void tracker.trackSubmission( + new Promise((resolve) => { + admit = resolve; + }), + ); + let settled = false; + void tracker.settleInFlightSubmissions().then(() => { + settled = true; + }); + + await Promise.resolve(); + expect(settled).toBe(false); + + admit?.(); + await vi.waitFor(() => expect(settled).toBe(true)); + + const rejected = tracker.trackSubmission( + Promise.reject(new Error("rejected admission")), + ); + await expect(rejected).rejects.toThrow("rejected admission"); + await expect(tracker.settleInFlightSubmissions()).resolves.toBeUndefined(); +}); + +test("returns a fixture-scoped mutation result through the same Flue client", async () => { + const admission: AgentSendResult = { + streamUrl: "http://brunch.test/stream", + offset: "offset-2", + submissionId: "submission-2", + uid: "uid-2", + }; + const send = vi.fn(async () => admission); + const wait = vi.fn(async () => {}); + const client = { + send, + wait, + } as Pick as FlueClient; + const transport = createBrunchPanelTransport( + Promise.resolve(client), + new BrunchPanelConversationTracker(), + { clientToolNames: new Set(["addArc"]) }, + ); + const stream = await transport.sendMessages({ + trigger: "submit-message", + chatId: "conversation-stable", + messageId: "assistant-1", + messages: [ + { + id: "assistant-1", + role: "assistant", + parts: [ + { + type: "dynamic-tool", + toolName: "addArc", + toolCallId: "add-arc-1", + state: "output-available", + input: {}, + output: { applied: true }, + }, + ], + }, + ], + abortSignal: undefined, + }); + await stream.pipeTo(new WritableStream()); + + expect(send).toHaveBeenCalledWith({ + idempotencyKey: "ai-sdk:client-tools:assistant-1:add-arc-1", + message: { + kind: "signal", + type: "client-tool-result", + tagName: "client-tool-result", + body: JSON.stringify([ + { + toolCallId: "add-arc-1", + toolName: "addArc", + output: { applied: true }, + }, + ]), + attributes: { toolCallIds: "add-arc-1" }, + }, + signal: undefined, + }); +}); + +test("refuses fixture traffic when the mounted Flue route is unavailable", async () => { + const transport = createUnavailableBrunchPanelTransport( + "Fixture route unavailable.", + ); + + await expect( + transport.sendMessages({ + trigger: "submit-message", + chatId: "conversation-stable", + messageId: undefined, + messages: [], + abortSignal: undefined, + }), + ).rejects.toThrow("Fixture route unavailable."); +}); + +test("publishes a typed admission failure for the exact panel input", async () => { + const send = vi.fn(async () => { + throw new FlueApiError(500, ""); + }); + const tracker = new BrunchPanelConversationTracker(); + const failureListener = vi.fn(); + tracker.subscribeToAdmissionFailure( + { kind: "user", messageId: "voice-realtime:1:item-1:0" }, + failureListener, + ); const transport = createBrunchPanelTransport( - sourceTransport, - "conversation-stable", + Promise.resolve({ send } as Pick as FlueClient), + tracker, ); - await transport.sendMessages({ chatId: "generated-by-use-chat" } as never); - await transport.reconnectToStream({ - chatId: "generated-by-use-chat", - } as never); - expect(seenChatIds).toEqual(["conversation-stable", "conversation-stable"]); + const submission = transport.sendMessages({ + trigger: "submit-message", + chatId: "conversation-stable", + messageId: undefined, + messages: [ + { + id: "voice-realtime:1:item-1:0", + role: "user", + parts: [{ type: "text", text: "One Voice turn." }], + }, + ], + abortSignal: undefined, + }); + + await expect(submission).rejects.toMatchObject({ + failure: { kind: "ambiguous" }, + name: "FlueChatAdmissionError", + }); + expect(failureListener).toHaveBeenCalledOnce(); + expect(failureListener).toHaveBeenCalledWith( + expect.objectContaining({ + failure: { kind: "ambiguous" }, + name: "FlueChatAdmissionError", + }), + ); + expect(send).toHaveBeenCalledOnce(); }); diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/brunch-panel-transport.ts b/apps/petrinaut-website/src/main/app/local-storage-demo/brunch-panel-transport.ts index 3cdc3e19459..b8746caea34 100644 --- a/apps/petrinaut-website/src/main/app/local-storage-demo/brunch-panel-transport.ts +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/brunch-panel-transport.ts @@ -1,15 +1,196 @@ +import { + createFlueChatTransport, + FlueChatAdmissionError, +} from "@hashintel/brunch-agent-transport-aisdk"; import { SWEEP_TOOL_NAME } from "@hashintel/brunch-agent/client-tools"; +import { BRUNCH_QUESTION_TOOL_NAME } from "@hashintel/brunch-agent/question-marker"; +import { readPetrinautDocToolName } from "@hashintel/petrinaut-core"; import { sweepOutputSchema } from "../brunch-sweep-output"; +const brunchClientToolNames = new Set([readPetrinautDocToolName]); + import type { SweepCapture, SweepCompletionFailure, SweepCompletionReport, } from "../brunch-sweep-output"; +import type { AgentSendResult, FlueClient } from "@flue/sdk"; +import type { + FlueChatResponseMessageCompletedEvent, + FlueChatResponseMessageStartedEvent, + FlueChatTransportOptions, +} from "@hashintel/brunch-agent-transport-aisdk"; import type { PetrinautAiChatTransport } from "@hashintel/petrinaut/ui"; import type { UIMessageChunk } from "ai"; +export type BrunchPanelAdmission = Parameters< + NonNullable +>[0]; +export type BrunchPanelAdmissionTarget = Pick< + BrunchPanelAdmission, + "kind" | "messageId" +>; + +export class BrunchPanelConversationTracker { + readonly #admissionFailureSubscriptions = new Set<{ + readonly listener: (error: FlueChatAdmissionError) => void; + readonly target: BrunchPanelAdmissionTarget; + }>(); + readonly #admissionSubscriptions = new Set<{ + readonly listener: (admission: BrunchPanelAdmission) => void; + readonly target: BrunchPanelAdmissionTarget; + }>(); + readonly #inFlightSubmissions = new Set>(); + readonly #inputSubmissions = new Map< + string, + AgentSendResult["submissionId"] + >(); + readonly #responseSubmissions = new Map< + string, + AgentSendResult["submissionId"][] + >(); + readonly #responseMessageStartedListeners = new Set< + (event: FlueChatResponseMessageStartedEvent) => void + >(); + readonly #responseMessageCompletedListeners = new Set< + (event: FlueChatResponseMessageCompletedEvent) => void + >(); + readonly #stopRequestedListeners = new Set<() => void>(); + + public recordAdmission(admission: BrunchPanelAdmission): void { + if (admission.kind === "user") { + this.#inputSubmissions.set( + admission.messageId, + admission.admission.submissionId, + ); + } + for (const subscription of this.#admissionSubscriptions) { + if ( + subscription.target.kind === admission.kind && + subscription.target.messageId === admission.messageId + ) { + this.#admissionSubscriptions.delete(subscription); + subscription.listener(admission); + } + } + } + + /** + * A client-tool continuation is projected onto the assistant message it + * resumes, so one message can be written by several submissions. Keep them + * all: Voice correlates a reply by membership, whichever side admitted the + * continuation. + */ + public recordResponse(event: FlueChatResponseMessageStartedEvent): void { + const recorded = this.#responseSubmissions.get(event.messageId); + if (recorded === undefined) { + this.#responseSubmissions.set(event.messageId, [event.submissionId]); + } else if (!recorded.includes(event.submissionId)) { + recorded.push(event.submissionId); + } + for (const listener of this.#responseMessageStartedListeners) { + listener(event); + } + } + + public recordResponseMessageCompleted( + event: FlueChatResponseMessageCompletedEvent, + ): void { + for (const listener of this.#responseMessageCompletedListeners) { + listener(event); + } + } + + public recordStopRequested(): void { + for (const listener of this.#stopRequestedListeners) { + listener(); + } + } + + /** + * Resolves once every submission currently between `send()` and its + * admission has been admitted or rejected, so a conversation-wide abort + * issued afterwards has a settled target rather than racing the admission. + */ + public settleInFlightSubmissions(): Promise { + return Promise.allSettled(this.#inFlightSubmissions).then(() => undefined); + } + + public trackSubmission(submission: Promise): Promise { + this.#inFlightSubmissions.add(submission); + const release = (): void => { + this.#inFlightSubmissions.delete(submission); + }; + submission.then(release, release); + return submission; + } + + public recordAdmissionFailure( + target: BrunchPanelAdmissionTarget, + error: FlueChatAdmissionError, + ): void { + for (const subscription of this.#admissionFailureSubscriptions) { + if ( + subscription.target.kind === target.kind && + subscription.target.messageId === target.messageId + ) { + this.#admissionFailureSubscriptions.delete(subscription); + subscription.listener(error); + } + } + } + + public submissionForInput( + messageId: string, + ): AgentSendResult["submissionId"] | undefined { + return this.#inputSubmissions.get(messageId); + } + + public submissionsForResponse( + messageId: string, + ): readonly AgentSendResult["submissionId"][] | undefined { + return this.#responseSubmissions.get(messageId); + } + + public subscribeToAdmission( + target: BrunchPanelAdmissionTarget, + listener: (admission: BrunchPanelAdmission) => void, + ): () => void { + const subscription = { listener, target }; + this.#admissionSubscriptions.add(subscription); + return () => this.#admissionSubscriptions.delete(subscription); + } + + public subscribeToAdmissionFailure( + target: BrunchPanelAdmissionTarget, + listener: (error: FlueChatAdmissionError) => void, + ): () => void { + const subscription = { listener, target }; + this.#admissionFailureSubscriptions.add(subscription); + return () => this.#admissionFailureSubscriptions.delete(subscription); + } + + public subscribeToResponseMessageCompleted( + listener: (event: FlueChatResponseMessageCompletedEvent) => void, + ): () => void { + this.#responseMessageCompletedListeners.add(listener); + return () => this.#responseMessageCompletedListeners.delete(listener); + } + + public subscribeToResponseMessageStarted( + listener: (event: FlueChatResponseMessageStartedEvent) => void, + ): () => void { + this.#responseMessageStartedListeners.add(listener); + return () => this.#responseMessageStartedListeners.delete(listener); + } + + public subscribeToStopRequested(listener: () => void): () => void { + this.#stopRequestedListeners.add(listener); + return () => this.#stopRequestedListeners.delete(listener); + } +} + const formatFailure = (failure: SweepCompletionFailure): string => { const location = failure.nodeId === undefined @@ -126,26 +307,73 @@ const decorateBrunchStream = ( ); }; -/** - * Pin Petrinaut's stock transport to one stable conversation id so reload, - * client-tool follow-up, and the voice dock share Flue's conversation. - */ +/** Adapt one mounted Flue conversation to Petrinaut's AI SDK rendering contract. */ export const createBrunchPanelTransport = ( - transport: PetrinautAiChatTransport, - conversationId: string, -): PetrinautAiChatTransport => ({ - reconnectToStream: async (options) => { - const stream = await transport.reconnectToStream({ - ...options, - chatId: conversationId, - }); - return stream === null ? null : decorateBrunchStream(stream); + clientPromise: Promise, + tracker: BrunchPanelConversationTracker, + options?: { + /** Fixture-scoped client tools; defaults to the Petrinaut docs reader alone. */ + readonly clientToolNames?: ReadonlySet; + readonly mapClientToolInput?: (input: { + readonly input: unknown; + readonly toolName: string; + }) => unknown; + readonly onAdmission?: (admission: AgentSendResult) => void; }, - sendMessages: async (options) => - decorateBrunchStream( - await transport.sendMessages({ - ...options, - chatId: conversationId, - }), +): PetrinautAiChatTransport => ({ + reconnectToStream: async () => null, + sendMessages: (sendOptions) => + tracker.trackSubmission( + (async () => { + const client = await clientPromise; + const transport = createFlueChatTransport({ + client, + clientToolNames: options?.clientToolNames ?? brunchClientToolNames, + ...(options?.mapClientToolInput === undefined + ? {} + : { mapClientToolInput: options.mapClientToolInput }), + hiddenToolNames: new Set([BRUNCH_QUESTION_TOOL_NAME]), + onAdmission: (event) => { + tracker.recordAdmission(event); + options?.onAdmission?.(event.admission); + }, + onResponseMessage: (event) => tracker.recordResponse(event), + onResponseMessageCompleted: (event) => + tracker.recordResponseMessageCompleted(event), + }); + try { + return decorateBrunchStream( + await transport.sendMessages(sendOptions), + ); + } catch (error) { + const messageId = + sendOptions.messageId ?? sendOptions.messages.at(-1)?.id; + if ( + error instanceof FlueChatAdmissionError && + messageId !== undefined + ) { + tracker.recordAdmissionFailure( + { + kind: + sendOptions.messageId === undefined + ? "user" + : "client-tool-result", + messageId, + }, + error, + ); + } + throw error; + } + })(), ), }); + +export const createUnavailableBrunchPanelTransport = ( + reason: string, +): PetrinautAiChatTransport => ({ + reconnectToStream: async () => null, + sendMessages: async () => { + throw new Error(reason); + }, +}); diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/crew-reservation-history.ts b/apps/petrinaut-website/src/main/app/local-storage-demo/crew-reservation-history.ts new file mode 100644 index 00000000000..f5030832123 --- /dev/null +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/crew-reservation-history.ts @@ -0,0 +1,14 @@ +import type { WorkpieceHistory } from "@hashintel/brunch-agent/workpiece"; + +/** + * Canonical Flue history plus the durable offset observed by the browser. + * Preparation and settlement share this shape rather than independently + * extending the workpiece projection. + */ +export type CrewReservationHistory = WorkpieceHistory & { + readonly offset: string; + readonly settlements: readonly { + readonly outcome: string; + readonly submissionId: string; + }[]; +}; diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/crew-reservation-settled-manifest.test.ts b/apps/petrinaut-website/src/main/app/local-storage-demo/crew-reservation-settled-manifest.test.ts new file mode 100644 index 00000000000..36f3a324538 --- /dev/null +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/crew-reservation-settled-manifest.test.ts @@ -0,0 +1,452 @@ +import { describe, expect, test } from "vitest"; + +import { + preparedWorkpieceAuthorship, + preparedWorkpieceClaimBoundary, + preparedWorkpieceSignalTag, + type WorkpieceHistoryMessage, +} from "@hashintel/brunch-agent/workpiece"; + +import { + hasCrewReservationTargetArc, + settleCrewReservationManifest, +} from "./crew-reservation-settled-manifest"; +import { + crewReservationFixtureId, + dispatchCrewPlaceId, + preparedCrewReservationNet, + preparedCrewReservationWorkpiece, + startFinalInspectionTransitionId, +} from "./prepared-crew-reservation-fixture"; + +const preparedMessage: WorkpieceHistoryMessage = { + id: "prepared-message", + role: "system", + purpose: "dispatch", + submissionId: "prepare-submission", + signal: { + tagName: preparedWorkpieceSignalTag, + attributes: { + fixtureId: crewReservationFixtureId, + authorship: preparedWorkpieceAuthorship, + claimBoundary: preparedWorkpieceClaimBoundary, + }, + }, + parts: [ + { + type: "text", + text: preparedCrewReservationWorkpiece, + }, + ], +}; + +const settledHistory = ( + messages: readonly WorkpieceHistoryMessage[] = [preparedMessage], +) => ({ + conversationId: "canonical-flue-conversation", + offset: "10", + messages, + settlements: [{ submissionId: "prepare-submission", outcome: "completed" }], +}); + +const targetMutationMessages = ( + toolCallId = "target-arc-call", +): readonly [WorkpieceHistoryMessage, WorkpieceHistoryMessage] => [ + { + id: "target-mutation-request", + role: "assistant", + purpose: "assistant", + submissionId: "confirmation-turn", + parts: [ + { + type: "dynamic-tool", + toolCallId, + toolName: "addArc", + input: { + transitionId: startFinalInspectionTransitionId, + arcDirection: "input", + placeId: dispatchCrewPlaceId, + weight: 1, + }, + }, + ], + }, + { + id: "target-mutation-result", + role: "system", + purpose: "dispatch", + submissionId: "mutation-continuation", + signal: { + tagName: "client-tool-result", + }, + parts: [ + { + type: "text", + text: JSON.stringify([ + { + toolCallId, + toolName: "addArc", + output: { applied: true }, + }, + ]), + }, + ], + }, +]; + +describe("crew-reservation settled manifest", () => { + test("records a coherent prepared bundle without inventing the target arc", async () => { + const result = await settleCrewReservationManifest({ + definition: preparedCrewReservationNet, + history: settledHistory(), + settledAt: "2026-09-03T12:00:00.000Z", + }); + + expect(result).toMatchObject({ + status: "settled", + manifest: { + fixtureId: crewReservationFixtureId, + revision: 0, + conversation: { + canonicalId: "canonical-flue-conversation", + }, + latestWorkpiece: { + authorship: "test-authored", + sourceMessageId: "prepared-message", + }, + document: { + targetArc: "absent", + }, + }, + }); + }); + + test("advances only after a completed model revision and document change", async () => { + const initial = await settleCrewReservationManifest({ + definition: preparedCrewReservationNet, + history: settledHistory(), + settledAt: "2026-09-03T12:00:00.000Z", + }); + if (initial.status !== "settled") { + throw new Error("Expected the prepared fixture to settle"); + } + + const revisedMessage: WorkpieceHistoryMessage = { + id: "revised-workpiece", + role: "assistant", + purpose: "assistant", + submissionId: "confirmation-turn", + parts: [ + { + type: "text", + text: preparedCrewReservationWorkpiece.replace( + "It deliberately lacks", + "The confirmation resolves", + ), + }, + ], + }; + const revisedDefinition = structuredClone(preparedCrewReservationNet); + const startInspection = revisedDefinition.transitions.find( + ({ id }) => id === startFinalInspectionTransitionId, + ); + if (startInspection === undefined) { + throw new Error("Missing prepared start-inspection transition"); + } + startInspection.inputArcs.push({ + placeId: dispatchCrewPlaceId, + type: "standard", + weight: 1, + }); + + const result = await settleCrewReservationManifest({ + definition: revisedDefinition, + history: { + ...settledHistory([ + preparedMessage, + ...targetMutationMessages(), + revisedMessage, + ]), + offset: "20", + settlements: [ + { submissionId: "prepare-submission", outcome: "completed" }, + { submissionId: "confirmation-turn", outcome: "completed" }, + ], + }, + previous: initial.manifest, + settledAt: "2026-09-03T12:05:00.000Z", + }); + + expect(hasCrewReservationTargetArc(revisedDefinition)).toBe(true); + expect(result).toMatchObject({ + status: "settled", + manifest: { + revision: 1, + latestWorkpiece: { authorship: "model-produced" }, + document: { targetArc: "present" }, + }, + }); + }); + + test("numbers a model revision that settles first by its history, not as revision zero", async () => { + // The transport waits for preparation, not for the revision-zero manifest, + // so a user who submits immediately can produce the model revision before + // any manifest exists. Its manifest must still say revision one. + const revisedMessage: WorkpieceHistoryMessage = { + id: "revised-workpiece", + role: "assistant", + purpose: "assistant", + submissionId: "confirmation-turn", + parts: [ + { + type: "text", + text: preparedCrewReservationWorkpiece.replace( + "It deliberately lacks", + "The confirmation resolves", + ), + }, + ], + }; + const revisedDefinition = structuredClone(preparedCrewReservationNet); + const startInspection = revisedDefinition.transitions.find( + ({ id }) => id === startFinalInspectionTransitionId, + ); + if (startInspection === undefined) { + throw new Error("Missing prepared start-inspection transition"); + } + startInspection.inputArcs.push({ + placeId: dispatchCrewPlaceId, + type: "standard", + weight: 1, + }); + + const result = await settleCrewReservationManifest({ + definition: revisedDefinition, + history: { + ...settledHistory([ + preparedMessage, + ...targetMutationMessages(), + revisedMessage, + ]), + settlements: [ + { submissionId: "prepare-submission", outcome: "completed" }, + { submissionId: "confirmation-turn", outcome: "completed" }, + ], + }, + settledAt: "2026-09-03T12:05:00.000Z", + }); + + expect(result).toMatchObject({ + status: "settled", + manifest: { + revision: 1, + latestWorkpiece: { authorship: "model-produced" }, + }, + }); + }); + + test("refuses a model revision without one successful correlated target mutation", async () => { + const revisedMessage: WorkpieceHistoryMessage = { + id: "revised-workpiece", + role: "assistant", + purpose: "assistant", + submissionId: "confirmation-turn", + parts: [{ type: "text", text: preparedCrewReservationWorkpiece }], + }; + const revisedDefinition = structuredClone(preparedCrewReservationNet); + const startInspection = revisedDefinition.transitions.find( + ({ id }) => id === startFinalInspectionTransitionId, + ); + if (startInspection === undefined) { + throw new Error("Missing prepared start-inspection transition"); + } + startInspection.inputArcs.push({ + placeId: dispatchCrewPlaceId, + type: "standard", + weight: 1, + }); + const history = { + ...settledHistory([preparedMessage, revisedMessage]), + settlements: [ + { submissionId: "prepare-submission", outcome: "completed" }, + { submissionId: "confirmation-turn", outcome: "completed" }, + ], + }; + + await expect( + settleCrewReservationManifest({ + definition: revisedDefinition, + history, + settledAt: "2026-09-03T12:05:00.000Z", + }), + ).resolves.toEqual({ + status: "refused", + reason: "missing-correlated-mutation", + }); + + const [targetCall, targetResult] = targetMutationMessages(); + await expect( + settleCrewReservationManifest({ + definition: revisedDefinition, + history: { + ...history, + messages: [ + preparedMessage, + targetCall, + { + ...targetResult, + parts: [ + { + type: "text", + text: JSON.stringify([ + { + toolCallId: "target-arc-call", + toolName: "addArc", + output: { applied: false, reason: "no-op" }, + }, + ]), + }, + ], + }, + revisedMessage, + ], + }, + settledAt: "2026-09-03T12:05:00.000Z", + }), + ).resolves.toEqual({ + status: "refused", + reason: "missing-correlated-mutation", + }); + + await expect( + settleCrewReservationManifest({ + definition: revisedDefinition, + history: { + ...history, + messages: [ + preparedMessage, + ...targetMutationMessages(), + targetMutationMessages()[1], + revisedMessage, + ], + }, + settledAt: "2026-09-03T12:05:00.000Z", + }), + ).resolves.toMatchObject({ status: "settled" }); + + await expect( + settleCrewReservationManifest({ + definition: revisedDefinition, + history: { + ...history, + messages: [ + preparedMessage, + ...targetMutationMessages(), + ...targetMutationMessages("second-target-arc-call"), + revisedMessage, + ], + }, + settledAt: "2026-09-03T12:05:00.000Z", + }), + ).resolves.toEqual({ + status: "refused", + reason: "missing-correlated-mutation", + }); + }); + + test("retains the previous bundle when recovery is partial", async () => { + const initial = await settleCrewReservationManifest({ + definition: preparedCrewReservationNet, + history: settledHistory(), + settledAt: "2026-09-03T12:00:00.000Z", + }); + if (initial.status !== "settled") { + throw new Error("Expected the prepared fixture to settle"); + } + + await expect( + settleCrewReservationManifest({ + definition: preparedCrewReservationNet, + history: { + ...settledHistory(), + conversationId: "different-conversation", + }, + previous: initial.manifest, + settledAt: "2026-09-03T12:05:00.000Z", + }), + ).resolves.toEqual({ + status: "refused", + reason: "conversation-mismatch", + }); + + await expect( + settleCrewReservationManifest({ + definition: preparedCrewReservationNet, + history: { + ...settledHistory(), + settlements: [], + }, + previous: initial.manifest, + settledAt: "2026-09-03T12:05:00.000Z", + }), + ).resolves.toEqual({ + status: "refused", + reason: "missing-completed-settlement", + }); + }); + + test("does not publish a new revision for an unchanged coherent bundle", async () => { + const initial = await settleCrewReservationManifest({ + definition: preparedCrewReservationNet, + history: settledHistory(), + settledAt: "2026-09-03T12:00:00.000Z", + }); + if (initial.status !== "settled") { + throw new Error("Expected the prepared fixture to settle"); + } + + await expect( + settleCrewReservationManifest({ + definition: preparedCrewReservationNet, + history: { ...settledHistory(), offset: "11" }, + previous: initial.manifest, + settledAt: "2026-09-03T12:05:00.000Z", + }), + ).resolves.toEqual(initial); + }); + + test("keeps the prepared bundle selected when the document changes first", async () => { + const initial = await settleCrewReservationManifest({ + definition: preparedCrewReservationNet, + history: settledHistory(), + settledAt: "2026-09-03T12:00:00.000Z", + }); + if (initial.status !== "settled") { + throw new Error("Expected the prepared fixture to settle"); + } + const partialDefinition = structuredClone(preparedCrewReservationNet); + const startInspection = partialDefinition.transitions.find( + ({ id }) => id === startFinalInspectionTransitionId, + ); + if (startInspection === undefined) { + throw new Error("Missing prepared start-inspection transition"); + } + startInspection.inputArcs.push({ + placeId: dispatchCrewPlaceId, + type: "standard", + weight: 1, + }); + + await expect( + settleCrewReservationManifest({ + definition: partialDefinition, + history: settledHistory(), + previous: initial.manifest, + settledAt: "2026-09-03T12:05:00.000Z", + }), + ).resolves.toEqual({ + status: "refused", + reason: "bundle-mismatch", + }); + }); +}); diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/crew-reservation-settled-manifest.ts b/apps/petrinaut-website/src/main/app/local-storage-demo/crew-reservation-settled-manifest.ts new file mode 100644 index 00000000000..efdfe49bb3a --- /dev/null +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/crew-reservation-settled-manifest.ts @@ -0,0 +1,277 @@ +import { sha256 as sha256Bytes } from "@noble/hashes/sha2.js"; +import { bytesToHex } from "@noble/hashes/utils.js"; + +import { clientToolHistoryFrom } from "@hashintel/brunch-agent-transport-aisdk"; +import { selectRunbookWorkpiece } from "@hashintel/brunch-agent/workpiece"; +import { isSDCPNEqual, type SDCPN } from "@hashintel/petrinaut-core"; +import { normalizePetrinautAiToolInput } from "@hashintel/petrinaut-core/ai"; + +import { + crewReservationConversationId, + crewReservationDocumentId, + crewReservationFixtureId, + dispatchCrewPlaceId, + preparedCrewReservationNet, + startFinalInspectionTransitionId, +} from "./prepared-crew-reservation-fixture"; + +import type { CrewReservationHistory } from "./crew-reservation-history"; + +export const crewReservationSettledManifestStorageKey = + "brunch:prepared-fixture:crew-reservation-v1:settled"; + +declare const manifestValueBrand: unique symbol; +type ManifestValue = string & { + readonly [manifestValueBrand]: Kind; +}; + +export type CanonicalConversationId = ManifestValue<"canonical-conversation">; +export type ConversationOffset = ManifestValue<"conversation-offset">; +export type FlueMessageId = ManifestValue<"flue-message">; +export type FlueSubmissionId = ManifestValue<"flue-submission">; +export type ManifestId = ManifestValue<"manifest">; +export type Sha256Digest = ManifestValue<"sha256">; + +export const asCanonicalConversationId = ( + value: string, +): CanonicalConversationId => value as CanonicalConversationId; +export const asConversationOffset = (value: string): ConversationOffset => + value as ConversationOffset; +export const asFlueMessageId = (value: string): FlueMessageId => + value as FlueMessageId; +export const asFlueSubmissionId = (value: string): FlueSubmissionId => + value as FlueSubmissionId; +export const asManifestId = (value: string): ManifestId => value as ManifestId; +export const asSha256Digest = (value: string): Sha256Digest => + value as Sha256Digest; + +const isRecord = (value: unknown): value is Record => + typeof value === "object" && value !== null; + +export interface CrewReservationSettledManifest { + readonly conversation: { + readonly canonicalId: CanonicalConversationId; + readonly logicalId: typeof crewReservationConversationId; + readonly offset: ConversationOffset; + }; + readonly document: { + readonly id: typeof crewReservationDocumentId; + readonly sha256: Sha256Digest; + readonly targetArc: "absent" | "present"; + }; + readonly fixtureId: typeof crewReservationFixtureId; + readonly latestWorkpiece: { + readonly authorship: "model-produced" | "test-authored"; + readonly contentSha256: Sha256Digest; + readonly sourceKind: "assistant" | "prepared-signal"; + readonly sourceMessageId: FlueMessageId; + readonly sourceMessageSha256: Sha256Digest; + readonly sourceSubmissionId: FlueSubmissionId; + }; + readonly manifestId: ManifestId; + readonly revision: number; + readonly settledAt: string; + readonly version: 1; +} + +export type CrewReservationSettlementResult = + | { + readonly manifest: CrewReservationSettledManifest; + readonly status: "settled"; + } + | { + readonly reason: + | "bundle-mismatch" + | "conversation-mismatch" + | "missing-correlated-mutation" + | "missing-completed-settlement" + | "missing-workpiece"; + readonly status: "refused"; + }; + +const targetMutationCallIds = ( + history: CrewReservationHistory, +): readonly string[] => { + const { calls } = clientToolHistoryFrom(history.messages); + return calls.flatMap(({ input, toolCallId, toolName }) => { + if (toolName !== "addArc") return []; + const normalizedInput = normalizePetrinautAiToolInput("addArc", input); + return isRecord(normalizedInput) && + normalizedInput.transitionId === startFinalInspectionTransitionId && + normalizedInput.arcDirection === "input" && + normalizedInput.placeId === dispatchCrewPlaceId && + normalizedInput.weight === 1 + ? [toolCallId] + : []; + }); +}; + +const successfulMutationResultIds = ( + history: CrewReservationHistory, +): readonly string[] => { + const { results } = clientToolHistoryFrom(history.messages); + return results.flatMap(({ output, toolCallId, toolName }) => + toolName === "addArc" && + typeof output === "object" && + output !== null && + "applied" in output && + output.applied === true + ? [toolCallId] + : [], + ); +}; + +const hasOneCorrelatedTargetMutation = ( + history: CrewReservationHistory, +): boolean => { + const successfulResultIds = new Set(successfulMutationResultIds(history)); + const correlatedTargetCallIds = new Set( + targetMutationCallIds(history).filter((toolCallId) => + successfulResultIds.has(toolCallId), + ), + ); + return correlatedTargetCallIds.size === 1; +}; + +export const sha256Digest = (value: string): Sha256Digest => + asSha256Digest(bytesToHex(sha256Bytes(new TextEncoder().encode(value)))); + +export const hasCrewReservationTargetArc = (definition: SDCPN): boolean => { + const transition = definition.transitions.find( + ({ id }) => id === startFinalInspectionTransitionId, + ); + return ( + transition?.inputArcs.some( + (arc) => + arc.placeId === dispatchCrewPlaceId && + arc.type === "standard" && + arc.weight === 1, + ) ?? false + ); +}; + +const preparedCrewReservationNetWithTargetArc = (): SDCPN => { + const definition = structuredClone(preparedCrewReservationNet); + const transition = definition.transitions.find( + ({ id }) => id === startFinalInspectionTransitionId, + ); + if (transition === undefined) { + throw new Error("The prepared fixture has no start-inspection transition."); + } + transition.inputArcs.push({ + placeId: dispatchCrewPlaceId, + type: "standard", + weight: 1, + }); + return definition; +}; + +export const settleCrewReservationManifest = async (input: { + readonly definition: SDCPN; + readonly history: CrewReservationHistory; + readonly previous?: CrewReservationSettledManifest; + readonly settledAt: string; +}): Promise => { + if ( + input.previous !== undefined && + input.previous.conversation.canonicalId !== input.history.conversationId + ) { + return { status: "refused", reason: "conversation-mismatch" }; + } + + const workpiece = selectRunbookWorkpiece(input.history); + if (workpiece === undefined || workpiece.sourceSubmissionId === undefined) { + return { status: "refused", reason: "missing-workpiece" }; + } + const sourceSettlement = input.history.settlements.find( + ({ submissionId }) => submissionId === workpiece.sourceSubmissionId, + ); + if (sourceSettlement?.outcome !== "completed") { + return { + status: "refused", + reason: "missing-completed-settlement", + }; + } + const targetArcPresent = hasCrewReservationTargetArc(input.definition); + if ( + workpiece.authorship === "model-produced" && + (!targetArcPresent || + !isSDCPNEqual( + input.definition, + preparedCrewReservationNetWithTargetArc(), + ) || + !hasOneCorrelatedTargetMutation(input.history)) + ) { + return { + status: "refused", + reason: "missing-correlated-mutation", + }; + } + + const contentSha256 = sha256Digest(workpiece.content); + const documentSha256 = sha256Digest(JSON.stringify(input.definition)); + const sourceMessageSha256 = sha256Digest( + JSON.stringify(workpiece.sourceMessage), + ); + if (workpiece.authorship === "test-authored") { + const preparedDocumentSha256 = sha256Digest( + JSON.stringify(preparedCrewReservationNet), + ); + if ( + targetArcPresent || + documentSha256 !== preparedDocumentSha256 || + !isSDCPNEqual(input.definition, preparedCrewReservationNet) + ) { + return { status: "refused", reason: "bundle-mismatch" }; + } + } + if ( + input.previous?.latestWorkpiece.sourceMessageId === + workpiece.sourceMessageId + ) { + if ( + input.previous.document.sha256 !== documentSha256 || + input.previous.latestWorkpiece.sourceMessageSha256 !== + sourceMessageSha256 || + input.previous.latestWorkpiece.contentSha256 !== contentSha256 + ) { + return { status: "refused", reason: "bundle-mismatch" }; + } + return { status: "settled", manifest: input.previous }; + } + const withoutId = { + version: 1 as const, + fixtureId: crewReservationFixtureId, + // Numbered by the history, not by how many manifests this browser has + // settled: a model revision that settles before the prepared bundle did + // must not be labelled the test-authored revision zero. + revision: workpiece.revision, + settledAt: input.settledAt, + conversation: { + logicalId: crewReservationConversationId, + canonicalId: asCanonicalConversationId(input.history.conversationId), + offset: asConversationOffset(input.history.offset), + }, + latestWorkpiece: { + authorship: workpiece.authorship, + contentSha256, + sourceKind: workpiece.sourceKind, + sourceMessageId: asFlueMessageId(workpiece.sourceMessageId), + sourceMessageSha256, + sourceSubmissionId: asFlueSubmissionId(workpiece.sourceSubmissionId), + }, + document: { + id: crewReservationDocumentId, + sha256: documentSha256, + targetArc: targetArcPresent ? ("present" as const) : ("absent" as const), + }, + } satisfies Omit; + + return { + status: "settled", + manifest: { + ...withoutId, + manifestId: asManifestId(sha256Digest(JSON.stringify(withoutId))), + }, + }; +}; diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/local-storage-demo-app.test.tsx b/apps/petrinaut-website/src/main/app/local-storage-demo/local-storage-demo-app.test.tsx index 02e1bfe1b7f..878bd25c03e 100644 --- a/apps/petrinaut-website/src/main/app/local-storage-demo/local-storage-demo-app.test.tsx +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/local-storage-demo-app.test.tsx @@ -1,26 +1,54 @@ /** * @vitest-environment jsdom */ -import { act, cleanup, render } from "@testing-library/react"; +import { act, cleanup, render, waitFor } from "@testing-library/react"; import { isValidElement, type ReactNode } from "react"; import { afterEach, describe, expect, test, vi } from "vitest"; +import { FlueChatAdmissionError } from "@hashintel/brunch-agent-transport-aisdk"; import { defaultPetrinautNavigationHistoryPolicy } from "@hashintel/petrinaut/react"; +import { OpenAIRealtimeSession } from "../voice-interview/openai-realtime-session"; import { VoiceInterviewControl } from "../voice-interview/voice-interview-control"; +import { BrunchPanelConversationTracker } from "./brunch-panel-transport"; import { getBrunchVoiceMode, LocalStorageDemoApp, + requestFlueStop, } from "./local-storage-demo-app"; - +import { + crewReservationConversationId, + crewReservationFixtureId, +} from "./prepared-crew-reservation-fixture"; + +import type { + AgentConversationObservationSnapshot, + FlueClient, +} from "@flue/sdk"; import type { PetrinautNavigationController } from "@hashintel/petrinaut/react"; +import type { PetrinautAiAssistant } from "@hashintel/petrinaut/ui"; const defaultTransportOptions = vi.hoisted(() => ({ current: null as unknown, })); +const flueClientMock = vi.hoisted(() => ({ current: null as unknown })); +const renderedPetrinaut = vi.hoisted(() => ({ aiAssistant: null as unknown })); + +vi.mock("@flue/sdk", () => ({ + createFlueClient: () => flueClientMock.current, +})); + +const brunchPreviewConfig = vi.hoisted(() => ({ + chatEndpoint: "/agents/chat", + isBrunchConfigured: true, +})); +vi.mock("./brunch-preview-config", () => ({ + resolveBrunchPreviewConfig: () => brunchPreviewConfig, +})); const editorProps = vi.hoisted(() => ({ current: null as { + aiAssistant?: unknown; navigation?: unknown; createNewNet?: (params: { petriNetDefinition: unknown; @@ -41,6 +69,7 @@ vi.mock("@hashintel/petrinaut/ui", () => ({ }, Petrinaut: (props: Record) => { editorProps.current = props; + renderedPetrinaut.aiAssistant = props.aiAssistant; return null; }, WalkthroughProvider: ({ children }: { children: ReactNode }) => children, @@ -54,37 +83,240 @@ describe("local storage demo Brunch voice integration", () => { test("installs the app-owned voice control for a configured Brunch transport", () => { const config = { available: true as const, connectionTimeoutMs: 15_000 }; - const voiceMode = getBrunchVoiceMode(config); - const control = voiceMode?.({ - canAcceptVoiceInput: true, - conversationId: "petrinaut-preview:net-1", - inputMode: "text", - isAiAssistantOpen: true, - messages: [], - registerVoiceModeControls: vi.fn(() => () => undefined), - reportVoiceSessionState: vi.fn(), - setInputMode: vi.fn(), - setVoiceActive: vi.fn(), - status: "ready", - stop: vi.fn(async () => undefined), - submitText: vi.fn(async () => ({ - kind: "message" as const, - messageId: "message-1", - })), - submitVoiceInput: vi.fn(async () => ({ - kind: "message" as const, - messageId: "voice-message-1", - })), - }); + const tracker = new BrunchPanelConversationTracker(); + const voiceMode = getBrunchVoiceMode(config, tracker); + const renderControl = () => + voiceMode?.({ + canAcceptVoiceInput: true, + conversationId: "petrinaut-preview:net-1", + inputMode: "text", + isAiAssistantOpen: true, + messages: [], + registerVoiceModeControls: vi.fn(() => () => undefined), + reportVoiceSessionState: vi.fn(), + setInputMode: vi.fn(), + setVoiceActive: vi.fn(), + status: "ready", + stop: vi.fn(async () => undefined), + submitText: vi.fn(async () => ({ + kind: "message" as const, + messageId: "message-1", + })), + submitVoiceInput: vi.fn(async () => ({ + kind: "message" as const, + messageId: "voice-message-1", + })), + }); + const control = renderControl(); expect(isValidElement(control)).toBe(true); if (!isValidElement(control)) { throw new Error("Expected the configured composer control to render."); } - expect(control).toMatchObject({ - props: { config }, - type: VoiceInterviewControl, + const failureListener = vi.fn(); + const responseCompletedListener = vi.fn(); + const responseStartedListener = vi.fn(); + const stopListener = vi.fn(); + const target = { kind: "user" as const, messageId: "voice-turn-1" }; + const controlProps = control.props as { + config: typeof config; + resolveInputSubmission: (messageId: string) => string | undefined; + resolveResponseSubmission: ( + messageId: string, + ) => readonly string[] | undefined; + subscribeToAdmission: ( + admissionTarget: typeof target, + listener: (submissionId: string) => void, + ) => () => void; + subscribeToAdmissionFailure: ( + admissionTarget: typeof target, + listener: (error: FlueChatAdmissionError) => void, + ) => () => void; + subscribeToResponseMessageCompleted: ( + listener: typeof responseCompletedListener, + ) => () => void; + subscribeToResponseMessageStarted: ( + listener: typeof responseStartedListener, + ) => () => void; + subscribeToStopRequested: (listener: () => void) => () => void; + }; + expect(control.type).toBe(VoiceInterviewControl); + expect(controlProps.config).toBe(config); + + const rerenderedControl = renderControl(); + expect(isValidElement(rerenderedControl)).toBe(true); + if (!isValidElement(rerenderedControl)) { + throw new Error("Expected the configured composer control to rerender."); + } + const rerenderedControlProps = + rerenderedControl.props as typeof controlProps; + expect(rerenderedControlProps.resolveInputSubmission).toBe( + controlProps.resolveInputSubmission, + ); + expect(rerenderedControlProps.resolveResponseSubmission).toBe( + controlProps.resolveResponseSubmission, + ); + expect(rerenderedControlProps.subscribeToAdmission).toBe( + controlProps.subscribeToAdmission, + ); + expect(rerenderedControlProps.subscribeToAdmissionFailure).toBe( + controlProps.subscribeToAdmissionFailure, + ); + expect(rerenderedControlProps.subscribeToResponseMessageCompleted).toBe( + controlProps.subscribeToResponseMessageCompleted, + ); + expect(rerenderedControlProps.subscribeToResponseMessageStarted).toBe( + controlProps.subscribeToResponseMessageStarted, + ); + expect(rerenderedControlProps.subscribeToStopRequested).toBe( + controlProps.subscribeToStopRequested, + ); + + const unsubscribe = controlProps.subscribeToAdmissionFailure( + target, + failureListener, + ); + const unsubscribeFromStop = + controlProps.subscribeToStopRequested(stopListener); + const unsubscribeFromResponseCompleted = + controlProps.subscribeToResponseMessageCompleted( + responseCompletedListener, + ); + const unsubscribeFromResponseStarted = + controlProps.subscribeToResponseMessageStarted(responseStartedListener); + const admissionError = new FlueChatAdmissionError({ kind: "ambiguous" }); + + tracker.recordAdmissionFailure(target, admissionError); + tracker.recordResponse({ + messageId: "assistant-1", + position: { batch: 1, index: 0 }, + submissionId: "submission-1", + }); + tracker.recordResponseMessageCompleted({ + messageId: "assistant-1", + position: { batch: 1, index: 1 }, + submissionId: "submission-1", + }); + tracker.recordStopRequested(); + + expect(failureListener).toHaveBeenCalledWith(admissionError); + expect(responseStartedListener).toHaveBeenCalledOnce(); + expect(responseCompletedListener).toHaveBeenCalledOnce(); + expect(stopListener).toHaveBeenCalledOnce(); + unsubscribe(); + unsubscribeFromResponseCompleted(); + unsubscribeFromResponseStarted(); + unsubscribeFromStop(); + }); + + test("registers no brunch_ask tool in the production Brunch preview", async () => { + renderedPetrinaut.aiAssistant = null; + flueClientMock.current = { + observe: () => ({ + close: vi.fn(), + getSnapshot: () => ({ phase: "absent" }), + refresh: vi.fn(), + subscribe: () => () => undefined, + }), + }; + vi.stubGlobal( + "fetch", + vi.fn(async () => + Response.json({ available: false }), + ), + ); + + const rendered = render( + {}} search={{}} />, + ); + await waitFor(() => expect(renderedPetrinaut.aiAssistant).not.toBeNull()); + const aiAssistant = renderedPetrinaut.aiAssistant as PetrinautAiAssistant; + + expect(aiAssistant.requestStop).toBeTypeOf("function"); + expect(aiAssistant.interactiveTools).toEqual([]); + expect( + aiAssistant.interactiveTools?.some( + ({ toolName }) => toolName === "brunch_ask", + ), + ).toBe(false); + + rendered.unmount(); + vi.unstubAllGlobals(); + }); + + test("keeps durable Flue Stop distinct from local playback cancellation", async () => { + renderedPetrinaut.aiAssistant = null; + let snapshot: AgentConversationObservationSnapshot = { + conversation: { + conversationId: "conversation-stop", + settlements: [], + messages: [], + }, + offset: "offset-before-stop", + phase: "live" as const, + error: undefined, + }; + const listeners = new Set<() => void>(); + const localPlaybackCancellation = vi.spyOn( + OpenAIRealtimeSession.prototype, + "cancelOutput", + ); + const abort = vi.fn(async () => { + snapshot = { + conversation: { + conversationId: "conversation-stop", + settlements: [ + { submissionId: "submission-stop", outcome: "aborted" as const }, + ], + messages: [], + }, + offset: "offset-after-stop", + phase: "live" as const, + error: undefined, + }; + for (const listener of listeners) listener(); + return { aborted: true }; }); + flueClientMock.current = { + abort, + observe: () => ({ + close: vi.fn(), + getSnapshot: () => snapshot, + refresh: vi.fn(), + subscribe: (listener: () => void) => { + listeners.add(listener); + return () => listeners.delete(listener); + }, + }), + }; + vi.stubGlobal( + "fetch", + vi.fn(async () => + Response.json({ available: false }), + ), + ); + + const rendered = render( + {}} search={{}} />, + ); + await waitFor(() => + expect( + (renderedPetrinaut.aiAssistant as PetrinautAiAssistant).requestStop, + ).toBeTypeOf("function"), + ); + const aiAssistant = renderedPetrinaut.aiAssistant as PetrinautAiAssistant; + + await expect(aiAssistant.requestStop?.()).resolves.toBe("stop-requested"); + expect(abort).toHaveBeenCalledOnce(); + expect(localPlaybackCancellation).not.toHaveBeenCalled(); + expect( + (renderedPetrinaut.aiAssistant as PetrinautAiAssistant) + .renderComposerControl, + ).toBeUndefined(); + + rendered.unmount(); + localPlaybackCancellation.mockRestore(); + vi.unstubAllGlobals(); }); test("correlates the existing Brunch transport request", () => { @@ -96,6 +328,49 @@ describe("local storage demo Brunch voice integration", () => { /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u, ); }); + + test.each([ + [true, "stop-requested"], + [false, "already-settled"], + ] as const)( + "maps Flue abort result %s onto the host Stop contract", + async (aborted, expected) => { + const abort = vi.fn(async () => ({ aborted })); + const client = { abort } as Pick as FlueClient; + + await expect( + requestFlueStop( + Promise.resolve(client), + new BrunchPanelConversationTracker(), + ), + ).resolves.toBe(expected); + expect(abort).toHaveBeenCalledOnce(); + }, + ); + + test("lets an in-flight admission land before requesting the durable abort", async () => { + const abort = vi.fn(async () => ({ aborted: true })); + const client = { abort } as Pick as FlueClient; + const tracker = new BrunchPanelConversationTracker(); + const stopListener = vi.fn(); + tracker.subscribeToStopRequested(stopListener); + let admit: (() => void) | undefined; + void tracker.trackSubmission( + new Promise((resolve) => { + admit = resolve; + }), + ); + + const stop = requestFlueStop(Promise.resolve(client), tracker); + expect(stopListener).toHaveBeenCalledOnce(); + await Promise.resolve(); + await Promise.resolve(); + expect(abort).not.toHaveBeenCalled(); + + admit?.(); + await expect(stop).resolves.toBe("stop-requested"); + expect(abort).toHaveBeenCalledOnce(); + }); }); /** @@ -284,3 +559,37 @@ describe("local storage demo URL navigation", () => { expect(mountedNavigation().state.selection).toEqual([]); }); }); + +describe("local storage demo prepared fixture", () => { + afterEach(() => { + cleanup(); + editorProps.current = null; + brunchPreviewConfig.isBrunchConfigured = true; + }); + + test("neither advertises nor opens the fixture while Brunch is unconfigured", () => { + brunchPreviewConfig.isBrunchConfigured = false; + // With Brunch disabled there is no Flue client to prepare the fixture conversation. Opening the fixture URL + // anyway once left the banner on "preparing" forever with every send + // unavailable; the URL now falls back to the ordinary per-net demo. + seedStoredNet(); + + render( + {}} + search={{ "brunch-fixture": crewReservationFixtureId }} + />, + ); + + expect( + document.querySelector('[aria-label="Prepared fixture selector"]'), + ).toBeNull(); + expect( + document.querySelector('[aria-label="Prepared fixture status"]'), + ).toBeNull(); + const aiAssistant = editorProps.current?.aiAssistant as + | { conversationId?: string } + | undefined; + expect(aiAssistant?.conversationId).not.toBe(crewReservationConversationId); + }); +}); diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/local-storage-demo-app.tsx b/apps/petrinaut-website/src/main/app/local-storage-demo/local-storage-demo-app.tsx index 28f385e4ef1..6f030d99c9e 100644 --- a/apps/petrinaut-website/src/main/app/local-storage-demo/local-storage-demo-app.tsx +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/local-storage-demo-app.tsx @@ -3,10 +3,15 @@ * @role Editable demo shell: nets in local storage, one live document handle */ +import { createFlueClient, type FlueConversationSettlement } from "@flue/sdk"; import { castDraft, produce } from "immer"; -import { useEffect, useMemo, useState } from "react"; +import { useCallback, useEffect, useMemo, useState } from "react"; +import { createPortal } from "react-dom"; -import { BRUNCH_PRINCIPAL_HEADER } from "@hashintel/brunch-agent-transport-aisdk/headers"; +import { + agentOwnershipHeaders, + flueConversationIdWeb, +} from "@hashintel/brunch-agent-transport-aisdk"; import { createJsonDocHandle, type MinimalNetMetadata, @@ -22,6 +27,7 @@ import { DefaultChatTransport, Petrinaut, type PetrinautAiMessage, + type PetrinautAiStopResult, type PetrinautAiVoiceMode, type PetrinautAiVoiceModeContext, WalkthroughProvider, @@ -39,11 +45,30 @@ import { type OpenAIVoiceConfig, VoiceInterviewControl, } from "../voice-interview/voice-interview-control"; -import { brunchAskInteractiveTool } from "./brunch-ask-interactive-tool"; import { getOrCreateBrunchConversationId } from "./brunch-conversation-id"; -import { createBrunchPanelTransport } from "./brunch-panel-transport"; +import { + BrunchPanelConversationTracker, + type BrunchPanelAdmissionTarget, + createBrunchPanelTransport, + createUnavailableBrunchPanelTransport, +} from "./brunch-panel-transport"; import { resolveBrunchPreviewConfig } from "./brunch-preview-config"; import { getOrCreateBrunchPrincipal } from "./brunch-principal"; +import { isCrewReservationFixtureSelected } from "./local-storage-demo-search"; +import { + crewReservationDocumentId, + preparedCrewReservationNet, +} from "./prepared-crew-reservation-fixture"; +import { + PreparedFixtureBanner, + PreparedFixtureSelector, +} from "./prepared-fixture-banner"; +import { resolveCrewReservationBundle } from "./resolve-crew-reservation-bundle"; +import { + crewReservationFixtureConfiguration, + useCrewReservationFixtureSession, +} from "./use-crew-reservation-fixture-session"; +import { useCrewReservationSettledManifestStorage } from "./use-crew-reservation-settled-manifest"; import { useFlueChatHistory } from "./use-flue-chat-history"; import { useLocalStorageAiMessages } from "./use-local-storage-ai-messages"; import { @@ -56,6 +81,7 @@ import { import { walkthroughSteps } from "./walkthrough/walkthrough-steps"; import type { SharedExampleSearch } from "../../../examples/example-search"; +import type { LocalStorageDemoSearch } from "./local-storage-demo-search"; const createDefaultStoredSDCPN = (): SDCPNInLocalStorage => ({ id: "net-1", @@ -64,6 +90,13 @@ const createDefaultStoredSDCPN = (): SDCPNInLocalStorage => ({ lastUpdated: new Date(0).toISOString(), }); +const preparedCrewReservationStoredSDCPN: SDCPNInLocalStorage = { + id: crewReservationDocumentId, + title: "Prepared final inspection and dispatch", + sdcpn: preparedCrewReservationNet, + lastUpdated: new Date(0).toISOString(), +}; + const DEMO_CAPABILITIES = { disabledExtensions: [], } satisfies PetrinautHandleCapabilities; @@ -72,20 +105,47 @@ const brunchPreviewConfig = resolveBrunchPreviewConfig( import.meta.env.VITE_BRUNCH_CHAT_ENDPOINT, ); -// Only Brunch keeps a conversation to hydrate from; the generic fallback route -// has no history door. -const brunchHistoryEndpoint = brunchPreviewConfig.isBrunchConfigured - ? brunchPreviewConfig.chatEndpoint - : null; - export const getBrunchVoiceMode = ( config: OpenAIVoiceConfig | null | undefined, -): PetrinautAiVoiceMode | undefined => - config - ? (context: PetrinautAiVoiceModeContext) => ( - - ) - : undefined; + tracker?: BrunchPanelConversationTracker, + settlements?: readonly FlueConversationSettlement[], +): PetrinautAiVoiceMode | undefined => { + if (!config) return undefined; + + const resolveInputSubmission = tracker?.submissionForInput.bind(tracker); + const resolveResponseSubmission = + tracker?.submissionsForResponse.bind(tracker); + const subscribeToResponseMessageCompleted = + tracker?.subscribeToResponseMessageCompleted.bind(tracker); + const subscribeToResponseMessageStarted = + tracker?.subscribeToResponseMessageStarted.bind(tracker); + const subscribeToStopRequested = + tracker?.subscribeToStopRequested.bind(tracker); + const subscribeToAdmission = + tracker === undefined + ? undefined + : (target: BrunchPanelAdmissionTarget, listener: (id: string) => void) => + tracker.subscribeToAdmission(target, ({ admission }) => + listener(admission.submissionId), + ); + const subscribeToAdmissionFailure = + tracker?.subscribeToAdmissionFailure.bind(tracker); + + return (context: PetrinautAiVoiceModeContext) => ( + + ); +}; const createHandle = (net: SDCPNInLocalStorage): PetrinautDocHandle => createJsonDocHandle({ @@ -99,14 +159,55 @@ const brunchPrincipal = getOrCreateBrunchPrincipal(); const stockChatTransport = new DefaultChatTransport({ api: brunchPreviewConfig.chatEndpoint, headers: () => ({ - [BRUNCH_PRINCIPAL_HEADER]: brunchPrincipal, [VOICE_REQUEST_ID_HEADER]: crypto.randomUUID(), }), }); +const createBrunchFlueClient = async (conversationId: string) => { + const identity = { conversationId, principalKey: brunchPrincipal }; + const instanceId = await flueConversationIdWeb(identity); + const mountUrl = new URL( + brunchPreviewConfig.chatEndpoint, + window.location.origin, + ); + mountUrl.pathname = `${mountUrl.pathname.replace(/\/+$/u, "")}/${instanceId}`; + return createFlueClient({ + url: mountUrl.href, + headers: agentOwnershipHeaders(identity), + }); +}; + +/** + * Flue's `abort()` is conversation-wide and only reaches unsettled work, so a + * Stop pressed while `send()` is still in flight must first let that admission + * land; otherwise `aborted: false` would read as "already settled" while the + * admitted turn keeps running. + */ +export const requestFlueStop = async ( + clientPromise: Promise>, + tracker: BrunchPanelConversationTracker, +): Promise => { + tracker.recordStopRequested(); + const client = await clientPromise; + await tracker.settleInFlightSubmissions(); + const result = await client.abort(); + return result.aborted ? "stop-requested" : "already-settled"; +}; + +const createConversationTrackerFor = ( + _conversationId: string | null, +): BrunchPanelConversationTracker => new BrunchPanelConversationTracker(); + const getStoredSDCPNsForDisplay = ( storedSDCPNs: Record, + crewReservationDocument: SDCPNInLocalStorage | undefined, ): Record => { + if (crewReservationDocument !== undefined) { + return { + ...storedSDCPNs, + [crewReservationDocument.id]: crewReservationDocument, + }; + } if (Object.values(storedSDCPNs).length > 0) { return storedSDCPNs; } @@ -163,11 +264,12 @@ export const LocalStorageDemoApp = ({ search: SharedExampleSearch, history: "push" | "replace", ) => void; - search: SharedExampleSearch; + search: LocalStorageDemoSearch; }) => { const sentryFeedbackAction = useSentryFeedbackAction(); - const [openAIVoiceConfig, setOpenAIVoiceConfig] = - useState(); + const [openAIVoiceConfig, setOpenAIVoiceConfig] = useState< + OpenAIVoiceConfig | null | undefined + >(() => (brunchPreviewConfig.isBrunchConfigured ? undefined : null)); /** * History is left to the library's default on purpose. That default already * replaces rather than pushes while an intent continues, so a drag-select @@ -197,12 +299,65 @@ export const LocalStorageDemoApp = ({ const { aiMessagesByNetId, setAiMessagesByNetId } = useLocalStorageAiMessages(); const { storedSDCPNs, setStoredSDCPNs } = useLocalStorageSDCPNs(); - const storedSDCPNsForDisplay = getStoredSDCPNsForDisplay(storedSDCPNs); + const { settledManifest, setSettledManifest } = + useCrewReservationSettledManifestStorage(); + /** + * The fixture is only reachable when Brunch is configured: without an + * endpoint there is no Flue client to prepare the conversation, so the URL + * falls back to the ordinary demo rather than a banner stuck on preparing. + */ + const crewReservationFixtureSelected = + brunchPreviewConfig.isBrunchConfigured && + isCrewReservationFixtureSelected(search); + const crewReservationBundle = crewReservationFixtureSelected + ? resolveCrewReservationBundle({ + fallbackDocument: preparedCrewReservationStoredSDCPN, + manifest: settledManifest, + storedDocument: storedSDCPNs[crewReservationDocumentId], + }) + : undefined; + const storedSDCPNsForDisplay = getStoredSDCPNsForDisplay( + storedSDCPNs, + crewReservationBundle?.selectedDocument, + ); + + useEffect(() => { + if ( + !crewReservationFixtureSelected || + storedSDCPNs[crewReservationDocumentId] !== undefined + ) { + return; + } + setStoredSDCPNs((previous) => ({ + ...previous, + [crewReservationDocumentId]: preparedCrewReservationStoredSDCPN, + })); + }, [crewReservationFixtureSelected, setStoredSDCPNs, storedSDCPNs]); + + const persistCrewReservationSnapshot = useCallback( + (sha256: string, definition: SDCPN) => { + setStoredSDCPNs((previous) => { + const document = + previous[crewReservationDocumentId] ?? + preparedCrewReservationStoredSDCPN; + + return { + ...previous, + [crewReservationDocumentId]: { + ...document, + coherentSnapshots: { + ...document.coherentSnapshots, + [sha256]: structuredClone(definition), + }, + }, + }; + }); + }, + [setStoredSDCPNs], + ); useEffect(() => { if (!brunchPreviewConfig.isBrunchConfigured) { - // eslint-disable-next-line react-hooks-js/set-state-in-effect -- Resolve the loading sentinel when voice is not configured. - setOpenAIVoiceConfig(null); return; } @@ -219,21 +374,19 @@ export const LocalStorageDemoApp = ({ return () => abortController.abort(); }, []); - const brunchVoiceMode = useMemo( - () => getBrunchVoiceMode(openAIVoiceConfig), - [openAIVoiceConfig], - ); - // Pick the most recently modified net const mostRecentlyModifiedNet = Object.values(storedSDCPNsForDisplay).sort( (a, b) => new Date(b.lastUpdated).getTime() - new Date(a.lastUpdated).getTime(), )[0] ?? null; + const initiallySelectedNet = crewReservationFixtureSelected + ? storedSDCPNsForDisplay[crewReservationDocumentId] + : mostRecentlyModifiedNet; // The net currently selected in the UI. const [currentNetId, setCurrentNetId] = useState( - () => mostRecentlyModifiedNet?.id ?? null, + () => initiallySelectedNet?.id ?? null, ); // Metadata and persisted SDCPN snapshot for the selected net. @@ -243,9 +396,7 @@ export const LocalStorageDemoApp = ({ // Live editable document handle for the selected net only. const [activeHandle, setActiveHandle] = useState(() => - mostRecentlyModifiedNet - ? createActiveHandle(mostRecentlyModifiedNet) - : null, + initiallySelectedNet ? createActiveHandle(initiallySelectedNet) : null, ); useEffect(() => { @@ -273,7 +424,9 @@ export const LocalStorageDemoApp = ({ }); }, [activeHandle, setStoredSDCPNs]); - const existingNets: MinimalNetMetadata[] = Object.values(storedSDCPNs) + const existingNets: MinimalNetMetadata[] = Object.values( + storedSDCPNsForDisplay, + ) .map((net) => ({ netId: net.id, title: net.title, @@ -368,34 +521,109 @@ export const LocalStorageDemoApp = ({ ); }; - const conversationId = currentNetId - ? getOrCreateBrunchConversationId(currentNetId) - : null; + const preparedFixtureIsCurrent = + crewReservationFixtureSelected && + currentNetId === crewReservationDocumentId; + const fixtureConfiguration = preparedFixtureIsCurrent + ? crewReservationFixtureConfiguration + : undefined; + const conversationId = + currentNetId === null + ? null + : (fixtureConfiguration?.conversationId ?? + getOrCreateBrunchConversationId(currentNetId)); + const flueClientPromise = useMemo( + () => + brunchPreviewConfig.isBrunchConfigured && conversationId !== null + ? createBrunchFlueClient(conversationId) + : null, + [conversationId], + ); + const conversationTracker = useMemo( + // Correlation state belongs to one conversation and must not cross a net switch. + () => createConversationTrackerFor(conversationId), + [conversationId], + ); const flueHistory = useFlueChatHistory( - brunchHistoryEndpoint, + flueClientPromise, conversationId ?? "", - brunchPrincipal, + fixtureConfiguration?.clientToolNames, + fixtureConfiguration?.mapClientToolInput, ); - const petrinautAiChatTransport = useMemo( + const brunchVoiceMode = useMemo( () => - conversationId === null - ? createBrunchPanelTransport(stockChatTransport, "") - : createBrunchPanelTransport(stockChatTransport, conversationId), - [conversationId], + getBrunchVoiceMode( + openAIVoiceConfig, + conversationTracker, + flueHistory.settlements, + ), + [conversationTracker, flueHistory.settlements, openAIVoiceConfig], ); + const crewReservationSession = useCrewReservationFixtureSession({ + clientPromise: flueClientPromise, + definition: storedSDCPNs[crewReservationDocumentId]?.sdcpn, + enabled: fixtureConfiguration !== undefined, + history: flueHistory.snapshot, + historyError: flueHistory.error?.message, + persistCoherentSnapshot: persistCrewReservationSnapshot, + refreshHistory: flueHistory.refresh, + setSettledManifest, + settledManifest, + snapshotMissing: crewReservationBundle?.snapshotMissing ?? false, + }); + const transportClientPromise = + fixtureConfiguration === undefined + ? flueClientPromise + : crewReservationSession.transportClientPromise; + const petrinautAiChatTransport = useMemo(() => { + if (transportClientPromise !== null) { + return createBrunchPanelTransport( + transportClientPromise, + conversationTracker, + { + ...(fixtureConfiguration === undefined + ? {} + : { + clientToolNames: fixtureConfiguration.clientToolNames, + mapClientToolInput: fixtureConfiguration.mapClientToolInput, + }), + onAdmission: flueHistory.refresh, + }, + ); + } + return fixtureConfiguration !== undefined + ? createUnavailableBrunchPanelTransport( + crewReservationSession.transportUnavailableReason, + ) + : stockChatTransport; + }, [ + conversationTracker, + crewReservationSession.transportUnavailableReason, + fixtureConfiguration, + flueHistory.refresh, + transportClientPromise, + ]); const aiAssistant = useMemo( () => ({ ...(conversationId === null ? {} : { conversationId }), - interactiveTools: [brunchAskInteractiveTool], + canClearMessages: flueClientPromise === null, + interactiveTools: [], transport: petrinautAiChatTransport, - messages: flueHistory.ready - ? flueHistory.messages - : currentNetId - ? aiMessagesByNetId[currentNetId] - : undefined, + ...(flueClientPromise === null + ? {} + : { + requestStop: () => + requestFlueStop(flueClientPromise, conversationTracker), + }), + messages: + flueClientPromise === null + ? currentNetId + ? aiMessagesByNetId[currentNetId] + : undefined + : flueHistory.messages, onMessages: (messages: PetrinautAiMessage[]) => { - if (!currentNetId) { + if (!currentNetId || flueClientPromise !== null) { return; } @@ -405,7 +633,7 @@ export const LocalStorageDemoApp = ({ })); }, onClearMessages: () => { - if (!currentNetId) { + if (!currentNetId || flueClientPromise !== null) { return; } @@ -424,10 +652,11 @@ export const LocalStorageDemoApp = ({ [ aiMessagesByNetId, brunchVoiceMode, + conversationTracker, conversationId, currentNetId, + flueClientPromise, flueHistory.messages, - flueHistory.ready, petrinautAiChatTransport, setAiMessagesByNetId, ], @@ -442,7 +671,25 @@ export const LocalStorageDemoApp = ({ } return ( -
+
+ {preparedFixtureIsCurrent && + createPortal( + , + document.body, + )} + {brunchPreviewConfig.isBrunchConfigured && !preparedFixtureIsCurrent && ( + + )} { + test("owns the fixture key beside the shared contract", () => { + expect( + validateLocalStorageDemoSearch({ + "brunch-fixture": crewReservationFixtureId, + itemType: "place", + itemId: "place-1", + }), + ).toEqual({ + "brunch-fixture": crewReservationFixtureId, + itemType: "place", + itemId: "place-1", + }); + expect(validateLocalStorageDemoSearch({ "brunch-fixture": 7 })).toEqual({}); + }); + + test("carries the fixture key across a shared-contract write", () => { + expect( + withBrunchFixtureKey( + { "brunch-fixture": crewReservationFixtureId, subnet: "subnet-1" }, + { itemType: "place", itemId: "place-1" }, + ), + ).toEqual({ + "brunch-fixture": crewReservationFixtureId, + itemType: "place", + itemId: "place-1", + }); + }); + + test("changes route identity only when fixture mode changes", () => { + expect(localStorageDemoRouteIdentity({})).toBe("ordinary"); + expect(localStorageDemoRouteIdentity({ subnet: "subnet-1" })).toBe( + "ordinary", + ); + expect( + localStorageDemoRouteIdentity({ + "brunch-fixture": crewReservationFixtureId, + }), + ).toBe(crewReservationFixtureId); + }); + + test("selects only the explicit stable fixture value", () => { + expect( + isCrewReservationFixtureSelected({ + "brunch-fixture": crewReservationFixtureId, + }), + ).toBe(true); + expect( + isCrewReservationFixtureSelected({ "brunch-fixture": "another-fixture" }), + ).toBe(false); + expect(isCrewReservationFixtureSelected({})).toBe(false); + }); +}); diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/local-storage-demo-search.ts b/apps/petrinaut-website/src/main/app/local-storage-demo/local-storage-demo-search.ts new file mode 100644 index 00000000000..59b2a584190 --- /dev/null +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/local-storage-demo-search.ts @@ -0,0 +1,61 @@ +import { z } from "zod"; + +import { + validateSharedExampleSearch, + type SharedExampleSearch, +} from "../../../examples/example-search"; +import { + crewReservationFixtureId, + crewReservationFixtureQuery, +} from "./prepared-crew-reservation-fixture"; + +/** + * Accepting only strings keeps the router's JSON-decoding search parser from + * coercing a fixture id into some other value; anything else drops out. + */ +const optionalSearchStringSchema = z.string().optional().catch(undefined); + +const fixtureSearchSchema = z.object({ + [crewReservationFixtureQuery]: optionalSearchStringSchema, +}); + +export type LocalStorageDemoSearch = z.infer & + SharedExampleSearch; + +/** + * The local demo URL names the prepared fixture it opened and speaks the + * shared example contract for the location inside the net. + */ +export const validateLocalStorageDemoSearch = ( + input: Record, +): LocalStorageDemoSearch => ({ + ...fixtureSearchSchema.parse(input), + ...validateSharedExampleSearch(input), +}); + +/** + * Replaces the contract part of the demo search and carries the fixture key + * over. Every other route writes a contract-only search; here the fixture key + * names the prepared conversation, and dropping it on the first selection + * would silently swap the fixture's tools and conversation for the ordinary + * per-net conversation mid-session. + */ +export const withBrunchFixtureKey = ( + current: LocalStorageDemoSearch, + next: SharedExampleSearch, +): LocalStorageDemoSearch => ({ + [crewReservationFixtureQuery]: current[crewReservationFixtureQuery], + ...next, +}); + +export const isCrewReservationFixtureSelected = ( + search: LocalStorageDemoSearch, +): boolean => search[crewReservationFixtureQuery] === crewReservationFixtureId; + +/** Identity of the stateful editor selected by the route's fixture mode. */ +export const localStorageDemoRouteIdentity = ( + search: LocalStorageDemoSearch, +): "ordinary" | typeof crewReservationFixtureId => + isCrewReservationFixtureSelected(search) + ? crewReservationFixtureId + : "ordinary"; diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/prepare-crew-reservation-conversation.test.ts b/apps/petrinaut-website/src/main/app/local-storage-demo/prepare-crew-reservation-conversation.test.ts new file mode 100644 index 00000000000..23a69be894d --- /dev/null +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/prepare-crew-reservation-conversation.test.ts @@ -0,0 +1,87 @@ +import { describe, expect, test, vi } from "vitest"; + +import { + preparedWorkpieceInitialDataMode, + preparedWorkpieceSignalTag, +} from "@hashintel/brunch-agent/workpiece"; + +import { prepareCrewReservationConversation } from "./prepare-crew-reservation-conversation"; +import { + crewReservationFixtureId, + preparedCrewReservationDelivery, + preparedCrewReservationWorkpiece, +} from "./prepared-crew-reservation-fixture"; + +const preparedHistory = { + conversationId: "canonical-conversation", + offset: "2", + settlements: [{ submissionId: "prepare-submission", outcome: "completed" }], + messages: [ + { + id: "prepared-message", + role: "system", + purpose: "dispatch", + submissionId: "prepare-submission", + signal: { + tagName: preparedWorkpieceSignalTag, + attributes: { + fixtureId: crewReservationFixtureId, + authorship: "test-authored", + claimBoundary: "prepared-not-model-produced", + }, + }, + parts: [{ type: "text", text: preparedCrewReservationWorkpiece }], + }, + ], +}; + +describe("prepareCrewReservationConversation", () => { + test("recovers an existing prepared conversation without resubmitting", async () => { + const send = vi.fn(); + const wait = vi.fn(); + + await expect( + prepareCrewReservationConversation({ + history: vi.fn().mockResolvedValue(preparedHistory), + send, + wait, + }), + ).resolves.toEqual(preparedHistory); + expect(send).not.toHaveBeenCalled(); + expect(wait).not.toHaveBeenCalled(); + }); + + test("creates revision zero once through the tagged signal delivery", async () => { + const history = vi + .fn() + .mockRejectedValueOnce({ status: 404 }) + .mockResolvedValueOnce(preparedHistory); + const admission = { submissionId: "prepare-submission" }; + const send = vi.fn().mockResolvedValue(admission); + const wait = vi.fn().mockResolvedValue(undefined); + + await expect( + prepareCrewReservationConversation({ history, send, wait }), + ).resolves.toEqual(preparedHistory); + expect(send).toHaveBeenCalledWith({ + uid: null, + initialData: { mode: preparedWorkpieceInitialDataMode }, + ...preparedCrewReservationDelivery, + }); + expect(wait).toHaveBeenCalledWith(admission); + expect(history).toHaveBeenCalledTimes(2); + }); + + test("refuses an existing conversation without this fixture source", async () => { + await expect( + prepareCrewReservationConversation({ + history: vi.fn().mockResolvedValue({ + ...preparedHistory, + messages: [], + }), + send: vi.fn(), + wait: vi.fn(), + }), + ).rejects.toThrow(/no recoverable workpiece/u); + }); +}); diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/prepare-crew-reservation-conversation.ts b/apps/petrinaut-website/src/main/app/local-storage-demo/prepare-crew-reservation-conversation.ts new file mode 100644 index 00000000000..7c8625c06b7 --- /dev/null +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/prepare-crew-reservation-conversation.ts @@ -0,0 +1,81 @@ +import { + preparedWorkpieceInitialDataMode, + selectRunbookWorkpiece, +} from "@hashintel/brunch-agent/workpiece"; + +import { + crewReservationFixtureId, + preparedCrewReservationDelivery, +} from "./prepared-crew-reservation-fixture"; + +import type { CrewReservationHistory } from "./crew-reservation-history"; +import type { AgentSendResult } from "@flue/sdk"; + +export interface PreparedFixtureConversationClient { + readonly history: () => Promise; + readonly send: (input: { + readonly idempotencyKey: string; + readonly initialData: { + readonly mode: typeof preparedWorkpieceInitialDataMode; + }; + readonly message: typeof preparedCrewReservationDelivery.message; + readonly uid: null; + }) => Promise; + readonly wait: (admission: AgentSendResult) => Promise; +} + +const isNotFound = (error: unknown): boolean => + typeof error === "object" && + error !== null && + "status" in error && + error.status === 404; + +const assertPreparedFixtureHistory = ( + history: CrewReservationHistory, +): CrewReservationHistory => { + const currentWorkpiece = selectRunbookWorkpiece(history); + if ( + currentWorkpiece?.sourceKind !== "prepared-signal" && + currentWorkpiece?.sourceKind !== "assistant" + ) { + throw new Error( + "The prepared fixture conversation has no recoverable workpiece.", + ); + } + const preparedSource = history.messages.find( + (message) => + message.signal?.tagName === + preparedCrewReservationDelivery.message.tagName, + ); + if ( + preparedSource?.signal?.attributes?.fixtureId !== crewReservationFixtureId + ) { + throw new Error( + "The prepared fixture conversation belongs to a different fixture.", + ); + } + return history; +}; + +/** + * Create revision zero through Flue's public signal delivery, or recover the + * already-created append-only conversation. Concurrent tabs converge through + * the delivery's deterministic idempotency key. + */ +export const prepareCrewReservationConversation = async ( + client: PreparedFixtureConversationClient, +): Promise => { + try { + return assertPreparedFixtureHistory(await client.history()); + } catch (error) { + if (!isNotFound(error)) throw error; + } + + const admission = await client.send({ + uid: null, + initialData: { mode: preparedWorkpieceInitialDataMode }, + ...preparedCrewReservationDelivery, + }); + await client.wait(admission); + return assertPreparedFixtureHistory(await client.history()); +}; diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/prepared-crew-reservation-fixture.test.ts b/apps/petrinaut-website/src/main/app/local-storage-demo/prepared-crew-reservation-fixture.test.ts new file mode 100644 index 00000000000..a5ac7378027 --- /dev/null +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/prepared-crew-reservation-fixture.test.ts @@ -0,0 +1,87 @@ +import { describe, expect, test } from "vitest"; + +import { readPetrinautDocToolName } from "@hashintel/petrinaut-core"; + +import { + crewReservationFixtureClientToolNames, + crewReservationFixtureId, + dispatchCrewPlaceId, + preparedCrewReservationDelivery, + preparedCrewReservationNet, + preparedCrewReservationWorkpiece, + startFinalInspectionTransitionId, +} from "./prepared-crew-reservation-fixture"; +import { crewReservationFixtureConfiguration } from "./use-crew-reservation-fixture-session"; + +const transitionById = (transitionId: string) => { + const transition = preparedCrewReservationNet.transitions.find( + (candidate) => candidate.id === transitionId, + ); + if (transition === undefined) { + throw new Error(`Missing prepared transition ${transitionId}`); + } + return transition; +}; + +describe("prepared crew-reservation fixture", () => { + test("advertises only the selected canonical read and mutation", () => { + expect(crewReservationFixtureClientToolNames).toEqual([ + "getLatestNetDefinition", + "addArc", + ]); + }); + + test("keeps the always-mounted browser tools answerable in fixture mode", () => { + for (const toolName of [ + readPetrinautDocToolName, + ...crewReservationFixtureClientToolNames, + ]) { + expect( + crewReservationFixtureConfiguration.clientToolNames.has(toolName), + ).toBe(true); + } + }); + + test("has the batch flow and crew return but omits the target input arc", () => { + const startInspection = transitionById(startFinalInspectionTransitionId); + const signOff = transitionById("sign-off"); + + expect(startInspection.inputArcs).toContainEqual({ + placeId: "batch-ready", + type: "standard", + weight: 1, + }); + expect(startInspection.inputArcs).not.toContainEqual( + expect.objectContaining({ placeId: dispatchCrewPlaceId }), + ); + expect(signOff.outputArcs).toEqual( + expect.arrayContaining([ + { placeId: "ready-for-dispatch", weight: 1 }, + { placeId: dispatchCrewPlaceId, weight: 1 }, + ]), + ); + }); + + test("carries the quantity, unknowns, and honest claim boundary", () => { + expect(preparedCrewReservationWorkpiece).toContain( + "Exactly one dispatch crew", + ); + expect(preparedCrewReservationWorkpiece).toContain( + "requires explicit true-user confirmation", + ); + expect(preparedCrewReservationWorkpiece).not.toContain( + "- Final inspection reserves the sole available dispatch crew.", + ); + expect(preparedCrewReservationWorkpiece).toContain( + "timing, failure modes, and recovery behavior remain unresolved", + ); + expect(preparedCrewReservationWorkpiece).toContain( + "not model-produced evidence", + ); + expect(preparedCrewReservationDelivery.message.attributes).toEqual({ + fixtureId: crewReservationFixtureId, + authorship: "test-authored", + claimBoundary: "prepared-not-model-produced", + }); + }); +}); diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/prepared-crew-reservation-fixture.ts b/apps/petrinaut-website/src/main/app/local-storage-demo/prepared-crew-reservation-fixture.ts new file mode 100644 index 00000000000..50b5182536f --- /dev/null +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/prepared-crew-reservation-fixture.ts @@ -0,0 +1,150 @@ +import { createPreparedWorkpieceDelivery } from "@hashintel/brunch-agent/workpiece"; +import { + getLatestNetDefinitionToolName, + type PetrinautAiToolName, +} from "@hashintel/petrinaut-core/ai"; + +import type { SDCPN } from "@hashintel/petrinaut-core"; + +export const crewReservationFixtureId = "crew-reservation-v1"; +export const crewReservationDocumentId = + "mission-6-crew-reservation-document-v1"; +export const crewReservationConversationId = + "mission-6-crew-reservation-conversation-v1"; +export const crewReservationFixtureQuery = "brunch-fixture"; +export const crewReservationFixtureClientToolNames = [ + getLatestNetDefinitionToolName, + "addArc", +] as const satisfies readonly PetrinautAiToolName[]; + +export const dispatchCrewPlaceId = "dispatch-crew-available"; +export const startFinalInspectionTransitionId = "start-final-inspection"; + +export const preparedCrewReservationWorkpiece = [ + "Fixture authorship: test-authored preparation for Mission 6.", + "Non-claims: not a Mission 4 candidate, not model-produced evidence, not capture-backed provenance, and not proof of automatic full-net projection.", + "", + "```runbook-ir", + "# Final inspection and dispatch workpiece", + "", + "## Purpose and posture", + "Maintain the narrow batch path from final inspection to dispatch readiness and test one evidence-backed decision against the live Petrinaut document.", + "", + "## Operational account", + "- A batch that is ready enters final inspection.", + "- The prepared topology returns the sole dispatch crew at sign-off.", + "- Whether final inspection reserves that crew is an unconfirmed hypothesis; changing the workpiece or net requires explicit true-user confirmation.", + "", + "## Quantity and resource policy", + "Exactly one dispatch crew is available in this fixture. Revision zero does not establish whether starting final inspection consumes it; the prepared topology currently returns it at sign-off.", + "", + "## Current Petrinaut correspondence", + "The prepared non-empty net contains the batch path and the crew return from sign-off. The standard weight-1 input arc from `Dispatch crew available` to `Start final inspection` is absent while the reservation policy remains unconfirmed.", + "", + "## Explicit unknowns", + "Crew reservation awaits true-user confirmation. Inspection and sign-off timing, failure modes, and recovery behavior remain unresolved.", + "", + "## Claim boundary", + "This prepared revision is test-authored diagnostic material. It is not model-produced evidence and does not establish capture provenance, behavioral execution, or broad projection quality.", + "```", +].join("\n"); + +export const preparedCrewReservationDelivery = createPreparedWorkpieceDelivery({ + body: preparedCrewReservationWorkpiece, + fixtureId: crewReservationFixtureId, + revision: 0, +}); + +export const preparedCrewReservationNet: SDCPN = { + places: [ + { + id: "batch-ready", + name: "Batch ready", + colorId: null, + dynamicsEnabled: false, + differentialEquationId: null, + x: 80, + y: 100, + }, + { + id: "under-final-inspection", + name: "Under final inspection", + colorId: null, + dynamicsEnabled: false, + differentialEquationId: null, + x: 420, + y: 100, + }, + { + id: "ready-for-dispatch", + name: "Ready for dispatch", + colorId: null, + dynamicsEnabled: false, + differentialEquationId: null, + x: 760, + y: 100, + }, + { + id: dispatchCrewPlaceId, + name: "Dispatch crew available", + colorId: null, + dynamicsEnabled: false, + differentialEquationId: null, + x: 420, + y: 360, + }, + ], + transitions: [ + { + id: startFinalInspectionTransitionId, + name: "Start final inspection", + inputArcs: [ + { + placeId: "batch-ready", + type: "standard", + weight: 1, + }, + ], + outputArcs: [ + { + placeId: "under-final-inspection", + weight: 1, + }, + ], + lambdaType: "predicate", + lambdaCode: "", + transitionKernelCode: "", + x: 250, + y: 100, + }, + { + id: "sign-off", + name: "Sign-off", + inputArcs: [ + { + placeId: "under-final-inspection", + type: "standard", + weight: 1, + }, + ], + outputArcs: [ + { + placeId: "ready-for-dispatch", + weight: 1, + }, + { + placeId: dispatchCrewPlaceId, + weight: 1, + }, + ], + lambdaType: "predicate", + lambdaCode: "", + transitionKernelCode: "", + x: 590, + y: 100, + }, + ], + types: [], + parameters: [], + differentialEquations: [], +}; diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/prepared-fixture-banner.test.tsx b/apps/petrinaut-website/src/main/app/local-storage-demo/prepared-fixture-banner.test.tsx new file mode 100644 index 00000000000..f5991f4062b --- /dev/null +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/prepared-fixture-banner.test.tsx @@ -0,0 +1,104 @@ +import { renderToStaticMarkup } from "react-dom/server"; +import { describe, expect, test } from "vitest"; + +import { + asCanonicalConversationId, + asConversationOffset, + asFlueMessageId, + asFlueSubmissionId, + asManifestId, + asSha256Digest, + type CrewReservationSettledManifest, +} from "./crew-reservation-settled-manifest"; +import { + crewReservationConversationId, + crewReservationDocumentId, + crewReservationFixtureId, +} from "./prepared-crew-reservation-fixture"; +import { + PreparedFixtureBanner, + PreparedFixtureSelector, +} from "./prepared-fixture-banner"; + +const settledManifest = { + version: 1 as const, + fixtureId: crewReservationFixtureId, + revision: 3, + settledAt: "2026-09-03T15:00:00.000Z", + manifestId: asManifestId("manifest-3"), + conversation: { + logicalId: crewReservationConversationId, + canonicalId: asCanonicalConversationId("canonical-conversation"), + offset: asConversationOffset("20"), + }, + latestWorkpiece: { + authorship: "model-produced" as const, + contentSha256: asSha256Digest("content-hash"), + sourceKind: "assistant" as const, + sourceMessageId: asFlueMessageId("assistant-3"), + sourceMessageSha256: asSha256Digest("message-hash"), + sourceSubmissionId: asFlueSubmissionId("submission-3"), + }, + document: { + id: crewReservationDocumentId, + sha256: asSha256Digest("document-hash"), + targetArc: "present" as const, + }, +} satisfies CrewReservationSettledManifest; + +describe("PreparedFixtureBanner", () => { + test("offers a stable labelled fixture selector", () => { + const markup = renderToStaticMarkup(); + + expect(markup).toContain("Prepared fixture selector"); + expect(markup).toContain("Open the labelled crew-reservation fixture"); + expect(markup).toContain("?brunch-fixture=crew-reservation-v1"); + }); + + test("visibly states authorship, non-claims, and automatic settlement", () => { + const markup = renderToStaticMarkup( + , + ); + + expect(markup).toContain("Test-authored prepared fixture"); + expect(markup).toContain("not model-produced evidence"); + expect(markup).toContain("does not claim capture provenance"); + expect(markup).toContain("automatically mirrored document"); + expect(markup).toContain("Current Markdown workpiece"); + expect(markup).toContain("Final inspection and dispatch workpiece"); + }); + + test("visibly retains the prior bundle when settlement is refused", () => { + const markup = renderToStaticMarkup( + , + ); + + expect(markup).toContain( + "Settlement refused (missing-correlated-mutation)", + ); + expect(markup).toContain("bundle revision 3 remains selected"); + }); + + test("shows a selected revision as revalidating during a history gap", () => { + const markup = renderToStaticMarkup( + , + ); + + expect(markup).toContain( + "Bundle revision 3 remains selected while canonical history reconnects", + ); + expect(markup).toContain( + "The selected bundle’s Markdown workpiece is unavailable", + ); + expect(markup).not.toContain("Preparing the conversation"); + }); +}); diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/prepared-fixture-banner.tsx b/apps/petrinaut-website/src/main/app/local-storage-demo/prepared-fixture-banner.tsx new file mode 100644 index 00000000000..05120ff16a3 --- /dev/null +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/prepared-fixture-banner.tsx @@ -0,0 +1,102 @@ +import { latestRunbookIrBlock } from "@hashintel/brunch-agent/workpiece"; + +import { + crewReservationFixtureId, + crewReservationFixtureQuery, + preparedCrewReservationWorkpiece, +} from "./prepared-crew-reservation-fixture"; + +import type { CrewReservationSettledManifest } from "./crew-reservation-settled-manifest"; +import type { CrewReservationSettlementStatus } from "./use-crew-reservation-settled-manifest"; + +const fixturePanelStyle = { + background: "rgba(255, 255, 255, 0.96)", + border: "1px solid #c9d2df", + borderRadius: 8, + boxShadow: "0 2px 8px rgba(20, 33, 50, 0.12)", + left: 16, + maxWidth: 520, + padding: "10px 12px", + position: "absolute", + top: 16, + zIndex: 20, +} as const; + +const fixtureBannerStyle = { + ...fixturePanelStyle, + left: "50%", + position: "fixed", + top: 80, + transform: "translateX(-50%)", + width: "calc(100vw - 32px)", +} as const; + +export const PreparedFixtureSelector = () => ( + +); + +export const PreparedFixtureBanner = ({ + currentWorkpiece, + settledManifest, + settlementStatus = { state: "preparing" }, +}: { + readonly currentWorkpiece?: string; + readonly settledManifest: CrewReservationSettledManifest | null; + readonly settlementStatus?: CrewReservationSettlementStatus; +}) => { + const displayedWorkpiece = + currentWorkpiece ?? + (settledManifest === null + ? latestRunbookIrBlock(preparedCrewReservationWorkpiece) + : undefined); + + return ( + + ); +}; diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/resolve-crew-reservation-bundle.test.ts b/apps/petrinaut-website/src/main/app/local-storage-demo/resolve-crew-reservation-bundle.test.ts new file mode 100644 index 00000000000..7da06ba9129 --- /dev/null +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/resolve-crew-reservation-bundle.test.ts @@ -0,0 +1,192 @@ +import { describe, expect, test } from "vitest"; + +import { + latestRunbookIrBlock, + preparedWorkpieceAuthorship, + preparedWorkpieceClaimBoundary, + preparedWorkpieceSignalTag, +} from "@hashintel/brunch-agent/workpiece"; + +import { + asCanonicalConversationId, + asConversationOffset, + asFlueMessageId, + asFlueSubmissionId, + asManifestId, + sha256Digest, + type CrewReservationSettledManifest, +} from "./crew-reservation-settled-manifest"; +import { + crewReservationConversationId, + crewReservationDocumentId, + crewReservationFixtureId, + preparedCrewReservationNet, + preparedCrewReservationWorkpiece, +} from "./prepared-crew-reservation-fixture"; +import { + resolveCrewReservationBundle, + workpieceForCrewReservationBundle, +} from "./resolve-crew-reservation-bundle"; + +import type { CrewReservationHistory } from "./crew-reservation-history"; +import type { SDCPNInLocalStorage } from "./use-local-storage-sdcpns"; + +const preparedMessage = { + id: "prepared-message", + role: "system", + purpose: "dispatch", + submissionId: "prepare-submission", + signal: { + tagName: preparedWorkpieceSignalTag, + attributes: { + fixtureId: crewReservationFixtureId, + authorship: preparedWorkpieceAuthorship, + claimBoundary: preparedWorkpieceClaimBoundary, + }, + }, + parts: [{ type: "text", text: preparedCrewReservationWorkpiece }], +} as const; + +const preparedContent = latestRunbookIrBlock(preparedCrewReservationWorkpiece); +if (preparedContent === undefined) { + throw new Error("The prepared fixture has no runbook-ir workpiece."); +} + +const manifest: CrewReservationSettledManifest = { + version: 1, + fixtureId: crewReservationFixtureId, + manifestId: asManifestId("manifest"), + revision: 0, + settledAt: "2026-09-04T08:00:00.000Z", + conversation: { + canonicalId: asCanonicalConversationId("canonical"), + logicalId: crewReservationConversationId, + offset: asConversationOffset("2"), + }, + document: { + id: crewReservationDocumentId, + sha256: sha256Digest(JSON.stringify(preparedCrewReservationNet)), + targetArc: "absent", + }, + latestWorkpiece: { + authorship: "test-authored", + contentSha256: sha256Digest(preparedContent), + sourceKind: "prepared-signal", + sourceMessageId: asFlueMessageId(preparedMessage.id), + sourceMessageSha256: sha256Digest(JSON.stringify(preparedMessage)), + sourceSubmissionId: asFlueSubmissionId(preparedMessage.submissionId), + }, +}; + +const fallbackDocument: SDCPNInLocalStorage = { + id: crewReservationDocumentId, + title: "Prepared", + sdcpn: preparedCrewReservationNet, + lastUpdated: "1970-01-01T00:00:00.000Z", +}; + +const history: CrewReservationHistory = { + conversationId: "canonical", + offset: "3", + settlements: [], + messages: [ + preparedMessage, + { + id: "newer-message", + role: "assistant", + purpose: "assistant", + parts: [ + { + type: "text", + text: "```runbook-ir\n# Unsettled newer workpiece\n```", + }, + ], + }, + ], +}; + +describe("resolveCrewReservationBundle", () => { + test("selects a coherent document whose content matches the manifest digest", () => { + const partialDefinition = structuredClone(preparedCrewReservationNet); + const firstPlace = partialDefinition.places.at(0); + if (firstPlace === undefined) { + throw new Error("The prepared fixture has no places."); + } + firstPlace.name = "Partial write"; + + const selection = resolveCrewReservationBundle({ + fallbackDocument, + manifest, + storedDocument: { + ...fallbackDocument, + sdcpn: partialDefinition, + coherentSnapshots: { + [manifest.document.sha256]: preparedCrewReservationNet, + }, + }, + }); + + expect(selection.snapshotMissing).toBe(false); + expect(selection.selectedDocument.sdcpn).toEqual( + preparedCrewReservationNet, + ); + expect(selection.selectedDocument.sdcpn).not.toEqual(partialDefinition); + }); + + test("refuses a snapshot stored under a digest that its content does not match", () => { + const corruptedSnapshot = structuredClone(preparedCrewReservationNet); + const firstPlace = corruptedSnapshot.places.at(0); + if (firstPlace === undefined) { + throw new Error("The prepared fixture has no places."); + } + firstPlace.name = "Corrupted snapshot"; + + const selection = resolveCrewReservationBundle({ + fallbackDocument, + manifest, + storedDocument: { + ...fallbackDocument, + coherentSnapshots: { + [manifest.document.sha256]: corruptedSnapshot, + }, + }, + }); + + expect(selection.snapshotMissing).toBe(true); + expect(selection.selectedDocument.sdcpn).toEqual(fallbackDocument.sdcpn); + expect(selection.selectedDocument.sdcpn).not.toEqual(corruptedSnapshot); + }); + + test("keeps a missing snapshot diagnosable without inventing a revision", () => { + expect( + resolveCrewReservationBundle({ + fallbackDocument, + manifest, + storedDocument: fallbackDocument, + }), + ).toEqual({ + selectedDocument: fallbackDocument, + snapshotMissing: true, + }); + }); +}); + +describe("workpieceForCrewReservationBundle", () => { + test("selects the source whose content and record match the manifest hashes", () => { + expect(workpieceForCrewReservationBundle(history, manifest)).toContain( + "# Final inspection and dispatch workpiece", + ); + }); + + test("refuses a selected source whose manifest hash does not match", () => { + expect( + workpieceForCrewReservationBundle(history, { + ...manifest, + latestWorkpiece: { + ...manifest.latestWorkpiece, + sourceMessageSha256: sha256Digest("mismatched source"), + }, + }), + ).toBeUndefined(); + }); +}); diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/resolve-crew-reservation-bundle.ts b/apps/petrinaut-website/src/main/app/local-storage-demo/resolve-crew-reservation-bundle.ts new file mode 100644 index 00000000000..9a601aa517a --- /dev/null +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/resolve-crew-reservation-bundle.ts @@ -0,0 +1,98 @@ +import { + latestRunbookIrBlock, + selectRunbookWorkpiece, +} from "@hashintel/brunch-agent/workpiece"; + +import { + sha256Digest, + type CrewReservationSettledManifest, +} from "./crew-reservation-settled-manifest"; + +import type { CrewReservationHistory } from "./crew-reservation-history"; +import type { SDCPNInLocalStorage } from "./use-local-storage-sdcpns"; + +export interface CrewReservationBundleSelection { + readonly selectedDocument: SDCPNInLocalStorage; + readonly snapshotMissing: boolean; +} + +export const resolveCrewReservationBundle = (input: { + readonly fallbackDocument: SDCPNInLocalStorage; + readonly manifest: CrewReservationSettledManifest | null; + readonly storedDocument: SDCPNInLocalStorage | undefined; +}): CrewReservationBundleSelection => { + const liveDocument = input.storedDocument ?? input.fallbackDocument; + if (input.manifest === null) { + return { + selectedDocument: liveDocument, + snapshotMissing: false, + }; + } + + const coherentDefinition = + liveDocument.coherentSnapshots?.[input.manifest.document.sha256]; + if ( + coherentDefinition === undefined || + sha256Digest(JSON.stringify(coherentDefinition)) !== + input.manifest.document.sha256 + ) { + return { + selectedDocument: liveDocument, + snapshotMissing: true, + }; + } + + return { + selectedDocument: { + ...liveDocument, + sdcpn: coherentDefinition, + }, + snapshotMissing: false, + }; +}; + +export const workpieceForCrewReservationBundle = ( + history: CrewReservationHistory | undefined, + manifest: CrewReservationSettledManifest | null, +): string | undefined => { + if (history === undefined) return undefined; + if (manifest === null) return selectRunbookWorkpiece(history)?.content; + + const selectedMessageIndex = history.messages.findIndex( + ({ id }) => id === manifest.latestWorkpiece.sourceMessageId, + ); + if (selectedMessageIndex === -1) return undefined; + const selectedMessage = history.messages[selectedMessageIndex]; + if (selectedMessage === undefined) return undefined; + + const content = latestRunbookIrBlock( + selectedMessage.parts + .flatMap((part) => (part.type === "text" ? [part.text] : [])) + .join("\n"), + ); + if ( + content === undefined || + sha256Digest(content) !== manifest.latestWorkpiece.contentSha256 || + sha256Digest(JSON.stringify(selectedMessage)) !== + manifest.latestWorkpiece.sourceMessageSha256 + ) { + return undefined; + } + + const selectedWorkpiece = selectRunbookWorkpiece({ + ...history, + messages: history.messages.slice(0, selectedMessageIndex + 1), + }); + if ( + selectedWorkpiece?.sourceMessageId !== + manifest.latestWorkpiece.sourceMessageId || + selectedWorkpiece.sourceSubmissionId !== + manifest.latestWorkpiece.sourceSubmissionId || + selectedWorkpiece.authorship !== manifest.latestWorkpiece.authorship || + selectedWorkpiece.sourceKind !== manifest.latestWorkpiece.sourceKind + ) { + return undefined; + } + + return content; +}; diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/use-crew-reservation-fixture-session.ts b/apps/petrinaut-website/src/main/app/local-storage-demo/use-crew-reservation-fixture-session.ts new file mode 100644 index 00000000000..ad13ccfcef1 --- /dev/null +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/use-crew-reservation-fixture-session.ts @@ -0,0 +1,127 @@ +import { useEffect, useMemo } from "react"; + +import { + getLatestNetDefinitionToolName, + normalizePetrinautAiToolInput, +} from "@hashintel/petrinaut-core/ai"; + +import { brunchClientToolNames } from "./brunch-client-tools"; +import { + crewReservationConversationId, + crewReservationFixtureClientToolNames, +} from "./prepared-crew-reservation-fixture"; +import { workpieceForCrewReservationBundle } from "./resolve-crew-reservation-bundle"; +import { useCrewReservationSettlement } from "./use-crew-reservation-settled-manifest"; +import { usePrepareCrewReservationConversation } from "./use-prepare-crew-reservation-conversation"; + +import type { CrewReservationHistory } from "./crew-reservation-history"; +import type { CrewReservationSettledManifest } from "./crew-reservation-settled-manifest"; +import type { FlueClient } from "@flue/sdk"; +import type { SDCPN } from "@hashintel/petrinaut-core"; + +/** + * The fixture adds its canonical Petrinaut read and least mutation to the + * browser catalog rather than replacing it: the SDCPN plugin mounts the docs + * reader in every mode, so a docs read must still be answered here or the + * turn stalls awaiting a client result that never comes. + */ +const clientToolNames: ReadonlySet = new Set([ + ...brunchClientToolNames, + ...crewReservationFixtureClientToolNames, +]); + +export const crewReservationFixtureConfiguration = { + clientToolNames, + conversationId: crewReservationConversationId, + mapClientToolInput: ({ + input, + toolName, + }: { + readonly input: unknown; + readonly toolName: string; + }) => + toolName === "addArc" || toolName === getLatestNetDefinitionToolName + ? normalizePetrinautAiToolInput(toolName, input) + : input, +} as const; + +export const useCrewReservationFixtureSession = (input: { + readonly clientPromise: Promise | null; + readonly definition: SDCPN | undefined; + readonly enabled: boolean; + readonly history: CrewReservationHistory | undefined; + readonly historyError: string | undefined; + readonly persistCoherentSnapshot: (sha256: string, definition: SDCPN) => void; + readonly refreshHistory: () => void; + readonly setSettledManifest: ( + value: + | CrewReservationSettledManifest + | null + | (( + previous: CrewReservationSettledManifest | null, + ) => CrewReservationSettledManifest | null), + ) => void; + readonly settledManifest: CrewReservationSettledManifest | null; + readonly snapshotMissing: boolean; +}) => { + const { + clientPromise, + definition, + enabled, + history, + historyError, + persistCoherentSnapshot, + refreshHistory, + setSettledManifest, + settledManifest, + snapshotMissing, + } = input; + const preparation = usePrepareCrewReservationConversation( + clientPromise, + enabled, + ); + const preparationStatus = preparation.status; + + useEffect(() => { + if ( + preparationStatus.state === "ready" || + preparationStatus.state === "failed" + ) { + refreshHistory(); + } + }, [preparationStatus.state, refreshHistory]); + + const settlementStatus = useCrewReservationSettlement({ + definition: enabled ? definition : undefined, + enabled, + history: enabled ? history : undefined, + historyError: enabled ? historyError : undefined, + persistCoherentSnapshot, + preparationError: + preparationStatus.state === "failed" + ? preparationStatus.error + : undefined, + setSettledManifest, + settledManifest, + snapshotMissing, + }); + + const currentWorkpiece = useMemo(() => { + try { + return workpieceForCrewReservationBundle(history, settledManifest); + } catch { + return undefined; + } + }, [history, settledManifest]); + + return { + currentWorkpiece, + preparationStatus, + settlementStatus, + transportClientPromise: preparation.clientPromise, + transportUnavailableReason: + preparationStatus.state === "failed" + ? preparationStatus.error + : "The prepared fixture conversation is still being prepared.", + }; +}; diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/use-crew-reservation-settled-manifest.test.ts b/apps/petrinaut-website/src/main/app/local-storage-demo/use-crew-reservation-settled-manifest.test.ts new file mode 100644 index 00000000000..474e0b616b6 --- /dev/null +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/use-crew-reservation-settled-manifest.test.ts @@ -0,0 +1,223 @@ +/** + * @vitest-environment jsdom + */ +import { act, cleanup, renderHook, waitFor } from "@testing-library/react"; +import { afterEach, beforeEach, expect, test, vi } from "vitest"; + +import { + preparedWorkpieceAuthorship, + preparedWorkpieceClaimBoundary, + preparedWorkpieceSignalTag, +} from "@hashintel/brunch-agent/workpiece"; + +import { crewReservationSettledManifestStorageKey } from "./crew-reservation-settled-manifest"; +import { + crewReservationFixtureId, + dispatchCrewPlaceId, + preparedCrewReservationNet, + preparedCrewReservationWorkpiece, + startFinalInspectionTransitionId, +} from "./prepared-crew-reservation-fixture"; +import { + useCrewReservationSettlement, + useCrewReservationSettledManifestStorage, +} from "./use-crew-reservation-settled-manifest"; + +const preparedHistory = { + conversationId: "canonical-conversation", + offset: "2", + settlements: [{ submissionId: "prepare-submission", outcome: "completed" }], + messages: [ + { + id: "prepared-message", + role: "system", + purpose: "dispatch", + submissionId: "prepare-submission", + signal: { + tagName: preparedWorkpieceSignalTag, + attributes: { + fixtureId: crewReservationFixtureId, + authorship: preparedWorkpieceAuthorship, + claimBoundary: preparedWorkpieceClaimBoundary, + }, + }, + parts: [{ type: "text", text: preparedCrewReservationWorkpiece }], + }, + ], +}; + +beforeEach(() => { + window.localStorage.clear(); +}); + +afterEach(() => { + cleanup(); + window.localStorage.clear(); +}); + +test("keeps the prior runtime bundle selected while a document write is partial", async () => { + const persistCoherentSnapshot = vi.fn(); + const { result, rerender } = renderHook( + ({ definition }: { definition: typeof preparedCrewReservationNet }) => { + const storage = useCrewReservationSettledManifestStorage(); + const status = useCrewReservationSettlement({ + definition, + enabled: true, + history: preparedHistory, + historyError: undefined, + persistCoherentSnapshot, + preparationError: undefined, + setSettledManifest: storage.setSettledManifest, + settledManifest: storage.settledManifest, + snapshotMissing: false, + }); + return { ...storage, status }; + }, + { initialProps: { definition: preparedCrewReservationNet } }, + ); + + await waitFor(() => expect(result.current.status.state).toBe("settled")); + const settledManifest = result.current.settledManifest; + expect(settledManifest?.revision).toBe(0); + expect(persistCoherentSnapshot).toHaveBeenCalledWith( + settledManifest?.document.sha256, + preparedCrewReservationNet, + ); + + const partialDefinition = structuredClone(preparedCrewReservationNet); + const startInspection = partialDefinition.transitions.find( + ({ id }) => id === startFinalInspectionTransitionId, + ); + if (startInspection === undefined) { + throw new Error("Missing prepared start-inspection transition"); + } + startInspection.inputArcs.push({ + placeId: dispatchCrewPlaceId, + type: "standard", + weight: 1, + }); + rerender({ definition: partialDefinition }); + + await waitFor(() => expect(result.current.status.state).toBe("refused")); + expect(result.current.settledManifest).toEqual(settledManifest); + expect( + JSON.parse( + window.localStorage.getItem(crewReservationSettledManifestStorageKey) ?? + "null", + ), + ).toEqual(settledManifest); +}); + +test("retains a selected bundle while canonical history reconnects", async () => { + const persistCoherentSnapshot = vi.fn(); + const { result, rerender } = renderHook( + ({ history }: { history: typeof preparedHistory | undefined }) => { + const storage = useCrewReservationSettledManifestStorage(); + const status = useCrewReservationSettlement({ + definition: preparedCrewReservationNet, + enabled: true, + history, + historyError: undefined, + persistCoherentSnapshot, + preparationError: undefined, + setSettledManifest: storage.setSettledManifest, + settledManifest: storage.settledManifest, + snapshotMissing: false, + }); + return { ...storage, status }; + }, + { + initialProps: { + history: preparedHistory as typeof preparedHistory | undefined, + }, + }, + ); + await waitFor(() => expect(result.current.status.state).toBe("settled")); + const settledManifest = result.current.settledManifest; + + rerender({ history: undefined }); + + expect(result.current.status).toEqual({ state: "revalidating" }); + expect(result.current.settledManifest).toEqual(settledManifest); +}); + +test("does not publish a bundle while its coherent snapshot is unavailable", async () => { + const persistCoherentSnapshot = vi.fn(); + const { result } = renderHook(() => { + const storage = useCrewReservationSettledManifestStorage(); + const status = useCrewReservationSettlement({ + definition: preparedCrewReservationNet, + enabled: true, + history: preparedHistory, + historyError: undefined, + persistCoherentSnapshot, + preparationError: undefined, + setSettledManifest: storage.setSettledManifest, + settledManifest: storage.settledManifest, + snapshotMissing: true, + }); + return { ...storage, status }; + }); + + await act(async () => undefined); + + expect(result.current.status).toEqual({ + state: "refused", + reason: "bundle-snapshot-unavailable", + }); + expect(persistCoherentSnapshot).not.toHaveBeenCalled(); + expect(result.current.settledManifest).toBeNull(); +}); + +test("surfaces canonical history failure without publishing a bundle", async () => { + const persistCoherentSnapshot = vi.fn(); + const { result } = renderHook(() => { + const storage = useCrewReservationSettledManifestStorage(); + const status = useCrewReservationSettlement({ + definition: preparedCrewReservationNet, + enabled: true, + history: undefined, + historyError: "History unavailable.", + persistCoherentSnapshot, + preparationError: undefined, + setSettledManifest: storage.setSettledManifest, + settledManifest: storage.settledManifest, + snapshotMissing: false, + }); + return { ...storage, status }; + }); + + await waitFor(() => expect(result.current.status.state).toBe("refused")); + expect(result.current.status).toEqual({ + state: "refused", + reason: "history-unavailable", + detail: "History unavailable.", + }); + expect(result.current.settledManifest).toBeNull(); +}); + +test("distinguishes preparation failure from unavailable history", async () => { + const persistCoherentSnapshot = vi.fn(); + const { result } = renderHook(() => { + const storage = useCrewReservationSettledManifestStorage(); + const status = useCrewReservationSettlement({ + definition: preparedCrewReservationNet, + enabled: true, + history: undefined, + historyError: undefined, + persistCoherentSnapshot, + preparationError: "Provider authentication failed.", + setSettledManifest: storage.setSettledManifest, + settledManifest: storage.settledManifest, + snapshotMissing: false, + }); + return { ...storage, status }; + }); + + expect(result.current.status).toEqual({ + state: "refused", + reason: "preparation-failed", + detail: "Provider authentication failed.", + }); + expect(result.current.settledManifest).toBeNull(); +}); diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/use-crew-reservation-settled-manifest.ts b/apps/petrinaut-website/src/main/app/local-storage-demo/use-crew-reservation-settled-manifest.ts new file mode 100644 index 00000000000..aafad811942 --- /dev/null +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/use-crew-reservation-settled-manifest.ts @@ -0,0 +1,167 @@ +import { useLocalStorage } from "@mantine/hooks"; +import { useEffect, useState } from "react"; + +import { + crewReservationSettledManifestStorageKey, + settleCrewReservationManifest, + type CrewReservationSettledManifest, + type CrewReservationSettlementResult, +} from "./crew-reservation-settled-manifest"; + +import type { CrewReservationHistory } from "./crew-reservation-history"; +import type { SDCPN } from "@hashintel/petrinaut-core"; + +export type CrewReservationSettlementStatus = + | { readonly state: "idle" | "preparing" | "revalidating" } + | { readonly state: "settled" } + | { + readonly detail?: string; + readonly reason: + | Extract< + CrewReservationSettlementResult, + { status: "refused" } + >["reason"] + | "bundle-snapshot-unavailable" + | "history-unavailable" + | "preparation-failed" + | "settlement-failed"; + readonly state: "refused"; + }; + +export const useCrewReservationSettledManifestStorage = () => { + const [settledManifest, setSettledManifest] = + useLocalStorage({ + key: crewReservationSettledManifestStorageKey, + defaultValue: null, + getInitialValueInEffect: false, + }); + return { settledManifest, setSettledManifest }; +}; + +export const useCrewReservationSettlement = (input: { + readonly definition: SDCPN | undefined; + readonly enabled: boolean; + readonly history: CrewReservationHistory | undefined; + readonly historyError: string | undefined; + readonly persistCoherentSnapshot: (sha256: string, definition: SDCPN) => void; + readonly preparationError: string | undefined; + readonly setSettledManifest: ( + value: + | CrewReservationSettledManifest + | null + | (( + previous: CrewReservationSettledManifest | null, + ) => CrewReservationSettledManifest | null), + ) => void; + readonly settledManifest: CrewReservationSettledManifest | null; + readonly snapshotMissing: boolean; +}) => { + const { + definition, + enabled, + history, + historyError, + persistCoherentSnapshot, + preparationError, + setSettledManifest, + settledManifest, + snapshotMissing, + } = input; + const [observedStatus, setObservedStatus] = + useState({ state: "preparing" }); + + useEffect(() => { + if ( + !enabled || + historyError !== undefined || + snapshotMissing || + definition === undefined || + history === undefined + ) { + return; + } + + let cancelled = false; + const definitionSnapshot = structuredClone(definition); + const settle = async (): Promise => { + let result: CrewReservationSettlementResult; + try { + result = await settleCrewReservationManifest({ + definition: definitionSnapshot, + history, + ...(settledManifest === null ? {} : { previous: settledManifest }), + settledAt: new Date().toISOString(), + }); + } catch (error) { + if (!cancelled) { + setObservedStatus({ + state: "refused", + reason: "settlement-failed", + detail: + error instanceof Error + ? error.message + : "The coherent bundle could not be inspected.", + }); + } + return; + } + if (cancelled) return; + if (result.status === "refused") { + setObservedStatus({ + state: "refused", + reason: result.reason, + }); + return; + } + persistCoherentSnapshot( + result.manifest.document.sha256, + definitionSnapshot, + ); + if (result.manifest.manifestId !== settledManifest?.manifestId) { + setSettledManifest(result.manifest); + } + setObservedStatus({ state: "settled" }); + }; + void settle(); + + return () => { + cancelled = true; + }; + }, [ + definition, + enabled, + history, + historyError, + persistCoherentSnapshot, + setSettledManifest, + settledManifest, + snapshotMissing, + ]); + + const status: CrewReservationSettlementStatus = !enabled + ? { state: "idle" } + : historyError !== undefined + ? { + state: "refused", + reason: "history-unavailable", + detail: historyError, + } + : snapshotMissing + ? { + state: "refused", + reason: "bundle-snapshot-unavailable", + } + : preparationError !== undefined && + (definition === undefined || history === undefined) + ? { + state: "refused", + reason: "preparation-failed", + detail: preparationError, + } + : definition === undefined || history === undefined + ? settledManifest === null + ? { state: "preparing" } + : { state: "revalidating" } + : observedStatus; + return status; +}; diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/use-flue-chat-history.test.ts b/apps/petrinaut-website/src/main/app/local-storage-demo/use-flue-chat-history.test.ts index d06490a7235..1ff5228fbdf 100644 --- a/apps/petrinaut-website/src/main/app/local-storage-demo/use-flue-chat-history.test.ts +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/use-flue-chat-history.test.ts @@ -1,69 +1,391 @@ +import { FlueApiError } from "@flue/sdk"; /** * @vitest-environment jsdom */ -import { cleanup, renderHook, waitFor } from "@testing-library/react"; +import { act, cleanup, renderHook, waitFor } from "@testing-library/react"; import { afterEach, expect, test, vi } from "vitest"; -import { BRUNCH_PRINCIPAL_HEADER } from "@hashintel/brunch-agent-transport-aisdk/headers"; - import { useFlueChatHistory } from "./use-flue-chat-history"; -const brunchEndpoint = "https://brunch.test/api/chat"; +import type { + AgentConversationObservation, + AgentConversationObservationSnapshot, + FlueClient, +} from "@flue/sdk"; afterEach(() => { cleanup(); - vi.unstubAllGlobals(); }); -test("hydrates from the configured Brunch endpoint", async () => { - const fetchMock = vi.fn(async () => - Response.json({ - messages: [{ id: "assistant-1", role: "assistant", parts: [] }], - }), - ); - vi.stubGlobal("fetch", fetchMock); +const createObservationHarness = ( + initialSnapshot: AgentConversationObservationSnapshot, +) => { + let snapshot = initialSnapshot; + const listeners = new Set<() => void>(); + const refresh = vi.fn(); + const close = vi.fn(); + const observation: AgentConversationObservation = { + close, + getSnapshot: () => snapshot, + refresh, + subscribe: (listener) => { + listeners.add(listener); + return () => listeners.delete(listener); + }, + }; + const observe = vi.fn(() => observation); + return { + clientPromise: Promise.resolve({ + observe, + } as Pick as FlueClient), + close, + observe, + publish(next: AgentConversationObservationSnapshot) { + snapshot = next; + for (const listener of listeners) listener(); + }, + refresh, + }; +}; +test("hydrates through the public Flue observation projection", async () => { + const harness = createObservationHarness({ + conversation: { + conversationId: "conversation-1", + settlements: [], + messages: [ + { + id: "assistant-1", + role: "assistant", + purpose: "assistant", + display: "visible", + parts: [{ type: "text", text: "Canonical reply.", state: "done" }], + }, + ], + }, + offset: "offset-1", + phase: "live", + error: undefined, + }); const { result } = renderHook(() => - useFlueChatHistory(brunchEndpoint, "conversation-1", "principal-1"), + useFlueChatHistory(harness.clientPromise, "conversation-1"), ); await waitFor(() => expect(result.current.ready).toBe(true)); expect(result.current.messages).toStrictEqual([ - { id: "assistant-1", role: "assistant", parts: [] }, + { + id: "assistant-1", + role: "assistant", + parts: [{ type: "text", text: "Canonical reply.", state: "done" }], + }, ]); + expect(result.current.phase).toBe("live"); + expect(harness.observe).toHaveBeenCalledWith({ live: "sse" }); +}); + +test("exposes the canonical settlement index for Voice correlation", async () => { + const harness = createObservationHarness({ + conversation: { + conversationId: "conversation-1", + settlements: [{ submissionId: "submission-1", outcome: "aborted" }], + messages: [], + }, + offset: "offset-1", + phase: "live", + error: undefined, + }); + const { result } = renderHook(() => + useFlueChatHistory(harness.clientPromise, "conversation-1"), + ); - const [url, init] = fetchMock.mock.calls[0] as unknown as [ - URL, - { headers: Record }, - ]; - expect(url.toString()).toBe("https://brunch.test/api/chat?id=conversation-1"); - expect(init.headers[BRUNCH_PRINCIPAL_HEADER]).toBe("principal-1"); + await waitFor(() => expect(result.current.ready).toBe(true)); + expect(result.current.settlements).toEqual([ + { submissionId: "submission-1", outcome: "aborted" }, + ]); }); -test("asks nothing of the generic chat route, which keeps no history", () => { - const fetchMock = vi.fn(); - vi.stubGlobal("fetch", fetchMock); +test("preserves every persisted Voice tool origin across hydration and reopen", async () => { + const harness = createObservationHarness({ + conversation: { + conversationId: "conversation-1", + settlements: [], + messages: [ + { + id: "assistant-voice-tools", + role: "assistant", + purpose: "assistant", + display: "visible", + parts: [ + { + type: "dynamic-tool", + toolCallId: "tool-doc-1", + toolName: "readPetrinautDoc", + state: "output-available", + input: { doc: "ai-assistant" }, + output: { awaiting: "client" }, + }, + { + type: "dynamic-tool", + toolCallId: "tool-doc-2", + toolName: "readPetrinautDoc", + state: "output-available", + input: { doc: "ai-assistant" }, + output: { awaiting: "client" }, + }, + ], + }, + { + id: "signal-voice-results", + role: "system", + purpose: "dispatch", + display: "hidden", + signal: { tagName: "client-tool-result" }, + parts: [ + { + type: "text", + text: JSON.stringify([ + { + toolCallId: "tool-doc-1", + toolName: "readPetrinautDoc", + output: "First guide", + source: "voice", + }, + { + toolCallId: "tool-doc-2", + toolName: "readPetrinautDoc", + output: "Second guide", + source: "voice", + }, + ]), + state: "done", + }, + ], + }, + ], + }, + offset: "offset-voice", + phase: "live", + error: undefined, + }); + const firstOpen = renderHook(() => + useFlueChatHistory(harness.clientPromise, "conversation-1"), + ); + + await waitFor(() => expect(firstOpen.result.current.ready).toBe(true)); + expect(firstOpen.result.current.messages?.[0]?.metadata).toEqual({ + source: "voice", + voiceToolCallIds: ["tool-doc-1", "tool-doc-2"], + }); + firstOpen.unmount(); + const reopened = renderHook(() => + useFlueChatHistory(harness.clientPromise, "conversation-1"), + ); + await waitFor(() => expect(reopened.result.current.ready).toBe(true)); + expect(reopened.result.current.messages?.[0]?.metadata).toEqual({ + source: "voice", + voiceToolCallIds: ["tool-doc-1", "tool-doc-2"], + }); +}); + +test("asks nothing of the generic chat route, which keeps no history", () => { const { result } = renderHook(() => - useFlueChatHistory(null, "conversation-1", "principal-1"), + useFlueChatHistory(null, "conversation-1"), ); - expect(fetchMock).not.toHaveBeenCalled(); expect(result.current.ready).toBe(false); expect(result.current.messages).toBeUndefined(); }); -test("leaves the panel on its local cache when hydration fails", async () => { - const fetchMock = vi.fn( - async () => new Response("Method not allowed", { status: 405 }), +test("represents an absent conversation as an empty canonical history", async () => { + const harness = createObservationHarness({ + conversation: undefined, + offset: undefined, + phase: "absent", + error: undefined, + }); + const { result } = renderHook(() => + useFlueChatHistory(harness.clientPromise, "conversation-1"), ); - vi.stubGlobal("fetch", fetchMock); + await waitFor(() => expect(result.current.phase).toBe("absent")); + expect(result.current.ready).toBe(true); + expect(result.current.messages).toEqual([]); +}); + +test("replays a refresh requested before observation setup completes", async () => { + const harness = createObservationHarness({ + conversation: undefined, + offset: undefined, + phase: "absent", + error: undefined, + }); const { result } = renderHook(() => - useFlueChatHistory(brunchEndpoint, "conversation-1", "principal-1"), + useFlueChatHistory(harness.clientPromise, "conversation-1"), ); - await waitFor(() => expect(fetchMock).toHaveBeenCalled()); - expect(result.current.ready).toBe(false); - expect(result.current.messages).toBeUndefined(); + act(() => { + result.current.refresh(); + }); + expect(harness.refresh).not.toHaveBeenCalled(); + + await waitFor(() => expect(harness.refresh).toHaveBeenCalledOnce()); +}); + +test("retains canonical messages while the SDK reconnects", async () => { + const conversation = { + conversationId: "conversation-1", + settlements: [ + { submissionId: "submission-1", outcome: "completed" as const }, + ], + messages: [ + { + id: "assistant-1", + role: "assistant" as const, + purpose: "assistant" as const, + display: "visible" as const, + parts: [ + { type: "text" as const, text: "Settled.", state: "done" as const }, + ], + }, + ], + }; + const harness = createObservationHarness({ + conversation, + offset: "offset-1", + phase: "live", + error: undefined, + }); + const { result } = renderHook(() => + useFlueChatHistory(harness.clientPromise, "conversation-1"), + ); + await waitFor(() => expect(result.current.phase).toBe("live")); + + harness.publish({ + conversation, + offset: "offset-1", + phase: "connecting", + error: new TypeError("network unavailable"), + }); + + await waitFor(() => expect(result.current.phase).toBe("connecting")); + expect(result.current.messages?.[0]?.id).toBe("assistant-1"); + expect(result.current.latestSettlement?.outcome).toBe("completed"); +}); + +test.each([401, 403])( + "surfaces fatal ownership status %s and exposes SDK refresh", + async (status) => { + const failure = new FlueApiError(status, ""); + const harness = createObservationHarness({ + conversation: undefined, + offset: undefined, + phase: "error", + error: failure, + }); + const { result } = renderHook(() => + useFlueChatHistory(harness.clientPromise, "conversation-1"), + ); + + await waitFor(() => expect(result.current.phase).toBe("error")); + expect(result.current.error).toBe(failure); + result.current.refresh(); + expect(harness.refresh).toHaveBeenCalledOnce(); + }, +); + +test("closes the SDK observation on unmount", async () => { + const harness = createObservationHarness({ + conversation: undefined, + offset: undefined, + phase: "loading", + error: undefined, + }); + const { unmount } = renderHook(() => + useFlueChatHistory(harness.clientPromise, "conversation-1"), + ); + await waitFor(() => expect(harness.observe).toHaveBeenCalledOnce()); + + unmount(); + + expect(harness.close).toHaveBeenCalledOnce(); +}); + +test("projects fixture client-tool results from canonical signal history", async () => { + const harness = createObservationHarness({ + conversation: { + conversationId: "conversation-1", + settlements: [], + messages: [ + { + id: "assistant-1", + role: "assistant", + purpose: "assistant", + display: "visible", + parts: [ + { + type: "dynamic-tool", + toolName: "addArc", + toolCallId: "arc-1", + state: "output-available", + input: { placeId: "crew" }, + output: { awaiting: "client" }, + }, + ], + }, + { + id: "result-1", + role: "system", + purpose: "dispatch", + display: "diagnostic", + signal: { tagName: "client-tool-result" }, + parts: [ + { + type: "text", + text: JSON.stringify([ + { + toolCallId: "arc-1", + toolName: "addArc", + output: { applied: true }, + }, + ]), + state: "done", + }, + ], + }, + ], + }, + offset: "offset-2", + phase: "live", + error: undefined, + }); + const clientToolNames = new Set(["addArc"]); + const { result } = renderHook(() => + useFlueChatHistory( + harness.clientPromise, + "conversation-1", + clientToolNames, + ), + ); + + await waitFor(() => expect(result.current.ready).toBe(true)); + expect(result.current.messages?.[0]?.parts).toEqual([ + { + type: "tool-addArc", + toolCallId: "arc-1", + state: "output-available", + input: { placeId: "crew" }, + output: { applied: true }, + }, + ]); + expect(result.current.snapshot?.offset).toBe("offset-2"); + expect(result.current.snapshot?.messages.map(({ id }) => id)).toEqual([ + "assistant-1", + "result-1", + ]); + + act(() => { + result.current.refresh(); + }); + expect(harness.refresh).toHaveBeenCalledTimes(1); }); diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/use-flue-chat-history.ts b/apps/petrinaut-website/src/main/app/local-storage-demo/use-flue-chat-history.ts index d33e4f1deac..2701945d5b8 100644 --- a/apps/petrinaut-website/src/main/app/local-storage-demo/use-flue-chat-history.ts +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/use-flue-chat-history.ts @@ -1,69 +1,161 @@ -import { useEffect, useState } from "react"; +import { useCallback, useEffect, useRef, useState } from "react"; -import { BRUNCH_PRINCIPAL_HEADER } from "@hashintel/brunch-agent-transport-aisdk/headers"; +import { snapshotToUiMessages } from "@hashintel/brunch-agent-transport-aisdk"; +import { BRUNCH_QUESTION_TOOL_NAME } from "@hashintel/brunch-agent/question-marker"; +import { readPetrinautDocToolName } from "@hashintel/petrinaut-core"; +import type { + AgentConversationObservation, + AgentConversationObservationPhase, + AgentConversationObservationSnapshot, + FlueClient, + FlueConversationSettlement, + FlueConversationState, +} from "@flue/sdk"; import type { PetrinautAiMessage } from "@hashintel/petrinaut/ui"; +const noSettlements: readonly FlueConversationSettlement[] = []; +const brunchClientToolNames = new Set([readPetrinautDocToolName]); + /** - * Hydrates the panel from the Brunch agent's `GET ?id=` door. - * - * `endpoint` is null whenever the preview runs against the generic OpenAI - * route instead: that route keeps no conversation history and answers anything - * but POST with 405, so asking it is pure noise. + * The observed canonical conversation together with the durable-stream offset + * it was read at. Fixture consumers use the offset to tell a settled bundle + * from a stale one; they never interpret it. */ +export type FlueHistorySnapshot = FlueConversationState & { + readonly offset: string; +}; + +const projectPetrinautMessages = ( + conversation: FlueConversationState, + clientToolNames: ReadonlySet, + mapClientToolInput: + | ((input: { + readonly input: unknown; + readonly toolName: string; + }) => unknown) + | undefined, +): PetrinautAiMessage[] => + // The host owns this narrowing: its configured client-tool catalog is the + // same catalog Petrinaut's message type exposes. + snapshotToUiMessages(conversation, { + clientToolNames, + ...(mapClientToolInput === undefined ? {} : { mapClientToolInput }), + hiddenToolNames: new Set([BRUNCH_QUESTION_TOOL_NAME]), + }) as PetrinautAiMessage[]; + export const useFlueChatHistory = ( - endpoint: string | null, + clientPromise: Promise | null, conversationId: string, - principal: string, + clientToolNames: ReadonlySet = brunchClientToolNames, + mapClientToolInput?: (input: { + readonly input: unknown; + readonly toolName: string; + }) => unknown, ): { + readonly error: Error | undefined; + readonly latestSettlement: FlueConversationSettlement | undefined; readonly messages: PetrinautAiMessage[] | undefined; + readonly phase: AgentConversationObservationPhase | undefined; readonly ready: boolean; + readonly refresh: () => void; + readonly settlements: readonly FlueConversationSettlement[]; + readonly snapshot: FlueHistorySnapshot | undefined; } => { - const [loaded, setLoaded] = useState<{ + const observationRef = useRef(null); + const [observed, setObserved] = useState<{ readonly conversationId: string; - readonly messages: PetrinautAiMessage[]; + readonly snapshot: AgentConversationObservationSnapshot; }>(); + const refreshRequestedRef = useRef(false); + const refresh = useCallback(() => { + const observation = observationRef.current; + if (observation === null) { + refreshRequestedRef.current = true; + return; + } + observation.refresh(); + }, []); + useEffect(() => { - if (endpoint === null || conversationId.length === 0) { + if (clientPromise === null || conversationId.length === 0) { + observationRef.current = null; + refreshRequestedRef.current = false; return; } let cancelled = false; - const load = async (): Promise => { + let unsubscribe: (() => void) | undefined; + let observation: AgentConversationObservation | undefined; + const observe = async (): Promise => { try { - // The endpoint is a full Brunch URL in every configured deployment, - // but resolving it against the page keeps a relative one working. - const url = new URL(endpoint, window.location.origin); - url.searchParams.set("id", conversationId); - const response = await fetch(url, { - headers: { [BRUNCH_PRINCIPAL_HEADER]: principal }, - }); - if (!response.ok) { - return; + const client = await clientPromise; + if (cancelled) return; + observation = client.observe({ live: "sse" }); + observationRef.current = observation; + if (refreshRequestedRef.current) { + refreshRequestedRef.current = false; + observation.refresh(); } - const body = (await response.json()) as { - messages?: PetrinautAiMessage[]; + const publish = (): void => { + if (!cancelled && observation !== undefined) { + setObserved({ + conversationId, + snapshot: observation.getSnapshot(), + }); + } }; - if (!cancelled) { - setLoaded({ - conversationId, - messages: body.messages ?? [], - }); - } - } catch { - // Leave `loaded` stale so the panel keeps using its localStorage cache. + publish(); + unsubscribe = observation.subscribe(publish); + } catch (caught) { + if (cancelled) return; + setObserved({ + conversationId, + snapshot: { + conversation: undefined, + offset: undefined, + phase: "error", + error: caught instanceof Error ? caught : new Error(String(caught)), + }, + }); } }; - void load(); + void observe(); return () => { cancelled = true; + unsubscribe?.(); + observation?.close(); + if (observationRef.current === observation) { + observationRef.current = null; + } }; - }, [conversationId, endpoint, principal]); + }, [clientPromise, conversationId]); - const ready = - conversationId.length > 0 && loaded?.conversationId === conversationId; + const observation = + observed?.conversationId === conversationId ? observed.snapshot : undefined; + const conversation = observation?.conversation; + const absent = observation?.phase === "absent"; + const ready = absent || conversation !== undefined; return { - messages: ready ? loaded.messages : undefined, + error: observation?.error, + latestSettlement: conversation?.settlements.at(-1), + messages: + conversation === undefined + ? absent + ? [] + : undefined + : projectPetrinautMessages( + conversation, + clientToolNames, + mapClientToolInput, + ), + phase: observation?.phase, ready, + refresh, + settlements: conversation?.settlements ?? noSettlements, + snapshot: + conversation === undefined || observation?.offset === undefined + ? undefined + : { ...conversation, offset: observation.offset }, }; }; diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/use-local-storage-sdcpns.ts b/apps/petrinaut-website/src/main/app/local-storage-demo/use-local-storage-sdcpns.ts index 12a20fe3376..e8c44be1577 100644 --- a/apps/petrinaut-website/src/main/app/local-storage-demo/use-local-storage-sdcpns.ts +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/use-local-storage-sdcpns.ts @@ -5,6 +5,12 @@ import type { SDCPN } from "@hashintel/petrinaut-core"; const rootLocalStorageKey = "petrinaut-sdcpn"; export type SDCPNInLocalStorage = { + /** + * Content-addressed coherent revisions retained by prepared fixtures. The + * live `sdcpn` remains the automatic mirror; these snapshots give a settled + * manifest a concrete document revision to select after a partial write. + */ + coherentSnapshots?: Record; id: string; lastUpdated: string; // ISO timestamp sdcpn: SDCPN; diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/use-prepare-crew-reservation-conversation.test.ts b/apps/petrinaut-website/src/main/app/local-storage-demo/use-prepare-crew-reservation-conversation.test.ts new file mode 100644 index 00000000000..1d71f49b9b8 --- /dev/null +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/use-prepare-crew-reservation-conversation.test.ts @@ -0,0 +1,34 @@ +/** + * @vitest-environment jsdom + */ +import { renderHook, waitFor } from "@testing-library/react"; +import { expect, test, vi } from "vitest"; + +import { usePrepareCrewReservationConversation } from "./use-prepare-crew-reservation-conversation"; + +import type { FlueClient } from "@flue/sdk"; + +test("reports preparation failure without rejecting the shared client", async () => { + const client = { + history: vi.fn().mockRejectedValue({ status: 404 }), + send: vi.fn().mockResolvedValue({ submissionId: "preparation" }), + wait: vi + .fn() + .mockRejectedValue(new Error("Provider authentication failed")), + } as unknown as FlueClient; + const clientPromise = Promise.resolve(client); + + const { result } = renderHook(() => + usePrepareCrewReservationConversation(clientPromise, true), + ); + + await waitFor(() => expect(result.current.status.state).toBe("failed")); + expect(result.current.status).toEqual({ + state: "failed", + error: "Provider authentication failed", + }); + await expect(clientPromise).resolves.toBe(client); + await expect(result.current.clientPromise).rejects.toThrow( + "Provider authentication failed", + ); +}); diff --git a/apps/petrinaut-website/src/main/app/local-storage-demo/use-prepare-crew-reservation-conversation.ts b/apps/petrinaut-website/src/main/app/local-storage-demo/use-prepare-crew-reservation-conversation.ts new file mode 100644 index 00000000000..6b66fa2de3a --- /dev/null +++ b/apps/petrinaut-website/src/main/app/local-storage-demo/use-prepare-crew-reservation-conversation.ts @@ -0,0 +1,69 @@ +import { useEffect, useMemo, useState } from "react"; + +import { prepareCrewReservationConversation } from "./prepare-crew-reservation-conversation"; + +import type { FlueClient } from "@flue/sdk"; + +export type CrewReservationPreparationStatus = + | { readonly state: "idle" | "preparing" | "ready" } + | { readonly error: string; readonly state: "failed" }; + +export const usePrepareCrewReservationConversation = ( + clientPromise: Promise | null, + enabled: boolean, +): { + readonly clientPromise: Promise | null; + readonly status: CrewReservationPreparationStatus; +} => { + const preparedClientPromise = useMemo(() => { + if (!enabled || clientPromise === null) return clientPromise; + return clientPromise.then(async (client) => { + await prepareCrewReservationConversation(client); + return client; + }); + }, [clientPromise, enabled]); + const [observed, setObserved] = useState<{ + readonly clientPromise: Promise; + readonly status: CrewReservationPreparationStatus; + }>(); + + useEffect(() => { + if (!enabled || preparedClientPromise === null) return; + + let cancelled = false; + const prepare = async (): Promise => { + try { + await preparedClientPromise; + if (!cancelled) { + setObserved({ + clientPromise: preparedClientPromise, + status: { state: "ready" }, + }); + } + } catch (error) { + if (cancelled) return; + setObserved({ + clientPromise: preparedClientPromise, + status: { + state: "failed", + error: + error instanceof Error + ? error.message + : "The prepared conversation could not be initialized.", + }, + }); + } + }; + void prepare(); + return () => { + cancelled = true; + }; + }, [enabled, preparedClientPromise]); + + const status: CrewReservationPreparationStatus = !enabled + ? { state: "idle" } + : observed?.clientPromise === preparedClientPromise + ? observed.status + : { state: "preparing" }; + return { clientPromise: preparedClientPromise, status }; +}; diff --git a/apps/petrinaut-website/src/main/app/voice-interview/canonical-speech.test.ts b/apps/petrinaut-website/src/main/app/voice-interview/canonical-speech.test.ts index dc12cda21c6..50807c4ba97 100644 --- a/apps/petrinaut-website/src/main/app/voice-interview/canonical-speech.test.ts +++ b/apps/petrinaut-website/src/main/app/voice-interview/canonical-speech.test.ts @@ -1,9 +1,8 @@ import { describe, expect, test } from "vitest"; -import { ASK_TOOL_NAME } from "@hashintel/brunch-agent/client-tools"; - import { hashCanonicalSpeechText, + selectCanonicalSpeech, selectCanonicalSpeechSegments, } from "./canonical-speech"; @@ -90,7 +89,7 @@ describe("canonical speech selection", () => { ]); }); - test("selects one exact validated brunch_ask question", () => { + test("does not treat structured tool input as canonical speech", () => { const messages = [ { id: "assistant-ask", @@ -99,21 +98,21 @@ describe("canonical speech selection", () => { { type: "dynamic-tool", toolCallId: "ask-1", - toolName: ASK_TOOL_NAME, + toolName: "brunch_ask", state: "input-available", input: { question: "Which operator confirms the batch?" }, }, { type: "dynamic-tool", toolCallId: "ask-malformed", - toolName: ASK_TOOL_NAME, + toolName: "brunch_ask", state: "input-available", input: { question: 42 }, }, { type: "dynamic-tool", toolCallId: "ask-submitted", - toolName: ASK_TOOL_NAME, + toolName: "brunch_ask", state: "output-available", input: { question: "Do not repeat an answered question." }, output: { answer: "Already answered." }, @@ -129,20 +128,128 @@ describe("canonical speech selection", () => { }, ] satisfies PetrinautAiMessage[]; - const selected = select(messages); - const contentHash = hashCanonicalSpeechText( - "Which operator confirms the batch?", - ); - expect(selected).toEqual([ + expect(select(messages)).toEqual([]); + }); + + test("selects an exact marked question separately from full-response text", () => { + const question = "Which operator confirms the batch?"; + const selection = selectCanonicalSpeech([ { - contentHash, - id: `canonical-speech:assistant-ask:ask-1:${contentHash}`, - messageId: "assistant-ask", - partId: "ask-1", - source: "brunch-ask", - text: "Which operator confirms the batch?", + id: "assistant-question", + role: "assistant", + parts: [ + { + type: "data-brunch-question", + data: { question, toolCallId: "tool-question-1" }, + }, + { + type: "text", + text: `The batch is ready. ${question} I can explain the choices.`, + state: "done", + }, + ], }, ]); + + expect(selection.segments.map(({ text }) => text)).toEqual([ + `The batch is ready. ${question} I can explain the choices.`, + ]); + expect(selection.questionSegment).toEqual({ + contentHash: hashCanonicalSpeechText(question), + id: `canonical-speech:assistant-question:question%3Atool-question-1:${hashCanonicalSpeechText(question)}`, + messageId: "assistant-question", + partId: "question:tool-question-1", + source: "assistant-question", + text: question, + }); + }); + + test.each([ + { + name: "missing exact finalized prose", + parts: [ + { + type: "data-brunch-question" as const, + data: { + question: "Which operator confirms the batch?", + toolCallId: "tool-question-1", + }, + }, + { + type: "text" as const, + text: "A different question appears in the response.", + state: "done" as const, + }, + ], + }, + { + name: "only provisional prose", + parts: [ + { + type: "data-brunch-question" as const, + data: { + question: "Which operator confirms the batch?", + toolCallId: "tool-question-1", + }, + }, + { + type: "text" as const, + text: "Which operator confirms the batch?", + state: "streaming" as const, + }, + ], + }, + { + name: "blank marker identity", + parts: [ + { + type: "data-brunch-question" as const, + data: { + question: "Which operator confirms the batch?", + toolCallId: " ", + }, + }, + { + type: "text" as const, + text: "Which operator confirms the batch?", + state: "done" as const, + }, + ], + }, + ])("rejects a question marker with $name", ({ parts }) => { + expect( + selectCanonicalSpeech([ + { + id: "assistant-invalid-question", + role: "assistant", + parts, + }, + ]).questionSegment, + ).toBeUndefined(); + }); + + test("does not correlate a marker to text from another assistant message", () => { + const question = "Which operator confirms the batch?"; + + expect( + selectCanonicalSpeech([ + { + id: "assistant-marker", + role: "assistant", + parts: [ + { + type: "data-brunch-question", + data: { question, toolCallId: "tool-question-1" }, + }, + ], + }, + { + id: "assistant-text", + role: "assistant", + parts: [{ type: "text", text: question, state: "done" }], + }, + ]).questionSegment, + ).toBeUndefined(); }); test("uses stable source identity plus an exact-text fingerprint", () => { diff --git a/apps/petrinaut-website/src/main/app/voice-interview/canonical-speech.ts b/apps/petrinaut-website/src/main/app/voice-interview/canonical-speech.ts index bb111385b7e..fd466e1448d 100644 --- a/apps/petrinaut-website/src/main/app/voice-interview/canonical-speech.ts +++ b/apps/petrinaut-website/src/main/app/voice-interview/canonical-speech.ts @@ -1,10 +1,11 @@ import { - ASK_TOOL_NAME, - parseBrunchAskInput, -} from "@hashintel/brunch-agent/client-tools"; + BRUNCH_QUESTION_DATA_NAME, + parseBrunchQuestionData, +} from "@hashintel/brunch-agent/question-marker"; import { hashCanonicalSpeechText } from "../../../canonical-speech-fingerprint"; +import type { AgentSendResult } from "@flue/sdk"; import type { PetrinautAiMessage } from "@hashintel/petrinaut/ui"; export { hashCanonicalSpeechText }; @@ -14,7 +15,12 @@ export interface CanonicalSpeechSegment { readonly id: string; readonly messageId: string; readonly partId: string; - readonly source: "assistant-text" | "brunch-ask"; + readonly source: "assistant-question" | "assistant-text"; + /** + * Every Flue submission that wrote to this segment's message: the one that + * started it plus any client-tool continuation projected back onto it. + */ + readonly submissionIds?: readonly AgentSendResult["submissionId"][]; readonly text: string; } @@ -40,16 +46,28 @@ const createSegment = ( }; }; -export const selectCanonicalSpeechSegments = ( +export interface CanonicalSpeechSelection { + readonly questionSegment?: CanonicalSpeechSegment; + readonly segments: CanonicalSpeechSegment[]; +} + +export const selectCanonicalSpeech = ( messages: PetrinautAiMessage[], -): CanonicalSpeechSegment[] => { +): CanonicalSpeechSelection => { const segments: CanonicalSpeechSegment[] = []; + let questionSegment: CanonicalSpeechSegment | undefined; for (const message of messages) { if (message.role !== "assistant") { continue; } + const finalizedTexts = message.parts.flatMap((part) => + part.type === "text" && part.state !== "streaming" && part.text.trim() + ? [part.text] + : [], + ); + for (const [partIndex, part] of message.parts.entries()) { if ( part.type === "text" && @@ -64,32 +82,36 @@ export const selectCanonicalSpeechSegments = ( part.text, ), ); - continue; } + } - if ( - part.type !== "dynamic-tool" || - part.toolName !== ASK_TOOL_NAME || - part.state !== "input-available" - ) { - continue; + const questionMarkers = message.parts.flatMap((part) => { + if (part.type !== `data-${BRUNCH_QUESTION_DATA_NAME}`) { + return []; } - try { - const input = parseBrunchAskInput(part.input); - segments.push( - createSegment( - message.id, - part.toolCallId, - "brunch-ask", - input.question, - ), - ); - } catch { - // Malformed tool inputs remain visible as tool errors; they are not spoken. - } + const marker = parseBrunchQuestionData(part.data); + + return marker && + finalizedTexts.some((text) => text.includes(marker.question)) + ? [marker] + : []; + }); + const latestQuestionMarker = questionMarkers.at(-1); + + if (latestQuestionMarker) { + questionSegment = createSegment( + message.id, + `question:${latestQuestionMarker.toolCallId}`, + "assistant-question", + latestQuestionMarker.question, + ); } } - return segments; + return { questionSegment, segments }; }; + +export const selectCanonicalSpeechSegments = ( + messages: PetrinautAiMessage[], +): CanonicalSpeechSegment[] => selectCanonicalSpeech(messages).segments; diff --git a/apps/petrinaut-website/src/main/app/voice-interview/openai-realtime-session.test.ts b/apps/petrinaut-website/src/main/app/voice-interview/openai-realtime-session.test.ts index 2e486daae5d..65d5981e8f8 100644 --- a/apps/petrinaut-website/src/main/app/voice-interview/openai-realtime-session.test.ts +++ b/apps/petrinaut-website/src/main/app/voice-interview/openai-realtime-session.test.ts @@ -36,7 +36,7 @@ const canonicalSegment = ( id, messageId: `message-${id}`, partId: id, - source: "brunch-ask", + source: "assistant-text", text, }); @@ -221,7 +221,7 @@ describe("OpenAIRealtimeSession", () => { expect(harness.peers[0]!.close).toHaveBeenCalledOnce(); }); - test("keeps the microphone active through playback and reports automatic interruption", async () => { + test("keeps the microphone closed and rejects audio detected during playback", async () => { const harness = createHarness(); await harness.session.connect(); harness.session.setMicrophoneEnabled(true); @@ -242,30 +242,325 @@ describe("OpenAIRealtimeSession", () => { item_id: "item-user", type: "input_audio_buffer.speech_started", }); + channel.receive({ + response_id: "response-canonical", + type: "output_audio_buffer.stopped", + }); + channel.receive({ + content_index: 0, + item_id: "item-user", + transcript: "Assistant echo must not submit.", + type: "conversation.item.input_audio_transcription.completed", + }); + expect(harness.events).not.toContainEqual( + expect.objectContaining({ itemId: "item-user", type: "completed" }), + ); + expect(harness.events).not.toContainEqual( + expect.objectContaining({ + itemId: "item-user", + type: "input-speech-started", + }), + ); + }); + + test("rejects an accepted input item whose transcript completes after output starts", async () => { + const harness = createHarness(); + await harness.session.connect(); + harness.session.setMicrophoneEnabled(true); + const channel = harness.channels[0]!; + + channel.receive({ + audio_start_ms: 80, + item_id: "item-before-output", + type: "input_audio_buffer.speech_started", + }); + channel.receive({ + content_index: 0, + delta: "This started before output", + item_id: "item-before-output", + type: "conversation.item.input_audio_transcription.delta", + }); + expect(harness.events).toContainEqual({ + key: { + connectionEpoch: 1, + contentIndex: 0, + itemId: "item-before-output", + }, + text: "This started before output", + type: "partial", + }); + + harness.session.speakCanonical([ + canonicalSegment("ask-1", "What happens next?"), + ]); + authorizeLatestSpeechResponse(channel, "response-canonical"); + channel.receive({ + response_id: "response-canonical", + type: "output_audio_buffer.started", + }); + channel.receive({ + content_index: 0, + item_id: "item-before-output", + transcript: "This completed too late.", + type: "conversation.item.input_audio_transcription.completed", + }); + + expect( + harness.events.some( + (event) => + event.type === "completed" && + event.key.itemId === "item-before-output", + ), + ).toBe(false); + expect(harness.localTracks[0]!.enabled).toBe(false); + }); + + test("invalidates accepted input before requesting canonical speech output", async () => { + const harness = createHarness(); + await harness.session.connect(); + harness.session.setMicrophoneEnabled(true); + const channel = harness.channels[0]!; + let microphoneEnabledWhenResponseRequested: boolean | undefined; + channel.send.mockImplementation((payload: string) => { + if (JSON.parse(payload).type === "response.create") { + microphoneEnabledWhenResponseRequested = + harness.localTracks[0]!.enabled; + } + }); + + channel.receive({ + audio_start_ms: 80, + item_id: "item-before-request", + type: "input_audio_buffer.speech_started", + }); + channel.receive({ + content_index: 0, + delta: "This started before canonical speech", + item_id: "item-before-request", + type: "conversation.item.input_audio_transcription.delta", + }); + + harness.session.speakCanonical([ + canonicalSegment("ask-request", "What happens next?"), + ]); + expect(harness.events).toContainEqual( + expect.objectContaining({ type: "canonical-speech-requested" }), + ); + expect(microphoneEnabledWhenResponseRequested).toBe(false); + expect(harness.localTracks[0]!.enabled).toBe(false); + + channel.receive({ + content_index: 0, + item_id: "item-before-request", + transcript: "This completed before output started.", + type: "conversation.item.input_audio_transcription.completed", + }); + expect( + harness.events.some( + (event) => + event.type === "completed" && + event.key.itemId === "item-before-request", + ), + ).toBe(false); + + const handoff = harness.session.cancelOutput(); + let handoffSettled = false; + void handoff.then(() => { + handoffSettled = true; + }); + authorizeLatestSpeechResponse(channel, "response-before-output"); + channel.receive({ type: "input_audio_buffer.cleared" }); + channel.receive({ + response: { + id: "response-before-output", + output: [], + status: "cancelled", + }, + type: "response.done", + }); + await Promise.resolve(); + + expect(handoffSettled).toBe(false); + expect(harness.localTracks[0]!.enabled).toBe(false); + + channel.receive({ + response_id: "response-before-output", + type: "output_audio_buffer.cleared", + }); + await handoff; expect(harness.localTracks[0]!.enabled).toBe(true); - expect(harness.events).toEqual( - expect.arrayContaining([ - { - connectionEpoch: 1, - responseId: "response-canonical", - type: "output-started", - }, - { - connectionEpoch: 1, - itemId: "item-user", - type: "input-speech-started", - }, - { + + channel.receive({ + content_index: 0, + item_id: "item-before-request", + transcript: "The stale item cannot recover authority.", + type: "conversation.item.input_audio_transcription.completed", + }); + channel.receive({ + audio_start_ms: 160, + item_id: "item-after-handoff", + type: "input_audio_buffer.speech_started", + }); + channel.receive({ + content_index: 0, + item_id: "item-after-handoff", + transcript: "This is fresh after the handoff.", + type: "conversation.item.input_audio_transcription.completed", + }); + + expect( + harness.events.filter((event) => event.type === "completed"), + ).toEqual([ + { + key: { connectionEpoch: 1, - responseId: "response-canonical", - type: "output-interrupted", + contentIndex: 0, + itemId: "item-after-handoff", }, - ]), - ); + text: "This is fresh after the handoff.", + type: "completed", + }, + ]); }); - test("parses streamed tool arguments and the completed GA response output", async () => { + test("restores only the latest microphone preference after playback", async () => { + const harness = createHarness(); + await harness.session.connect(); + harness.session.setMicrophoneEnabled(true); + harness.session.speakCanonical([ + canonicalSegment("ask-1", "What happens next?"), + ]); + const channel = harness.channels[0]!; + authorizeLatestSpeechResponse(channel, "response-canonical"); + channel.receive({ + response_id: "response-canonical", + type: "output_audio_buffer.started", + }); + + expect(harness.localTracks[0]!.enabled).toBe(false); + harness.session.setMicrophoneEnabled(false); + channel.receive({ + response_id: "response-canonical", + type: "output_audio_buffer.stopped", + }); + + expect(harness.localTracks[0]!.enabled).toBe(false); + }); + + test("settles idle cancellation after input clear without response-scoped output", async () => { + const harness = createHarness(); + await harness.session.connect(); + harness.session.setMicrophoneEnabled(true); + const channel = harness.channels[0]!; + + const cancellation = harness.session.cancelOutput(); + let settled = false; + void cancellation.then(() => { + settled = true; + }); + channel.receive({ type: "input_audio_buffer.cleared" }); + await Promise.resolve(); + + expect(settled).toBe(true); + expect(harness.localTracks[0]!.enabled).toBe(true); + expect(sentEvents(channel)).toEqual([ + { type: "input_audio_buffer.clear" }, + { type: "output_audio_buffer.clear" }, + ]); + }); + + test("waits for input, output, and response settlement before completing handoff", async () => { + const harness = createHarness(); + await harness.session.connect(); + harness.session.setMicrophoneEnabled(true); + const channel = harness.channels[0]!; + channel.receive({ + audio_start_ms: 40, + item_id: "item-before-handoff", + type: "input_audio_buffer.speech_started", + }); + harness.session.speakCanonical([ + canonicalSegment("ask-handoff", "What happens next?"), + ]); + authorizeLatestSpeechResponse(channel, "response-handoff"); + channel.receive({ + response_id: "response-handoff", + type: "output_audio_buffer.started", + }); + + const cancellation = Promise.resolve(harness.session.cancelOutput()); + let settled = false; + void cancellation.then(() => { + settled = true; + }); + + expect(harness.localTracks[0]!.enabled).toBe(false); + expect(sentEvents(channel).slice(-3)).toEqual([ + { type: "input_audio_buffer.clear" }, + expect.objectContaining({ + response_id: "response-handoff", + type: "response.cancel", + }), + { type: "output_audio_buffer.clear" }, + ]); + channel.receive({ + content_index: 0, + item_id: "item-before-handoff", + transcript: "This began too early.", + type: "conversation.item.input_audio_transcription.completed", + }); + channel.receive({ type: "input_audio_buffer.cleared" }); + channel.receive({ + response_id: "response-handoff", + type: "output_audio_buffer.cleared", + }); + await Promise.resolve(); + expect(settled).toBe(false); + expect(harness.localTracks[0]!.enabled).toBe(false); + + channel.receive({ + response: { + id: "response-handoff", + output: [], + status: "cancelled", + }, + type: "response.done", + }); + await cancellation; + + expect(harness.localTracks[0]!.enabled).toBe(true); + expect( + harness.events.some( + (event) => + event.type === "completed" && + event.key.itemId === "item-before-handoff", + ), + ).toBe(false); + + channel.receive({ + audio_start_ms: 120, + item_id: "item-after-handoff", + type: "input_audio_buffer.speech_started", + }); + channel.receive({ + content_index: 0, + item_id: "item-after-handoff", + transcript: "This began after the handoff.", + type: "conversation.item.input_audio_transcription.completed", + }); + expect(harness.events).toContainEqual({ + key: { + connectionEpoch: 1, + contentIndex: 0, + itemId: "item-after-handoff", + }, + text: "This began after the handoff.", + type: "completed", + }); + }); + + test("never exposes model function arguments as user input", async () => { const harness = createHarness(); await harness.session.connect(); const channel = harness.channels[0]!; @@ -286,6 +581,8 @@ describe("OpenAIRealtimeSession", () => { response_id: "response-tool", type: "response.function_call_arguments.delta", }); + expect(harness.events).toEqual([]); + channel.receive({ response: { id: "response-tool", @@ -304,54 +601,46 @@ describe("OpenAIRealtimeSession", () => { }); expect(harness.events).toEqual([ - { - callId: "call-1", - connectionEpoch: 1, - delta: '{"answer":"Approved"}', - itemId: "item-function", - responseId: "response-tool", - type: "tool-arguments-delta", - }, - { - arguments: '{"answer":"Approved"}', - callId: "call-1", - connectionEpoch: 1, - itemId: "item-function", - name: "continue_interview", - responseId: "response-tool", - type: "tool-arguments-done", - }, - { - connectionEpoch: 1, - responseId: "response-tool", - status: "completed", - type: "response-terminal", - }, + expect.objectContaining({ code: "invalid-response", type: "error" }), ]); + }); - harness.session.completeFunctionCall("call-1", [ - canonicalSegment("ask-2", "Who acts next?"), + test("preserves exact canonical whitespace while rejecting blank speech", async () => { + const harness = createHarness(); + await harness.session.connect(); + const channel = harness.channels[0]!; + + harness.session.speakCanonical([ + canonicalSegment("ask-exact", " Exact Brunch text.\n"), ]); - const [functionOutput, responseCreate] = sentEvents(channel).slice(-2); - expect(functionOutput).toEqual({ - type: "conversation.item.create", - item: { - type: "function_call_output", - call_id: "call-1", - output: JSON.stringify({ response_text: ["Who acts next?"] }), - }, - }); - expect(responseCreate).toMatchObject({ + + expect(sentEvents(channel)[0]).toMatchObject({ type: "response.create", response: { - instructions: - "Speak only the response_text strings supplied by Petrinaut, in array order and verbatim. Deliver them as a warm, calm, curious, confident, concise, and professionally neutral expert interviewer, at a measured conversational pace with natural emphasis. Never sound robotic, fawning, rushed, overenthusiastic, or patronizing. Do not add, remove, paraphrase, acknowledge, or explain anything.", - output_modalities: ["audio"], - parallel_tool_calls: false, + conversation: "none", + input: [ + { + type: "message", + role: "system", + content: [ + { + type: "input_text", + text: JSON.stringify({ + response_text: [" Exact Brunch text.\n"], + }), + }, + ], + }, + ], tool_choice: "none", tools: [], }, }); + const sentCount = sentEvents(channel).length; + expect(() => + harness.session.speakCanonical([canonicalSegment("ask-blank", " \n\t")]), + ).toThrow(); + expect(sentEvents(channel)).toHaveLength(sentCount); }); test("queues canonical speech behind an active Realtime response", async () => { @@ -368,6 +657,9 @@ describe("OpenAIRealtimeSession", () => { ]); expect(sentEvents(channel)).toEqual([]); + expect(harness.events).not.toContainEqual( + expect.objectContaining({ type: "canonical-speech-requested" }), + ); channel.receive({ response: { id: "response-active", @@ -384,6 +676,11 @@ describe("OpenAIRealtimeSession", () => { metadata: { petrinaut_kind: "canonical-speech" }, }, }); + expect(harness.events).toContainEqual({ + connectionEpoch: 1, + speechRequestId: "canonical-1-1", + type: "canonical-speech-requested", + }); expect(harness.events).toContainEqual({ connectionEpoch: 1, responseId: "response-active", @@ -392,6 +689,166 @@ describe("OpenAIRealtimeSession", () => { }); }); + test("keeps the microphone closed when an earlier stop follows a queued response request", async () => { + const harness = createHarness(); + await harness.session.connect(); + harness.session.setMicrophoneEnabled(true); + const channel = harness.channels[0]!; + harness.session.speakCanonical([ + canonicalSegment("early", "First canonical segment."), + ]); + authorizeLatestSpeechResponse(channel, "response-early"); + channel.receive({ + response_id: "response-early", + type: "output_audio_buffer.started", + }); + harness.session.speakCanonical([ + canonicalSegment("follow-on", "Second canonical segment."), + ]); + + channel.receive({ + response: { + id: "response-early", + output: [], + status: "completed", + }, + type: "response.done", + }); + expect(harness.events.at(-1)).toMatchObject({ + speechRequestId: "canonical-1-2", + type: "canonical-speech-requested", + }); + authorizeLatestSpeechResponse(channel, "response-follow-on"); + channel.receive({ + response: { + id: "response-follow-on", + output: [], + status: "completed", + }, + type: "response.done", + }); + + channel.receive({ + response_id: "response-early", + type: "output_audio_buffer.stopped", + }); + + expect(harness.localTracks[0]!.enabled).toBe(false); + + channel.receive({ + response_id: "response-follow-on", + type: "output_audio_buffer.started", + }); + channel.receive({ + response_id: "response-follow-on", + type: "output_audio_buffer.stopped", + }); + expect(harness.events).toContainEqual({ + connectionEpoch: 1, + responseId: "response-follow-on", + speechRequestId: "canonical-1-2", + status: "completed", + type: "response-terminal", + }); + expect(harness.localTracks[0]!.enabled).toBe(true); + }); + + test("releases active canonical ownership after acknowledged cancellation", async () => { + const harness = createHarness(); + await harness.session.connect(); + harness.session.setMicrophoneEnabled(true); + const channel = harness.channels[0]!; + harness.session.speakCanonical([ + canonicalSegment("cancelled", "Cancel this canonical segment."), + ]); + authorizeLatestSpeechResponse(channel, "response-cancelled"); + + const cancellation = harness.session.cancelOutput(); + let settled = false; + void cancellation.then(() => { + settled = true; + }); + channel.receive({ type: "input_audio_buffer.cleared" }); + channel.receive({ + response: { + id: "response-cancelled", + output: [], + status: "cancelled", + }, + type: "response.done", + }); + await Promise.resolve(); + + expect(settled).toBe(false); + expect(harness.localTracks[0]!.enabled).toBe(false); + + channel.receive({ + response_id: "response-cancelled", + type: "output_audio_buffer.cleared", + }); + await cancellation; + + expect(harness.localTracks[0]!.enabled).toBe(true); + }); + + test("waits for output clear when cancelling generated audio before playback", async () => { + const harness = createHarness(); + await harness.session.connect(); + harness.session.setMicrophoneEnabled(true); + const channel = harness.channels[0]!; + harness.session.speakCanonical([ + canonicalSegment("generated", "Generated canonical segment."), + ]); + authorizeLatestSpeechResponse(channel, "response-generated"); + channel.receive({ + response: { + id: "response-generated", + output: [], + status: "completed", + }, + type: "response.done", + }); + + const cancellation = harness.session.cancelOutput(); + let settled = false; + void cancellation.then(() => { + settled = true; + }); + channel.receive({ type: "input_audio_buffer.cleared" }); + await Promise.resolve(); + + expect(settled).toBe(false); + expect(harness.localTracks[0]!.enabled).toBe(false); + + channel.receive({ + response_id: "response-generated", + type: "output_audio_buffer.cleared", + }); + await cancellation; + + expect(harness.localTracks[0]!.enabled).toBe(true); + }); + + test("force-settles cancellation when the provider fails before output clear", async () => { + const harness = createHarness(); + await harness.session.connect(); + harness.session.setMicrophoneEnabled(true); + const cancellation = harness.session.cancelOutput(); + + harness.channels[0]!.receive({ + error: { message: "private provider detail" }, + type: "error", + }); + + await expect(cancellation).resolves.toBeUndefined(); + expect(harness.localTracks[0]!.enabled).toBe(false); + expect(harness.localTracks[0]!.stop).toHaveBeenCalledOnce(); + expect(harness.events.at(-1)).toMatchObject({ + code: "invalid-response", + type: "error", + }); + }); + test("cancels canonical speech before the response starts", async () => { const harness = createHarness(); await harness.session.connect(); @@ -401,7 +858,7 @@ describe("OpenAIRealtimeSession", () => { ]); const responseCreate = sentEvents(channel)[0]!; - harness.session.cancelOutput(); + void harness.session.cancelOutput(); expect( sentEvents(channel).filter(({ type }) => type === "response.cancel"), @@ -548,7 +1005,7 @@ describe("OpenAIRealtimeSession", () => { type: "output_audio_buffer.started", }); - harness.session.cancelOutput(); + void harness.session.cancelOutput(); const cancelEvent = sentEvents(channel).findLast( ({ type }) => type === "response.cancel", )!; @@ -592,7 +1049,7 @@ describe("OpenAIRealtimeSession", () => { type: "output_audio_buffer.started", }); - harness.session.cancelOutput(); + void harness.session.cancelOutput(); const cancelEvent = sentEvents(channel).findLast( ({ type }) => type === "response.cancel", )!; @@ -707,21 +1164,38 @@ describe("OpenAIRealtimeSession", () => { type: "response.done", }); - expect(harness.events).toEqual([ - expect.objectContaining({ - code: "invalid-response", - type: "error", - }), - ]); + expect(harness.events.at(-1)).toMatchObject({ + code: "invalid-response", + type: "error", + }); expect(harness.peers[0]!.close).toHaveBeenCalledOnce(); }); - test("treats transcripts as display-only and never closes capture", async () => { + test("requires a matching speech-start boundary before exposing transcripts", async () => { const harness = createHarness(); await harness.session.connect(); harness.session.setMicrophoneEnabled(true); const channel = harness.channels[0]!; + channel.receive({ + content_index: 0, + delta: "Missing boundary", + item_id: "item-without-boundary", + type: "conversation.item.input_audio_transcription.delta", + }); + channel.receive({ + content_index: 0, + item_id: "item-without-boundary", + transcript: "This must stay rejected.", + type: "conversation.item.input_audio_transcription.completed", + }); + expect(harness.events).toEqual([]); + + channel.receive({ + audio_start_ms: 100, + item_id: "item-user", + type: "input_audio_buffer.speech_started", + }); channel.receive({ content_index: 0, delta: "The supervisor", @@ -736,6 +1210,11 @@ describe("OpenAIRealtimeSession", () => { }); expect(harness.events).toEqual([ + { + connectionEpoch: 1, + itemId: "item-user", + type: "input-speech-started", + }, { key: { connectionEpoch: 1, contentIndex: 0, itemId: "item-user" }, text: "The supervisor", @@ -750,11 +1229,67 @@ describe("OpenAIRealtimeSession", () => { expect(harness.localTracks[0]!.enabled).toBe(true); }); + test("does not retroactively accept a completion that precedes its speech boundary", async () => { + const harness = createHarness(); + await harness.session.connect(); + harness.session.setMicrophoneEnabled(true); + const channel = harness.channels[0]!; + + channel.receive({ + content_index: 0, + item_id: "item-reordered", + transcript: "This completed before its boundary.", + type: "conversation.item.input_audio_transcription.completed", + }); + channel.receive({ + audio_start_ms: 100, + item_id: "item-reordered", + type: "input_audio_buffer.speech_started", + }); + + expect(harness.events).toEqual([ + { + connectionEpoch: 1, + itemId: "item-reordered", + type: "input-speech-started", + }, + ]); + }); + + test("does not reuse a speech boundary from a previous connection epoch", async () => { + const harness = createHarness(); + await harness.session.connect(); + harness.session.setMicrophoneEnabled(true); + harness.channels[0]!.receive({ + audio_start_ms: 100, + item_id: "reused-item", + type: "input_audio_buffer.speech_started", + }); + + await harness.session.disconnect(); + await harness.session.connect(); + harness.session.setMicrophoneEnabled(true); + harness.events.length = 0; + harness.channels[1]!.receive({ + content_index: 0, + item_id: "reused-item", + transcript: "This lacks a current-epoch boundary.", + type: "conversation.item.input_audio_transcription.completed", + }); + + expect(harness.events).toEqual([]); + }); + test("keeps the duplex session alive when optional input transcription fails", async () => { const harness = createHarness(); await harness.session.connect(); harness.session.setMicrophoneEnabled(true); + harness.channels[0]!.receive({ + audio_start_ms: 100, + item_id: "item-user", + type: "input_audio_buffer.speech_started", + }); harness.channels[0]!.receive({ content_index: 0, error: { message: "private provider detail" }, @@ -763,6 +1298,11 @@ describe("OpenAIRealtimeSession", () => { }); expect(harness.events).toEqual([ + { + connectionEpoch: 1, + itemId: "item-user", + type: "input-speech-started", + }, { key: { connectionEpoch: 1, contentIndex: 0, itemId: "item-user" }, type: "transcription-failed", diff --git a/apps/petrinaut-website/src/main/app/voice-interview/openai-realtime-session.ts b/apps/petrinaut-website/src/main/app/voice-interview/openai-realtime-session.ts index f7c13d9c28c..10705cc17d4 100644 --- a/apps/petrinaut-website/src/main/app/voice-interview/openai-realtime-session.ts +++ b/apps/petrinaut-website/src/main/app/voice-interview/openai-realtime-session.ts @@ -19,13 +19,6 @@ export interface OpenAIRealtimeTranscriptKey { readonly itemId: string; } -interface RealtimeToolEventIdentity { - readonly callId: string; - readonly connectionEpoch: number; - readonly itemId: string; - readonly responseId: string; -} - export type OpenAIRealtimeSessionEvent = | { readonly key: OpenAIRealtimeTranscriptKey; @@ -50,8 +43,14 @@ export type OpenAIRealtimeSessionEvent = | { readonly connectionEpoch: number; readonly responseId: string; + readonly speechRequestId: string; readonly type: "output-started"; } + | { + readonly connectionEpoch: number; + readonly speechRequestId: string; + readonly type: "canonical-speech-requested"; + } | { readonly connectionEpoch: number; readonly responseId: string; @@ -65,18 +64,10 @@ export type OpenAIRealtimeSessionEvent = | { readonly connectionEpoch: number; readonly responseId: string; + readonly speechRequestId?: string; readonly status: "cancelled" | "completed" | "failed" | "incomplete"; readonly type: "response-terminal"; } - | (RealtimeToolEventIdentity & { - readonly delta: string; - readonly type: "tool-arguments-delta"; - }) - | (RealtimeToolEventIdentity & { - readonly arguments: string; - readonly name: string; - readonly type: "tool-arguments-done"; - }) | { readonly code: VoiceErrorCode; readonly message: string; @@ -129,6 +120,10 @@ type PendingClientEvent = }; type SessionListener = (event: OpenAIRealtimeSessionEvent) => void; +type ResponseTerminalStatus = Extract< + OpenAIRealtimeSessionEvent, + { type: "response-terminal" } +>["status"]; const CANONICAL_RESPONSE_INSTRUCTIONS = "Speak only the response_text strings supplied by Petrinaut, in array order and verbatim. Deliver them as a warm, calm, curious, confident, concise, and professionally neutral expert interviewer, at a measured conversational pace with natural emphasis. Never sound robotic, fawning, rushed, overenthusiastic, or patronizing. Do not add, remove, paraphrase, acknowledge, or explain anything."; @@ -186,19 +181,25 @@ const waitForAbort = ( }; export class OpenAIRealtimeSession { + readonly #acceptedInputItemIds = new Set(); readonly #dependencies: OpenAIRealtimeSessionDependencies; readonly #activeResponseIds = new Set(); readonly #listeners = new Set(); readonly #authorizedResponseIds = new Set(); readonly #cancelledCanonicalResponseIds = new Set(); readonly #cancelledSpeechRequestIds = new Set(); + readonly #cancelOutputAwaitingRequestIds = new Set(); + readonly #cancelOutputAwaitingResponseIds = new Set(); readonly #canonicalResponseIds = new Set(); readonly #canonicalSpeechQueue: CanonicalSpeechRequest[] = []; readonly #completedResponseCancelEventIds = new Set(); readonly #pendingClientEvents = new Map(); readonly #pendingSpeechRequests = new Map(); + readonly #playbackOverlappingInputItemIds = new Set(); readonly #remoteStreams = new Set(); + readonly #speechRequestIds = new Map(); readonly #speechTimings = new Map(); + readonly #terminalCanonicalResponseIds = new Set(); readonly #transcriptionTimings = new Map(); #abortController: AbortController | null = null; #activeEpoch: number | null = null; @@ -207,6 +208,10 @@ export class OpenAIRealtimeSession { #connected = false; #connectedAt: number | null = null; #clientEventSequence = 0; + #cancelOutputAwaitingInputBufferClear = false; + #cancelOutputAwaitingOutputBufferClear = false; + #cancelOutputPromise: Promise | null = null; + #cancelOutputResolve: (() => void) | null = null; #connectionRequestId: string | null = null; #dataChannel: RTCDataChannel | null = null; #epoch = 0; @@ -216,6 +221,7 @@ export class OpenAIRealtimeSession { #meterHasSample = false; #meterLevel = 0; #meterSamples: Uint8Array | null = null; + #microphoneRequested = false; #microphoneTrack: MediaStreamTrack | null = null; #peerConnection: RTCPeerConnection | null = null; #remoteAudio: RemoteAudio | null = null; @@ -386,73 +392,83 @@ export class OpenAIRealtimeSession { } public setMicrophoneEnabled(enabled: boolean): void { - if (!this.#microphoneTrack) { - return; - } - const isEnabled = enabled && this.#connected; - this.#microphoneTrack.enabled = isEnabled; - if (isEnabled) { - this.#startMeter(); - } else { - this.#stopMeter(); - } + this.#microphoneRequested = enabled && this.#connected; + this.#syncMicrophoneTrack(); } public speakCanonical(segments: CanonicalSpeechSegment[]): void { this.#requestCanonicalSpeech(segments, true); } - public completeFunctionCall( - callId: string, - segments: CanonicalSpeechSegment[], - ): void { - if (!callId) { - throw new VoiceError("speech", "invalid-response", ""); + public cancelOutput(): Promise { + if (!this.#connected || this.#dataChannel?.readyState !== "open") { + return Promise.resolve(); } - const responseText = this.#canonicalResponseText(segments); - this.#send({ - type: "conversation.item.create", - item: { - type: "function_call_output", - call_id: callId, - output: JSON.stringify({ response_text: responseText }), - }, + if (this.#cancelOutputPromise) { + return this.#cancelOutputPromise; + } + + const cancelOutputPromise = new Promise((resolve) => { + this.#cancelOutputResolve = resolve; }); - this.#requestCanonicalSpeech(segments, false); - } + this.#cancelOutputPromise = cancelOutputPromise; + this.#cancelOutputAwaitingInputBufferClear = true; + this.#cancelOutputAwaitingOutputBufferClear = + this.#authorizedResponseIds.size > 0 || + this.#terminalCanonicalResponseIds.size > 0 || + this.#speakingResponseId !== null; + for (const itemId of this.#acceptedInputItemIds) { + this.#playbackOverlappingInputItemIds.add(itemId); + } + this.#acceptedInputItemIds.clear(); + this.#syncMicrophoneTrack(); - public cancelOutput(): void { - if (!this.#connected || this.#dataChannel?.readyState !== "open") { - return; - } + try { + this.#send({ type: "input_audio_buffer.clear" }); - for (const request of this.#canonicalSpeechQueue.splice(0)) { - this.#cancelPendingSpeechRequest(request.speechRequestId); - } + for (const request of this.#canonicalSpeechQueue.splice(0)) { + this.#cancelPendingSpeechRequest(request.speechRequestId); + } - if (this.#responseCreateEventId !== null) { - const pendingEvent = this.#pendingClientEvents.get( - this.#responseCreateEventId, - ); - if (pendingEvent?.kind === "response-create") { - this.#cancelledSpeechRequestIds.add( - pendingEvent.request.speechRequestId, + if (this.#responseCreateEventId !== null) { + const pendingEvent = this.#pendingClientEvents.get( + this.#responseCreateEventId, ); + if (pendingEvent?.kind === "response-create") { + this.#cancelledSpeechRequestIds.add( + pendingEvent.request.speechRequestId, + ); + this.#cancelOutputAwaitingRequestIds.add( + pendingEvent.request.speechRequestId, + ); + } } - } - for (const responseId of this.#canonicalResponseIds) { - if ( - this.#activeResponseIds.has(responseId) && - !this.#cancelledCanonicalResponseIds.has(responseId) - ) { - this.#cancelledCanonicalResponseIds.add(responseId); - this.#cancelOutputResponse(responseId); + for (const responseId of this.#canonicalResponseIds) { + if ( + this.#activeResponseIds.has(responseId) && + !this.#cancelledCanonicalResponseIds.has(responseId) + ) { + this.#cancelOutputAwaitingResponseIds.add(responseId); + this.#cancelledCanonicalResponseIds.add(responseId); + this.#cancelResponse(responseId); + } } + + this.#send({ type: "output_audio_buffer.clear" }); + } catch { + this.#finishOutputCancellation(true); + this.#handleConnectionFailure("network", "speech"); } + + this.#finishOutputCancellation(); + return cancelOutputPromise; } #cancelOutputResponse(responseId: string): void { + if (this.#cancelOutputPromise) { + this.#cancelOutputAwaitingOutputBufferClear = true; + } this.#cancelResponse(responseId); this.#send({ type: "output_audio_buffer.clear" }); } @@ -464,9 +480,12 @@ export class OpenAIRealtimeSession { #canonicalResponseText(segments: CanonicalSpeechSegment[]): string[] { const responseText = segments .slice(0, MAX_CANONICAL_SEGMENTS) - .map(({ text }) => text.trim()) - .filter(Boolean); - if (responseText.length === 0 || responseText.length !== segments.length) { + .map(({ text }) => text); + if ( + responseText.length === 0 || + responseText.length !== segments.length || + responseText.some((text) => text.trim().length === 0) + ) { throw new VoiceError("speech", "invalid-response", ""); } return responseText; @@ -567,15 +586,28 @@ export class OpenAIRealtimeSession { request, responseTerminalSequence: this.#responseTerminalSequence, }); + for (const itemId of this.#acceptedInputItemIds) { + this.#playbackOverlappingInputItemIds.add(itemId); + } + this.#acceptedInputItemIds.clear(); + this.#syncMicrophoneTrack(); try { this.#send({ event_id: eventId, response: request.response, type: "response.create", }); + if (this.#activeEpoch !== null) { + this.#emit({ + connectionEpoch: this.#activeEpoch, + speechRequestId: request.speechRequestId, + type: "canonical-speech-requested", + }); + } } catch (error) { this.#responseCreateEventId = null; this.#pendingClientEvents.delete(eventId); + this.#syncMicrophoneTrack(); throw error; } } @@ -604,6 +636,12 @@ export class OpenAIRealtimeSession { this.#handleResponseDone(parsed, connectionEpoch); return; } + if (parsed.type === "input_audio_buffer.cleared") { + this.#acceptedInputItemIds.clear(); + this.#cancelOutputAwaitingInputBufferClear = false; + this.#finishOutputCancellation(); + return; + } if (parsed.type === "input_audio_buffer.committed") { const itemId = nonEmptyString(parsed.item_id); if (itemId) this.#startTranscription(itemId); @@ -612,23 +650,22 @@ export class OpenAIRealtimeSession { if (parsed.type === "input_audio_buffer.speech_started") { const itemId = nonEmptyString(parsed.item_id); if (!itemId || nonNegativeInteger(parsed.audio_start_ms) === null) return; + if (this.#speakingResponseId || !this.#microphoneTrack?.enabled) { + this.#playbackOverlappingInputItemIds.add(itemId); + return; + } + this.#acceptedInputItemIds.add(itemId); this.#emit({ connectionEpoch, itemId, type: "input-speech-started", }); - if (this.#speakingResponseId) { - this.#emit({ - connectionEpoch, - responseId: this.#speakingResponseId, - type: "output-interrupted", - }); - } return; } if (parsed.type === "input_audio_buffer.speech_stopped") { const itemId = nonEmptyString(parsed.item_id); if (!itemId || nonNegativeInteger(parsed.audio_end_ms) === null) return; + if (this.#playbackOverlappingInputItemIds.has(itemId)) return; this.#emit({ connectionEpoch, itemId, @@ -638,15 +675,12 @@ export class OpenAIRealtimeSession { } if ( parsed.type === "output_audio_buffer.started" || - parsed.type === "output_audio_buffer.stopped" + parsed.type === "output_audio_buffer.stopped" || + parsed.type === "output_audio_buffer.cleared" ) { this.#handleOutputBufferEvent(parsed, connectionEpoch); return; } - if (parsed.type === "response.function_call_arguments.delta") { - this.#handleToolEvent(parsed, connectionEpoch); - return; - } if ( parsed.type === "conversation.item.input_audio_transcription.delta" || parsed.type === "conversation.item.input_audio_transcription.completed" || @@ -668,6 +702,9 @@ export class OpenAIRealtimeSession { if (metadata?.petrinaut_kind !== "canonical-speech" || !speechRequestId) { return; } + if (this.#cancelOutputAwaitingRequestIds.delete(speechRequestId)) { + this.#cancelOutputAwaitingResponseIds.add(responseId); + } this.#completeResponseCreateEvent(speechRequestId); this.#canonicalResponseIds.add(responseId); if (this.#cancelledSpeechRequestIds.delete(speechRequestId)) { @@ -682,6 +719,7 @@ export class OpenAIRealtimeSession { } this.#pendingSpeechRequests.delete(speechRequestId); this.#authorizedResponseIds.add(responseId); + this.#speechRequestIds.set(responseId, speechRequestId); this.#speechTimings.set(responseId, timing); } @@ -722,6 +760,10 @@ export class OpenAIRealtimeSession { ) { this.#pendingClientEvents.delete(sourceEventId); this.#completedResponseCancelEventIds.delete(sourceEventId); + if (pendingEvent?.kind === "response-cancel") { + this.#cancelOutputAwaitingResponseIds.delete(pendingEvent.responseId); + this.#finishOutputCancellation(); + } return; } @@ -740,7 +782,11 @@ export class OpenAIRealtimeSession { pendingEvent.request.speechRequestId, ) ) { + this.#cancelOutputAwaitingRequestIds.delete( + pendingEvent.request.speechRequestId, + ); this.#cancelPendingSpeechRequest(pendingEvent.request.speechRequestId); + this.#finishOutputCancellation(); return; } this.#canonicalSpeechQueue.unshift(pendingEvent.request); @@ -773,77 +819,54 @@ export class OpenAIRealtimeSession { this.#handleConnectionFailure("invalid-response", "connection"); return; } + const terminalStatus = status as ResponseTerminalStatus; this.#responseTerminalSequence += 1; this.#activeResponseIds.delete(responseId); + this.#cancelOutputAwaitingResponseIds.delete(responseId); + this.#finishOutputCancellation(); this.#clearResponseCancelEvents(responseId); this.#waitingForResponseTerminal = false; + const speechRequestId = this.#speechRequestIds.get(responseId); + const terminalEvent = { + connectionEpoch, + responseId, + ...(speechRequestId === undefined ? {} : { speechRequestId }), + status: terminalStatus, + type: "response-terminal" as const, + }; if (this.#cancelledCanonicalResponseIds.delete(responseId)) { - this.#emit({ - connectionEpoch, - responseId, - status, - type: "response-terminal", - }); + if (this.#speakingResponseId === responseId) { + this.#emit({ + connectionEpoch, + responseId, + type: "output-interrupted", + }); + } + this.#emit(terminalEvent); this.#finishSpeech(responseId, "request-aborted"); this.#resumeCanonicalSpeechQueue(); return; } - if (status === "completed") { + if (terminalStatus === "completed") { const output = response.output; if (!Array.isArray(output)) { this.#handleConnectionFailure("invalid-response", "connection"); return; } - const functionCalls = output - .map(asRecord) - .filter( - (item): item is Record => - item?.type === "function_call", - ); - if ( - functionCalls.length > 1 || - (functionCalls.length > 0 && this.#canonicalResponseIds.has(responseId)) - ) { + if (output.some((item) => asRecord(item)?.type === "function_call")) { this.#handleConnectionFailure("invalid-response", "connection"); return; } - for (const item of functionCalls) { - const argumentsJson = nonEmptyString(item.arguments); - const callId = nonEmptyString(item.call_id); - const itemId = nonEmptyString(item.id); - const name = nonEmptyString(item.name); - if ( - !argumentsJson || - !callId || - !itemId || - !name || - (item.status !== undefined && item.status !== "completed") - ) { - this.#handleConnectionFailure("invalid-response", "connection"); - return; - } - this.#emit({ - arguments: argumentsJson, - callId, - connectionEpoch, - itemId, - name, - responseId, - type: "tool-arguments-done", - }); + if (this.#authorizedResponseIds.has(responseId)) { + this.#terminalCanonicalResponseIds.add(responseId); } - this.#emit({ - connectionEpoch, - responseId, - status, - type: "response-terminal", - }); + this.#emit(terminalEvent); this.#resumeCanonicalSpeechQueue(); return; } - if (status === "cancelled") { + if (terminalStatus === "cancelled") { if (this.#speakingResponseId === responseId) { this.#emit({ connectionEpoch, @@ -851,22 +874,12 @@ export class OpenAIRealtimeSession { type: "output-interrupted", }); } - this.#emit({ - connectionEpoch, - responseId, - status, - type: "response-terminal", - }); + this.#emit(terminalEvent); this.#finishSpeech(responseId, "request-aborted"); this.#resumeCanonicalSpeechQueue(); return; } - this.#emit({ - connectionEpoch, - responseId, - status, - type: "response-terminal", - }); + this.#emit(terminalEvent); if (this.#authorizedResponseIds.has(responseId)) { this.#finishSpeech(responseId, "invalid-response"); } @@ -901,6 +914,9 @@ export class OpenAIRealtimeSession { if (!responseId) return; if (event.type === "output_audio_buffer.started") { if (this.#cancelledCanonicalResponseIds.has(responseId)) { + if (this.#cancelOutputPromise) { + this.#cancelOutputAwaitingOutputBufferClear = true; + } this.#send({ type: "output_audio_buffer.clear" }); return; } @@ -909,40 +925,49 @@ export class OpenAIRealtimeSession { this.#handleConnectionFailure("invalid-response", "connection"); return; } + for (const itemId of this.#acceptedInputItemIds) { + this.#playbackOverlappingInputItemIds.add(itemId); + } + this.#acceptedInputItemIds.clear(); this.#speakingResponseId = responseId; - this.#emit({ connectionEpoch, responseId, type: "output-started" }); + this.#syncMicrophoneTrack(); + const speechRequestId = this.#speechRequestIds.get(responseId); + if (!speechRequestId) { + this.#handleConnectionFailure("invalid-response", "connection"); + return; + } + this.#emit({ + connectionEpoch, + responseId, + speechRequestId, + type: "output-started", + }); return; } const wasSpeaking = this.#speakingResponseId === responseId; + const wasCleared = event.type === "output_audio_buffer.cleared"; this.#finishSpeech( responseId, - this.#cancelledCanonicalResponseIds.has(responseId) + wasCleared || this.#cancelledCanonicalResponseIds.has(responseId) ? "request-aborted" : undefined, ); + if (wasCleared && this.#cancelOutputAwaitingOutputBufferClear) { + for (const terminalResponseId of this.#terminalCanonicalResponseIds) { + this.#finishSpeech(terminalResponseId, "request-aborted"); + } + } if (wasSpeaking) { - this.#emit({ connectionEpoch, responseId, type: "output-stopped" }); + this.#emit({ + connectionEpoch, + responseId, + type: wasCleared ? "output-interrupted" : "output-stopped", + }); + } + if (wasCleared && this.#cancelOutputAwaitingOutputBufferClear) { + this.#cancelOutputAwaitingOutputBufferClear = false; + this.#finishOutputCancellation(); } - } - - #handleToolEvent( - event: Record, - connectionEpoch: number, - ): void { - const callId = nonEmptyString(event.call_id); - const itemId = nonEmptyString(event.item_id); - const responseId = nonEmptyString(event.response_id); - const outputIndex = nonNegativeInteger(event.output_index); - if (!callId || !itemId || !responseId || outputIndex === null) return; - if (typeof event.delta !== "string") return; - this.#emit({ - callId, - connectionEpoch, - delta: event.delta, - itemId, - responseId, - type: "tool-arguments-delta", - }); } #handleTranscriptEvent( @@ -953,9 +978,29 @@ export class OpenAIRealtimeSession { const contentIndex = nonNegativeInteger(event.content_index); if (!itemId || contentIndex === null) return; const key = { connectionEpoch, contentIndex, itemId }; + const overlapsPlayback = + this.#playbackOverlappingInputItemIds.has(itemId) || + !this.#acceptedInputItemIds.has(itemId); + if (overlapsPlayback) { + if ( + event.type === + "conversation.item.input_audio_transcription.completed" || + event.type === "conversation.item.input_audio_transcription.failed" + ) { + this.#finishTranscription( + itemId, + event.type === "conversation.item.input_audio_transcription.failed" + ? "invalid-response" + : undefined, + ); + this.#acceptedInputItemIds.delete(itemId); + } + return; + } this.#startTranscription(itemId); if (event.type === "conversation.item.input_audio_transcription.failed") { this.#finishTranscription(itemId, "invalid-response"); + this.#acceptedInputItemIds.delete(itemId); this.#emit({ key, type: "transcription-failed" }); return; } @@ -968,6 +1013,7 @@ export class OpenAIRealtimeSession { event.type === "conversation.item.input_audio_transcription.completed" ) { this.#finishTranscription(itemId); + this.#acceptedInputItemIds.delete(itemId); } this.#emit({ key, @@ -1004,10 +1050,36 @@ export class OpenAIRealtimeSession { errorCode, ); } + this.#speechRequestIds.delete(responseId); this.#authorizedResponseIds.delete(responseId); + this.#terminalCanonicalResponseIds.delete(responseId); if (this.#speakingResponseId === responseId) { this.#speakingResponseId = null; } + this.#syncMicrophoneTrack(); + } + + #finishOutputCancellation(force = false): void { + if ( + !this.#cancelOutputPromise || + (!force && + (this.#cancelOutputAwaitingInputBufferClear || + this.#cancelOutputAwaitingOutputBufferClear || + this.#cancelOutputAwaitingRequestIds.size > 0 || + this.#cancelOutputAwaitingResponseIds.size > 0)) + ) { + return; + } + + const resolve = this.#cancelOutputResolve; + this.#cancelOutputPromise = null; + this.#cancelOutputResolve = null; + this.#cancelOutputAwaitingInputBufferClear = false; + this.#cancelOutputAwaitingOutputBufferClear = false; + this.#cancelOutputAwaitingRequestIds.clear(); + this.#cancelOutputAwaitingResponseIds.clear(); + this.#syncMicrophoneTrack(); + resolve?.(); } #emit(event: OpenAIRealtimeSessionEvent): void { @@ -1188,6 +1260,26 @@ export class OpenAIRealtimeSession { this.#meterFrame = this.#dependencies.requestAnimationFrame(sample); } + #syncMicrophoneTrack(): void { + if (!this.#microphoneTrack) { + return; + } + const enabled = + this.#microphoneRequested && + this.#connected && + this.#cancelOutputPromise === null && + this.#authorizedResponseIds.size === 0 && + this.#canonicalSpeechQueue.length === 0 && + this.#responseCreateEventId === null && + this.#speakingResponseId === null; + this.#microphoneTrack.enabled = enabled; + if (enabled) { + this.#startMeter(); + } else { + this.#stopMeter(); + } + } + #stopMeter(): void { if (this.#meterFrame === null) return; this.#dependencies.cancelAnimationFrame(this.#meterFrame); @@ -1277,19 +1369,26 @@ export class OpenAIRealtimeSession { ); } this.#transcriptionTimings.clear(); + this.#acceptedInputItemIds.clear(); this.#activeResponseIds.clear(); this.#cancelledCanonicalResponseIds.clear(); this.#cancelledSpeechRequestIds.clear(); + this.#cancelOutputAwaitingRequestIds.clear(); + this.#cancelOutputAwaitingResponseIds.clear(); this.#canonicalSpeechQueue.length = 0; this.#completedResponseCancelEventIds.clear(); this.#pendingClientEvents.clear(); this.#pendingSpeechRequests.clear(); + this.#playbackOverlappingInputItemIds.clear(); this.#speechTimings.clear(); + this.#speechRequestIds.clear(); + this.#terminalCanonicalResponseIds.clear(); this.#authorizedResponseIds.clear(); this.#canonicalResponseIds.clear(); this.#responseCreateEventId = null; this.#responseTerminalSequence = 0; this.#speakingResponseId = null; + this.#microphoneRequested = false; this.#waitingForResponseTerminal = false; this.#activeEpoch = null; this.#connected = false; @@ -1336,6 +1435,7 @@ export class OpenAIRealtimeSession { this.#mediaStream = null; } this.#microphoneTrack = null; + this.#finishOutputCancellation(true); } #waitForDataChannelOpen( diff --git a/apps/petrinaut-website/src/main/app/voice-interview/realtime-brunch-bridge.test.ts b/apps/petrinaut-website/src/main/app/voice-interview/realtime-brunch-bridge.test.ts index a723f2dfe5a..3f2596e316d 100644 --- a/apps/petrinaut-website/src/main/app/voice-interview/realtime-brunch-bridge.test.ts +++ b/apps/petrinaut-website/src/main/app/voice-interview/realtime-brunch-bridge.test.ts @@ -1,5 +1,7 @@ import { describe, expect, test, vi } from "vitest"; +import { FlueChatAdmissionError } from "@hashintel/brunch-agent-transport-aisdk"; + import { createRealtimeSubmissionId, RealtimeBrunchBridge, @@ -7,25 +9,63 @@ import { } from "./realtime-brunch-bridge"; import type { CanonicalSpeechSegment } from "./canonical-speech"; -import type { OpenAIRealtimeSessionEvent } from "./openai-realtime-session"; +import type { + OpenAIRealtimeSessionEvent, + OpenAIRealtimeTranscriptKey, +} from "./openai-realtime-session"; const segment = ( id: string, text: string, - source: CanonicalSpeechSegment["source"] = "brunch-ask", + submissionId?: string, ): CanonicalSpeechSegment => ({ contentHash: "fnv1a32:12345678", id, messageId: `message-${id}`, partId: id, - source, + source: "assistant-text", + ...(submissionId === undefined ? {} : { submissionIds: [submissionId] }), + text, +}); + +const transcriptKey = ( + connectionEpoch: number, + itemId = "user-item-1", + contentIndex = 0, +): OpenAIRealtimeTranscriptKey => ({ connectionEpoch, contentIndex, itemId }); + +const completedTranscript = ( + connectionEpoch: number, + text = "The supervisor approves it.", + itemId = "user-item-1", + contentIndex = 0, +): Extract => ({ + key: transcriptKey(connectionEpoch, itemId, contentIndex), text, + type: "completed", +}); + +const failedTranscript = ( + connectionEpoch: number, + itemId = "user-item-1", +): Extract => ({ + key: transcriptKey(connectionEpoch, itemId), + type: "transcription-failed", +}); + +const completedResponseMessage = ( + messageId: string, + submissionId: string, + index: number, +) => ({ + messageId, + position: { batch: 1, index }, + submissionId, }); const createHarness = () => { let listener: ((event: OpenAIRealtimeSessionEvent) => void) | undefined; const session = { - completeFunctionCall: vi.fn(), speakCanonical: vi.fn(), subscribe: vi.fn((next: (event: OpenAIRealtimeSessionEvent) => void) => { listener = next; @@ -34,15 +74,18 @@ const createHarness = () => { }; }), }; - const submitInterviewAnswer = vi.fn( - async (): Promise< - | { kind: "interactive-tool"; toolCallId: string } - | { kind: "message"; messageId: string } - > => ({ - kind: "interactive-tool", - toolCallId: "ask-current", - }), - ); + const submitInterviewAnswer = vi.fn< + ConstructorParameters< + typeof RealtimeBrunchBridge + >[0]["submitInterviewAnswer"] + >(async (input) => { + input.onAdmission("submission-voice-1"); + return { + kind: "message", + messageId: input.id, + submissionId: "submission-voice-1", + }; + }); const bridge = new RealtimeBrunchBridge({ session, submitInterviewAnswer, @@ -59,422 +102,808 @@ const createHarness = () => { }; }; -const toolDelta = ( - connectionEpoch: number, - delta: string, -): Extract => ({ - callId: "call-1", - connectionEpoch, - delta, - itemId: "function-item-1", - responseId: "response-1", - type: "tool-arguments-delta", -}); - -const toolDone = ( - connectionEpoch: number, - argumentsJson = '{"answer":"The supervisor approves it."}', -): Extract => ({ - arguments: argumentsJson, - callId: "call-1", - connectionEpoch, - itemId: "function-item-1", - name: "continue_interview", - responseId: "response-1", - type: "tool-arguments-done", -}); - -const responseTerminal = ( - connectionEpoch: number, - status: "cancelled" | "completed" | "failed" | "incomplete", - responseId = "response-1", -): Extract => ({ - connectionEpoch, - responseId, - status, - type: "response-terminal", -}); +const startReady = ( + harness: ReturnType, + connectionEpoch = 3, +): void => { + harness.bridge.updateChat({ + canAcceptInterviewAnswer: true, + canonicalSegments: [], + status: "ready", + }); + harness.bridge.start(connectionEpoch); +}; describe("RealtimeBrunchBridge", () => { - test("speaks the current canonical turn without replaying history", () => { + test("rehydrates settled canonical speech without submission or playback", () => { const harness = createHarness(); - const historical = segment( - "history", - "Do not replay this.", - "assistant-text", - ); - const preamble = { - ...segment("preamble", "Thanks. One more question.", "assistant-text"), - messageId: "message-current-turn", - }; - const question = { - ...segment("ask-current", "What happens after approval?"), - messageId: "message-current-turn", - }; harness.bridge.updateChat({ canAcceptInterviewAnswer: true, - canonicalSegments: [historical, preamble, question], + canonicalSegments: [ + segment("settled", "Already delivered.", "submission-settled"), + ], status: "ready", }); - harness.bridge.start(4); + harness.bridge.start(9); - expect(harness.session.speakCanonical).toHaveBeenCalledOnce(); - expect(harness.session.speakCanonical).toHaveBeenCalledWith([ - preamble, - question, - ]); + expect(harness.submitInterviewAnswer).not.toHaveBeenCalled(); + expect(harness.session.speakCanonical).not.toHaveBeenCalled(); + expect(harness.events).toEqual([]); }); - test("streams and validates one tool call, preserves ask correlation, and waits for canonical Brunch output", async () => { + test("does not dispatch canonical updates that arrive during output cancellation", () => { const harness = createHarness(); - const question = segment("ask-current", "What happens after approval?"); - harness.bridge.updateChat({ - canAcceptInterviewAnswer: true, - canonicalSegments: [question], - status: "ready", - }); - harness.bridge.start(7); - harness.session.speakCanonical.mockClear(); - - harness.emit(toolDelta(7, '{"answer":"The supervisor')); - harness.emit(toolDelta(7, ' approves it."}')); - harness.emit(toolDone(7)); - - await vi.waitFor(() => - expect(harness.submitInterviewAnswer).toHaveBeenCalledOnce(), + startReady(harness); + const cancelledSegment = segment( + "cancelled-update", + "Do not speak this cancelled update.", ); - expect(harness.submitInterviewAnswer).toHaveBeenCalledWith({ - id: createRealtimeSubmissionId(7, "call-1"), - text: "The supervisor approves it.", - }); - expect(harness.session.completeFunctionCall).not.toHaveBeenCalled(); + harness.bridge.cancelPendingSpeech(); harness.bridge.updateChat({ canAcceptInterviewAnswer: false, - canonicalSegments: [question], + canonicalSegments: [cancelledSegment], status: "streaming", }); - const acknowledgement = segment( - "acknowledgement", - "Thanks. I have recorded that.", - "assistant-text", - ); - const nextQuestion = segment( - "ask-next", - "Who is informed next?", - "brunch-ask", - ); + + expect(harness.session.speakCanonical).not.toHaveBeenCalled(); + + harness.bridge.completeTurnHandoff(); + const laterSegment = segment("later-update", "Speak this later update."); harness.bridge.updateChat({ canAcceptInterviewAnswer: true, - canonicalSegments: [question, acknowledgement, nextQuestion], + canonicalSegments: [cancelledSegment, laterSegment], status: "ready", }); + expect(harness.session.speakCanonical).toHaveBeenCalledOnce(); + expect(harness.session.speakCanonical).toHaveBeenCalledWith([laterSegment]); + }); + + test("submits only a completed transcript through the user admission target", async () => { + const harness = createHarness(); + startReady(harness, 7); + const key = transcriptKey(7); + + harness.emit({ key, text: "The supervisor", type: "partial" }); + harness.emit({ + arguments: '{"answer":"Fabricated answer"}', + callId: "legacy-call", + connectionEpoch: 7, + itemId: "legacy-item", + name: "continue_interview", + responseId: "legacy-response", + type: "tool-arguments-done", + } as unknown as OpenAIRealtimeSessionEvent); + expect(harness.submitInterviewAnswer).not.toHaveBeenCalled(); + + harness.emit(completedTranscript(7, " The supervisor\napproves it. ")); + await vi.waitFor(() => - expect(harness.session.completeFunctionCall).toHaveBeenCalledWith( - "call-1", - [acknowledgement, nextQuestion], - ), + expect(harness.submitInterviewAnswer).toHaveBeenCalledOnce(), ); - expect(harness.events.map(({ type }) => type)).toEqual([ - "submission-started", - "submission-accepted", - "canonical-response-ready", - ]); + const deliveryId = createRealtimeSubmissionId(key); + expect(harness.submitInterviewAnswer).toHaveBeenCalledWith( + expect.objectContaining({ + admissionTarget: { kind: "user", messageId: deliveryId }, + id: deliveryId, + text: "The supervisor approves it.", + }), + ); + expect(harness.events).toContainEqual({ + answer: "The supervisor approves it.", + deliveryId, + type: "submission-started", + }); + expect(JSON.stringify(harness.events)).not.toContain("Fabricated answer"); }); - test("uses the first spoken turn to start Brunch when no question exists", async () => { + test("rejects unfinished input invalidated by output and accepts fresh input", async () => { const harness = createHarness(); - harness.submitInterviewAnswer.mockResolvedValueOnce({ - kind: "message", - messageId: "message-kickoff", + startReady(harness); + + harness.emit({ + connectionEpoch: 3, + itemId: "item-before-output", + type: "input-speech-started", }); - harness.bridge.updateChat({ - canAcceptInterviewAnswer: true, - canonicalSegments: [], - status: "ready", + harness.emit({ + connectionEpoch: 3, + responseId: "response-output", + speechRequestId: "speech-output", + type: "output-started", }); - harness.bridge.start(7); + harness.emit( + completedTranscript(3, "This completed too late.", "item-before-output"), + ); - harness.emit(toolDone(7, '{"answer":"Battery charger workflow"}')); + expect(harness.submitInterviewAnswer).not.toHaveBeenCalled(); + expect(harness.events).toContainEqual({ + reason: "unavailable", + type: "transcript-rejected", + }); + harness.emit({ + connectionEpoch: 3, + responseId: "response-output", + type: "output-stopped", + }); + harness.emit({ + connectionEpoch: 3, + itemId: "item-after-output", + type: "input-speech-started", + }); + harness.emit(completedTranscript(3, "This is fresh.", "item-after-output")); await vi.waitFor(() => - expect(harness.submitInterviewAnswer).toHaveBeenCalledWith({ - id: createRealtimeSubmissionId(7, "call-1"), - text: "Battery charger workflow", - }), + expect(harness.submitInterviewAnswer).toHaveBeenCalledOnce(), ); - harness.bridge.updateChat({ - canAcceptInterviewAnswer: false, - canonicalSegments: [], - status: "submitted", + expect(harness.submitInterviewAnswer).toHaveBeenCalledWith( + expect.objectContaining({ text: "This is fresh." }), + ); + + harness.emit(completedTranscript(3, "Stale replay.", "item-before-output")); + expect(harness.submitInterviewAnswer).toHaveBeenCalledOnce(); + }); + + test("rejects unfinished input as soon as canonical speech is requested", async () => { + const harness = createHarness(); + startReady(harness); + + harness.emit({ + connectionEpoch: 3, + itemId: "item-before-request", + type: "input-speech-started", + }); + harness.emit({ + connectionEpoch: 3, + speechRequestId: "speech-request", + type: "canonical-speech-requested", }); - const firstQuestion = segment( - "ask-first", - "What starts the battery charger workflow?", + harness.emit( + completedTranscript( + 3, + "This completed before output started.", + "item-before-request", + ), ); - harness.bridge.updateChat({ - canAcceptInterviewAnswer: true, - canonicalSegments: [firstQuestion], - status: "ready", + + expect(harness.submitInterviewAnswer).not.toHaveBeenCalled(); + expect(harness.events).toContainEqual({ + reason: "unavailable", + type: "transcript-rejected", }); - expect(harness.session.completeFunctionCall).toHaveBeenCalledWith( - "call-1", - [firstQuestion], + harness.emit( + completedTranscript( + 3, + "The stale item cannot recover authority.", + "item-before-request", + ), ); - expect(harness.events.map(({ type }) => type)).toEqual([ - "submission-started", - "submission-accepted", - "canonical-response-ready", - ]); - }); + expect(harness.submitInterviewAnswer).not.toHaveBeenCalled(); - test("requires a correlated Brunch busy cycle before accepting new canonical segments", async () => { - const harness = createHarness(); - const question = segment("ask-current", "What happens after approval?"); - harness.bridge.updateChat({ - canAcceptInterviewAnswer: true, - canonicalSegments: [question], - status: "ready", + harness.bridge.completeTurnHandoff(); + harness.emit({ + connectionEpoch: 3, + itemId: "item-after-handoff", + type: "input-speech-started", }); - harness.bridge.start(7); - harness.emit(toolDone(7)); + harness.emit( + completedTranscript(3, "This is fresh.", "item-after-handoff"), + ); + await vi.waitFor(() => expect(harness.submitInterviewAnswer).toHaveBeenCalledOnce(), ); - const unrelated = segment( - "unrelated", - "An unrelated canonical update.", - "assistant-text", + expect(harness.submitInterviewAnswer).toHaveBeenCalledWith( + expect.objectContaining({ text: "This is fresh." }), ); + }); - harness.bridge.updateChat({ - canAcceptInterviewAnswer: true, - canonicalSegments: [question, unrelated], - status: "ready", + test("retains follow-on output ownership across an earlier response stop", async () => { + const harness = createHarness(); + startReady(harness); + harness.emit({ + connectionEpoch: 3, + speechRequestId: "speech-early", + type: "canonical-speech-requested", + }); + harness.emit({ + connectionEpoch: 3, + responseId: "response-early", + speechRequestId: "speech-early", + type: "output-started", + }); + harness.emit({ + connectionEpoch: 3, + responseId: "response-early", + status: "completed", + type: "response-terminal", + }); + harness.emit({ + connectionEpoch: 3, + speechRequestId: "speech-follow-on", + type: "canonical-speech-requested", + }); + harness.emit({ + connectionEpoch: 3, + responseId: "response-follow-on", + speechRequestId: "speech-follow-on", + status: "completed", + type: "response-terminal", + }); + harness.emit({ + connectionEpoch: 3, + responseId: "response-early", + type: "output-stopped", }); - expect(harness.session.completeFunctionCall).not.toHaveBeenCalled(); + harness.emit({ + connectionEpoch: 3, + itemId: "item-during-follow-on", + type: "input-speech-started", + }); + harness.emit( + completedTranscript( + 3, + "This overlaps pending follow-on output.", + "item-during-follow-on", + ), + ); - harness.bridge.updateChat({ - canAcceptInterviewAnswer: false, - canonicalSegments: [question, unrelated], - status: "submitted", + expect(harness.submitInterviewAnswer).not.toHaveBeenCalled(); + expect(harness.events).toContainEqual({ + reason: "unavailable", + type: "transcript-rejected", }); - harness.bridge.updateChat({ - canAcceptInterviewAnswer: true, - canonicalSegments: [question, unrelated], - status: "ready", + + harness.bridge.completeTurnHandoff(); + harness.emit({ + connectionEpoch: 3, + itemId: "item-after-handoff", + type: "input-speech-started", }); + harness.emit( + completedTranscript(3, "This is fresh.", "item-after-handoff"), + ); - expect(harness.session.completeFunctionCall).toHaveBeenCalledWith( - "call-1", - [unrelated], + await vi.waitFor(() => + expect(harness.submitInterviewAnswer).toHaveBeenCalledOnce(), + ); + expect(harness.submitInterviewAnswer).toHaveBeenCalledWith( + expect.objectContaining({ text: "This is fresh." }), ); }); - test("rejects streamed arguments whose response or item identity changes", async () => { + test("releases pending output ownership when cancellation settles before playback", async () => { const harness = createHarness(); - harness.bridge.updateChat({ - canAcceptInterviewAnswer: true, - canonicalSegments: [segment("ask-current", "Question")], - status: "ready", + startReady(harness); + harness.emit({ + connectionEpoch: 3, + speechRequestId: "speech-cancelled", + type: "canonical-speech-requested", }); - harness.bridge.start(3); - harness.emit(toolDelta(3, '{"answer":"Answer"}')); harness.emit({ - ...toolDone(3, '{"answer":"Answer"}'), - responseId: "response-2", + connectionEpoch: 3, + responseId: "response-cancelled", + speechRequestId: "speech-cancelled", + status: "cancelled", + type: "response-terminal", + } as OpenAIRealtimeSessionEvent); + harness.emit({ + connectionEpoch: 3, + itemId: "item-after-cancellation", + type: "input-speech-started", }); - await Promise.resolve(); + harness.emit( + completedTranscript( + 3, + "This follows acknowledged cancellation.", + "item-after-cancellation", + ), + ); - expect(harness.submitInterviewAnswer).not.toHaveBeenCalled(); - expect(harness.events).toEqual([ + await vi.waitFor(() => + expect(harness.submitInterviewAnswer).toHaveBeenCalledOnce(), + ); + expect(harness.submitInterviewAnswer).toHaveBeenCalledWith( expect.objectContaining({ - code: "interview-correlation", - type: "error", + text: "This follows acknowledged cancellation.", }), + ); + }); + + test("derives stable delivery identity from epoch, item, and content index", () => { + expect( + createRealtimeSubmissionId(transcriptKey(12, "item/with spaces", 4)), + ).toBe("voice-realtime:12:item%2Fwith%20spaces:4"); + }); + + test("submits duplicate completed transcript events exactly once", async () => { + const harness = createHarness(); + startReady(harness); + const transcript = completedTranscript(3); + + harness.emit(transcript); + harness.emit(transcript); + + await vi.waitFor(() => + expect(harness.submitInterviewAnswer).toHaveBeenCalledOnce(), + ); + expect(harness.events).toContainEqual({ + reason: "duplicate", + type: "transcript-rejected", + }); + }); + + test.each([ + ["", "empty"], + [" \n\t ", "empty"], + ["a".repeat(32_001), "over-limit"], + ] as const)( + "rejects an invalid completed transcript as %s", + (text, reason) => { + const harness = createHarness(); + startReady(harness); + + harness.emit(completedTranscript(3, text)); + + expect(harness.submitInterviewAnswer).not.toHaveBeenCalled(); + expect(harness.events).toEqual([{ reason, type: "transcript-rejected" }]); + }, + ); + + test("rejects a failed transcript and accepts the next keyed turn", async () => { + const harness = createHarness(); + startReady(harness); + + harness.emit(failedTranscript(3, "failed-item")); + expect(harness.events).toEqual([ + { reason: "failed", type: "transcript-rejected" }, ]); + + harness.emit(completedTranscript(3, "Retried answer.", "retry-item")); + await vi.waitFor(() => + expect(harness.submitInterviewAnswer).toHaveBeenCalledWith( + expect.objectContaining({ text: "Retried answer." }), + ), + ); }); - test("rejects concurrent argument streams before either can submit", async () => { + test("rejects completed transcripts while the shared submission path is unavailable", () => { const harness = createHarness(); harness.bridge.updateChat({ - canAcceptInterviewAnswer: true, - canonicalSegments: [segment("ask-current", "Question")], - status: "ready", + canAcceptInterviewAnswer: false, + canonicalSegments: [], + status: "streaming", }); harness.bridge.start(3); - harness.emit(toolDelta(3, '{"answer":"First"}')); - harness.emit({ - ...toolDelta(3, '{"answer":"Second"}'), - callId: "call-2", - itemId: "function-item-2", - }); + harness.emit(completedTranscript(3)); expect(harness.submitInterviewAnswer).not.toHaveBeenCalled(); expect(harness.events).toEqual([ - expect.objectContaining({ type: "error" }), + { reason: "unavailable", type: "transcript-rejected" }, ]); }); - test("discards a cancelled argument stream without poisoning the next answer", async () => { + test("ignores transcripts from an inactive connection epoch", () => { + const harness = createHarness(); + startReady(harness, 2); + + harness.emit(completedTranscript(1, "Stale answer")); + harness.emit(failedTranscript(1, "stale-failed")); + + expect(harness.submitInterviewAnswer).not.toHaveBeenCalled(); + expect(harness.events).toEqual([]); + }); + + test("correlates the admitted submission with exact canonical response segments", async () => { const harness = createHarness(); + startReady(harness, 7); + harness.emit(completedTranscript(7)); + await vi.waitFor(() => + expect(harness.submitInterviewAnswer).toHaveBeenCalledOnce(), + ); + const input = harness.submitInterviewAnswer.mock.calls[0]?.[0]; + expect(input).toBeDefined(); + + input?.onAdmission("submission-voice-1"); + harness.bridge.updateChat({ + canAcceptInterviewAnswer: false, + canonicalSegments: [], + status: "submitted", + }); + const unrelated = segment( + "unrelated", + "Do not speak this.", + "submission-other", + ); + const correlated = segment( + "correlated", + "Speak this canonical response.", + "submission-voice-1", + ); + const correlatedQuestion: CanonicalSpeechSegment = { + ...segment( + "correlated-question", + "Which operator confirms the batch?", + "submission-voice-1", + ), + messageId: correlated.messageId, + source: "assistant-question", + }; harness.bridge.updateChat({ canAcceptInterviewAnswer: true, - canonicalSegments: [segment("ask-current", "Question")], + canonicalSegments: [unrelated, correlated], + questionSegment: correlatedQuestion, status: "ready", }); - harness.bridge.start(3); - harness.emit(toolDelta(3, '{"answer":"Cancelled"}')); - harness.emit(responseTerminal(3, "cancelled")); - harness.emit(toolDone(3, '{"answer":"Cancelled"}')); - harness.emit({ - ...toolDelta(3, '{"answer":"Accepted"}'), - callId: "call-2", - itemId: "function-item-2", - responseId: "response-2", - }); - harness.emit({ - ...toolDone(3, '{"answer":"Accepted"}'), - callId: "call-2", - itemId: "function-item-2", - responseId: "response-2", + const deliveryId = createRealtimeSubmissionId(transcriptKey(7)); + expect(harness.session.speakCanonical).toHaveBeenCalledWith([correlated]); + expect(harness.events.map(({ type }) => type)).toEqual([ + "submission-started", + "submission-admitted", + "submission-accepted", + "canonical-text-ready", + "submission-settled", + "canonical-response-ready", + ]); + expect(harness.events.at(-1)).toEqual({ + deliveryId, + questionSegment: correlatedQuestion, + segments: [correlated], + type: "canonical-response-ready", }); + }); + test("speaks a completed canonical segment while chat remains streaming and settles separately", async () => { + const harness = createHarness(); + startReady(harness, 7); + harness.emit(completedTranscript(7)); await vi.waitFor(() => expect(harness.submitInterviewAnswer).toHaveBeenCalledOnce(), ); - expect(harness.submitInterviewAnswer).toHaveBeenCalledWith({ - id: createRealtimeSubmissionId(3, "call-2"), - text: "Accepted", + const correlated = segment( + "correlated", + "Speak this committed response.", + "submission-voice-1", + ); + harness.bridge.updateChat({ + canAcceptInterviewAnswer: false, + canonicalSegments: [correlated], + status: "streaming", }); - expect(harness.events).not.toContainEqual( - expect.objectContaining({ type: "error" }), + + expect(harness.session.speakCanonical).not.toHaveBeenCalled(); + harness.bridge.notifyResponseMessageCompleted( + completedResponseMessage(correlated.messageId, "submission-voice-1", 1), + ); + + expect(harness.session.speakCanonical).toHaveBeenCalledWith([correlated]); + expect(harness.events.map(({ type }) => type)).not.toContain( + "submission-settled", + ); + expect(harness.events.map(({ type }) => type)).not.toContain( + "canonical-response-ready", ); - }); - test("rejects an unfinished argument stream from a completed response", () => { - const harness = createHarness(); harness.bridge.updateChat({ canAcceptInterviewAnswer: true, - canonicalSegments: [segment("ask-current", "Question")], + canonicalSegments: [correlated], status: "ready", }); - harness.bridge.start(3); - harness.emit(toolDelta(3, '{"answer":"Incomplete')); - - harness.emit(responseTerminal(3, "completed")); - expect(harness.submitInterviewAnswer).not.toHaveBeenCalled(); - expect(harness.events).toEqual([ - expect.objectContaining({ - code: "interview-correlation", - type: "error", - }), + expect(harness.session.speakCanonical).toHaveBeenCalledOnce(); + expect(harness.events.slice(-2).map(({ type }) => type)).toEqual([ + "submission-settled", + "canonical-response-ready", ]); }); - test("rejects duplicate, stale, overlapping, and malformed calls without another Brunch submission", async () => { + test("does not let a completed reasoning-only or tool-only step authorize later text", async () => { const harness = createHarness(); - const question = segment("ask-current", "What happens after approval?"); + startReady(harness, 7); + harness.emit(completedTranscript(7)); + await vi.waitFor(() => + expect(harness.submitInterviewAnswer).toHaveBeenCalledOnce(), + ); harness.bridge.updateChat({ - canAcceptInterviewAnswer: true, - canonicalSegments: [question], - status: "ready", + canAcceptInterviewAnswer: false, + canonicalSegments: [], + status: "streaming", + }); + + const messageId = "reasoning-or-tool-message"; + harness.bridge.notifyResponseMessageCompleted( + completedResponseMessage(messageId, "submission-voice-1", 1), + ); + harness.bridge.updateChat({ + canAcceptInterviewAnswer: false, + canonicalSegments: [], + status: "streaming", + }); + harness.bridge.notifyResponseMessageStarted({ + messageId, + position: { batch: 1, index: 2 }, + submissionId: "submission-voice-1", + }); + const laterText = { + ...segment( + "not-yet-completed", + "Do not let the earlier completion authorize this text.", + ), + messageId, + submissionIds: ["submission-voice-1"], + }; + harness.bridge.updateChat({ + canAcceptInterviewAnswer: false, + canonicalSegments: [laterText], + status: "streaming", }); - harness.bridge.start(2); - harness.emit(toolDone(1)); - harness.emit(toolDelta(2, '{"answer":"The supervisor approves it."}')); - harness.emit(toolDone(2)); - harness.emit(toolDone(2)); + expect(harness.session.speakCanonical).not.toHaveBeenCalled(); + + harness.bridge.notifyResponseMessageCompleted( + completedResponseMessage(messageId, "submission-voice-1", 3), + ); + expect(harness.session.speakCanonical).toHaveBeenCalledWith([laterText]); + }); + + test("speaks later continuation segments once and in canonical order", async () => { + const harness = createHarness(); + startReady(harness, 7); + harness.emit(completedTranscript(7)); await vi.waitFor(() => expect(harness.submitInterviewAnswer).toHaveBeenCalledOnce(), ); + harness.bridge.updateChat({ + canAcceptInterviewAnswer: false, + canonicalSegments: [], + status: "streaming", + }); + const first = { + ...segment("first", "First committed segment."), + messageId: "assistant-response", + submissionIds: ["submission-voice-1"], + }; + harness.bridge.notifyResponseMessageCompleted( + completedResponseMessage(first.messageId, "submission-voice-1", 1), + ); + harness.bridge.updateChat({ + canAcceptInterviewAnswer: false, + canonicalSegments: [first], + status: "streaming", + }); + harness.bridge.notifyResponseMessageCompleted( + completedResponseMessage(first.messageId, "submission-voice-1", 1), + ); - harness.emit({ - ...toolDone(2, '{"answer":"Overlapping"}'), - callId: "call-2", - itemId: "function-item-2", + const second = { + ...segment("second", "Second committed segment."), + messageId: first.messageId, + submissionIds: ["submission-voice-1", "submission-continuation"], + }; + const third = { + ...segment("third", "Third committed segment."), + messageId: first.messageId, + submissionIds: ["submission-voice-1", "submission-continuation"], + }; + harness.bridge.updateChat({ + canAcceptInterviewAnswer: false, + canonicalSegments: [first, second, third], + status: "streaming", }); + expect(harness.session.speakCanonical).toHaveBeenCalledTimes(1); - expect(harness.submitInterviewAnswer).toHaveBeenCalledOnce(); - expect(harness.events.at(-1)).toMatchObject({ type: "error" }); + harness.bridge.notifyResponseMessageCompleted( + completedResponseMessage(first.messageId, "submission-continuation", 2), + ); + + const fourth = { + ...segment("fourth", "Fourth committed segment."), + messageId: first.messageId, + submissionIds: ["submission-voice-1", "submission-continuation"], + }; + harness.bridge.updateChat({ + canAcceptInterviewAnswer: false, + canonicalSegments: [first, second, third, fourth], + status: "streaming", + }); + harness.bridge.notifyResponseMessageCompleted( + completedResponseMessage(first.messageId, "submission-continuation", 3), + ); + + expect(harness.session.speakCanonical.mock.calls).toEqual([ + [[first]], + [[second, third]], + [[fourth]], + ]); }); - test.each([ - ["wrong tool", { ...toolDone(3), name: "invent_question" }], - ["invalid JSON", toolDone(3, "not-json")], - ["extra property", toolDone(3, '{"answer":"Valid","extra":true}')], - ["empty answer", toolDone(3, '{"answer":" "}')], - ])("rejects %s arguments", async (_label, event) => { + test("does not start speech cancelled while its correlated response is pending", async () => { const harness = createHarness(); + startReady(harness, 7); + harness.emit(completedTranscript(7)); + await vi.waitFor(() => + expect(harness.submitInterviewAnswer).toHaveBeenCalledOnce(), + ); + harness.bridge.updateChat({ + canAcceptInterviewAnswer: false, + canonicalSegments: [], + status: "streaming", + }); + + harness.bridge.cancelPendingSpeech(); + + const correlated = segment( + "correlated", + "Retain this without speaking it.", + "submission-voice-1", + ); + harness.bridge.notifyResponseMessageCompleted( + completedResponseMessage(correlated.messageId, "submission-voice-1", 1), + ); + harness.bridge.updateChat({ + canAcceptInterviewAnswer: false, + canonicalSegments: [correlated], + status: "streaming", + }); harness.bridge.updateChat({ canAcceptInterviewAnswer: true, - canonicalSegments: [segment("ask-current", "Question")], + canonicalSegments: [correlated], status: "ready", }); - harness.bridge.start(3); - - harness.emit(event); - await Promise.resolve(); - expect(harness.submitInterviewAnswer).not.toHaveBeenCalled(); - expect(harness.events).toEqual([ - expect.objectContaining({ type: "error" }), - ]); + expect(harness.session.speakCanonical).not.toHaveBeenCalled(); + expect(harness.events.at(-1)).toMatchObject({ + segments: [correlated], + speechCancelled: true, + type: "canonical-response-ready", + }); }); - test("rejects a composer result that does not match the pending brunch_ask", async () => { + test("does not speak a completed segment from an aborted submission", async () => { const harness = createHarness(); - harness.submitInterviewAnswer.mockResolvedValueOnce({ - kind: "interactive-tool", - toolCallId: "another-ask", + startReady(harness, 7); + harness.emit(completedTranscript(7)); + await vi.waitFor(() => + expect(harness.submitInterviewAnswer).toHaveBeenCalledOnce(), + ); + const aborted = segment( + "aborted", + "Never speak an aborted response.", + "submission-voice-1", + ); + harness.bridge.notifyResponseMessageCompleted( + completedResponseMessage(aborted.messageId, "submission-voice-1", 1), + ); + harness.bridge.updateChat({ + canAcceptInterviewAnswer: false, + canonicalSegments: [aborted], + settlements: [{ outcome: "aborted", submissionId: "submission-voice-1" }], + status: "streaming", }); harness.bridge.updateChat({ canAcceptInterviewAnswer: true, - canonicalSegments: [segment("ask-current", "Question")], + canonicalSegments: [aborted], + settlements: [{ outcome: "aborted", submissionId: "submission-voice-1" }], status: "ready", }); - harness.bridge.start(5); - harness.emit(toolDone(5)); + expect(harness.session.speakCanonical).not.toHaveBeenCalled(); + expect(harness.events.at(-1)).toEqual({ + deliveryId: createRealtimeSubmissionId(transcriptKey(7)), + outcome: "aborted", + type: "submission-stopped", + }); + }); + + test("rejects a path-B result that does not preserve the delivery identity", async () => { + const harness = createHarness(); + harness.submitInterviewAnswer.mockResolvedValueOnce({ + kind: "message", + messageId: "different-message", + submissionId: "submission-voice-1", + }); + startReady(harness); + + harness.emit(completedTranscript(3)); await vi.waitFor(() => - expect(harness.events.at(-1)).toMatchObject({ type: "error" }), + expect(harness.events).toContainEqual( + expect.objectContaining({ + code: "interview-correlation", + type: "error", + }), + ), ); - expect(harness.session.completeFunctionCall).not.toHaveBeenCalled(); }); - test("speaks new canonical text turns without creating a Realtime tool result", () => { + test.each([ + { + code: "admission-rejected", + failure: { kind: "rejected", status: 403 } as const, + message: "Brunch rejected the message before admission (HTTP 403).", + }, + { + code: "admission-conflict", + failure: { + kind: "submission-conflict", + status: 409, + submissionId: "submission-existing", + } as const, + message: + "The delivery key already belongs to admitted submission submission-existing; the changed payload was not admitted.", + }, + { + code: "admission-ambiguous", + failure: { kind: "ambiguous" } as const, + message: + "Brunch may have accepted the message, but admission could not be confirmed. Reopen the conversation before trying again.", + }, + { + code: "admission-aborted", + failure: { kind: "aborted" } as const, + message: "The local chat submission was cancelled.", + }, + ])( + "preserves a $failure.kind admission outcome", + async ({ code, failure, message }) => { + const harness = createHarness(); + harness.submitInterviewAnswer.mockRejectedValueOnce( + new FlueChatAdmissionError(failure), + ); + startReady(harness); + + harness.emit(completedTranscript(3)); + + await vi.waitFor(() => + expect(harness.events).toContainEqual({ + code, + failure, + message, + type: "error", + }), + ); + expect(harness.submitInterviewAnswer).toHaveBeenCalledOnce(); + }, + ); + + test("requires a shared chat busy cycle before accepting new canonical text", async () => { const harness = createHarness(); - const question = segment("ask-current", "Question"); + startReady(harness); + harness.emit(completedTranscript(3)); + await vi.waitFor(() => + expect(harness.submitInterviewAnswer).toHaveBeenCalledOnce(), + ); + const response = segment( + "response", + "Canonical response.", + "submission-voice-1", + ); + harness.bridge.updateChat({ canAcceptInterviewAnswer: true, - canonicalSegments: [question], + canonicalSegments: [response], status: "ready", }); - harness.bridge.start(8); - harness.session.speakCanonical.mockClear(); - const response = segment( - "typed-response", - "Canonical response", - "assistant-text", - ); + expect(harness.session.speakCanonical).not.toHaveBeenCalled(); + harness.bridge.updateChat({ + canAcceptInterviewAnswer: false, + canonicalSegments: [response], + status: "streaming", + }); harness.bridge.updateChat({ canAcceptInterviewAnswer: true, - canonicalSegments: [question, response], + canonicalSegments: [response], status: "ready", }); expect(harness.session.speakCanonical).toHaveBeenCalledWith([response]); - expect(harness.session.completeFunctionCall).not.toHaveBeenCalled(); }); }); diff --git a/apps/petrinaut-website/src/main/app/voice-interview/realtime-brunch-bridge.ts b/apps/petrinaut-website/src/main/app/voice-interview/realtime-brunch-bridge.ts index 1a84fa74c62..3172b93b15d 100644 --- a/apps/petrinaut-website/src/main/app/voice-interview/realtime-brunch-bridge.ts +++ b/apps/petrinaut-website/src/main/app/voice-interview/realtime-brunch-bridge.ts @@ -1,31 +1,66 @@ -import type { CanonicalSpeechSegment } from "./canonical-speech"; -import type { OpenAIRealtimeSessionEvent } from "./openai-realtime-session"; +import { FlueChatAdmissionError } from "@hashintel/brunch-agent-transport-aisdk"; -type ChatStatus = "ready" | "submitted" | "streaming" | "error"; +import type { CanonicalSpeechSegment } from "./canonical-speech"; +import type { + OpenAIRealtimeSessionEvent, + OpenAIRealtimeTranscriptKey, +} from "./openai-realtime-session"; +import type { AgentSendResult, FlueConversationSettlement } from "@flue/sdk"; +import type { + FlueChatAdmissionFailure, + FlueChatResponseMessageCompletedEvent, + FlueChatResponseMessageStartedEvent, + FlueChatTransportOptions, +} from "@hashintel/brunch-agent-transport-aisdk"; +import type { + PetrinautAiComposerSubmitTextResult, + PetrinautAiVoiceModeContext, +} from "@hashintel/petrinaut/ui"; + +export type VoiceSubmissionSettlement = Pick< + FlueConversationSettlement, + "outcome" | "submissionId" +>; interface ChatUpdate { readonly canAcceptInterviewAnswer: boolean; readonly canonicalSegments: CanonicalSpeechSegment[]; - readonly status: ChatStatus; + readonly questionSegment?: CanonicalSpeechSegment; + /** Local logical termination when the panel withheld a continuation. */ + readonly stopped?: boolean; + /** Flue's settlement index remains the durable outcome authority. */ + readonly settlements?: readonly VoiceSubmissionSettlement[]; + readonly status: PetrinautAiVoiceModeContext["status"]; } interface RealtimeBridgeSession { - completeFunctionCall( - callId: string, - segments: CanonicalSpeechSegment[], - ): void; speakCanonical(segments: CanonicalSpeechSegment[]): void; subscribe(listener: (event: OpenAIRealtimeSessionEvent) => void): () => void; } -interface SubmitInterviewAnswerInput { +type SubmitVoiceInput = Parameters< + PetrinautAiVoiceModeContext["submitVoiceInput"] +>[0]; +type FlueChatAdmission = Parameters< + NonNullable +>[0]; +export type RealtimeBrunchAdmissionTarget = Pick< + FlueChatAdmission, + "kind" | "messageId" +>; + +type SubmitInterviewAnswerInput = Pick & { + readonly admissionTarget: RealtimeBrunchAdmissionTarget; readonly id: string; - readonly text: string; -} + readonly onAdmission: (submissionId: AgentSendResult["submissionId"]) => void; + readonly signal: AbortSignal; +}; type SubmitInterviewAnswerResult = - | { readonly kind: "interactive-tool"; readonly toolCallId: string } - | { readonly kind: "message"; readonly messageId: string }; + | Extract + | (Extract & { + readonly submissionId?: AgentSendResult["submissionId"]; + }); interface RealtimeBrunchBridgeDependencies { readonly session: RealtimeBridgeSession; @@ -34,44 +69,94 @@ interface RealtimeBrunchBridgeDependencies { ) => Promise; } +interface CompletedResponseMessage extends FlueChatResponseMessageCompletedEvent { + consumed: boolean; +} + interface ActiveSubmission { + readonly abortController: AbortController; readonly baselineSegmentIds: ReadonlySet; - readonly callId: string; - readonly epoch: number; - readonly pendingQuestionId: string | null; + readonly completedResponseMessages: CompletedResponseMessage[]; + readonly deliveryId: string; correlated: boolean; + firstTextEmitted: boolean; sawBusyChatStatus: boolean; + speechCancelled: boolean; + submissionId: AgentSendResult["submissionId"] | null; } -interface ArgumentStream { - readonly chunks: string[]; - readonly itemId: string; - readonly responseId: string; -} +type RealtimeAdmissionErrorCode = + | "admission-aborted" + | "admission-ambiguous" + | "admission-conflict" + | "admission-rejected"; -export type RealtimeBridgeErrorCode = +type RealtimeInterviewErrorCode = | "interview-correlation" | "interview-response" | "interview-submission"; +export type RealtimeBridgeErrorCode = + | RealtimeAdmissionErrorCode + | RealtimeInterviewErrorCode; + +export type RealtimeTranscriptRejectionReason = + | "duplicate" + | "empty" + | "failed" + | "over-limit" + | "unavailable"; + export type RealtimeBrunchBridgeEvent = | { readonly answer: string; - readonly callId: string; + readonly deliveryId: string; readonly type: "submission-started"; } | { readonly answer: string; - readonly callId: string; + readonly deliveryId: string; readonly type: "submission-accepted"; } | { - readonly callId: string; + readonly deliveryId: string; + readonly submissionId: AgentSendResult["submissionId"]; + readonly type: "submission-admitted"; + } + | { + readonly deliveryId: string; + readonly questionSegment?: CanonicalSpeechSegment; readonly segments: CanonicalSpeechSegment[]; + readonly speechCancelled?: true; readonly type: "canonical-response-ready"; } | { - readonly code: RealtimeBridgeErrorCode; + readonly deliveryId: string; + readonly type: "canonical-text-ready"; + } + | { + readonly deliveryId: string; + readonly type: "submission-settled"; + } + | { + readonly deliveryId: string; + readonly outcome: + | Exclude + | "withheld"; + readonly type: "submission-stopped"; + } + | { + readonly reason: RealtimeTranscriptRejectionReason; + readonly type: "transcript-rejected"; + } + | { + readonly code: RealtimeInterviewErrorCode; + readonly message: string; + readonly type: "error"; + } + | { + readonly code: RealtimeAdmissionErrorCode; + readonly failure: FlueChatAdmissionFailure; readonly message: string; readonly type: "error"; }; @@ -82,45 +167,53 @@ const INVALID_BRIDGE_EVENT = "The voice response could not be matched to the interview. Reconnect voice or use text instead."; const ANSWER_LIMIT = 32_000; -export const createRealtimeSubmissionId = ( - connectionEpoch: number, - callId: string, -): string => `voice-realtime:${connectionEpoch}:${encodeURIComponent(callId)}`; - -const latestPendingQuestion = ( - segments: CanonicalSpeechSegment[], -): CanonicalSpeechSegment | undefined => - segments.findLast(({ source }) => source === "brunch-ask"); - -const parseContinueInterviewArguments = ( - argumentsJson: string, -): string | null => { - try { - const value: unknown = JSON.parse(argumentsJson); - if (typeof value !== "object" || value === null || Array.isArray(value)) { - return null; - } - const record = value as Record; - if (Object.keys(record).length !== 1 || typeof record.answer !== "string") { - return null; - } - const answer = record.answer.trim(); - return answer && Array.from(answer).length <= ANSWER_LIMIT ? answer : null; - } catch { - return null; +export const createRealtimeSubmissionId = ({ + connectionEpoch, + contentIndex, + itemId, +}: OpenAIRealtimeTranscriptKey): string => + `voice-realtime:${connectionEpoch}:${encodeURIComponent(itemId)}:${contentIndex}`; + +const transcriptKeyId = (key: OpenAIRealtimeTranscriptKey): string => + createRealtimeSubmissionId(key); + +const normalizeTranscript = (transcript: string): string => + transcript.trim().replace(/\s+/gu, " "); + +const positionPrecedes = ( + first: FlueChatResponseMessageCompletedEvent["position"], + second: FlueChatResponseMessageStartedEvent["position"], +): boolean => + first.batch < second.batch || + (first.batch === second.batch && first.index < second.index); + +const admissionErrorCode = ( + failure: FlueChatAdmissionFailure, +): RealtimeAdmissionErrorCode => { + switch (failure.kind) { + case "aborted": + return "admission-aborted"; + case "ambiguous": + return "admission-ambiguous"; + case "rejected": + return "admission-rejected"; + case "submission-conflict": + return "admission-conflict"; } }; export class RealtimeBrunchBridge { - readonly #argumentDeltas = new Map(); + readonly #acceptedInputItemIds = new Set(); + readonly #activeOutputResponseIds = new Set(); readonly #listeners = new Set(); - readonly #processedCalls = new Set(); + readonly #pendingSpeechRequestIds = new Set(); + readonly #playbackOverlappingInputItemIds = new Set(); + readonly #processedTranscripts = new Set(); readonly #session: RealtimeBridgeSession; readonly #submitInterviewAnswer: ( input: SubmitInterviewAnswerInput, ) => Promise; readonly #seenSegmentIds = new Set(); - readonly #terminalResponseIds = new Set(); #activeEpoch: number | null = null; #activeSubmission: ActiveSubmission | null = null; #chat: ChatUpdate = { @@ -129,6 +222,7 @@ export class RealtimeBrunchBridge { status: "ready", }; #generation = 0; + #outputCancellationPending = false; public constructor({ session, @@ -144,34 +238,86 @@ export class RealtimeBrunchBridge { return () => this.#listeners.delete(listener); } + public cancelPendingSpeech(): void { + this.#outputCancellationPending = true; + if (this.#activeSubmission) { + this.#activeSubmission.speechCancelled = true; + } + } + + public completeTurnHandoff(): void { + this.#activeOutputResponseIds.clear(); + this.#outputCancellationPending = false; + this.#pendingSpeechRequestIds.clear(); + } + + public notifyResponseMessageCompleted( + event: FlueChatResponseMessageCompletedEvent, + ): void { + const active = this.#activeSubmission; + if ( + active === null || + active.completedResponseMessages.some( + ({ position }) => + position.batch === event.position.batch && + position.index === event.position.index, + ) + ) { + return; + } + active.completedResponseMessages.push({ + ...event, + consumed: false, + }); + this.#completeCorrelatedSubmission(); + } + + public notifyResponseMessageStarted( + event: FlueChatResponseMessageStartedEvent, + ): void { + const active = this.#activeSubmission; + if (active === null) { + return; + } + for (const completion of active.completedResponseMessages) { + if ( + !completion.consumed && + completion.messageId === event.messageId && + positionPrecedes(completion.position, event.position) + ) { + completion.consumed = true; + } + } + } + public start(connectionEpoch: number): void { ++this.#generation; + this.#activeSubmission?.abortController.abort(); this.#activeEpoch = connectionEpoch; this.#activeSubmission = null; - this.#argumentDeltas.clear(); - this.#processedCalls.clear(); + this.#acceptedInputItemIds.clear(); + this.#playbackOverlappingInputItemIds.clear(); + this.#processedTranscripts.clear(); + this.#activeOutputResponseIds.clear(); + this.#outputCancellationPending = false; + this.#pendingSpeechRequestIds.clear(); this.#seenSegmentIds.clear(); - this.#terminalResponseIds.clear(); for (const segment of this.#chat.canonicalSegments) { this.#seenSegmentIds.add(segment.id); } - - const question = latestPendingQuestion(this.#chat.canonicalSegments); - if (question) { - this.#session.speakCanonical( - this.#chat.canonicalSegments.filter( - ({ messageId }) => messageId === question.messageId, - ), - ); - } } public stop(): void { ++this.#generation; + this.#activeSubmission?.abortController.abort(); this.#activeEpoch = null; this.#activeSubmission = null; - this.#argumentDeltas.clear(); - this.#terminalResponseIds.clear(); + this.#acceptedInputItemIds.clear(); + this.#playbackOverlappingInputItemIds.clear(); + this.#processedTranscripts.clear(); + this.#activeOutputResponseIds.clear(); + this.#outputCancellationPending = false; + this.#pendingSpeechRequestIds.clear(); } public updateChat(update: ChatUpdate): void { @@ -193,6 +339,12 @@ export class RealtimeBrunchBridge { this.#completeCorrelatedSubmission(); return; } + if (this.#outputCancellationPending || update.stopped) { + for (const segment of update.canonicalSegments) { + this.#seenSegmentIds.add(segment.id); + } + return; + } if (update.status !== "ready") { return; } @@ -219,209 +371,388 @@ export class RealtimeBrunchBridge { } } + #rejectTranscript(reason: RealtimeTranscriptRejectionReason): void { + this.#emit({ reason, type: "transcript-rejected" }); + } + #fail( message: string, - code: RealtimeBridgeErrorCode = "interview-correlation", + code: RealtimeInterviewErrorCode = "interview-correlation", ): void { ++this.#generation; + this.#activeSubmission?.abortController.abort(); this.#activeSubmission = null; - this.#argumentDeltas.clear(); this.#emit({ code, message, type: "error" }); } + #failAdmission(error: FlueChatAdmissionError): void { + ++this.#generation; + this.#activeSubmission?.abortController.abort(); + this.#activeSubmission = null; + this.#emit({ + code: admissionErrorCode(error.failure), + failure: error.failure, + message: error.message, + type: "error", + }); + } + #handleSessionEvent(event: OpenAIRealtimeSessionEvent): void { if ( - !("connectionEpoch" in event) || + "connectionEpoch" in event && event.connectionEpoch !== this.#activeEpoch ) { return; } - if (event.type === "response-terminal") { - this.#handleResponseTerminal(event); + if (event.type === "input-speech-started") { + if (this.#ownsOutputTurn()) { + this.#playbackOverlappingInputItemIds.add(event.itemId); + } else { + this.#acceptedInputItemIds.add(event.itemId); + } + return; + } + if (event.type === "canonical-speech-requested") { + this.#pendingSpeechRequestIds.add(event.speechRequestId); + for (const itemId of this.#acceptedInputItemIds) { + this.#playbackOverlappingInputItemIds.add(itemId); + } + this.#acceptedInputItemIds.clear(); + return; + } + if (event.type === "output-started") { + this.#pendingSpeechRequestIds.delete(event.speechRequestId); + this.#activeOutputResponseIds.add(event.responseId); + for (const itemId of this.#acceptedInputItemIds) { + this.#playbackOverlappingInputItemIds.add(itemId); + } + this.#acceptedInputItemIds.clear(); return; } if ( - event.type !== "tool-arguments-delta" && - event.type !== "tool-arguments-done" + event.type === "output-stopped" || + event.type === "output-interrupted" ) { + this.#activeOutputResponseIds.delete(event.responseId); return; } - - const responseKey = `${event.connectionEpoch}:${event.responseId}`; - if (this.#terminalResponseIds.has(responseKey)) { + if (event.type === "response-terminal") { + if (event.status !== "completed" && event.speechRequestId !== undefined) { + this.#pendingSpeechRequestIds.delete(event.speechRequestId); + } return; } - const callKey = `${event.connectionEpoch}:${event.callId}`; - if (this.#processedCalls.has(callKey)) { + if (event.type !== "completed" && event.type !== "transcription-failed") { return; } - if (event.type === "tool-arguments-delta") { - const stream = this.#argumentDeltas.get(callKey); - if (!stream && this.#argumentDeltas.size > 0) { - this.#processedCalls.add(callKey); - this.#fail(INVALID_BRIDGE_EVENT); - return; - } - if ( - stream && - (stream.itemId !== event.itemId || - stream.responseId !== event.responseId) - ) { - this.#processedCalls.add(callKey); - this.#fail(INVALID_BRIDGE_EVENT); - return; - } - if (stream) { - stream.chunks.push(event.delta); - } else { - this.#argumentDeltas.set(callKey, { - chunks: [event.delta], - itemId: event.itemId, - responseId: event.responseId, - }); - } + if (event.key.connectionEpoch !== this.#activeEpoch) { return; } - this.#processedCalls.add(callKey); - const stream = this.#argumentDeltas.get(callKey); - if (!stream && this.#argumentDeltas.size > 0) { - this.#fail(INVALID_BRIDGE_EVENT); + const keyId = transcriptKeyId(event.key); + if (this.#processedTranscripts.has(keyId)) { + this.#rejectTranscript("duplicate"); return; } - this.#argumentDeltas.delete(callKey); - if ( - this.#activeSubmission || - event.name !== "continue_interview" || - (stream !== undefined && - (stream.itemId !== event.itemId || - stream.responseId !== event.responseId || - stream.chunks.join("") !== event.arguments)) - ) { - this.#fail(INVALID_BRIDGE_EVENT); + this.#processedTranscripts.add(keyId); + this.#acceptedInputItemIds.delete(event.key.itemId); + + if (this.#playbackOverlappingInputItemIds.has(event.key.itemId)) { + this.#rejectTranscript("unavailable"); return; } - const answer = parseContinueInterviewArguments(event.arguments); - const question = latestPendingQuestion(this.#chat.canonicalSegments); + if (event.type === "transcription-failed") { + this.#rejectTranscript("failed"); + return; + } if ( - !answer || + this.#activeSubmission || !this.#chat.canAcceptInterviewAnswer || - (!question && this.#chat.status !== "ready") + this.#chat.status !== "ready" ) { - this.#fail(INVALID_BRIDGE_EVENT); + this.#rejectTranscript("unavailable"); return; } + const answer = normalizeTranscript(event.text); + if (answer.length === 0) { + this.#rejectTranscript("empty"); + return; + } + if (Array.from(answer).length > ANSWER_LIMIT) { + this.#rejectTranscript("over-limit"); + return; + } + + const deliveryId = createRealtimeSubmissionId(event.key); const generation = this.#generation; this.#activeSubmission = { + abortController: new AbortController(), baselineSegmentIds: new Set( this.#chat.canonicalSegments.map(({ id }) => id), ), - callId: event.callId, + completedResponseMessages: [], correlated: false, - epoch: event.connectionEpoch, - pendingQuestionId: question?.partId ?? null, + deliveryId, + firstTextEmitted: false, sawBusyChatStatus: false, + speechCancelled: false, + submissionId: null, }; - this.#emit({ answer, callId: event.callId, type: "submission-started" }); - void this.#submit(event, answer, generation); + this.#emit({ answer, deliveryId, type: "submission-started" }); + void this.#submit(answer, deliveryId, generation); } - #handleResponseTerminal( - event: Extract, - ): void { - const responseKey = `${event.connectionEpoch}:${event.responseId}`; - const matchingStreams = [...this.#argumentDeltas].filter( - ([, stream]) => stream.responseId === event.responseId, + #ownsOutputTurn(): boolean { + return ( + this.#activeOutputResponseIds.size > 0 || + this.#pendingSpeechRequestIds.size > 0 ); - if (event.status === "completed" && matchingStreams.length > 0) { - this.#fail(INVALID_BRIDGE_EVENT); - return; - } - - for (const [callKey] of matchingStreams) { - this.#argumentDeltas.delete(callKey); - this.#processedCalls.add(callKey); - } - this.#terminalResponseIds.add(responseKey); } async #submit( - event: Extract, answer: string, + deliveryId: string, generation: number, ): Promise { try { + const activeAtSubmission = this.#activeSubmission; + if (!activeAtSubmission) return; const result = await this.#submitInterviewAnswer({ - id: createRealtimeSubmissionId(event.connectionEpoch, event.callId), + admissionTarget: { kind: "user", messageId: deliveryId }, + id: deliveryId, + onAdmission: (submissionId) => { + const active = this.#activeSubmission; + if ( + generation !== this.#generation || + !active || + active.deliveryId !== deliveryId + ) { + return; + } + if (active.submissionId !== null) { + if (active.submissionId !== submissionId) { + this.#fail(INVALID_BRIDGE_EVENT); + } + return; + } + active.submissionId = submissionId; + this.#emit({ + deliveryId, + submissionId, + type: "submission-admitted", + }); + }, + signal: activeAtSubmission.abortController.signal, text: answer, }); const active = this.#activeSubmission; if ( generation !== this.#generation || !active || - active.callId !== event.callId || - active.epoch !== event.connectionEpoch + active.deliveryId !== deliveryId ) { return; } - const resultMatchesSubmission = - active.pendingQuestionId === null - ? result.kind === "message" - : result.kind === "interactive-tool" && - result.toolCallId === active.pendingQuestionId; - if (!resultMatchesSubmission) { + if (result.kind !== "message" || result.messageId !== deliveryId) { + this.#fail(INVALID_BRIDGE_EVENT); + return; + } + const resultSubmissionId = result.submissionId ?? null; + if ( + active.submissionId !== null && + resultSubmissionId !== null && + active.submissionId !== resultSubmissionId + ) { this.#fail(INVALID_BRIDGE_EVENT); return; } + active.submissionId ??= resultSubmissionId; active.correlated = true; - this.#emit({ - answer, - callId: event.callId, - type: "submission-accepted", - }); + this.#emit({ answer, deliveryId, type: "submission-accepted" }); this.#completeCorrelatedSubmission(); - } catch { + } catch (error) { if (generation === this.#generation) { - this.#fail( - "The interview could not accept that answer. Use the composer to retry.", - "interview-submission", - ); + if (error instanceof FlueChatAdmissionError) { + this.#failAdmission(error); + } else { + this.#fail( + "The interview could not accept that answer. Use the composer to retry.", + "interview-submission", + ); + } } } } #completeCorrelatedSubmission(): void { const active = this.#activeSubmission; - if ( - !active?.correlated || - !active.sawBusyChatStatus || - this.#chat.status !== "ready" - ) { + if (!active?.correlated || !active.sawBusyChatStatus) { return; } + if (this.#chat.stopped && this.#chat.status === "ready") { + // Cancellation can finish before this step commits its final prose. + // Retire it now so a later render cannot restart the withheld speech. + for (const segment of this.#chat.canonicalSegments) { + this.#seenSegmentIds.add(segment.id); + } + const settlement = this.#chat.settlements?.find( + ({ submissionId }) => submissionId === active.submissionId, + ); + this.#emit({ deliveryId: active.deliveryId, type: "submission-settled" }); + this.#activeSubmission = null; + this.#emit({ + deliveryId: active.deliveryId, + outcome: + settlement && settlement.outcome !== "completed" + ? settlement.outcome + : "withheld", + type: "submission-stopped", + }); + return; + } + // A reply may be written by the admitted submission itself or by a + // client-tool continuation projected onto the same message, and an ask + // follow-up writes into the message that asked; so match membership and + // exclude only what was already there when this answer was submitted. const responseSegments = this.#chat.canonicalSegments.filter( - ({ id }) => !active.baselineSegmentIds.has(id), + (segment) => + !active.baselineSegmentIds.has(segment.id) && + (active.submissionId === null || + (segment.submissionIds?.includes(active.submissionId) ?? false)), + ); + if (responseSegments.length > 0 && !active.firstTextEmitted) { + // Completed canonical text can land while the turn is still streaming; + // record that instant separately from settlement. + active.firstTextEmitted = true; + this.#emit({ + deliveryId: active.deliveryId, + type: "canonical-text-ready", + }); + } + const stoppedSettlement = + active.submissionId === null + ? undefined + : this.#chat.settlements?.find( + ({ submissionId }) => submissionId === active.submissionId, + ); + if (stoppedSettlement && stoppedSettlement.outcome !== "completed") { + if (this.#chat.status === "ready") { + this.#completeStoppedSubmission(active); + } + return; + } + const completionMatchesSegment = ( + completion: CompletedResponseMessage, + segment: CanonicalSpeechSegment, + ): boolean => + completion.messageId === segment.messageId && + (segment.submissionIds?.includes(completion.submissionId) ?? false); + const pendingCompletions = active.completedResponseMessages.filter( + ({ consumed }) => !consumed, + ); + const eligibleCompletions = pendingCompletions.filter((completion) => + responseSegments.some( + (segment) => + !this.#seenSegmentIds.has(segment.id) && + completionMatchesSegment(completion, segment), + ), ); + const completedSegments = responseSegments.filter( + (segment) => + !this.#seenSegmentIds.has(segment.id) && + eligibleCompletions.some((completion) => + completionMatchesSegment(completion, segment), + ), + ); + if (!active.speechCancelled) { + if (completedSegments.length > 0) { + try { + this.#session.speakCanonical(completedSegments); + for (const segment of completedSegments) { + this.#seenSegmentIds.add(segment.id); + } + } catch { + this.#fail(INVALID_BRIDGE_EVENT); + return; + } + } + } + for (const completion of eligibleCompletions) { + completion.consumed = true; + } + if (this.#chat.status !== "ready") { + return; + } if (responseSegments.length === 0) { + this.#completeStoppedSubmission(active); return; } - try { - this.#session.completeFunctionCall(active.callId, responseSegments); - } catch { - this.#fail(INVALID_BRIDGE_EVENT); - return; + this.#emit({ + deliveryId: active.deliveryId, + type: "submission-settled", + }); + if (!active.speechCancelled) { + const unscheduledSegments = responseSegments.filter( + ({ id }) => !this.#seenSegmentIds.has(id), + ); + if (unscheduledSegments.length > 0) { + try { + this.#session.speakCanonical(unscheduledSegments); + } catch { + this.#fail(INVALID_BRIDGE_EVENT); + return; + } + } } for (const segment of responseSegments) { this.#seenSegmentIds.add(segment.id); } + const questionSegment = this.#chat.questionSegment; + const correlatedQuestion = + questionSegment && + responseSegments.some( + ({ messageId }) => messageId === questionSegment.messageId, + ) && + (active.submissionId === null || + (questionSegment.submissionIds?.includes(active.submissionId) ?? false)) + ? questionSegment + : undefined; this.#activeSubmission = null; this.#emit({ - callId: active.callId, + deliveryId: active.deliveryId, + ...(correlatedQuestion ? { questionSegment: correlatedQuestion } : {}), segments: responseSegments, + ...(active.speechCancelled ? { speechCancelled: true as const } : {}), type: "canonical-response-ready", }); } + + /** + * A turn that settled short of a reply leaves no canonical text behind. Only + * Flue's settlement index distinguishes it from a turn still in progress or + * a completed step whose client-tool follow-up the panel is about to send, + * so wait for that record and never treat silence alone as a stop. + */ + #completeStoppedSubmission(active: ActiveSubmission): void { + if (active.submissionId === null) return; + const settlement = this.#chat.settlements?.find( + ({ submissionId }) => submissionId === active.submissionId, + ); + if (settlement === undefined || settlement.outcome === "completed") { + return; + } + this.#emit({ + deliveryId: active.deliveryId, + type: "submission-settled", + }); + this.#activeSubmission = null; + this.#emit({ + deliveryId: active.deliveryId, + outcome: settlement.outcome, + type: "submission-stopped", + }); + } } diff --git a/apps/petrinaut-website/src/main/app/voice-interview/voice-browser-tools.integration.test.tsx b/apps/petrinaut-website/src/main/app/voice-interview/voice-browser-tools.integration.test.tsx new file mode 100644 index 00000000000..08f33472342 --- /dev/null +++ b/apps/petrinaut-website/src/main/app/voice-interview/voice-browser-tools.integration.test.tsx @@ -0,0 +1,305 @@ +/** @vitest-environment jsdom */ +import { act, cleanup, render, waitFor } from "@testing-library/react"; +import { useLayoutEffect } from "react"; +import { afterEach, expect, test, vi } from "vitest"; + +import { createJsonDocHandle } from "@hashintel/petrinaut-core"; +import { Petrinaut } from "@hashintel/petrinaut/ui"; + +import { + BrunchPanelConversationTracker, + createBrunchPanelTransport, +} from "../local-storage-demo/brunch-panel-transport"; +import { selectCanonicalSpeech } from "./canonical-speech"; +import { RealtimeBrunchBridge } from "./realtime-brunch-bridge"; +import { submitVoiceInputWithAdmission } from "./voice-interview-control"; + +import type { CanonicalSpeechSegment } from "./canonical-speech"; +import type { OpenAIRealtimeSessionEvent } from "./openai-realtime-session"; +import type { RealtimeBrunchBridgeEvent } from "./realtime-brunch-bridge"; +import type { AgentSendResult, FlueClient } from "@flue/sdk"; +import type { PetrinautAiVoiceModeContext } from "@hashintel/petrinaut/ui"; + +vi.hoisted(() => { + window.matchMedia = (media) => ({ + media, + matches: false, + onchange: null, + addListener() {}, + removeListener() {}, + addEventListener() {}, + removeEventListener() {}, + dispatchEvent: () => true, + }); +}); + +const VoiceObserver = ({ + current, + onUpdate, +}: { + current: PetrinautAiVoiceModeContext; + onUpdate: (context: PetrinautAiVoiceModeContext) => void; +}) => { + useLayoutEffect(() => onUpdate(current), [current, onUpdate]); + return null; +}; +const inertWorker = () => ({ + postMessage() {}, + addEventListener() {}, + removeEventListener() {}, + terminate() {}, +}); +const hosts: Array<() => void> = []; +afterEach(() => { + cleanup(); + for (const close of hosts.splice(0)) close(); + vi.restoreAllMocks(); + vi.unstubAllGlobals(); +}); + +test.each([ + { preamble: true, outcome: "completed" }, + { preamble: false, outcome: "completed" }, + { preamble: false, outcome: "invalid-input" }, + { preamble: false, outcome: "withheld" }, + { preamble: true, outcome: "withheld" }, +])( + "settles the real panel/Voice browser-tool path ($outcome, preamble: $preamble)", + async ({ preamble, outcome }) => { + vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockReturnValue(null); + vi.stubGlobal( + "ResizeObserver", + class { + observe() {} + unobserve() {} + disconnect() {} + }, + ); + const tracker = new BrunchPanelConversationTracker(); + let context: PetrinautAiVoiceModeContext | undefined; + let emitInput: ((event: OpenAIRealtimeSessionEvent) => void) | undefined; + let finishContinuation: (() => void) | undefined; + let finishStoppedStep: (() => void) | undefined; + const events: RealtimeBrunchBridgeEvent[] = []; + const speakCanonical = + vi.fn<(segments: CanonicalSpeechSegment[]) => void>(); + const send = vi.fn( + async (): Promise => ({ + submissionId: `submission-${send.mock.calls.length}`, + uid: "uid", + offset: "0", + streamUrl: "http://local.test/agents/chat/test/stream", + }), + ); + const wait = vi.fn(async (admission, options) => { + const submissionId = (admission as AgentSendResult).submissionId; + const continuation = submissionId === "submission-2"; + if (continuation) + await new Promise((resolve) => { + finishContinuation = resolve; + }); + if (!continuation && outcome === "withheld") + await new Promise((resolve) => { + finishStoppedStep = resolve; + }); + const messageId = continuation ? "continuation" : "assistant"; + let ordinal = 0; + const position = () => ({ + batch: continuation ? 2 : 1, + index: ordinal++, + }); + await options?.onEvent?.({ + type: "message-started", + conversationId: "test", + submissionId, + messageId, + turnId: messageId, + position: position(), + }); + if (preamble || continuation) + await options?.onEvent?.({ + type: "message-delta", + conversationId: "test", + messageId, + kind: "text", + delta: continuation + ? "The guide is available." + : "Checking the guide.", + position: position(), + }); + if (!continuation) + await options?.onEvent?.({ + type: "tool-input", + conversationId: "test", + messageId, + toolCallId: "read-guide", + toolName: "readPetrinautDoc", + input: { + doc: outcome === "invalid-input" ? "missing-page" : "ai-assistant", + }, + position: position(), + }); + await options?.onEvent?.({ + type: "message-completed", + conversationId: "test", + messageId, + position: position(), + }); + await options?.onEvent?.({ + type: "submission-settled", + conversationId: "test", + submissionId, + outcome: "completed", + position: position(), + }); + }); + const client = { send, wait } as Pick< + FlueClient, + "send" | "wait" + > as FlueClient; + const bridge = new RealtimeBrunchBridge({ + session: { + speakCanonical, + subscribe: (listener) => { + emitInput = listener; + return () => {}; + }, + }, + submitInterviewAnswer: async (input) => { + if (!context) throw new Error("Panel did not mount"); + return submitVoiceInputWithAdmission({ + input, + submitVoiceInput: context.submitVoiceInput, + resolveInputSubmission: (messageId) => + tracker.submissionForInput(messageId), + subscribeToAdmission: (target, listener) => + tracker.subscribeToAdmission(target, ({ admission }) => + listener(admission.submissionId), + ), + subscribeToAdmissionFailure: (target, listener) => + tracker.subscribeToAdmissionFailure(target, listener), + }); + }, + }); + hosts.push(() => bridge.stop()); + bridge.subscribe((event) => events.push(event)); + tracker.subscribeToResponseMessageCompleted((event) => + bridge.notifyResponseMessageCompleted(event), + ); + tracker.subscribeToResponseMessageStarted((event) => + bridge.notifyResponseMessageStarted(event), + ); + const updateVoice = (current: PetrinautAiVoiceModeContext) => { + context = current; + bridge.updateChat({ + canAcceptInterviewAnswer: current.canAcceptVoiceInput, + status: current.status, + stopped: current.stopped, + canonicalSegments: selectCanonicalSpeech(current.messages).segments.map( + (segment) => ({ + ...segment, + submissionIds: tracker.submissionsForResponse(segment.messageId), + }), + ), + }); + }; + const handle = createJsonDocHandle({ + id: "voice-browser-test", + initial: { + places: [], + transitions: [], + types: [], + parameters: [], + differentialEquations: [], + }, + }); + render( + { + tracker.recordStopRequested(); + bridge.cancelPendingSpeech(); + bridge.completeTurnHandoff(); + finishStoppedStep?.(); + return "already-settled"; + }, + transport: createBrunchPanelTransport( + Promise.resolve(client), + tracker, + ), + renderVoiceMode: (current) => ( + + ), + }} + />, + ); + await waitFor(() => expect(context).toBeDefined()); + await act(async () => { + bridge.start(1); + emitInput?.({ + type: "completed", + key: { connectionEpoch: 1, contentIndex: 0, itemId: "spoken-input" }, + text: "Read the guide.", + }); + }); + if (outcome === "invalid-input") { + await waitFor(() => expect(context?.status).toBe("error")); + expect(events).toContainEqual( + expect.objectContaining({ type: "error", code: "interview-response" }), + ); + expect(send).toHaveBeenCalledOnce(); + expect(speakCanonical).not.toHaveBeenCalled(); + return; + } + if (outcome === "withheld") { + await waitFor(() => expect(finishStoppedStep).toBeDefined()); + await act(async () => { + await context?.stop(); + }); + await waitFor(() => + expect(events).toContainEqual( + expect.objectContaining({ + type: "submission-stopped", + outcome: "withheld", + }), + ), + ); + // A later render must not resurrect prose committed after cancellation. + if (context) updateVoice(context); + expect(send).toHaveBeenCalledOnce(); + expect(speakCanonical).not.toHaveBeenCalled(); + return; + } + await waitFor(() => expect(finishContinuation).toBeDefined()); + expect(send).toHaveBeenCalledTimes(2); + expect(context?.status).not.toBe("ready"); + expect( + events.some((event) => event.type === "canonical-response-ready"), + ).toBe(false); + expect(send.mock.calls[1]?.[0].message).toMatchObject({ + kind: "signal", + attributes: { toolCallIds: "read-guide" }, + }); + await act(async () => { + finishContinuation?.(); + }); + await waitFor(() => + expect(events).toContainEqual( + expect.objectContaining({ type: "canonical-response-ready" }), + ), + ); + expect(context?.status).toBe("ready"); + expect( + speakCanonical.mock.calls + .flatMap(([segments]) => segments) + .map((segment) => segment.text), + ).toEqual( + preamble + ? ["Checking the guide.", "The guide is available."] + : ["The guide is available."], + ); + }, +); diff --git a/apps/petrinaut-website/src/main/app/voice-interview/voice-interview-control.test.tsx b/apps/petrinaut-website/src/main/app/voice-interview/voice-interview-control.test.tsx index b4e37880a96..632a4332269 100644 --- a/apps/petrinaut-website/src/main/app/voice-interview/voice-interview-control.test.tsx +++ b/apps/petrinaut-website/src/main/app/voice-interview/voice-interview-control.test.tsx @@ -12,16 +12,20 @@ import { import { StrictMode, useState } from "react"; import { afterEach, beforeEach, describe, expect, test, vi } from "vitest"; +import { FlueChatAdmissionError } from "@hashintel/brunch-agent-transport-aisdk"; + import { OpenAIRealtimeSession } from "./openai-realtime-session"; import { acknowledgeVoiceInterviewDisclosure, isVoiceInterviewDisclosureAcknowledged, loadOpenAIVoiceConfig, + submitVoiceInputWithAdmission, VOICE_INTERVIEW_DISCLOSURE_STORAGE_KEY, VoiceInterviewControl, } from "./voice-interview-control"; import { VoiceTurnController } from "./voice-turn-controller"; +import type { AgentSendResult } from "@flue/sdk"; import type { PetrinautAiVoiceModeContext, PetrinautAiVoiceModeControls, @@ -180,6 +184,138 @@ afterEach(() => { }); describe("voice interview control", () => { + test("keeps an interactive-tool submission pending until Flue admits its continuation", async () => { + const events: string[] = []; + let notifyAdmission: + | ((submissionId: AgentSendResult["submissionId"]) => void) + | undefined; + const unsubscribe = vi.fn(); + const subscribeToAdmission = vi.fn( + ( + _target: { + readonly kind: "client-tool-result" | "user"; + readonly messageId: string; + }, + listener: (submissionId: AgentSendResult["submissionId"]) => void, + ) => { + notifyAdmission = listener; + return unsubscribe; + }, + ); + const submitVoiceInput = vi.fn< + PetrinautAiVoiceModeContext["submitVoiceInput"] + >(async () => { + events.push("composer-result"); + return { + kind: "interactive-tool", + toolCallId: "ask-current", + }; + }); + const resultPromise = submitVoiceInputWithAdmission({ + input: { + admissionTarget: { + kind: "client-tool-result", + messageId: "assistant-question", + }, + id: "voice-realtime:1:call-1", + onAdmission: () => events.push("admitted"), + signal: new AbortController().signal, + text: "Approved", + }, + submitVoiceInput, + subscribeToAdmission, + }); + let completed = false; + void resultPromise.then(() => { + completed = true; + }); + + await vi.waitFor(() => expect(submitVoiceInput).toHaveBeenCalledOnce()); + expect(completed).toBe(false); + expect(unsubscribe).not.toHaveBeenCalled(); + + notifyAdmission?.("submission-1"); + + await expect(resultPromise).resolves.toEqual({ + kind: "interactive-tool", + toolCallId: "ask-current", + }); + expect(events).toEqual(["composer-result", "admitted"]); + expect(unsubscribe).toHaveBeenCalledOnce(); + }); + + test("releases a pending admission subscription when the bridge cancels", async () => { + const abortController = new AbortController(); + const unsubscribe = vi.fn(); + const resultPromise = submitVoiceInputWithAdmission({ + input: { + admissionTarget: { + kind: "client-tool-result", + messageId: "assistant-question", + }, + id: "voice-realtime:1:call-1", + onAdmission: vi.fn(), + signal: abortController.signal, + text: "Approved", + }, + submitVoiceInput: async () => ({ + kind: "interactive-tool", + toolCallId: "ask-current", + }), + subscribeToAdmission: () => unsubscribe, + }); + + abortController.abort(); + + await expect(resultPromise).rejects.toMatchObject({ + failure: { kind: "aborted" }, + name: "FlueChatAdmissionError", + }); + expect(unsubscribe).toHaveBeenCalledOnce(); + }); + + test("preserves a typed failure reported after the panel submission resolves", async () => { + const admissionError = new FlueChatAdmissionError({ kind: "ambiguous" }); + let reportFailure: ((error: FlueChatAdmissionError) => void) | undefined; + const unsubscribeFromAdmission = vi.fn(); + const unsubscribeFromFailure = vi.fn(); + const resultPromise = submitVoiceInputWithAdmission({ + input: { + admissionTarget: { kind: "user", messageId: "voice-turn-1" }, + id: "voice-turn-1", + onAdmission: vi.fn(), + signal: new AbortController().signal, + text: "One Voice turn.", + }, + submitVoiceInput: async () => ({ + kind: "message", + messageId: "voice-turn-1", + }), + subscribeToAdmission: () => unsubscribeFromAdmission, + subscribeToAdmissionFailure: (_target, listener) => { + reportFailure = listener; + return unsubscribeFromFailure; + }, + }); + let settled = false; + void resultPromise.then( + () => { + settled = true; + }, + () => { + settled = true; + }, + ); + await Promise.resolve(); + expect(settled).toBe(false); + + reportFailure?.(admissionError); + + await expect(resultPromise).rejects.toBe(admissionError); + expect(unsubscribeFromAdmission).toHaveBeenCalledOnce(); + expect(unsubscribeFromFailure).toHaveBeenCalledOnce(); + }); + test("stores and reads the versioned disclosure acknowledgement", () => { const values = new Map(); const storage = { @@ -235,7 +371,7 @@ describe("voice interview control", () => { await expect(loadOpenAIVoiceConfig(fetch)).resolves.toBeNull(); }); - test("keeps the first-use disclosure inline without a text-handoff action", () => { + test("keeps the first-use disclosure inline without a text-handoff action", async () => { render(); fireEvent.click(screen.getByRole("button", { name: "Select Voice" })); @@ -243,16 +379,33 @@ describe("voice interview control", () => { const disclosure = screen.getByRole("region", { name: "Voice mode consent", }); - expect(disclosure).not.toBeNull(); - expect(within(disclosure).getByText("Voice mode")).not.toBeNull(); expect( - screen.getByText("OpenAI processes live audio", { exact: false }), + within(disclosure).getByText("Start a voice conversation"), + ).not.toBeNull(); + expect( + within(disclosure).getByText( + "OpenAI processes live audio and speaks the interviewer’s words. Petrinaut saves finalized answers—not audio.", + ), ).not.toBeNull(); + + const consent = within(disclosure).getByRole("checkbox", { + name: "I understand how voice data is handled.", + }); + const start = within(disclosure).getByRole("button", { + name: "Start voice", + }); + expect(start.hasAttribute("disabled")).toBe(true); + fireEvent.click(consent); + await waitFor(() => + expect( + within(disclosure) + .getByRole("button", { name: "Start voice" }) + .hasAttribute("disabled"), + ).toBe(false), + ); expect( - screen - .getByRole("button", { name: "Start voice mode" }) - .hasAttribute("disabled"), - ).toBe(true); + within(disclosure).getByRole("button", { name: "Test microphone" }), + ).not.toBeNull(); expect( screen.queryByRole("button", { name: "Use text instead" }), ).toBeNull(); @@ -272,7 +425,14 @@ describe("voice interview control", () => { fireEvent.click(screen.getByRole("button", { name: "Select Voice" })); fireEvent.click(screen.getByRole("checkbox")); - fireEvent.click(screen.getByRole("button", { name: "Start voice mode" })); + await waitFor(() => + expect( + screen + .getByRole("button", { name: "Start voice" }) + .hasAttribute("disabled"), + ).toBe(false), + ); + fireEvent.click(screen.getByRole("button", { name: "Start voice" })); expect(await screen.findByText("Session: error")).not.toBeNull(); expect(screen.getByText("Voice active")).not.toBeNull(); @@ -288,6 +448,75 @@ describe("voice interview control", () => { expect(screen.getByText("Session: error")).not.toBeNull(); }); + test("keeps one microphone check pending and reports its result", async () => { + let resolveCheck: ((stream: MediaStream) => void) | undefined; + const getUserMedia = vi.fn( + () => + new Promise((resolve) => { + resolveCheck = resolve; + }), + ); + vi.stubGlobal("navigator", { mediaDevices: { getUserMedia } }); + render(); + + fireEvent.click(screen.getByRole("button", { name: "Select Voice" })); + const check = screen.getByRole("button", { name: "Test microphone" }); + fireEvent.click(check); + fireEvent.click(check); + + expect(getUserMedia).toHaveBeenCalledOnce(); + expect(check.getAttribute("aria-busy")).toBe("true"); + + resolveCheck?.({ getTracks: () => [] } as unknown as MediaStream); + + expect(await screen.findByText("Microphone ready.")).not.toBeNull(); + await waitFor(() => expect(check.getAttribute("aria-busy")).toBe("false")); + }); + + test.each([ + { + failure: "media devices are missing", + stubMedia: () => vi.stubGlobal("navigator", {}), + }, + { + failure: "getUserMedia throws synchronously", + stubMedia: () => + vi.stubGlobal("navigator", { + mediaDevices: { + getUserMedia: () => { + throw new DOMException("Unavailable", "NotSupportedError"); + }, + }, + }), + }, + ])( + "reports an accessible microphone failure when $failure", + async ({ stubMedia }) => { + stubMedia(); + render(); + + fireEvent.click(screen.getByRole("button", { name: "Select Voice" })); + const disclosure = screen.getByRole("region", { + name: "Voice mode consent", + }); + const check = within(disclosure).getByRole("button", { + name: "Test microphone", + }); + + fireEvent.click(check); + + const status = await within(disclosure).findByText( + "Microphone access was not available.", + ); + expect(status.getAttribute("aria-live")).toBe("polite"); + expect(status.getAttribute("aria-atomic")).toBe("true"); + expect(check.getAttribute("aria-describedby")).toBe(status.id); + await waitFor(() => + expect(check.getAttribute("aria-busy")).toBe("false"), + ); + }, + ); + test("starts directly after acknowledgement and ends through the registered control", async () => { window.localStorage.setItem( VOICE_INTERVIEW_DISCLOSURE_STORAGE_KEY, @@ -312,6 +541,18 @@ describe("voice interview control", () => { expect(screen.getByText("Voice inactive")).not.toBeNull(); }); + test("registers replay controls that remain snapshot-gated", async () => { + render(); + + await waitFor(() => expect(registeredVoiceModeControls).toBeDefined()); + + expect(registeredVoiceModeControls?.readFullResponse).toBeTypeOf( + "function", + ); + expect(registeredVoiceModeControls?.takeTurn).toBeTypeOf("function"); + expect(registeredVoiceModeControls?.repeatQuestion).toBeTypeOf("function"); + }); + test("restarts when Voice is reselected before teardown completes", async () => { window.localStorage.setItem( VOICE_INTERVIEW_DISCLOSURE_STORAGE_KEY, @@ -405,18 +646,25 @@ describe("voice interview control", () => { expect(screen.getByText("Panel closed")).not.toBeNull(); }); - test("records acknowledgement only when the interview starts", () => { + test("records acknowledgement only when the interview starts", async () => { stubUnavailableMicrophone(); render(); fireEvent.click(screen.getByRole("button", { name: "Select Voice" })); - fireEvent.click(screen.getByRole("button", { name: "Check microphone" })); + fireEvent.click(screen.getByRole("button", { name: "Test microphone" })); expect( window.localStorage.getItem(VOICE_INTERVIEW_DISCLOSURE_STORAGE_KEY), ).toBeNull(); fireEvent.click(screen.getByRole("checkbox")); - fireEvent.click(screen.getByRole("button", { name: "Start voice mode" })); + await waitFor(() => + expect( + screen + .getByRole("button", { name: "Start voice" }) + .hasAttribute("disabled"), + ).toBe(false), + ); + fireEvent.click(screen.getByRole("button", { name: "Start voice" })); expect( window.localStorage.getItem(VOICE_INTERVIEW_DISCLOSURE_STORAGE_KEY), ).toBe("acknowledged"); diff --git a/apps/petrinaut-website/src/main/app/voice-interview/voice-interview-control.tsx b/apps/petrinaut-website/src/main/app/voice-interview/voice-interview-control.tsx index ee911bc6d4d..7094a09f9aa 100644 --- a/apps/petrinaut-website/src/main/app/voice-interview/voice-interview-control.tsx +++ b/apps/petrinaut-website/src/main/app/voice-interview/voice-interview-control.tsx @@ -6,13 +6,22 @@ import { useSyncExternalStore, } from "react"; -import { Button } from "@hashintel/ds-components"; +import { + FlueChatAdmissionError, + type FlueChatResponseMessageCompletedEvent, + type FlueChatResponseMessageStartedEvent, +} from "@hashintel/brunch-agent-transport-aisdk"; +import { Button, Checkbox } from "@hashintel/ds-components"; import { css } from "@hashintel/ds-helpers/css"; import { reportVoiceDiagnostic } from "../../../voice-diagnostics"; -import { selectCanonicalSpeechSegments } from "./canonical-speech"; +import { selectCanonicalSpeech } from "./canonical-speech"; import { OpenAIRealtimeSession } from "./openai-realtime-session"; -import { RealtimeBrunchBridge } from "./realtime-brunch-bridge"; +import { + RealtimeBrunchBridge, + type RealtimeBrunchAdmissionTarget, + type VoiceSubmissionSettlement, +} from "./realtime-brunch-bridge"; import { toVoiceSessionState } from "./voice-session-state"; import { VoiceTurnController, @@ -20,8 +29,106 @@ import { type VoiceTurnSnapshot, } from "./voice-turn-controller"; +import type { CanonicalSpeechSegment } from "./canonical-speech"; +import type { AgentSendResult } from "@flue/sdk"; import type { PetrinautAiVoiceModeContext } from "@hashintel/petrinaut/ui"; +type ResolveSubmission = ( + messageId: string, +) => AgentSendResult["submissionId"] | undefined; +type ResolveSubmissions = ( + messageId: string, +) => readonly AgentSendResult["submissionId"][] | undefined; +type SubscribeToAdmission = ( + target: RealtimeBrunchAdmissionTarget, + listener: (submissionId: AgentSendResult["submissionId"]) => void, +) => () => void; +type SubscribeToAdmissionFailure = ( + target: RealtimeBrunchAdmissionTarget, + listener: (error: FlueChatAdmissionError) => void, +) => () => void; +type SubscribeToResponseMessageCompleted = ( + listener: (event: FlueChatResponseMessageCompletedEvent) => void, +) => () => void; +type SubscribeToResponseMessageStarted = ( + listener: (event: FlueChatResponseMessageStartedEvent) => void, +) => () => void; +type SubscribeToStopRequested = (listener: () => void) => () => void; +type SubmitInterviewAnswer = ConstructorParameters< + typeof RealtimeBrunchBridge +>[0]["submitInterviewAnswer"]; +type SubmitInterviewAnswerInput = Parameters[0]; +type SubmitInterviewAnswerResult = Awaited>; + +export const submitVoiceInputWithAdmission = async ({ + input, + resolveInputSubmission, + submitVoiceInput, + subscribeToAdmission, + subscribeToAdmissionFailure, +}: { + readonly input: SubmitInterviewAnswerInput; + readonly resolveInputSubmission?: ResolveSubmission; + readonly submitVoiceInput: PetrinautAiVoiceModeContext["submitVoiceInput"]; + readonly subscribeToAdmission?: SubscribeToAdmission; + readonly subscribeToAdmissionFailure?: SubscribeToAdmissionFailure; +}): Promise => { + let unsubscribe = () => {}; + let unsubscribeFromFailure = () => {}; + let removeAbortListener = () => {}; + const cancelled = new Promise((_resolve, reject) => { + const rejectForAbort = () => + reject(new FlueChatAdmissionError({ kind: "aborted" })); + if (input.signal.aborted) { + rejectForAbort(); + return; + } + input.signal.addEventListener("abort", rejectForAbort, { once: true }); + removeAbortListener = () => + input.signal.removeEventListener("abort", rejectForAbort); + }); + const admissionObserved = + subscribeToAdmission === undefined && + subscribeToAdmissionFailure === undefined + ? Promise.resolve() + : new Promise((resolve, reject) => { + if (subscribeToAdmission !== undefined) { + unsubscribe = subscribeToAdmission( + input.admissionTarget, + (submissionId) => { + input.onAdmission(submissionId); + resolve(); + }, + ); + } + if (subscribeToAdmissionFailure !== undefined) { + unsubscribeFromFailure = subscribeToAdmissionFailure( + input.admissionTarget, + reject, + ); + } + }); + try { + const [result] = await Promise.race([ + Promise.all([submitVoiceInput(input), admissionObserved]), + cancelled, + ]); + if (result.kind !== "message") return result; + const submissionId = resolveInputSubmission?.(result.messageId); + if (resolveInputSubmission !== undefined && submissionId === undefined) { + throw new Error("The Flue admission could not be correlated."); + } + return { + ...result, + ...(submissionId === undefined ? {} : { submissionId }), + }; + } finally { + removeAbortListener(); + unsubscribe(); + unsubscribeFromFailure(); + } +}; + export interface OpenAIVoiceConfig { readonly available: true; readonly connectionTimeoutMs: number; @@ -109,31 +216,82 @@ export const loadOpenAIVoiceConfig = async ( } }; -const disclosureStyle = css({ - display: "flex", +const VoiceModeIcon = () => ( + +); + +const disclosureFrameStyle = css({ width: "full", - flexDirection: "column", - gap: "2", - paddingX: "2", - paddingY: "2", + padding: "2", borderTopWidth: "thin", borderTopStyle: "solid", borderTopColor: "neutral.a20", + backgroundColor: "neutral.bg.subtle", color: "neutral.s100", + _focus: { outline: "none" }, +}); + +const disclosureCardStyle = css({ + display: "flex", + flexDirection: "column", + gap: "2", + padding: "3", + borderWidth: "thin", + borderStyle: "solid", + borderColor: "neutral.a20", + borderRadius: "xl", + backgroundColor: "neutral.s00", + boxShadow: + "[0px 0px 0px 1px rgba(0,0,0,0.03), 0px 8px 16px -12px rgba(0,0,0,0.18)]", +}); + +const disclosureHeaderStyle = css({ + display: "flex", + alignItems: "center", + gap: "2", +}); + +const disclosureIconStyle = css({ + display: "inline-flex", + width: "7", + height: "7", + flexShrink: "0", + alignItems: "center", + justifyContent: "center", + borderRadius: "lg", + backgroundColor: "blue.a20", + color: "blue.s90", }); const disclosureTitleStyle = css({ display: "flex", + minWidth: "[0]", flexDirection: "column", - gap: "1", + gap: "0.5", +}); + +const disclosureHeadingStyle = css({ fontSize: "sm", fontWeight: "semibold", + lineHeight: "tight", }); const disclosureSubtitleStyle = css({ color: "neutral.s80", fontSize: "xs", - fontWeight: "normal", }); const disclosureCopyStyle = css({ @@ -142,6 +300,14 @@ const disclosureCopyStyle = css({ lineHeight: "relaxed", }); +const disclosureConsentStyle = css({ + width: "full", + padding: "2", + borderRadius: "lg", + backgroundColor: "neutral.a10", + color: "neutral.s100", +}); + const disclosureActionsStyle = css({ display: "flex", flexWrap: "wrap", @@ -149,13 +315,22 @@ const disclosureActionsStyle = css({ gap: "2", }); +const disclosureStatusStyle = css({ + minHeight: "[18px]", + color: "neutral.s80", + fontSize: "xs", + lineHeight: "relaxed", +}); + const VoiceInterviewDisclosure = ({ + checkingMicrophone, consented, microphoneCheck, onCheckMicrophone, onConsentChange, onStart, }: { + readonly checkingMicrophone: boolean; readonly consented: boolean; readonly microphoneCheck: string; readonly onCheckMicrophone: () => void; @@ -171,40 +346,65 @@ const VoiceInterviewDisclosure = ({ return (
-
- Voice mode - - Talk through your process with AI - -
-

- OpenAI processes live audio and speaks the interviewer’s words. - Petrinaut keeps finalized answers in this conversation, not the audio. -

- - {microphoneCheck && ( -

- {microphoneCheck} +

+
+ + + +
+ + Start a voice conversation + + + Talk through your process with AI + +
+
+

+ OpenAI processes live audio and speaks the interviewer’s words. + Petrinaut saves finalized answers—not audio.

- )} -
- - + +
+ + +
+
+ {microphoneCheck} +
); @@ -213,7 +413,7 @@ const VoiceInterviewDisclosure = ({ const recordLatency = (event: VoiceLatencyEvent): void => { try { performance.measure(`voice-interview:${event.name}`, { - detail: { questionId: event.questionId }, + detail: { correlationId: event.correlationId }, duration: event.elapsedMs, start: 0, }); @@ -225,9 +425,25 @@ const recordLatency = (event: VoiceLatencyEvent): void => { const AvailableVoiceInterviewControl = ({ config, context, + resolveInputSubmission, + resolveResponseSubmission, + settlements, + subscribeToAdmission, + subscribeToAdmissionFailure, + subscribeToResponseMessageCompleted, + subscribeToResponseMessageStarted, + subscribeToStopRequested, }: { config: OpenAIVoiceConfig; context: PetrinautAiVoiceModeContext; + resolveInputSubmission?: ResolveSubmission; + resolveResponseSubmission?: ResolveSubmissions; + settlements?: readonly VoiceSubmissionSettlement[]; + subscribeToAdmission?: SubscribeToAdmission; + subscribeToAdmissionFailure?: SubscribeToAdmissionFailure; + subscribeToResponseMessageCompleted?: SubscribeToResponseMessageCompleted; + subscribeToResponseMessageStarted?: SubscribeToResponseMessageStarted; + subscribeToStopRequested?: SubscribeToStopRequested; }) => { "use no memo"; @@ -236,6 +452,9 @@ const AvailableVoiceInterviewControl = ({ // bridge, so these callbacks read what the layout effect below installs // rather than what was captured here. let latestSubmitVoiceInput = context.submitVoiceInput; + let latestResolveInputSubmission = resolveInputSubmission; + let latestSubscribeToAdmission = subscribeToAdmission; + let latestSubscribeToAdmissionFailure = subscribeToAdmissionFailure; const session = new OpenAIRealtimeSession({ cancelAnimationFrame: (handle) => globalThis.cancelAnimationFrame(handle), connectionTimeoutMs: config.connectionTimeoutMs, @@ -251,7 +470,14 @@ const AvailableVoiceInterviewControl = ({ }); const bridge = new RealtimeBrunchBridge({ session, - submitInterviewAnswer: (input) => latestSubmitVoiceInput(input), + submitInterviewAnswer: (input) => + submitVoiceInputWithAdmission({ + input, + resolveInputSubmission: latestResolveInputSubmission, + submitVoiceInput: latestSubmitVoiceInput, + subscribeToAdmission: latestSubscribeToAdmission, + subscribeToAdmissionFailure: latestSubscribeToAdmissionFailure, + }), }); const controller = new VoiceTurnController({ bridge, @@ -260,14 +486,25 @@ const AvailableVoiceInterviewControl = ({ submitText: (input) => latestSubmitVoiceInput(input), }); return { + bridge, controller, getSnapshot: () => controller.getSnapshot(), subscribe: (listener: (snapshot: VoiceTurnSnapshot) => void) => controller.subscribe(listener), updateSubmissionContext: ( nextSubmitVoiceInput: PetrinautAiVoiceModeContext["submitVoiceInput"], + nextResolveInputSubmission: + | ((messageId: string) => string | undefined) + | undefined, + nextSubscribeToAdmission: SubscribeToAdmission | undefined, + nextSubscribeToAdmissionFailure: + | SubscribeToAdmissionFailure + | undefined, ) => { latestSubmitVoiceInput = nextSubmitVoiceInput; + latestResolveInputSubmission = nextResolveInputSubmission; + latestSubscribeToAdmission = nextSubscribeToAdmission; + latestSubscribeToAdmissionFailure = nextSubscribeToAdmissionFailure; }, }; }); @@ -279,6 +516,7 @@ const AvailableVoiceInterviewControl = ({ const [showDisclosure, setShowDisclosure] = useState(false); const [consented, setConsented] = useState(false); const [microphoneCheck, setMicrophoneCheck] = useState(""); + const [checkingMicrophone, setCheckingMicrophone] = useState(false); const handledVoiceSelectionRef = useRef(false); const { inputMode, @@ -288,18 +526,61 @@ const AvailableVoiceInterviewControl = ({ setVoiceActive, } = context; + useEffect( + () => + subscribeToResponseMessageCompleted?.((event) => + store.bridge.notifyResponseMessageCompleted(event), + ), + [store, subscribeToResponseMessageCompleted], + ); + useEffect( + () => + subscribeToResponseMessageStarted?.((event) => + store.bridge.notifyResponseMessageStarted(event), + ), + [store, subscribeToResponseMessageStarted], + ); + useEffect( + () => + subscribeToStopRequested?.(() => store.controller.cancelPendingSpeech()), + [store, subscribeToStopRequested], + ); + useLayoutEffect(() => { - store.updateSubmissionContext(context.submitVoiceInput); + store.updateSubmissionContext( + context.submitVoiceInput, + resolveInputSubmission, + subscribeToAdmission, + subscribeToAdmissionFailure, + ); + const canonicalSpeech = selectCanonicalSpeech(context.messages); + const correlateSegment = (segment: CanonicalSpeechSegment) => { + const submissionIds = resolveResponseSubmission?.(segment.messageId); + return submissionIds === undefined || submissionIds.length === 0 + ? segment + : { ...segment, submissionIds }; + }; store.controller.updateChat({ canAcceptInterviewAnswer: context.canAcceptVoiceInput, - canonicalSegments: selectCanonicalSpeechSegments(context.messages), + canonicalSegments: canonicalSpeech.segments.map(correlateSegment), + ...(canonicalSpeech.questionSegment + ? { questionSegment: correlateSegment(canonicalSpeech.questionSegment) } + : {}), + settlements, + stopped: context.stopped, status: context.status, }); }, [ context.canAcceptVoiceInput, context.messages, context.status, + context.stopped, context.submitVoiceInput, + resolveInputSubmission, + resolveResponseSubmission, + settlements, + subscribeToAdmission, + subscribeToAdmissionFailure, store, ]); @@ -310,12 +591,17 @@ const AvailableVoiceInterviewControl = ({ registerVoiceModeControls({ end: () => store.controller.end(), pause: () => store.controller.pause(), + readFullResponse: () => store.controller.readFullResponse(), reconnect: () => { void store.controller.reconnect(); }, - resume: () => store.controller.resume(), + repeatQuestion: () => store.controller.repeatQuestion(), + resume: () => { + void store.controller.resume(); + }, setMicrophoneMuted: (muted) => store.controller.setMicrophoneMuted(muted), + takeTurn: () => store.controller.takeTurn(), }), [registerVoiceModeControls, store], ); @@ -382,19 +668,38 @@ const AvailableVoiceInterviewControl = ({ return ( { - setMicrophoneCheck("Checking microphone…"); - void navigator.mediaDevices.getUserMedia({ audio: true }).then( - (stream) => { + if (checkingMicrophone) { + return; + } + setCheckingMicrophone(true); + setMicrophoneCheck(""); + let microphoneCheckPromise: Promise; + try { + const { mediaDevices } = navigator as { + readonly mediaDevices?: MediaDevices; + }; + microphoneCheckPromise = + mediaDevices === undefined + ? Promise.reject(new Error("Microphone access is unavailable.")) + : mediaDevices.getUserMedia({ audio: true }); + } catch (error) { + microphoneCheckPromise = Promise.reject(error); + } + void microphoneCheckPromise + .then((stream) => { for (const track of stream.getTracks()) { track.stop(); } setMicrophoneCheck("Microphone ready."); - }, - () => setMicrophoneCheck("Microphone access was not available."), - ); + }) + .catch(() => + setMicrophoneCheck("Microphone access was not available."), + ) + .finally(() => setCheckingMicrophone(false)); }} onConsentChange={setConsented} onStart={() => { @@ -412,13 +717,37 @@ const AvailableVoiceInterviewControl = ({ export const VoiceInterviewControl = ({ config, + resolveInputSubmission, + resolveResponseSubmission, + settlements, + subscribeToAdmission, + subscribeToAdmissionFailure, + subscribeToResponseMessageCompleted, + subscribeToResponseMessageStarted, + subscribeToStopRequested, ...context }: PetrinautAiVoiceModeContext & { readonly config: OpenAIVoiceConfig; + readonly resolveInputSubmission?: ResolveSubmission; + readonly resolveResponseSubmission?: ResolveSubmissions; + readonly settlements?: readonly VoiceSubmissionSettlement[]; + readonly subscribeToAdmission?: SubscribeToAdmission; + readonly subscribeToAdmissionFailure?: SubscribeToAdmissionFailure; + readonly subscribeToResponseMessageCompleted?: SubscribeToResponseMessageCompleted; + readonly subscribeToResponseMessageStarted?: SubscribeToResponseMessageStarted; + readonly subscribeToStopRequested?: SubscribeToStopRequested; }) => ( ); diff --git a/apps/petrinaut-website/src/main/app/voice-interview/voice-preview.integration.test.ts b/apps/petrinaut-website/src/main/app/voice-interview/voice-preview.integration.test.ts index 596389aad50..6f81ef30b4b 100644 --- a/apps/petrinaut-website/src/main/app/voice-interview/voice-preview.integration.test.ts +++ b/apps/petrinaut-website/src/main/app/voice-interview/voice-preview.integration.test.ts @@ -1,3 +1,4 @@ +import { FlueApiError } from "@flue/sdk"; import { describe, expect, test, vi } from "vitest"; import { createOpenAIRealtimeCallHandler } from "../../../server/voice/openai-realtime-call"; @@ -5,11 +6,20 @@ import { VOICE_REQUEST_ID_HEADER, type VoiceDiagnosticEvent, } from "../../../voice-diagnostics"; -import { selectCanonicalSpeechSegments } from "./canonical-speech"; +import { + BrunchPanelConversationTracker, + createBrunchPanelTransport, +} from "../local-storage-demo/brunch-panel-transport"; +import { selectCanonicalSpeech } from "./canonical-speech"; import { OpenAIRealtimeSession } from "./openai-realtime-session"; import { RealtimeBrunchBridge } from "./realtime-brunch-bridge"; +import { submitVoiceInputWithAdmission } from "./voice-interview-control"; import { VoiceTurnController } from "./voice-turn-controller"; +import type { CanonicalSpeechSegment } from "./canonical-speech"; +import type { OpenAIRealtimeSessionEvent } from "./openai-realtime-session"; +import type { RealtimeBrunchBridgeEvent } from "./realtime-brunch-bridge"; +import type { AgentSendResult, FlueClient } from "@flue/sdk"; import type { PetrinautAiMessage } from "@hashintel/petrinaut/ui"; const origin = "https://petrinaut.test"; @@ -66,11 +76,16 @@ const initialMessages = [ id: "initial-question-message", parts: [ { - input: { question: "What happens after approval?" }, - state: "input-available", - toolCallId: "ask-current", - toolName: "brunch_ask", - type: "dynamic-tool", + data: { + question: "What happens after approval?", + toolCallId: "tool-initial-question", + }, + type: "data-brunch-question", + }, + { + state: "done", + text: "What happens after approval?", + type: "text", }, ], role: "assistant", @@ -88,19 +103,100 @@ const responseMessages = [ id: "next-question-message", parts: [ { - input: { question: canonicalQuestion }, - state: "input-available", - toolCallId: "ask-next", - toolName: "brunch_ask", - type: "dynamic-tool", + data: { + question: canonicalQuestion, + toolCallId: "tool-next-question", + }, + type: "data-brunch-question", + }, + { + state: "done", + text: canonicalQuestion, + type: "text", }, ], role: "assistant", }, ] satisfies PetrinautAiMessage[]; +const createAdmissionOutcomeHarness = ( + client: Pick, +) => { + const tracker = new BrunchPanelConversationTracker(); + const transport = createBrunchPanelTransport( + Promise.resolve(client as FlueClient), + tracker, + ); + let realtimeListener: + | ((event: OpenAIRealtimeSessionEvent) => void) + | undefined; + const bridge = new RealtimeBrunchBridge({ + session: { + speakCanonical: vi.fn(), + subscribe: (listener) => { + realtimeListener = listener; + return () => { + realtimeListener = undefined; + }; + }, + }, + submitInterviewAnswer: (input) => + submitVoiceInputWithAdmission({ + input, + resolveInputSubmission: (messageId) => + tracker.submissionForInput(messageId), + submitVoiceInput: async ({ id, text }) => { + if (id === undefined) { + throw new Error("Voice message identity is required."); + } + void transport + .sendMessages({ + abortSignal: input.signal, + chatId: "conversation-1", + messageId: undefined, + messages: [ + { + id, + metadata: { source: "voice" }, + parts: [{ text, type: "text" }], + role: "user", + }, + ], + trigger: "submit-message", + }) + .catch(() => undefined); + return { kind: "message", messageId: id }; + }, + subscribeToAdmission: (target, listener) => + tracker.subscribeToAdmission(target, ({ admission }) => + listener(admission.submissionId), + ), + subscribeToAdmissionFailure: (target, listener) => + tracker.subscribeToAdmissionFailure(target, listener), + }), + }); + const events: RealtimeBrunchBridgeEvent[] = []; + bridge.subscribe((event) => events.push(event)); + bridge.updateChat({ + canAcceptInterviewAnswer: true, + canonicalSegments: [], + status: "ready", + }); + bridge.start(1); + + return { + emitCompletedTranscript: (itemId: string) => + realtimeListener?.({ + key: { connectionEpoch: 1, contentIndex: 0, itemId }, + text: spokenAnswer, + type: "completed", + }), + events, + }; +}; + describe("controlled voice preview", () => { - test("bridges one Realtime tool call through Brunch and back to canonical duplex audio", async () => { + test("bridges one completed transcript through Brunch and back to canonical half-duplex audio", async () => { const diagnostics: VoiceDiagnosticEvent[] = []; const reportDiagnostic = (event: VoiceDiagnosticEvent) => diagnostics.push(event); @@ -204,10 +300,59 @@ describe("controlled voice preview", () => { reportDiagnostic, requestAnimationFrame: vi.fn(() => 1), }); - const submitInterviewAnswer = vi.fn(async () => ({ - kind: "interactive-tool" as const, - toolCallId: "ask-current", - })); + const admission: AgentSendResult = { + offset: "offset-voice-1", + streamUrl: "https://petrinaut.test/agents/chat/instance-1", + submissionId: "submission-voice-1", + uid: "uid-voice-1", + }; + const send = vi.fn(async () => admission); + const wait = vi.fn(async () => undefined); + const tracker = new BrunchPanelConversationTracker(); + const transport = createBrunchPanelTransport( + Promise.resolve({ send, wait } as Pick< + FlueClient, + "send" | "wait" + > as FlueClient), + tracker, + ); + type SubmitInterviewAnswer = ConstructorParameters< + typeof RealtimeBrunchBridge + >[0]["submitInterviewAnswer"]; + const submitInterviewAnswer = vi.fn((input) => + submitVoiceInputWithAdmission({ + input, + resolveInputSubmission: (messageId) => + tracker.submissionForInput(messageId), + submitVoiceInput: async ({ id, text }) => { + if (id === undefined) { + throw new Error("Voice message identity is required."); + } + const stream = await transport.sendMessages({ + abortSignal: input.signal, + chatId: "conversation-1", + messageId: undefined, + messages: [ + { + id, + metadata: { source: "voice" }, + parts: [{ text, type: "text" }], + role: "user", + }, + ], + trigger: "submit-message", + }); + void stream.pipeTo(new WritableStream()); + return { kind: "message", messageId: id }; + }, + subscribeToAdmission: (target, listener) => + tracker.subscribeToAdmission(target, ({ admission: admitted }) => + listener(admitted.submissionId), + ), + subscribeToAdmissionFailure: (target, listener) => + tracker.subscribeToAdmissionFailure(target, listener), + }), + ); const bridge = new RealtimeBrunchBridge({ session, submitInterviewAnswer, @@ -215,32 +360,90 @@ describe("controlled voice preview", () => { const controller = new VoiceTurnController({ bridge, session, - submitText: submitInterviewAnswer, + submitText: vi.fn(async () => ({ kind: "message" as const })), + }); + await controller.start(); + dataChannel.receive({ + audio_start_ms: 200, + item_id: "pre-output-item", + type: "input_audio_buffer.speech_started", + }); + dataChannel.receive({ + content_index: 0, + delta: "Speech started before output", + item_id: "pre-output-item", + type: "conversation.item.input_audio_transcription.delta", }); + expect(controller.getSnapshot().partialText).toBe( + "Speech started before output", + ); + const initialSelection = selectCanonicalSpeech(initialMessages); + const initialSegments = initialSelection.segments; controller.updateChat({ canAcceptInterviewAnswer: true, - canonicalSegments: selectCanonicalSpeechSegments(initialMessages), + canonicalSegments: initialSegments, + questionSegment: initialSelection.questionSegment, status: "ready", }); + dataChannel.receive({ + content_index: 0, + item_id: "pre-output-item", + transcript: "This completed before output started.", + type: "conversation.item.input_audio_transcription.completed", + }); + expect(controller.getSnapshot()).toMatchObject({ + lastCommittedText: "", + microphoneEnabled: true, + partialText: "", + }); + expect(track.enabled).toBe(false); + expect(submitInterviewAnswer).not.toHaveBeenCalled(); + expect(send).not.toHaveBeenCalled(); + + dataChannel.receive({ + content_index: 0, + item_id: "pre-output-item", + transcript: "The stale item cannot recover authority.", + type: "conversation.item.input_audio_transcription.completed", + }); + expect(send).not.toHaveBeenCalled(); - await controller.start(); authorizeLatestSpeechResponse(dataChannel, "response-initial-question"); dataChannel.receive({ response_id: "response-initial-question", type: "output_audio_buffer.started", }); + expect(controller.getSnapshot()).toMatchObject({ + canTakeTurn: true, + output: "speaking", + }); + + const handoff = controller.takeTurn(); dataChannel.receive({ audio_start_ms: 300, - item_id: "user-item", + item_id: "playback-overlap", type: "input_audio_buffer.speech_started", }); + dataChannel.receive({ + content_index: 0, + item_id: "playback-overlap", + transcript: "Playback must not become input.", + type: "conversation.item.input_audio_transcription.completed", + }); + dataChannel.receive({ type: "input_audio_buffer.cleared" }); dataChannel.receive({ response: { id: "response-initial-question", + output: [], status: "cancelled", }, type: "response.done", }); + dataChannel.receive({ + response_id: "response-initial-question", + type: "output_audio_buffer.cleared", + }); + await handoff; expect(controller.getSnapshot()).toMatchObject({ input: "listening", microphoneEnabled: true, @@ -248,69 +451,93 @@ describe("controlled voice preview", () => { }); dataChannel.receive({ - call_id: "call-1", - delta: `{"answer":"${spokenAnswer}"}`, - item_id: "function-item-1", - output_index: 0, - response_id: "response-tool-1", - type: "response.function_call_arguments.delta", + audio_start_ms: 500, + item_id: "user-item", + type: "input_audio_buffer.speech_started", }); dataChannel.receive({ - response: { - id: "response-tool-1", - output: [ - { - arguments: `{"answer":"${spokenAnswer}"}`, - call_id: "call-1", - id: "function-item-1", - name: "continue_interview", - status: "completed", - type: "function_call", - }, - ], - status: "completed", - }, - type: "response.done", + content_index: 0, + delta: "The supervisor", + item_id: "user-item", + type: "conversation.item.input_audio_transcription.delta", + }); + dataChannel.receive({ + content_index: 0, + item_id: "user-item", + transcript: spokenAnswer, + type: "conversation.item.input_audio_transcription.completed", }); await vi.waitFor(() => - expect(submitInterviewAnswer).toHaveBeenCalledWith({ - id: "voice-realtime:1:call-1", - text: spokenAnswer, + expect(submitInterviewAnswer).toHaveBeenCalledWith( + expect.objectContaining({ + admissionTarget: { + kind: "user", + messageId: "voice-realtime:1:user-item:0", + }, + id: "voice-realtime:1:user-item:0", + text: spokenAnswer, + }), + ), + ); + await vi.waitFor(() => expect(send).toHaveBeenCalledOnce()); + expect(send).toHaveBeenCalledWith( + expect.objectContaining({ + idempotencyKey: "ai-sdk:user:voice-realtime:1:user-item:0", + message: { body: spokenAnswer, kind: "user" }, + }), + ); + await vi.waitFor(() => + expect(controller.getSnapshot()).toMatchObject({ + input: "submitting", + lastAnswerDelivery: "delivered", + microphoneEnabled: true, + output: "waiting-for-tool", }), ); - expect(controller.getSnapshot()).toMatchObject({ - input: "submitting", - lastAnswerDelivery: "delivered", - microphoneEnabled: true, - output: "waiting-for-tool", - }); controller.updateChat({ canAcceptInterviewAnswer: false, - canonicalSegments: selectCanonicalSpeechSegments(initialMessages), + canonicalSegments: initialSegments, status: "streaming", }); + const initialSegmentIds = new Set(initialSegments.map(({ id }) => id)); + const responseSelection = selectCanonicalSpeech(responseMessages); + const correlateResponse = (segment: CanonicalSpeechSegment) => + initialSegmentIds.has(segment.id) + ? segment + : { ...segment, submissionIds: [admission.submissionId] }; + const correlatedSegments = + responseSelection.segments.map(correlateResponse); controller.updateChat({ canAcceptInterviewAnswer: true, - canonicalSegments: selectCanonicalSpeechSegments(responseMessages), + canonicalSegments: correlatedSegments, + questionSegment: responseSelection.questionSegment + ? correlateResponse(responseSelection.questionSegment) + : undefined, status: "ready", }); - const [functionOutput, responseCreate] = sentEvents(dataChannel).slice(-2); - expect(functionOutput).toEqual({ - type: "conversation.item.create", - item: { - type: "function_call_output", - call_id: "call-1", - output: JSON.stringify({ - response_text: [canonicalReply, canonicalQuestion], - }), - }, - }); + const responseCreate = sentEvents(dataChannel).findLast( + ({ type }) => type === "response.create", + ); expect(responseCreate).toMatchObject({ type: "response.create", response: { + input: [ + { + content: [ + { + text: JSON.stringify({ + response_text: [canonicalReply, canonicalQuestion], + }), + type: "input_text", + }, + ], + role: "system", + type: "message", + }, + ], output_modalities: ["audio"], tool_choice: "none", tools: [], @@ -328,6 +555,48 @@ describe("controlled voice preview", () => { microphoneEnabled: true, output: "speaking", }); + expect(track.enabled).toBe(false); + + dataChannel.receive({ + response_id: "response-canonical-reply", + type: "output_audio_buffer.stopped", + }); + dataChannel.receive({ + response: { + id: "response-canonical-reply", + output: [], + status: "completed", + }, + type: "response.done", + }); + expect(controller.getSnapshot()).toMatchObject({ + canReadFullResponse: true, + canRepeatQuestion: true, + output: "idle", + }); + + controller.repeatQuestion(); + + const replayCreate = sentEvents(dataChannel).findLast( + ({ type }) => type === "response.create", + ); + expect(replayCreate).toMatchObject({ + response: { + input: [ + { + content: [ + { + text: JSON.stringify({ response_text: [canonicalQuestion] }), + type: "input_text", + }, + ], + role: "system", + type: "message", + }, + ], + }, + type: "response.create", + }); const remoteTrack = { kind: "audio", stop: vi.fn() }; const remoteStream = { @@ -360,11 +629,13 @@ describe("controlled voice preview", () => { turn_detection: { type: "semantic_vad", eagerness: "low", - create_response: true, - interrupt_response: true, + create_response: false, + interrupt_response: false, }, }, }, + tool_choice: "none", + tools: [], }); expect(diagnostics).toEqual( expect.arrayContaining([ @@ -390,4 +661,212 @@ describe("controlled voice preview", () => { expect(remoteAudio.pause).toHaveBeenCalledOnce(); expect(peer.close).toHaveBeenCalledOnce(); }); + + test("admits a Voice turn only through the Flue route", async () => { + const admission: AgentSendResult = { + streamUrl: "https://petrinaut.test/agents/chat/instance-1", + offset: "offset-1", + submissionId: "submission-voice-1", + uid: "uid-1", + }; + const send = vi.fn(async () => admission); + let settleSubmission: (() => void) | undefined; + const wait = vi.fn( + async (_admission, options) => + new Promise((resolve) => { + settleSubmission = () => { + void Promise.resolve( + options?.onEvent?.({ + type: "submission-settled", + conversationId: "conversation-1", + submissionId: admission.submissionId, + outcome: "completed", + position: { batch: 1, index: 0 }, + }), + ).then(() => resolve()); + }; + }), + ); + const client = { + send, + wait, + } as Pick as FlueClient; + const tracker = new BrunchPanelConversationTracker(); + const transport = createBrunchPanelTransport( + Promise.resolve(client), + tracker, + ); + let realtimeListener: + | ((event: OpenAIRealtimeSessionEvent) => void) + | undefined; + const bridge = new RealtimeBrunchBridge({ + session: { + speakCanonical: vi.fn(), + subscribe: (listener) => { + realtimeListener = listener; + return () => { + realtimeListener = undefined; + }; + }, + }, + submitInterviewAnswer: async ({ + admissionTarget, + id, + onAdmission, + signal, + text, + }) => { + const unsubscribe = tracker.subscribeToAdmission( + admissionTarget, + ({ admission: admitted }) => onAdmission(admitted.submissionId), + ); + const stream = await transport.sendMessages({ + trigger: "submit-message", + chatId: "conversation-1", + messageId: undefined, + messages: [ + { + id, + role: "user", + metadata: { source: "voice" }, + parts: [{ type: "text", text }], + }, + ], + abortSignal: signal, + }); + try { + await stream.pipeTo(new WritableStream()); + const submissionId = tracker.submissionForInput(id); + if (submissionId === undefined) { + throw new Error("missing Flue admission"); + } + return { kind: "message", messageId: id, submissionId }; + } finally { + unsubscribe(); + } + }, + }); + const bridgeEvents: RealtimeBrunchBridgeEvent[] = []; + bridge.subscribe((event) => bridgeEvents.push(event)); + bridge.updateChat({ + canAcceptInterviewAnswer: true, + canonicalSegments: [], + status: "ready", + }); + bridge.start(1); + + const finalized: OpenAIRealtimeSessionEvent = { + key: { + connectionEpoch: 1, + contentIndex: 0, + itemId: "input-item-1", + }, + text: spokenAnswer, + type: "completed", + }; + realtimeListener?.(finalized); + realtimeListener?.(finalized); + + await vi.waitFor(() => expect(send).toHaveBeenCalledOnce()); + await vi.waitFor(() => + expect(bridgeEvents).toContainEqual({ + deliveryId: "voice-realtime:1:input-item-1:0", + submissionId: admission.submissionId, + type: "submission-admitted", + }), + ); + expect(bridgeEvents).not.toContainEqual( + expect.objectContaining({ type: "submission-accepted" }), + ); + const sendInput = send.mock.calls[0]?.[0]; + expect(sendInput).toMatchObject({ + idempotencyKey: "ai-sdk:user:voice-realtime:1:input-item-1:0", + message: { kind: "user", body: spokenAnswer }, + }); + expect(sendInput?.signal).toBeInstanceOf(AbortSignal); + expect(admission.streamUrl).toContain("/agents/chat/"); + + settleSubmission?.(); + await vi.waitFor(() => + expect(bridgeEvents).toContainEqual( + expect.objectContaining({ type: "submission-accepted" }), + ), + ); + }); + + test("surfaces an ambiguous Flue admission through the panel observer without retrying", async () => { + const send = vi.fn(async () => { + throw new FlueApiError(500, ""); + }); + const abort = vi.fn(async () => ({ aborted: true })); + const harness = createAdmissionOutcomeHarness({ abort, send }); + + harness.emitCompletedTranscript("input-item-ambiguous"); + + await vi.waitFor(() => + expect(harness.events).toContainEqual({ + code: "admission-ambiguous", + failure: { kind: "ambiguous" }, + message: + "Brunch may have accepted the message, but admission could not be confirmed. Reopen the conversation before trying again.", + type: "error", + }), + ); + expect(send).toHaveBeenCalledOnce(); + expect(abort).not.toHaveBeenCalled(); + }); + + test("preserves a conflicting submission through the production admission path", async () => { + const send = vi.fn(async () => { + throw new FlueApiError(409, { + error: { + details: "", + message: "The delivery key already names another payload.", + meta: { submissionId: "submission-existing" }, + type: "submission_conflict", + }, + }); + }); + const abort = vi.fn(async () => ({ aborted: true })); + const harness = createAdmissionOutcomeHarness({ abort, send }); + + harness.emitCompletedTranscript("input-item-conflict"); + + await vi.waitFor(() => + expect(harness.events).toContainEqual({ + code: "admission-conflict", + failure: { + kind: "submission-conflict", + status: 409, + submissionId: "submission-existing", + }, + message: + "The delivery key already belongs to admitted submission submission-existing; the changed payload was not admitted.", + type: "error", + }), + ); + expect(send).toHaveBeenCalledOnce(); + expect(abort).not.toHaveBeenCalled(); + }); + + test("keeps local admission abort distinct from durable Flue abort", async () => { + const send = vi.fn(async () => { + throw new DOMException("Local admission cancelled", "AbortError"); + }); + const abort = vi.fn(async () => ({ aborted: true })); + const harness = createAdmissionOutcomeHarness({ abort, send }); + + harness.emitCompletedTranscript("input-item-aborted"); + + await vi.waitFor(() => + expect(harness.events).toContainEqual({ + code: "admission-aborted", + failure: { kind: "aborted" }, + message: "The local chat submission was cancelled.", + type: "error", + }), + ); + expect(send).toHaveBeenCalledOnce(); + expect(abort).not.toHaveBeenCalled(); + }); }); diff --git a/apps/petrinaut-website/src/main/app/voice-interview/voice-session-state.test.ts b/apps/petrinaut-website/src/main/app/voice-interview/voice-session-state.test.ts index d637a762607..912282facab 100644 --- a/apps/petrinaut-website/src/main/app/voice-interview/voice-session-state.test.ts +++ b/apps/petrinaut-website/src/main/app/voice-interview/voice-session-state.test.ts @@ -5,6 +5,9 @@ import { toVoiceSessionState } from "./voice-session-state"; import type { VoiceTurnSnapshot } from "./voice-turn-controller"; const listeningSnapshot = { + canReadFullResponse: false, + canRepeatQuestion: false, + canTakeTurn: false, canReviseLastAnswer: false, connection: "connected", currentQuestion: "What happens after approval?", @@ -12,6 +15,7 @@ const listeningSnapshot = { errorMessage: "", errorRequestId: "", input: "listening", + inputNotice: "none", lastAnswerDelivery: "none", lastCommittedText: "", microphoneEnabled: true, @@ -30,13 +34,40 @@ describe("toVoiceSessionState", () => { test("reports a listening turn with its microphone level", () => { expect(mapSnapshot()).toEqual({ + canReadFullResponse: false, + canRepeatQuestion: false, + canTakeTurn: false, errorMessage: null, microphoneLevel: 0.24, microphoneMuted: false, + notice: null, phase: "listening", }); }); + test("publishes safe handoff and canonical playback availability", () => { + expect( + mapSnapshot({ + canReadFullResponse: true, + canRepeatQuestion: true, + canTakeTurn: true, + }), + ).toMatchObject({ + canReadFullResponse: true, + canRepeatQuestion: true, + canTakeTurn: true, + }); + }); + + test("describes recoverable transcript rejections", () => { + expect(mapSnapshot({ inputNotice: "not-heard" })?.notice).toBe( + "We didn't catch that. Please try again.", + ); + expect(mapSnapshot({ inputNotice: "too-long" })?.notice).toBe( + "That answer is too long. Please try a shorter response.", + ); + }); + test("hands the turn to the assistant while it speaks", () => { expect(mapSnapshot({ output: "speaking", partialText: "" })).toMatchObject({ phase: "speaking", diff --git a/apps/petrinaut-website/src/main/app/voice-interview/voice-session-state.ts b/apps/petrinaut-website/src/main/app/voice-interview/voice-session-state.ts index e1a06464eb0..5d8bfce2219 100644 --- a/apps/petrinaut-website/src/main/app/voice-interview/voice-session-state.ts +++ b/apps/petrinaut-website/src/main/app/voice-interview/voice-session-state.ts @@ -65,6 +65,7 @@ const phaseOf = ( return "speaking"; } if ( + snapshot.output === "cancelling" || snapshot.output === "waiting-for-tool" || snapshot.input === "submitting" ) { @@ -93,6 +94,9 @@ export const toVoiceSessionState = ({ } return { + canReadFullResponse: snapshot.canReadFullResponse, + canRepeatQuestion: snapshot.canRepeatQuestion, + canTakeTurn: snapshot.canTakeTurn, errorMessage: snapshot.connection === "error" ? errorMessageOf(snapshot) : null, microphoneMuted: @@ -100,6 +104,12 @@ export const toVoiceSessionState = ({ snapshot.input !== "paused" && !snapshot.microphoneEnabled, microphoneLevel: snapshot.microphoneLevel, + notice: + snapshot.inputNotice === "not-heard" + ? "We didn't catch that. Please try again." + : snapshot.inputNotice === "too-long" + ? "That answer is too long. Please try a shorter response." + : null, phase: phaseOf(snapshot), }; }; diff --git a/apps/petrinaut-website/src/main/app/voice-interview/voice-turn-controller.test.ts b/apps/petrinaut-website/src/main/app/voice-interview/voice-turn-controller.test.ts index 76c09ccf495..7152451dcd0 100644 --- a/apps/petrinaut-website/src/main/app/voice-interview/voice-turn-controller.test.ts +++ b/apps/petrinaut-website/src/main/app/voice-interview/voice-turn-controller.test.ts @@ -6,18 +6,21 @@ import { VoiceTurnController } from "./voice-turn-controller"; import type { CanonicalSpeechSegment } from "./canonical-speech"; import type { OpenAIRealtimeSessionEvent } from "./openai-realtime-session"; import type { RealtimeBrunchBridgeEvent } from "./realtime-brunch-bridge"; +import type { VoiceLatencyEvent } from "./voice-turn-controller"; const createHarness = () => { let epoch = 0; + let now = 0; let sessionListener: | ((event: OpenAIRealtimeSessionEvent) => void) | undefined; let bridgeListener: ((event: RealtimeBrunchBridgeEvent) => void) | undefined; const session = { - cancelOutput: vi.fn(), + cancelOutput: vi.fn<() => Promise>(async () => undefined), connect: vi.fn(async () => ++epoch), disconnect: vi.fn(async () => undefined), setMicrophoneEnabled: vi.fn(), + speakCanonical: vi.fn(), subscribe: vi.fn( (listener: (event: OpenAIRealtimeSessionEvent) => void) => { sessionListener = listener; @@ -28,6 +31,8 @@ const createHarness = () => { ), }; const bridge = { + cancelPendingSpeech: vi.fn(), + completeTurnHandoff: vi.fn(), start: vi.fn(), stop: vi.fn(), subscribe: vi.fn((listener: (event: RealtimeBrunchBridgeEvent) => void) => { @@ -39,120 +44,1311 @@ const createHarness = () => { updateChat: vi.fn(), }; const submitText = vi.fn(async () => ({ kind: "message" as const })); - const controller = new VoiceTurnController({ bridge, session, submitText }); + const latencyEvents: VoiceLatencyEvent[] = []; + const controller = new VoiceTurnController({ + bridge, + now: () => now, + onLatencyEvent: (event) => latencyEvents.push(event), + session, + submitText, + }); return { + advanceTime: (elapsedMs: number) => { + now += elapsedMs; + }, bridge, controller, emitBridge: (event: RealtimeBrunchBridgeEvent) => bridgeListener?.(event), emitSession: (event: OpenAIRealtimeSessionEvent) => sessionListener?.(event), + latencyEvents, session, submitText, }; }; -const question = ( - id: string, - text = "What happens after approval?", -): CanonicalSpeechSegment => ({ - contentHash: "fnv1a32:12345678", - id, - messageId: `message-${id}`, - partId: id, - source: "brunch-ask", - text, -}); +const question = ( + id: string, + text = "What happens after approval?", +): CanonicalSpeechSegment => ({ + contentHash: "fnv1a32:12345678", + id, + messageId: `message-${id}`, + partId: id, + source: "assistant-text", + text, +}); + +const markedQuestion = ( + id: string, + text = "What happens after approval?", +): CanonicalSpeechSegment => ({ + ...question(id, text), + source: "assistant-question", +}); + +describe("VoiceTurnController", () => { + test("records the content-free Voice lifecycle once in causal order", async () => { + const harness = createHarness(); + await harness.controller.start(); + + harness.emitBridge({ + answer: "Private finalized answer", + deliveryId: "call-opaque", + type: "submission-started", + }); + harness.advanceTime(10); + harness.emitBridge({ + deliveryId: "call-opaque", + submissionId: "submission-opaque", + type: "submission-admitted", + }); + harness.emitBridge({ + deliveryId: "call-opaque", + submissionId: "submission-opaque", + type: "submission-admitted", + }); + harness.advanceTime(10); + harness.emitBridge({ + answer: "Private finalized answer", + deliveryId: "call-opaque", + type: "submission-accepted", + }); + harness.emitBridge({ + deliveryId: "call-opaque", + type: "canonical-text-ready", + }); + harness.advanceTime(10); + harness.emitBridge({ + deliveryId: "call-opaque", + type: "submission-settled", + }); + harness.advanceTime(10); + harness.emitSession({ + connectionEpoch: 1, + speechRequestId: "speech-opaque", + type: "canonical-speech-requested", + }); + harness.emitSession({ + connectionEpoch: 1, + speechRequestId: "speech-duplicate", + type: "canonical-speech-requested", + }); + harness.advanceTime(10); + const outputStarted: OpenAIRealtimeSessionEvent = { + connectionEpoch: 1, + responseId: "response-opaque", + speechRequestId: "speech-opaque", + type: "output-started", + }; + harness.emitSession(outputStarted); + harness.emitSession(outputStarted); + + expect(harness.latencyEvents).toEqual([ + { + correlationId: "call-opaque", + elapsedMs: 10, + name: "submission-admitted", + }, + { + correlationId: "call-opaque", + elapsedMs: 20, + name: "first-canonical-text", + }, + { + correlationId: "call-opaque", + elapsedMs: 30, + name: "submission-settled", + }, + { + correlationId: "call-opaque", + elapsedMs: 40, + name: "first-tts-request", + }, + { + correlationId: "call-opaque", + elapsedMs: 50, + name: "first-tts-audio", + }, + ]); + expect(JSON.stringify(harness.latencyEvents)).not.toContain( + "Private finalized answer", + ); + + await harness.controller.end(); + harness.emitBridge({ + deliveryId: "call-opaque", + type: "submission-settled", + }); + harness.emitSession(outputStarted); + expect(harness.latencyEvents).toHaveLength(5); + }); + + test("opens a continuous microphone before starting canonical question speech", async () => { + const harness = createHarness(); + const order: string[] = []; + harness.session.setMicrophoneEnabled.mockImplementation((enabled) => { + if (enabled) order.push("microphone-on"); + }); + harness.bridge.start.mockImplementation(() => order.push("bridge-start")); + harness.controller.updateChat({ + canAcceptInterviewAnswer: true, + canonicalSegments: [question("ask-1")], + questionSegment: markedQuestion("ask-1"), + status: "ready", + }); + + await harness.controller.start(); + + expect(order).toEqual(["microphone-on", "bridge-start"]); + expect(harness.controller.getSnapshot()).toMatchObject({ + connection: "connected", + currentQuestion: "What happens after approval?", + input: "listening", + microphoneEnabled: true, + output: "idle", + }); + }); + + test("tracks assistant playback without admitting automatic barge-in", async () => { + const harness = createHarness(); + await harness.controller.start(); + + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-1", + speechRequestId: "speech-1", + type: "output-started", + }); + expect(harness.controller.getSnapshot()).toMatchObject({ + input: "listening", + microphoneEnabled: true, + output: "speaking", + }); + + harness.emitSession({ + connectionEpoch: 1, + itemId: "item-user", + type: "input-speech-started", + }); + expect(harness.controller.getSnapshot()).toMatchObject({ + microphoneEnabled: true, + output: "speaking", + }); + expect(harness.session.cancelOutput).not.toHaveBeenCalled(); + }); + + test("clears pre-output capture and only commits fresh post-handoff input", async () => { + const harness = createHarness(); + harness.controller.updateChat({ + canAcceptInterviewAnswer: true, + canonicalSegments: [question("ask-late-transcript")], + questionSegment: markedQuestion("ask-late-transcript"), + status: "ready", + }); + await harness.controller.start(); + harness.emitSession({ + connectionEpoch: 1, + itemId: "item-before-output", + type: "input-speech-started", + }); + harness.emitSession({ + key: { + connectionEpoch: 1, + contentIndex: 0, + itemId: "item-before-output", + }, + text: "Pre-output partial", + type: "partial", + }); + expect(harness.controller.getSnapshot().partialText).toBe( + "Pre-output partial", + ); + + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-output", + speechRequestId: "speech-output", + type: "output-started", + }); + harness.emitSession({ + key: { + connectionEpoch: 1, + contentIndex: 0, + itemId: "item-before-output", + }, + text: "This completed too late.", + type: "completed", + }); + + expect(harness.controller.getSnapshot()).toMatchObject({ + lastCommittedText: "", + partialText: "", + }); + + await harness.controller.takeTurn(); + harness.emitSession({ + connectionEpoch: 1, + itemId: "item-after-handoff", + type: "input-speech-started", + }); + harness.emitSession({ + key: { + connectionEpoch: 1, + contentIndex: 0, + itemId: "item-after-handoff", + }, + text: "Fresh post-handoff answer.", + type: "completed", + }); + harness.emitBridge({ + answer: "Fresh post-handoff answer.", + deliveryId: "fresh-delivery", + type: "submission-started", + }); + + expect(harness.controller.getSnapshot()).toMatchObject({ + input: "submitting", + lastCommittedText: "Fresh post-handoff answer.", + partialText: "", + }); + }); + + test("clears capture when canonical speech is requested before output starts", async () => { + const harness = createHarness(); + harness.controller.updateChat({ + canAcceptInterviewAnswer: true, + canonicalSegments: [question("ask-request")], + questionSegment: markedQuestion("ask-request"), + status: "ready", + }); + await harness.controller.start(); + harness.emitBridge({ + deliveryId: "voice-request", + segments: [question("ask-request")], + type: "canonical-response-ready", + }); + harness.emitSession({ + connectionEpoch: 1, + itemId: "item-before-request", + type: "input-speech-started", + }); + harness.emitSession({ + key: { + connectionEpoch: 1, + contentIndex: 0, + itemId: "item-before-request", + }, + text: "Provisional pre-request words", + type: "partial", + }); + + harness.emitSession({ + connectionEpoch: 1, + speechRequestId: "speech-request", + type: "canonical-speech-requested", + }); + + expect(harness.session.setMicrophoneEnabled).toHaveBeenLastCalledWith( + false, + ); + expect(harness.controller.getSnapshot()).toMatchObject({ + canTakeTurn: true, + lastCommittedText: "", + partialText: "", + }); + harness.emitSession({ + key: { + connectionEpoch: 1, + contentIndex: 0, + itemId: "item-before-request", + }, + text: "This completed before output started.", + type: "completed", + }); + expect(harness.controller.getSnapshot()).toMatchObject({ + lastCommittedText: "", + partialText: "", + }); + expect(harness.submitText).not.toHaveBeenCalled(); + + await harness.controller.takeTurn(); + expect(harness.bridge.completeTurnHandoff).toHaveBeenCalledOnce(); + harness.emitSession({ + connectionEpoch: 1, + itemId: "item-after-handoff", + type: "input-speech-started", + }); + harness.emitSession({ + key: { + connectionEpoch: 1, + contentIndex: 0, + itemId: "item-after-handoff", + }, + text: "Fresh post-handoff answer.", + type: "completed", + }); + harness.emitBridge({ + answer: "Fresh post-handoff answer.", + deliveryId: "fresh-delivery", + type: "submission-started", + }); + + expect(harness.controller.getSnapshot()).toMatchObject({ + input: "submitting", + lastCommittedText: "Fresh post-handoff answer.", + partialText: "", + }); + }); + + test("offers handoff for canonical output without a question marker", async () => { + const harness = createHarness(); + await harness.controller.start(); + + harness.emitSession({ + connectionEpoch: 1, + speechRequestId: "speech-without-question", + type: "canonical-speech-requested", + }); + + expect(harness.controller.getSnapshot().canTakeTurn).toBe(true); + await harness.controller.takeTurn(); + expect(harness.bridge.completeTurnHandoff).toHaveBeenCalledOnce(); + }); + + test("offers handoff when canonical output follows an answered question", async () => { + const harness = createHarness(); + const answeredQuestion = markedQuestion("ask-answered"); + harness.controller.updateChat({ + canAcceptInterviewAnswer: true, + canonicalSegments: [answeredQuestion], + questionSegment: answeredQuestion, + status: "ready", + }); + await harness.controller.start(); + harness.emitBridge({ + answer: "The supervisor approves it.", + deliveryId: "call-answered", + type: "submission-started", + }); + harness.emitBridge({ + answer: "The supervisor approves it.", + deliveryId: "call-answered", + type: "submission-accepted", + }); + harness.emitBridge({ + deliveryId: "call-answered", + type: "submission-settled", + }); + harness.emitBridge({ + deliveryId: "call-answered", + segments: [question("follow-on", "Here is the follow-on detail.")], + type: "canonical-response-ready", + }); + + harness.emitSession({ + connectionEpoch: 1, + speechRequestId: "speech-after-answer", + type: "canonical-speech-requested", + }); + + expect(harness.controller.getSnapshot()).toMatchObject({ + canTakeTurn: true, + input: "listening", + output: "waiting-for-tool", + }); + }); + + test("keeps handoff unavailable while disconnected or paused", async () => { + const harness = createHarness(); + expect(harness.controller.getSnapshot().canTakeTurn).toBe(false); + await harness.controller.start(); + harness.emitSession({ + connectionEpoch: 1, + speechRequestId: "speech-before-pause", + type: "canonical-speech-requested", + }); + + harness.controller.pause(); + + expect(harness.controller.getSnapshot()).toMatchObject({ + canTakeTurn: false, + input: "paused", + }); + }); + + test("hands off an active response once and applies the latest mute preference after cancellation", async () => { + const harness = createHarness(); + let finishCancellation: (() => void) | undefined; + harness.controller.updateChat({ + canAcceptInterviewAnswer: true, + canonicalSegments: [question("ask-handoff")], + questionSegment: markedQuestion("ask-handoff"), + status: "ready", + }); + await harness.controller.start(); + harness.session.cancelOutput.mockImplementationOnce( + () => + new Promise((resolve) => { + finishCancellation = resolve; + }), + ); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-handoff", + speechRequestId: "speech-handoff", + type: "output-started", + }); + harness.session.cancelOutput.mockClear(); + + expect(harness.controller.getSnapshot().canTakeTurn).toBe(true); + const handoff = harness.controller.takeTurn(); + const repeatedHandoff = harness.controller.takeTurn(); + + expect(repeatedHandoff).toBe(handoff); + expect(harness.bridge.cancelPendingSpeech).toHaveBeenCalledOnce(); + expect(harness.session.cancelOutput).toHaveBeenCalledOnce(); + expect(harness.session.setMicrophoneEnabled).toHaveBeenLastCalledWith( + false, + ); + expect(harness.controller.getSnapshot()).toMatchObject({ + canTakeTurn: false, + output: "cancelling", + }); + + harness.session.setMicrophoneEnabled.mockClear(); + harness.controller.setMicrophoneMuted(true); + harness.controller.setMicrophoneMuted(false); + expect(harness.session.setMicrophoneEnabled).not.toHaveBeenCalled(); + expect(harness.controller.getSnapshot().microphoneEnabled).toBe(true); + + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-handoff", + type: "output-interrupted", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-handoff", + status: "cancelled", + type: "response-terminal", + }); + expect(harness.controller.getSnapshot().output).toBe("cancelling"); + + finishCancellation?.(); + await handoff; + + expect(harness.session.setMicrophoneEnabled).toHaveBeenCalledOnce(); + expect(harness.session.setMicrophoneEnabled).toHaveBeenCalledWith(true); + expect(harness.controller.getSnapshot()).toMatchObject({ + canTakeTurn: false, + microphoneEnabled: true, + output: "interrupted", + }); + }); + + test("reopens the microphone only after cancellation and Brunch settlement", async () => { + const harness = createHarness(); + harness.controller.updateChat({ + canAcceptInterviewAnswer: true, + canonicalSegments: [question("answered-question")], + questionSegment: markedQuestion("answered-question"), + status: "ready", + }); + await harness.controller.start(); + harness.emitBridge({ + answer: "The approved answer.", + deliveryId: "voice-request", + type: "submission-started", + }); + harness.emitBridge({ + answer: "The approved answer.", + deliveryId: "voice-request", + type: "submission-accepted", + }); + harness.controller.updateChat({ + canAcceptInterviewAnswer: false, + canonicalSegments: [question("next-question")], + questionSegment: markedQuestion("next-question"), + status: "streaming", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-handoff", + speechRequestId: "speech-handoff", + type: "output-started", + }); + harness.session.setMicrophoneEnabled.mockClear(); + + const handoff = harness.controller.takeTurn(); + let handoffFinished = false; + void handoff.then(() => { + handoffFinished = true; + }); + await Promise.resolve(); + + expect(handoffFinished).toBe(false); + expect(harness.bridge.completeTurnHandoff).not.toHaveBeenCalled(); + expect(harness.session.setMicrophoneEnabled).toHaveBeenCalledOnce(); + expect(harness.session.setMicrophoneEnabled).toHaveBeenCalledWith(false); + + harness.emitBridge({ + deliveryId: "voice-request", + type: "submission-settled", + }); + await handoff; + + expect(harness.bridge.completeTurnHandoff).toHaveBeenCalledOnce(); + expect(harness.session.setMicrophoneEnabled).toHaveBeenLastCalledWith(true); + }); + + test("cancels queued and later speech when the host stops a response", async () => { + const harness = createHarness(); + await harness.controller.start(); + + harness.controller.cancelPendingSpeech(); + + expect(harness.bridge.cancelPendingSpeech).toHaveBeenCalledOnce(); + expect(harness.session.cancelOutput).toHaveBeenCalledOnce(); + }); + + test("releases bridge ownership after pending output cancellation is acknowledged", async () => { + const harness = createHarness(); + let finishCancellation: (() => void) | undefined; + harness.session.cancelOutput.mockImplementationOnce( + () => + new Promise((resolve) => { + finishCancellation = resolve; + }), + ); + await harness.controller.start(); + harness.emitSession({ + connectionEpoch: 1, + speechRequestId: "speech-pending-cancellation", + type: "canonical-speech-requested", + }); + + harness.controller.cancelPendingSpeech(); + expect(harness.bridge.completeTurnHandoff).not.toHaveBeenCalled(); + + finishCancellation?.(); + await vi.waitFor(() => + expect(harness.bridge.completeTurnHandoff).toHaveBeenCalledOnce(), + ); + }); + + test("keeps the user turn when cancelled pending speech settles later", async () => { + const harness = createHarness(); + harness.controller.updateChat({ + canAcceptInterviewAnswer: true, + canonicalSegments: [question("ask-handoff")], + questionSegment: markedQuestion("ask-handoff"), + status: "ready", + }); + await harness.controller.start(); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-handoff", + speechRequestId: "speech-handoff", + type: "output-started", + }); + + await harness.controller.takeTurn(); + harness.session.setMicrophoneEnabled.mockClear(); + harness.emitBridge({ + deliveryId: "voice-1", + segments: [question("ask-late", "Retained late response")], + speechCancelled: true, + type: "canonical-response-ready", + }); + + expect(harness.controller.getSnapshot()).toMatchObject({ + input: "listening", + microphoneEnabled: true, + output: "interrupted", + }); + expect(harness.session.setMicrophoneEnabled).toHaveBeenLastCalledWith(true); + }); + + test("restores capture when cancelled settlement arrives after interrupted early speech", async () => { + const harness = createHarness(); + await harness.controller.start(); + harness.emitBridge({ + answer: "The supervisor approves it.", + deliveryId: "call-interrupted-early", + type: "submission-started", + }); + harness.emitBridge({ + answer: "The supervisor approves it.", + deliveryId: "call-interrupted-early", + type: "submission-accepted", + }); + harness.emitSession({ + connectionEpoch: 1, + speechRequestId: "speech-interrupted-early", + type: "canonical-speech-requested", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-interrupted-early", + speechRequestId: "speech-interrupted-early", + type: "output-started", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-interrupted-early", + type: "output-interrupted", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-interrupted-early", + status: "cancelled", + type: "response-terminal", + }); + harness.session.setMicrophoneEnabled.mockClear(); + + harness.emitBridge({ + deliveryId: "call-interrupted-early", + segments: [], + speechCancelled: true, + type: "canonical-response-ready", + }); + + expect(harness.controller.getSnapshot()).toMatchObject({ + input: "listening", + microphoneEnabled: true, + output: "interrupted", + }); + expect(harness.session.setMicrophoneEnabled).toHaveBeenLastCalledWith(true); + }); + + test("replays exact canonical response segments but does not infer a question from the final segment", async () => { + const harness = createHarness(); + const context = question("context", "Approval is required before release."); + const nextQuestion = question("ask-replay", "Who approves release?"); + await harness.controller.start(); + + harness.emitBridge({ + deliveryId: "voice-1", + segments: [context, nextQuestion], + type: "canonical-response-ready", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-source", + speechRequestId: "speech-source", + type: "output-started", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-source", + type: "output-stopped", + }); + + expect(harness.controller.getSnapshot()).toMatchObject({ + canReadFullResponse: false, + canRepeatQuestion: false, + }); + harness.controller.readFullResponse(); + expect(harness.session.speakCanonical).not.toHaveBeenCalled(); + + harness.emitSession({ + connectionEpoch: 1, + responseId: "unrelated-response", + status: "completed", + type: "response-terminal", + }); + expect(harness.controller.getSnapshot().canRepeatQuestion).toBe(false); + + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-source", + status: "completed", + type: "response-terminal", + }); + expect(harness.controller.getSnapshot()).toMatchObject({ + canReadFullResponse: true, + canRepeatQuestion: false, + }); + + expect(harness.session.speakCanonical).not.toHaveBeenCalled(); + + harness.controller.readFullResponse(); + expect(harness.session.speakCanonical).toHaveBeenCalledOnce(); + expect(harness.session.speakCanonical).toHaveBeenCalledWith([ + context, + nextQuestion, + ]); + }); + + test("repeats only the exact Brunch-marked question after replay settles", async () => { + const harness = createHarness(); + const context = question("context", "Approval is required before release."); + const finalProse = question( + "response-prose", + "The approver is recorded. I can explain the escalation path.", + ); + const exactQuestion: CanonicalSpeechSegment = { + ...question("marked-question", "Who approves release?"), + messageId: finalProse.messageId, + source: "assistant-question", + }; + await harness.controller.start(); + + harness.emitBridge({ + deliveryId: "voice-1", + questionSegment: exactQuestion, + segments: [context, finalProse], + type: "canonical-response-ready", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-source", + speechRequestId: "speech-source", + type: "output-started", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-source", + type: "output-stopped", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-source", + status: "completed", + type: "response-terminal", + }); + + expect(harness.controller.getSnapshot()).toMatchObject({ + canReadFullResponse: true, + canRepeatQuestion: true, + }); + + harness.controller.repeatQuestion(); + + expect(harness.session.speakCanonical).toHaveBeenCalledOnce(); + expect(harness.session.speakCanonical).toHaveBeenCalledWith([ + exactQuestion, + ]); + }); + + test.each(["resolved", "rejected"] as const)( + "keeps replay disabled until generic cancellation is %s", + async (cancellationOutcome) => { + const harness = createHarness(); + const replayQuestion = markedQuestion( + "replay-after-cancellation", + "Who approves release?", + ); + let finishCancellation: (() => void) | undefined; + harness.session.cancelOutput.mockImplementationOnce( + () => + new Promise((resolve, reject) => { + finishCancellation = () => { + if (cancellationOutcome === "resolved") { + resolve(); + } else { + reject(new Error("Cancellation failed.")); + } + }; + }), + ); + await harness.controller.start(); + harness.emitBridge({ + deliveryId: "voice-replay", + questionSegment: replayQuestion, + segments: [replayQuestion], + type: "canonical-response-ready", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-replay", + speechRequestId: "speech-replay", + type: "output-started", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-replay", + type: "output-stopped", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-replay", + status: "completed", + type: "response-terminal", + }); + expect(harness.controller.getSnapshot()).toMatchObject({ + canReadFullResponse: true, + canRepeatQuestion: true, + input: "listening", + output: "idle", + }); + + harness.controller.cancelPendingSpeech(); + + expect(harness.controller.getSnapshot()).toMatchObject({ + canReadFullResponse: false, + canRepeatQuestion: false, + }); + harness.controller.readFullResponse(); + harness.controller.repeatQuestion(); + expect(harness.session.speakCanonical).not.toHaveBeenCalled(); + + finishCancellation?.(); + await vi.waitFor(() => + expect(harness.controller.getSnapshot()).toMatchObject({ + canReadFullResponse: true, + canRepeatQuestion: true, + input: "listening", + output: "idle", + }), + ); + }, + ); + + test("disables replay while the user is capturing input", async () => { + const harness = createHarness(); + const segment = question("ask-capture"); + await harness.controller.start(); + harness.emitBridge({ + deliveryId: "voice-1", + segments: [segment], + type: "canonical-response-ready", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-source", + speechRequestId: "speech-source", + type: "output-started", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-source", + type: "output-stopped", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-source", + status: "completed", + type: "response-terminal", + }); + expect(harness.controller.getSnapshot()).toMatchObject({ + canReadFullResponse: true, + canRepeatQuestion: false, + }); + + harness.emitSession({ + connectionEpoch: 1, + itemId: "item-user", + type: "input-speech-started", + }); + + expect(harness.controller.getSnapshot()).toMatchObject({ + canReadFullResponse: false, + canRepeatQuestion: false, + }); + }); + + test("keeps capture closed from submission until canonical output settles", async () => { + const harness = createHarness(); + await harness.controller.start(); + harness.session.setMicrophoneEnabled.mockClear(); + + harness.emitBridge({ + answer: "The supervisor approves it.", + deliveryId: "call-1", + type: "submission-started", + }); + expect(harness.controller.getSnapshot()).toMatchObject({ + input: "submitting", + lastAnswerDelivery: "pending", + lastCommittedText: "The supervisor approves it.", + microphoneEnabled: true, + output: "waiting-for-tool", + }); + expect(harness.session.setMicrophoneEnabled).toHaveBeenLastCalledWith( + false, + ); + harness.emitBridge({ + answer: "The supervisor approves it.", + deliveryId: "call-1", + type: "submission-accepted", + }); + harness.emitBridge({ + deliveryId: "call-1", + segments: [question("ask-2", "Who acts next?")], + type: "canonical-response-ready", + }); + + expect(harness.controller.getSnapshot()).toMatchObject({ + input: "listening", + lastAnswerDelivery: "delivered", + microphoneEnabled: true, + output: "waiting-for-tool", + }); + expect(harness.session.setMicrophoneEnabled).not.toHaveBeenCalledWith(true); + + harness.emitSession({ + connectionEpoch: 1, + speechRequestId: "speech-next", + type: "canonical-speech-requested", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-next", + speechRequestId: "speech-next", + type: "output-started", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-next", + status: "completed", + type: "response-terminal", + }); + expect(harness.session.setMicrophoneEnabled).not.toHaveBeenCalledWith(true); -describe("VoiceTurnController", () => { - test("opens a continuous microphone before starting canonical question speech", async () => { + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-next", + type: "output-stopped", + }); + expect(harness.session.setMicrophoneEnabled).toHaveBeenLastCalledWith(true); + }); + + test("returns to listening after a durably stopped turn without speaking", async () => { const harness = createHarness(); - const order: string[] = []; - harness.session.setMicrophoneEnabled.mockImplementation((enabled) => { - if (enabled) order.push("microphone-on"); + await harness.controller.start(); + + harness.emitBridge({ + answer: "Stop this one.", + deliveryId: "voice-1", + type: "submission-started", }); - harness.bridge.start.mockImplementation(() => order.push("bridge-start")); - harness.controller.updateChat({ - canAcceptInterviewAnswer: true, - canonicalSegments: [question("ask-1")], - status: "ready", + harness.session.setMicrophoneEnabled.mockClear(); + harness.emitBridge({ + answer: "Stop this one.", + deliveryId: "voice-1", + type: "submission-accepted", + }); + harness.advanceTime(40); + harness.emitBridge({ deliveryId: "voice-1", type: "submission-settled" }); + harness.emitBridge({ + deliveryId: "voice-1", + outcome: "aborted", + type: "submission-stopped", + }); + + expect(harness.controller.getSnapshot()).toMatchObject({ + input: "listening", + lastAnswerDelivery: "delivered", + output: "idle", }); + expect(harness.session.setMicrophoneEnabled).toHaveBeenCalledOnce(); + expect(harness.session.setMicrophoneEnabled).toHaveBeenCalledWith(true); + expect(harness.latencyEvents).toContainEqual({ + correlationId: "voice-1", + elapsedMs: 40, + name: "submission-settled", + }); + }); + test("keeps finished early speech idle and restores capture after canonical settlement", async () => { + const harness = createHarness(); + const nextQuestion = markedQuestion("ask-early", "Who acts next?"); await harness.controller.start(); + harness.emitBridge({ + answer: "The supervisor approves it.", + deliveryId: "call-early", + type: "submission-started", + }); + harness.emitBridge({ + answer: "The supervisor approves it.", + deliveryId: "call-early", + type: "submission-accepted", + }); + harness.session.setMicrophoneEnabled.mockClear(); + harness.emitSession({ + connectionEpoch: 1, + speechRequestId: "speech-early", + type: "canonical-speech-requested", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-early", + speechRequestId: "speech-early", + type: "output-started", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-early", + status: "completed", + type: "response-terminal", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-early", + type: "output-stopped", + }); + + harness.emitBridge({ + deliveryId: "call-early", + questionSegment: nextQuestion, + segments: [nextQuestion], + type: "canonical-response-ready", + }); - expect(order).toEqual(["microphone-on", "bridge-start"]); expect(harness.controller.getSnapshot()).toMatchObject({ - connection: "connected", - currentQuestion: "What happens after approval?", + canReadFullResponse: true, + canRepeatQuestion: true, input: "listening", - microphoneEnabled: true, output: "idle", }); + expect(harness.session.setMicrophoneEnabled).toHaveBeenLastCalledWith(true); }); - test("keeps capture active while the interviewer speaks and interrupts automatically", async () => { + test("keeps capture closed when more canonical speech starts at settlement", async () => { const harness = createHarness(); + const finalSegment = markedQuestion("ask-final", "Who acts next?"); await harness.controller.start(); - + harness.emitBridge({ + answer: "The supervisor approves it.", + deliveryId: "call-queued", + type: "submission-started", + }); harness.emitSession({ connectionEpoch: 1, - responseId: "response-1", + speechRequestId: "speech-early", + type: "canonical-speech-requested", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-early", + speechRequestId: "speech-early", type: "output-started", }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-early", + status: "completed", + type: "response-terminal", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-early", + type: "output-stopped", + }); + harness.session.setMicrophoneEnabled.mockClear(); + + harness.emitSession({ + connectionEpoch: 1, + speechRequestId: "speech-final", + type: "canonical-speech-requested", + }); + harness.emitBridge({ + deliveryId: "call-queued", + questionSegment: finalSegment, + segments: [finalSegment], + type: "canonical-response-ready", + }); + expect(harness.controller.getSnapshot()).toMatchObject({ + canReadFullResponse: false, + canRepeatQuestion: false, input: "listening", - microphoneEnabled: true, - output: "speaking", + output: "waiting-for-tool", }); + expect(harness.session.setMicrophoneEnabled).not.toHaveBeenCalledWith(true); harness.emitSession({ connectionEpoch: 1, - itemId: "item-user", - type: "input-speech-started", + responseId: "response-final", + speechRequestId: "speech-final", + type: "output-started", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-final", + status: "completed", + type: "response-terminal", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-final", + type: "output-stopped", }); + expect(harness.controller.getSnapshot()).toMatchObject({ - microphoneEnabled: true, - output: "interrupted", + canReadFullResponse: true, + canRepeatQuestion: true, + output: "idle", }); - expect(harness.session.cancelOutput).not.toHaveBeenCalled(); + expect(harness.session.setMicrophoneEnabled).toHaveBeenLastCalledWith(true); }); - test("represents submitting and output independently without closing capture", async () => { + test("keeps follow-on speech pending when the earlier output stop arrives late", async () => { const harness = createHarness(); + const followOnQuestion = markedQuestion("ask-follow-on", "Who acts next?"); + harness.controller.updateChat({ + canAcceptInterviewAnswer: true, + canonicalSegments: [followOnQuestion], + questionSegment: followOnQuestion, + status: "ready", + }); await harness.controller.start(); + harness.emitSession({ + connectionEpoch: 1, + speechRequestId: "speech-early", + type: "canonical-speech-requested", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-early", + speechRequestId: "speech-early", + type: "output-started", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-early", + status: "completed", + type: "response-terminal", + }); + harness.emitSession({ + connectionEpoch: 1, + speechRequestId: "speech-follow-on", + type: "canonical-speech-requested", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-follow-on", + speechRequestId: "speech-follow-on", + status: "completed", + type: "response-terminal", + }); + harness.session.setMicrophoneEnabled.mockClear(); - harness.emitBridge({ - answer: "The supervisor approves it.", - callId: "call-1", - type: "submission-started", + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-early", + type: "output-stopped", }); + expect(harness.controller.getSnapshot()).toMatchObject({ - input: "submitting", - lastAnswerDelivery: "pending", - lastCommittedText: "The supervisor approves it.", - microphoneEnabled: true, + canReadFullResponse: false, + canRepeatQuestion: false, + canTakeTurn: true, output: "waiting-for-tool", }); + expect(harness.session.setMicrophoneEnabled).not.toHaveBeenCalledWith(true); + + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-follow-on", + speechRequestId: "speech-follow-on", + type: "output-started", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-follow-on", + type: "output-stopped", + }); + + expect(harness.controller.getSnapshot().output).toBe("idle"); + expect(harness.session.setMicrophoneEnabled).toHaveBeenLastCalledWith(true); + }); + + test("preserves speaking output when canonical settlement arrives during playback", async () => { + const harness = createHarness(); + const nextQuestion = markedQuestion("ask-playing", "Who acts next?"); + await harness.controller.start(); harness.emitBridge({ answer: "The supervisor approves it.", - callId: "call-1", - type: "submission-accepted", + deliveryId: "call-playing", + type: "submission-started", + }); + harness.emitSession({ + connectionEpoch: 1, + speechRequestId: "speech-playing", + type: "canonical-speech-requested", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-playing", + speechRequestId: "speech-playing", + type: "output-started", }); + harness.session.setMicrophoneEnabled.mockClear(); + harness.emitBridge({ - callId: "call-1", - segments: [question("ask-2", "Who acts next?")], + deliveryId: "call-playing", + questionSegment: nextQuestion, + segments: [nextQuestion], type: "canonical-response-ready", }); expect(harness.controller.getSnapshot()).toMatchObject({ + canReadFullResponse: false, + canRepeatQuestion: false, input: "listening", - lastAnswerDelivery: "delivered", - microphoneEnabled: true, - output: "waiting-for-tool", + output: "speaking", }); - expect(harness.session.setMicrophoneEnabled).not.toHaveBeenCalledWith( - false, + expect(harness.session.setMicrophoneEnabled).not.toHaveBeenCalledWith(true); + + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-playing", + status: "completed", + type: "response-terminal", + }); + harness.emitSession({ + connectionEpoch: 1, + responseId: "response-playing", + type: "output-stopped", + }); + + expect(harness.controller.getSnapshot()).toMatchObject({ + canReadFullResponse: true, + canRepeatQuestion: true, + output: "idle", + }); + expect(harness.session.setMicrophoneEnabled).toHaveBeenLastCalledWith(true); + }); + + test("restores capture after a cancelled reply finishes provider cancellation", async () => { + const harness = createHarness(); + let finishCancellation: (() => void) | undefined; + await harness.controller.start(); + harness.emitBridge({ + answer: "Cancel this reply.", + deliveryId: "call-cancelled", + type: "submission-started", + }); + harness.session.cancelOutput.mockImplementationOnce( + () => + new Promise((resolve) => { + finishCancellation = resolve; + }), ); + harness.controller.cancelPendingSpeech(); + harness.session.setMicrophoneEnabled.mockClear(); + + harness.emitBridge({ + deliveryId: "call-cancelled", + segments: [], + speechCancelled: true, + type: "canonical-response-ready", + }); + + expect(harness.controller.getSnapshot()).toMatchObject({ + input: "listening", + output: "interrupted", + }); + expect(harness.session.setMicrophoneEnabled).not.toHaveBeenCalledWith(true); + + finishCancellation?.(); + await Promise.resolve(); + + expect(harness.session.setMicrophoneEnabled).toHaveBeenLastCalledWith(true); }); test("restores submission state when resumed before Brunch releases the turn", async () => { @@ -160,13 +1356,14 @@ describe("VoiceTurnController", () => { await harness.controller.start(); harness.emitBridge({ answer: "The supervisor approves it.", - callId: "call-1", + deliveryId: "call-1", type: "submission-started", }); harness.controller.pause(); - harness.controller.resume(); + await harness.controller.resume(); + expect(harness.bridge.cancelPendingSpeech).toHaveBeenCalledOnce(); expect(harness.controller.getSnapshot()).toMatchObject({ input: "submitting", lastAnswerDelivery: "pending", @@ -175,11 +1372,11 @@ describe("VoiceTurnController", () => { harness.emitBridge({ answer: "The supervisor approves it.", - callId: "call-1", + deliveryId: "call-1", type: "submission-accepted", }); harness.emitBridge({ - callId: "call-1", + deliveryId: "call-1", segments: [question("ask-2", "Who acts next?")], type: "canonical-response-ready", }); @@ -195,27 +1392,29 @@ describe("VoiceTurnController", () => { harness.controller.updateChat({ canAcceptInterviewAnswer: true, canonicalSegments: [question("ask-1")], + questionSegment: markedQuestion("ask-1"), status: "ready", }); await harness.controller.start(); harness.emitBridge({ answer: "The supervisor approves it.", - callId: "call-1", + deliveryId: "call-1", type: "submission-started", }); harness.controller.updateChat({ canAcceptInterviewAnswer: true, canonicalSegments: [question("ask-2", "Who acts next?")], + questionSegment: markedQuestion("ask-2", "Who acts next?"), status: "ready", }); harness.emitBridge({ answer: "The supervisor approves it.", - callId: "call-1", + deliveryId: "call-1", type: "submission-accepted", }); harness.emitBridge({ - callId: "call-1", + deliveryId: "call-1", segments: [question("ask-2", "Who acts next?")], type: "canonical-response-ready", }); @@ -237,13 +1436,13 @@ describe("VoiceTurnController", () => { await harness.controller.start(); harness.emitBridge({ answer: "The supervisor approves it.", - callId: "call-1", + deliveryId: "call-1", type: "submission-started", }); harness.controller.pause(); harness.emitBridge({ - callId: "call-1", + deliveryId: "call-1", segments: [question("ask-2", "Who acts next?")], type: "canonical-response-ready", }); @@ -253,9 +1452,9 @@ describe("VoiceTurnController", () => { microphoneEnabled: false, output: "interrupted", }); - expect(harness.session.cancelOutput).toHaveBeenCalledTimes(2); + expect(harness.session.cancelOutput).toHaveBeenCalledOnce(); - harness.controller.resume(); + await harness.controller.resume(); expect(harness.controller.getSnapshot()).toMatchObject({ input: "listening", microphoneEnabled: true, @@ -290,6 +1489,33 @@ describe("VoiceTurnController", () => { expect(harness.submitText).not.toHaveBeenCalled(); }); + test.each(["empty", "failed"] as const)( + "reports a recoverable not-heard notice for a %s transcript", + async (reason) => { + const harness = createHarness(); + await harness.controller.start(); + harness.emitSession({ + connectionEpoch: 1, + itemId: "item-1", + type: "input-speech-started", + }); + harness.emitSession({ + key: { connectionEpoch: 1, contentIndex: 0, itemId: "item-1" }, + text: "Provisional words", + type: "partial", + }); + + harness.emitBridge({ reason, type: "transcript-rejected" }); + + expect(harness.controller.getSnapshot()).toMatchObject({ + input: "listening", + inputNotice: "not-heard", + partialText: "", + }); + expect(harness.submitText).not.toHaveBeenCalled(); + }, + ); + test("keeps completed display transcripts until submission and rejects late events", async () => { const harness = createHarness(); await harness.controller.start(); @@ -305,11 +1531,11 @@ describe("VoiceTurnController", () => { }); harness.emitBridge({ answer: "First answer", - callId: "call-1", + deliveryId: "call-1", type: "submission-started", }); harness.emitBridge({ - callId: "call-1", + deliveryId: "call-1", segments: [question("ask-2", "Who acts next?")], type: "canonical-response-ready", }); @@ -380,6 +1606,7 @@ describe("VoiceTurnController", () => { harness.emitSession({ connectionEpoch: 1, responseId: "response-1", + speechRequestId: "speech-1", type: "output-started", }); @@ -394,19 +1621,51 @@ describe("VoiceTurnController", () => { output: "interrupted", }); - harness.controller.resume(); + await harness.controller.resume(); expect(harness.controller.getSnapshot()).toMatchObject({ input: "listening", microphoneEnabled: true, }); }); + test("reuses pending output cancellation across paused chat updates", async () => { + const harness = createHarness(); + let finishCancellation: (() => void) | undefined; + harness.session.cancelOutput.mockImplementation( + () => + new Promise((resolve) => { + finishCancellation = resolve; + }), + ); + await harness.controller.start(); + harness.controller.pause(); + const listener = vi.fn(); + harness.controller.subscribe(listener); + const update = { + canAcceptInterviewAnswer: true, + canonicalSegments: [], + status: "ready" as const, + }; + + harness.controller.updateChat(update); + harness.controller.updateChat(update); + + expect(harness.session.cancelOutput).toHaveBeenCalledOnce(); + expect(listener).not.toHaveBeenCalled(); + + finishCancellation?.(); + await vi.waitFor(() => + expect(harness.bridge.completeTurnHandoff).toHaveBeenCalledOnce(), + ); + }); + test("mutes capture without interrupting what the interviewer is saying", async () => { const harness = createHarness(); await harness.controller.start(); harness.emitSession({ connectionEpoch: 1, responseId: "response-1", + speechRequestId: "speech-1", type: "output-started", }); @@ -471,7 +1730,7 @@ describe("VoiceTurnController", () => { output: "idle", }); - harness.controller.resume(); + await harness.controller.resume(); expect(harness.bridge.start).toHaveBeenCalledWith(1); expect(harness.controller.getSnapshot()).toMatchObject({ input: "listening", @@ -479,7 +1738,7 @@ describe("VoiceTurnController", () => { }); }); - test("cancels output that starts while paused without exposing speaking", async () => { + test("keeps pending cancellation when output starts while paused", async () => { const harness = createHarness(); await harness.controller.start(); harness.controller.pause(); @@ -490,10 +1749,11 @@ describe("VoiceTurnController", () => { harness.emitSession({ connectionEpoch: 1, responseId: "response-after-pause", + speechRequestId: "speech-after-pause", type: "output-started", }); - expect(harness.session.cancelOutput).toHaveBeenCalledOnce(); + expect(harness.session.cancelOutput).not.toHaveBeenCalled(); expect(observedOutputs).not.toContain("speaking"); expect(harness.controller.getSnapshot()).toMatchObject({ input: "paused", @@ -509,6 +1769,7 @@ describe("VoiceTurnController", () => { harness.emitSession({ connectionEpoch: 1, responseId: "stale-response", + speechRequestId: "stale-speech", type: "output-started", }); @@ -587,6 +1848,10 @@ describe("VoiceTurnController", () => { canonicalSegments: [ question("ask-reconnect", "What happens after approval?"), ], + questionSegment: markedQuestion( + "ask-reconnect", + "What happens after approval?", + ), status: "ready", }); await harness.controller.start(); @@ -613,12 +1878,16 @@ describe("VoiceTurnController", () => { canonicalSegments: [ question("ask-failed-delivery", "What happens after approval?"), ], + questionSegment: markedQuestion( + "ask-failed-delivery", + "What happens after approval?", + ), status: "ready", }); await harness.controller.start(); harness.emitBridge({ answer: "The supervisor approves it.", - callId: "call-1", + deliveryId: "call-1", type: "submission-started", }); harness.emitBridge({ @@ -636,6 +1905,52 @@ describe("VoiceTurnController", () => { expect(harness.session.connect).toHaveBeenCalledTimes(2); }); + test.each([ + { + code: "admission-rejected" as const, + failure: { kind: "rejected", status: 403 } as const, + message: "Brunch rejected the message before admission (HTTP 403).", + }, + { + code: "admission-conflict" as const, + failure: { + kind: "submission-conflict", + status: 409, + submissionId: "submission-existing", + } as const, + message: + "The delivery key already belongs to admitted submission submission-existing; the changed payload was not admitted.", + }, + { + code: "admission-ambiguous" as const, + failure: { kind: "ambiguous" } as const, + message: + "Brunch may have accepted the message, but admission could not be confirmed. Reopen the conversation before trying again.", + }, + { + code: "admission-aborted" as const, + failure: { kind: "aborted" } as const, + message: "The local chat submission was cancelled.", + }, + ])("surfaces $failure.kind admission safely", async (admissionFailure) => { + const harness = createHarness(); + await harness.controller.start(); + harness.emitBridge({ + answer: "The supervisor approves it.", + deliveryId: "voice-turn-1", + type: "submission-started", + }); + + harness.emitBridge({ ...admissionFailure, type: "error" }); + + expect(harness.controller.getSnapshot()).toMatchObject({ + connection: "error", + errorCode: admissionFailure.code, + errorMessage: admissionFailure.message, + lastAnswerDelivery: "failed", + }); + }); + test("clears a provisional transcript when the interview fails", async () => { const harness = createHarness(); await harness.controller.start(); @@ -687,7 +2002,7 @@ describe("VoiceTurnController", () => { await bridgeFailure.controller.start(); bridgeFailure.emitBridge({ answer: "Pending answer", - callId: "call-1", + deliveryId: "call-1", type: "submission-started", }); bridgeFailure.emitBridge({ diff --git a/apps/petrinaut-website/src/main/app/voice-interview/voice-turn-controller.ts b/apps/petrinaut-website/src/main/app/voice-interview/voice-turn-controller.ts index 4277717f7aa..4c8c5950c3a 100644 --- a/apps/petrinaut-website/src/main/app/voice-interview/voice-turn-controller.ts +++ b/apps/petrinaut-website/src/main/app/voice-interview/voice-turn-controller.ts @@ -5,7 +5,12 @@ import type { OpenAIRealtimeSessionEvent } from "./openai-realtime-session"; import type { RealtimeBridgeErrorCode, RealtimeBrunchBridgeEvent, + VoiceSubmissionSettlement, } from "./realtime-brunch-bridge"; +import type { + PetrinautAiComposerControlContext, + PetrinautAiVoiceModeContext, +} from "@hashintel/petrinaut/ui"; export type VoiceConnectionState = | "idle" @@ -14,13 +19,18 @@ export type VoiceConnectionState = | "error"; export type VoiceInputState = "listening" | "paused" | "submitting"; export type VoiceOutputState = + | "cancelling" | "idle" | "waiting-for-tool" | "speaking" | "interrupted"; export type VoiceAnswerDelivery = "none" | "pending" | "delivered" | "failed"; +export type VoiceInputNotice = "none" | "not-heard" | "too-long"; export interface VoiceTurnSnapshot { + readonly canReadFullResponse: boolean; + readonly canRepeatQuestion: boolean; + readonly canTakeTurn: boolean; readonly canReviseLastAnswer: boolean; readonly connection: VoiceConnectionState; readonly currentQuestion: string; @@ -28,6 +38,7 @@ export interface VoiceTurnSnapshot { readonly errorMessage: string; readonly errorRequestId: string; readonly input: VoiceInputState; + readonly inputNotice: VoiceInputNotice; readonly lastAnswerDelivery: VoiceAnswerDelivery; readonly lastCommittedText: string; readonly microphoneEnabled: boolean; @@ -37,35 +48,44 @@ export interface VoiceTurnSnapshot { } export interface VoiceLatencyEvent { + readonly correlationId: string; readonly elapsedMs: number; readonly name: + | "submission-admitted" + | "submission-settled" + | "first-canonical-text" + | "first-tts-request" + | "first-tts-audio" | "question-visible" | "question-spoken-started" | "question-spoken" | "answer-ready"; - readonly questionId: string; } -type ChatStatus = "ready" | "submitted" | "streaming" | "error"; - interface RealtimeSession { - cancelOutput(): void; + cancelOutput(): Promise; connect(): Promise; disconnect(): Promise; setMicrophoneEnabled(enabled: boolean): void; + speakCanonical(segments: CanonicalSpeechSegment[]): void; subscribe(listener: (event: OpenAIRealtimeSessionEvent) => void): () => void; } interface RealtimeBridge { + cancelPendingSpeech(): void; + completeTurnHandoff(): void; start(connectionEpoch: number): void; stop(): void; subscribe(listener: (event: RealtimeBrunchBridgeEvent) => void): () => void; updateChat(update: ChatUpdate): void; } -interface SubmitTextInput { +type ComposerSubmitTextInput = Parameters< + PetrinautAiComposerControlContext["submitText"] +>[0]; + +interface SubmitTextInput extends Pick { readonly target: "message"; - readonly text: string; } interface VoiceTurnControllerDependencies { @@ -79,12 +99,24 @@ interface VoiceTurnControllerDependencies { interface ChatUpdate { readonly canAcceptInterviewAnswer: boolean; readonly canonicalSegments: CanonicalSpeechSegment[]; - readonly status: ChatStatus; + readonly questionSegment?: CanonicalSpeechSegment; + readonly settlements?: readonly VoiceSubmissionSettlement[]; + readonly stopped?: boolean; + readonly status: PetrinautAiVoiceModeContext["status"]; +} + +interface PendingSubmissionSettlement { + readonly deliveryId: string; + readonly promise: Promise; + readonly resolve: () => void; } type SnapshotListener = (snapshot: VoiceTurnSnapshot) => void; const initialSnapshot: VoiceTurnSnapshot = { + canReadFullResponse: false, + canRepeatQuestion: false, + canTakeTurn: false, canReviseLastAnswer: false, connection: "idle", currentQuestion: "", @@ -92,6 +124,7 @@ const initialSnapshot: VoiceTurnSnapshot = { errorMessage: "", errorRequestId: "", input: "paused", + inputNotice: "none", lastAnswerDelivery: "none", lastCommittedText: "", microphoneEnabled: false, @@ -100,11 +133,6 @@ const initialSnapshot: VoiceTurnSnapshot = { partialText: "", }; -const latestQuestion = ( - segments: CanonicalSpeechSegment[], -): CanonicalSpeechSegment | undefined => - segments.findLast(({ source }) => source === "brunch-ask"); - export class VoiceTurnController { readonly #bridge: RealtimeBridge; readonly #listeners = new Set(); @@ -113,18 +141,32 @@ export class VoiceTurnController { readonly #session: RealtimeSession; readonly #submitText: (input: SubmitTextInput) => Promise; #activeEpoch: number | null = null; + #activeSpeechOutputEnded = false; + #activeSpeechResponseId: string | null = null; + #activeSpeechResponseTerminal = false; #answerFinalizedAt: number | null = null; #answeredQuestionId: string | null = null; #bridgeStarted = false; #currentQuestionId: string | null = null; #generation = 0; #inputStateOnResume: Exclude | null = null; + #inputTurnPending = false; + #latencyCorrelationId: string | null = null; + #lastResponseQuestion: CanonicalSpeechSegment | null = null; + #lastResponseSegments: CanonicalSpeechSegment[] = []; + #outputCancellationPromise: Promise | null = null; #pauseRequested = false; + readonly #pendingSpeechRequestIds = new Set(); + #pendingSubmissionSettlement: PendingSubmissionSettlement | null = null; + readonly #recordedLatencyEvents = new Set(); #snapshot = initialSnapshot; #submittingQuestionId: string | null = null; + #takingTurnPromise: Promise | null = null; #teardownPromise: Promise | null = null; + readonly #terminalSpeechRequestIds = new Set(); #transcriptItemId: string | null = null; #transcriptKey: string | null = null; + #ttsSpeechRequestId: string | null = null; public constructor({ bridge, @@ -180,8 +222,16 @@ export class VoiceTurnController { } this.#inputStateOnResume = null; + this.#inputTurnPending = false; + this.#outputCancellationPromise = null; this.#pauseRequested = false; + this.#pendingSpeechRequestIds.clear(); + this.#terminalSpeechRequestIds.clear(); + this.#completeSubmissionSettlement(); this.#bridgeStarted = false; + this.#activeSpeechOutputEnded = false; + this.#activeSpeechResponseId = null; + this.#activeSpeechResponseTerminal = false; this.#update({ connection: "connecting", errorCode: null, @@ -219,15 +269,29 @@ export class VoiceTurnController { public async end(): Promise { ++this.#generation; this.#activeEpoch = null; + this.#activeSpeechOutputEnded = false; + this.#activeSpeechResponseId = null; + this.#activeSpeechResponseTerminal = false; this.#answerFinalizedAt = null; this.#answeredQuestionId = null; this.#bridgeStarted = false; this.#currentQuestionId = null; this.#inputStateOnResume = null; + this.#inputTurnPending = false; + this.#latencyCorrelationId = null; + this.#lastResponseQuestion = null; + this.#lastResponseSegments = []; + this.#outputCancellationPromise = null; + this.#pendingSpeechRequestIds.clear(); + this.#recordedLatencyEvents.clear(); this.#submittingQuestionId = null; + this.#takingTurnPromise = null; + this.#terminalSpeechRequestIds.clear(); + this.#completeSubmissionSettlement(); this.#pauseRequested = false; this.#transcriptItemId = null; this.#transcriptKey = null; + this.#ttsSpeechRequestId = null; this.#bridge.stop(); this.#session.setMicrophoneEnabled(false); const teardownPromise = this.#teardownPromise ?? this.#session.disconnect(); @@ -274,7 +338,7 @@ export class VoiceTurnController { this.#inputStateOnResume = this.#snapshot.input; this.#pauseRequested = true; const output = this.#snapshot.output === "idle" ? "idle" : "interrupted"; - this.#session.cancelOutput(); + this.cancelPendingSpeech(); this.#session.setMicrophoneEnabled(false); this.#update({ input: "paused", @@ -297,17 +361,51 @@ export class VoiceTurnController { ) { return; } - this.#session.setMicrophoneEnabled(!muted); + if ( + this.#takingTurnPromise === null && + this.#outputCancellationPromise === null && + this.#activeSpeechResponseId === null && + (this.#snapshot.output === "idle" || + this.#snapshot.output === "interrupted") + ) { + this.#session.setMicrophoneEnabled(!muted); + } this.#update({ microphoneEnabled: !muted, microphoneLevel: 0 }); } - public resume(): void { + public async resume(): Promise { if ( this.#snapshot.connection !== "connected" || this.#snapshot.input !== "paused" ) { return; } + const generation = this.#generation; + while (this.#outputCancellationPromise || this.#takingTurnPromise) { + try { + await (this.#outputCancellationPromise ?? this.#takingTurnPromise); + } catch (error) { + if (generation !== this.#generation) return; + const voiceError = + error instanceof VoiceError + ? error + : new VoiceError("speech", "network", ""); + this.#setError( + voiceError.message, + voiceError.code, + voiceError.requestId, + ); + return; + } + const snapshotAfterCancellation = this.getSnapshot(); + if ( + generation !== this.#generation || + snapshotAfterCancellation.connection !== "connected" || + snapshotAfterCancellation.input !== "paused" + ) { + return; + } + } const input = this.#inputStateOnResume ?? "listening"; this.#inputStateOnResume = null; this.#pauseRequested = false; @@ -332,6 +430,11 @@ export class VoiceTurnController { this.#update({ input, microphoneEnabled: true }); } + public cancelPendingSpeech(): void { + this.#bridge.cancelPendingSpeech(); + void this.#cancelOutput(); + } + public async submitCorrection(correction: string): Promise { const correctedText = correction.trim(); const previousText = this.#snapshot.lastCommittedText; @@ -364,36 +467,123 @@ export class VoiceTurnController { } } + public readFullResponse(): void { + if (!this.#snapshot.canReadFullResponse) return; + this.#update({ output: "waiting-for-tool" }); + this.#session.speakCanonical([...this.#lastResponseSegments]); + } + + public repeatQuestion(): void { + if (!this.#snapshot.canRepeatQuestion || !this.#lastResponseQuestion) + return; + this.#update({ output: "waiting-for-tool" }); + this.#session.speakCanonical([this.#lastResponseQuestion]); + } + + /** + * Hands the turn to the user only after provider cancellation has cleared + * input and output and the active response has reached a terminal state. + */ + public takeTurn(): Promise { + if (this.#takingTurnPromise) return this.#takingTurnPromise; + if (!this.#snapshot.canTakeTurn) return Promise.resolve(); + + const generation = this.#generation; + this.#bridge.cancelPendingSpeech(); + this.#session.setMicrophoneEnabled(false); + this.#inputTurnPending = false; + this.#transcriptItemId = null; + this.#transcriptKey = null; + this.#update({ output: "cancelling", partialText: "" }); + + const submissionSettlement = + this.#pendingSubmissionSettlement?.promise ?? Promise.resolve(); + const takingTurnPromise = Promise.all([ + this.#session.cancelOutput(), + submissionSettlement, + ]) + .then(() => { + if ( + generation !== this.#generation || + this.#snapshot.connection !== "connected" || + this.#snapshot.input === "paused" + ) { + return; + } + this.#activeSpeechOutputEnded = false; + this.#activeSpeechResponseId = null; + this.#activeSpeechResponseTerminal = false; + this.#pendingSpeechRequestIds.clear(); + this.#terminalSpeechRequestIds.clear(); + this.#bridge.completeTurnHandoff(); + this.#session.setMicrophoneEnabled(this.#snapshot.microphoneEnabled); + this.#update({ output: "interrupted" }); + }) + .catch((error: unknown) => { + if (generation !== this.#generation) return; + const voiceError = + error instanceof VoiceError + ? error + : new VoiceError("speech", "network", ""); + this.#setError( + voiceError.message, + voiceError.code, + voiceError.requestId, + ); + }) + .finally(() => { + if (this.#takingTurnPromise === takingTurnPromise) { + this.#takingTurnPromise = null; + this.#update({}); + } + }); + this.#takingTurnPromise = takingTurnPromise; + this.#update({}); + return takingTurnPromise; + } + public updateChat(update: ChatUpdate): void { - const question = latestQuestion(update.canonicalSegments); + const question = update.questionSegment; if (question && question.id !== this.#currentQuestionId) { this.#currentQuestionId = question.id; this.#update({ currentQuestion: question.text }); this.#recordLatency("question-visible", question.id); } this.#bridge.updateChat(update); - if (this.#snapshot.input === "paused") { - this.#session.cancelOutput(); + if ( + this.#snapshot.input === "paused" && + (this.#activeSpeechResponseId !== null || + this.#pendingSpeechRequestIds.size > 0) + ) { + void this.#cancelOutput(); } } #handleBridgeEvent(event: RealtimeBrunchBridgeEvent): void { if (this.#snapshot.connection !== "connected") return; if (event.type === "error") { + this.#completeSubmissionSettlement(); this.#setError(event.message, event.code); return; } if (event.type === "submission-started") { + this.#beginSubmissionSettlement(event.deliveryId); const paused = this.#snapshot.input === "paused"; if (paused) { this.#inputStateOnResume = "submitting"; } + this.#inputTurnPending = false; this.#answerFinalizedAt = this.#now(); + this.#latencyCorrelationId = event.deliveryId; + this.#recordedLatencyEvents.clear(); this.#submittingQuestionId = this.#currentQuestionId; this.#transcriptItemId = null; this.#transcriptKey = null; + this.#ttsSpeechRequestId = null; + this.#session.setMicrophoneEnabled(false); this.#update({ input: paused ? "paused" : "submitting", + inputNotice: "none", lastAnswerDelivery: "pending", lastCommittedText: event.answer, output: "waiting-for-tool", @@ -401,25 +591,89 @@ export class VoiceTurnController { }); return; } + if (event.type === "transcript-rejected") { + if (event.reason === "duplicate" || event.reason === "unavailable") { + return; + } + this.#transcriptItemId = null; + this.#transcriptKey = null; + this.#update({ + inputNotice: event.reason === "over-limit" ? "too-long" : "not-heard", + partialText: "", + }); + return; + } if (event.type === "submission-accepted") { this.#answeredQuestionId = this.#submittingQuestionId; this.#submittingQuestionId = null; this.#update({ lastAnswerDelivery: "delivered" }); return; } + if (event.type === "submission-admitted") { + this.#recordLatency("submission-admitted", event.deliveryId); + return; + } + if (event.type === "canonical-text-ready") { + this.#recordLatency("first-canonical-text", event.deliveryId); + return; + } + if (event.type === "submission-settled") { + this.#completeSubmissionSettlement(event.deliveryId); + this.#recordLatency("submission-settled", event.deliveryId); + return; + } + if (event.type === "submission-stopped") { + this.#completeSubmissionSettlement(event.deliveryId); + // Brunch was stopped before it replied: nothing to speak, and the + // interviewer is free to listen again. + const pausedWhileStopped = this.#snapshot.input === "paused"; + if (pausedWhileStopped) { + this.#inputStateOnResume = "listening"; + } + this.#update({ + input: pausedWhileStopped ? "paused" : "listening", + output: "idle", + }); + this.#restoreMicrophoneIfCaptureAvailable(); + return; + } + this.#completeSubmissionSettlement(event.deliveryId); + this.#lastResponseQuestion = event.questionSegment ?? null; + this.#lastResponseSegments = [...event.segments]; + const responseEnd = event.segments.at(-1); + if (event.speechCancelled) { + const paused = this.#snapshot.input === "paused"; + if (paused) { + this.#inputStateOnResume = "listening"; + } + this.#update({ + input: paused ? "paused" : "listening", + output: "interrupted", + }); + this.#restoreMicrophoneIfCaptureAvailable(); + if (responseEnd) this.#recordLatency("answer-ready", responseEnd.id); + return; + } const paused = this.#snapshot.input === "paused"; if (paused) { this.#inputStateOnResume = "listening"; - this.#session.cancelOutput(); + void this.#cancelOutput(); } + const preserveSettledOutput = + this.#snapshot.output === "speaking" || + this.#snapshot.output === "waiting-for-tool" || + (this.#snapshot.output === "idle" && + this.#snapshot.input === "submitting"); this.#update({ input: paused ? "paused" : "listening", - output: paused ? "interrupted" : "waiting-for-tool", + output: paused + ? "interrupted" + : preserveSettledOutput + ? this.#snapshot.output + : "waiting-for-tool", }); - const question = event.segments.findLast( - ({ source }) => source === "brunch-ask", - ); - if (question) this.#recordLatency("answer-ready", question.id); + this.#restoreMicrophoneIfCaptureAvailable(); + if (responseEnd) this.#recordLatency("answer-ready", responseEnd.id); } #handleSessionEvent(event: OpenAIRealtimeSessionEvent): void { @@ -439,45 +693,112 @@ export class VoiceTurnController { ) { return; } + if (event.type === "canonical-speech-requested") { + this.#pendingSpeechRequestIds.add(event.speechRequestId); + this.#session.setMicrophoneEnabled(false); + this.#inputTurnPending = false; + this.#transcriptItemId = null; + this.#transcriptKey = null; + this.#update({ output: "waiting-for-tool", partialText: "" }); + if ( + this.#latencyCorrelationId !== null && + this.#ttsSpeechRequestId === null + ) { + this.#ttsSpeechRequestId = event.speechRequestId; + this.#recordLatency("first-tts-request", this.#latencyCorrelationId); + } + return; + } if (event.type === "output-started") { + this.#pendingSpeechRequestIds.delete(event.speechRequestId); + this.#activeSpeechOutputEnded = false; + this.#activeSpeechResponseId = event.responseId; + this.#activeSpeechResponseTerminal = + this.#terminalSpeechRequestIds.delete(event.speechRequestId); + this.#inputTurnPending = false; + this.#transcriptItemId = null; + this.#transcriptKey = null; if (this.#snapshot.input === "paused") { - this.#session.cancelOutput(); - this.#update({ output: "interrupted" }); + void this.#cancelOutput(); + this.#update({ output: "interrupted", partialText: "" }); return; } - this.#update({ output: "speaking" }); + this.#update({ output: "speaking", partialText: "" }); + if ( + this.#latencyCorrelationId !== null && + event.speechRequestId === this.#ttsSpeechRequestId + ) { + this.#recordLatency("first-tts-audio", this.#latencyCorrelationId); + } if (this.#currentQuestionId) { this.#recordLatency("question-spoken-started", this.#currentQuestionId); } return; } if (event.type === "output-stopped") { - this.#update({ output: "idle" }); + if (event.responseId !== this.#activeSpeechResponseId) return; + this.#activeSpeechOutputEnded = true; + if (this.#activeSpeechResponseTerminal) { + this.#clearSettledSpeech(); + } + this.#update({ + output: this.#outputAfterPlaybackEnds("idle"), + }); + this.#restoreMicrophoneIfCaptureAvailable(); if (this.#currentQuestionId) { this.#recordLatency("question-spoken", this.#currentQuestionId); } return; } if (event.type === "output-interrupted") { - this.#update({ output: "interrupted" }); + if (event.responseId !== this.#activeSpeechResponseId) return; + this.#activeSpeechOutputEnded = true; + if (this.#activeSpeechResponseTerminal) { + this.#clearSettledSpeech(); + } + this.#update({ + output: this.#outputAfterPlaybackEnds("interrupted"), + }); + this.#restoreMicrophoneIfCaptureAvailable(); return; } if (event.type === "input-speech-started") { + if ( + this.#takingTurnPromise || + this.#snapshot.output === "speaking" || + this.#snapshot.output === "cancelling" + ) { + return; + } + this.#inputTurnPending = true; this.#transcriptItemId = event.itemId; this.#transcriptKey = null; - if (this.#snapshot.output === "speaking") { - this.#update({ output: "interrupted", partialText: "" }); - } else { - this.#update({ partialText: "" }); + this.#update({ inputNotice: "none", partialText: "" }); + return; + } + if (event.type === "response-terminal") { + if (event.responseId === this.#activeSpeechResponseId) { + if (this.#activeSpeechOutputEnded) { + this.#clearSettledSpeech(); + } else { + this.#activeSpeechResponseTerminal = true; + } + this.#update({}); + this.#restoreMicrophoneIfCaptureAvailable(); + } else if ( + event.speechRequestId !== undefined && + this.#pendingSpeechRequestIds.has(event.speechRequestId) + ) { + if (event.status === "completed") { + this.#terminalSpeechRequestIds.add(event.speechRequestId); + } else { + this.#pendingSpeechRequestIds.delete(event.speechRequestId); + this.#terminalSpeechRequestIds.delete(event.speechRequestId); + } } return; } - if ( - event.type === "input-speech-stopped" || - event.type === "response-terminal" || - event.type === "tool-arguments-delta" || - event.type === "tool-arguments-done" - ) { + if (event.type === "input-speech-stopped") { return; } @@ -485,6 +806,7 @@ export class VoiceTurnController { if (event.key.connectionEpoch !== this.#activeEpoch) return; if (event.key.itemId !== this.#transcriptItemId) return; if (event.type === "transcription-failed") { + this.#inputTurnPending = false; this.#transcriptItemId = null; this.#transcriptKey = null; this.#update({ partialText: "" }); @@ -498,6 +820,7 @@ export class VoiceTurnController { }); return; } + this.#inputTurnPending = false; this.#transcriptItemId = null; this.#transcriptKey = null; this.#update({ @@ -512,10 +835,22 @@ export class VoiceTurnController { ): void { ++this.#generation; this.#activeEpoch = null; + this.#activeSpeechOutputEnded = false; + this.#activeSpeechResponseId = null; + this.#activeSpeechResponseTerminal = false; this.#inputStateOnResume = null; + this.#inputTurnPending = false; + this.#latencyCorrelationId = null; + this.#outputCancellationPromise = null; + this.#pendingSpeechRequestIds.clear(); + this.#recordedLatencyEvents.clear(); + this.#takingTurnPromise = null; + this.#terminalSpeechRequestIds.clear(); + this.#completeSubmissionSettlement(); this.#bridgeStarted = false; this.#transcriptItemId = null; this.#transcriptKey = null; + this.#ttsSpeechRequestId = null; this.#bridge.stop(); this.#session.setMicrophoneEnabled(false); void this.#session.disconnect(); @@ -536,12 +871,108 @@ export class VoiceTurnController { }); } - #recordLatency(name: VoiceLatencyEvent["name"], questionId: string): void { + #cancelOutput(): Promise { + if (this.#outputCancellationPromise) { + return this.#outputCancellationPromise; + } + const cancellationPromise = this.#session.cancelOutput(); + this.#outputCancellationPromise = cancellationPromise; + this.#update({}); + void cancellationPromise.then( + () => { + if (this.#outputCancellationPromise === cancellationPromise) { + this.#outputCancellationPromise = null; + this.#pendingSpeechRequestIds.clear(); + this.#terminalSpeechRequestIds.clear(); + this.#clearSettledSpeech(); + this.#bridge.completeTurnHandoff(); + const output = + this.#snapshot.output === "waiting-for-tool" || + this.#snapshot.output === "speaking" + ? "interrupted" + : this.#snapshot.output; + this.#update({ output }); + this.#restoreMicrophoneIfCaptureAvailable(); + } + }, + () => { + if (this.#outputCancellationPromise === cancellationPromise) { + this.#outputCancellationPromise = null; + this.#update({}); + this.#restoreMicrophoneIfCaptureAvailable(); + } + }, + ); + return cancellationPromise; + } + + #beginSubmissionSettlement(deliveryId: string): void { + this.#completeSubmissionSettlement(); + let resolve = () => {}; + const promise = new Promise((resolvePromise) => { + resolve = resolvePromise; + }); + this.#pendingSubmissionSettlement = { deliveryId, promise, resolve }; + } + + #completeSubmissionSettlement(deliveryId?: string): void { + const pending = this.#pendingSubmissionSettlement; + if ( + pending === null || + (deliveryId !== undefined && deliveryId !== pending.deliveryId) + ) { + return; + } + this.#pendingSubmissionSettlement = null; + pending.resolve(); + } + + #clearSettledSpeech(): void { + this.#activeSpeechOutputEnded = false; + this.#activeSpeechResponseId = null; + this.#activeSpeechResponseTerminal = false; + } + + #outputAfterPlaybackEnds( + settledOutput: Extract, + ): VoiceOutputState { + if (this.#takingTurnPromise) { + return "cancelling"; + } + if ( + this.#pendingSpeechRequestIds.size > 0 && + this.#outputCancellationPromise === null && + this.#snapshot.input !== "paused" + ) { + return "waiting-for-tool"; + } + return settledOutput; + } + + #restoreMicrophoneIfCaptureAvailable(): void { + if ( + this.#snapshot.connection === "connected" && + this.#snapshot.input === "listening" && + this.#activeSpeechResponseId === null && + this.#pendingSpeechRequestIds.size === 0 && + this.#takingTurnPromise === null && + this.#outputCancellationPromise === null && + (this.#snapshot.output === "idle" || + this.#snapshot.output === "interrupted") + ) { + this.#session.setMicrophoneEnabled(this.#snapshot.microphoneEnabled); + } + } + + #recordLatency(name: VoiceLatencyEvent["name"], correlationId: string): void { if (this.#answerFinalizedAt === null) return; + const eventKey = `${correlationId}:${name}`; + if (this.#recordedLatencyEvents.has(eventKey)) return; + this.#recordedLatencyEvents.add(eventKey); this.#onLatencyEvent?.({ + correlationId, elapsedMs: Math.max(0, this.#now() - this.#answerFinalizedAt), name, - questionId, }); } @@ -555,14 +986,41 @@ export class VoiceTurnController { ); } + #canReplay(snapshot: VoiceTurnSnapshot): boolean { + return ( + snapshot.connection === "connected" && + snapshot.input === "listening" && + !this.#inputTurnPending && + this.#activeSpeechResponseId === null && + this.#pendingSpeechRequestIds.size === 0 && + this.#outputCancellationPromise === null && + this.#takingTurnPromise === null && + (snapshot.output === "idle" || snapshot.output === "interrupted") + ); + } + + #canTakeTurn(snapshot: VoiceTurnSnapshot): boolean { + return ( + snapshot.connection === "connected" && + snapshot.input !== "paused" && + (snapshot.output === "waiting-for-tool" || + snapshot.output === "speaking") && + this.#takingTurnPromise === null + ); + } + #isPauseRequested(): boolean { return this.#pauseRequested; } #update(update: Partial): void { const snapshot = { ...this.#snapshot, ...update }; + const canReplay = this.#canReplay(snapshot); this.#snapshot = { ...snapshot, + canReadFullResponse: canReplay && this.#lastResponseSegments.length > 0, + canRepeatQuestion: canReplay && this.#lastResponseQuestion !== null, + canTakeTurn: this.#canTakeTurn(snapshot), canReviseLastAnswer: this.#canReviseLastAnswer(snapshot), }; for (const listener of this.#listeners) listener(this.#snapshot); diff --git a/apps/petrinaut-website/src/routes/index.tsx b/apps/petrinaut-website/src/routes/index.tsx index 4f969a72595..40f1e030805 100644 --- a/apps/petrinaut-website/src/routes/index.tsx +++ b/apps/petrinaut-website/src/routes/index.tsx @@ -4,8 +4,12 @@ import { useSearch, } from "@tanstack/react-router"; -import { validateSharedExampleSearch } from "../examples/example-search"; import { LocalStorageDemoApp } from "../main/app/local-storage-demo/local-storage-demo-app"; +import { + localStorageDemoRouteIdentity, + validateLocalStorageDemoSearch, + withBrunchFixtureKey, +} from "../main/app/local-storage-demo/local-storage-demo-search"; function IndexRoute() { const navigate = useNavigate({ from: "/" }); @@ -13,8 +17,14 @@ function IndexRoute() { return ( { - void navigate({ replace: history === "replace", search: nextSearch }); + void navigate({ + replace: history === "replace", + // Applied to the router's own previous search, so two navigations + // in one event compose instead of the second reverting the first. + search: (previous) => withBrunchFixtureKey(previous, nextSearch), + }); }} search={search} /> @@ -23,5 +33,5 @@ function IndexRoute() { export const Route = createFileRoute("/")({ component: IndexRoute, - validateSearch: validateSharedExampleSearch, + validateSearch: validateLocalStorageDemoSearch, }); diff --git a/apps/petrinaut-website/src/server/voice/openai-realtime-call.test.ts b/apps/petrinaut-website/src/server/voice/openai-realtime-call.test.ts index 38188a178c3..c7f4f94c284 100644 --- a/apps/petrinaut-website/src/server/voice/openai-realtime-call.test.ts +++ b/apps/petrinaut-website/src/server/voice/openai-realtime-call.test.ts @@ -86,7 +86,7 @@ describe("OpenAI Realtime call handler", () => { expect(fetch).not.toHaveBeenCalled(); }); - test("forwards only the SDP and server-owned duplex Realtime policy", async () => { + test("forwards only the SDP and server-owned half-duplex Realtime policy", async () => { const reportDiagnostic = vi.fn(); const fetch = vi.fn( async () => @@ -131,16 +131,16 @@ describe("OpenAI Realtime call handler", () => { type: "realtime", model: "gpt-realtime-2", output_modalities: ["audio"], - tool_choice: "required", - tools: [{ name: "continue_interview", type: "function" }], + tool_choice: "none", + tools: [], audio: { input: { transcription: { model: "gpt-4o-transcribe", language: "en" }, turn_detection: { type: "semantic_vad", eagerness: "low", - create_response: true, - interrupt_response: true, + create_response: false, + interrupt_response: false, }, }, }, diff --git a/apps/petrinaut-website/src/server/voice/openai-voice-policy.test.ts b/apps/petrinaut-website/src/server/voice/openai-voice-policy.test.ts index 1cdd3f0fead..523b8c85f17 100644 --- a/apps/petrinaut-website/src/server/voice/openai-voice-policy.test.ts +++ b/apps/petrinaut-website/src/server/voice/openai-voice-policy.test.ts @@ -46,18 +46,18 @@ describe("OpenAI voice policy", () => { ).toEqual({ available: true, connectionTimeoutMs: 15_000 }); }); - test("owns the trusted GPT-Realtime-2 duplex session policy", () => { - expect(OPENAI_REALTIME_POLICY_VERSION).toBe("brunch-control-plane-v1"); + test("owns the trusted GPT-Realtime-2 half-duplex session policy", () => { + expect(OPENAI_REALTIME_POLICY_VERSION).toBe("brunch-control-plane-v3"); expect(createOpenAIRealtimeSession()).toEqual({ type: "realtime", model: "gpt-realtime-2", output_modalities: ["audio"], reasoning: { effort: "low" }, parallel_tool_calls: false, - tool_choice: "required", + tool_choice: "none", instructions: `# Role and objective -You are the realtime voice of an expert interviewer for process-model elicitation. The person speaking is the domain expert. Listen attentively, submit each complete spoken answer to Brunch, and deliver Brunch's next interview turn. +You are the realtime voice of an expert interviewer for process-model elicitation. The person speaking is the domain expert. Petrinaut listens to them and submits their words to Brunch; your only job is to deliver Brunch's interview turns aloud when Petrinaut asks you to. # Personality and delivery @@ -65,29 +65,16 @@ Sound warm, calm, curious, confident, concise, and professionally neutral. Speak # Authority -Brunch is the sole authority for interview state, questions, captures, completion, and business decisions. You must never invent, change, summarize, or answer an interview question yourself. +Brunch is the sole authority for interview state, questions, captures, completion, and business decisions. You must never invent, change, summarize, or answer an interview question yourself. You must never restate, guess, or fill in what the speaker said. # Turn handling -After semantic turn detection finds that the user has finished a complete spoken answer, call continue_interview exactly once with that answer. Do not speak, emit a preamble, or emit conversational text before calling the tool. +Never respond on your own after the speaker stops talking. Petrinaut transcribes their words and decides what happens next. Do not speak, acknowledge, emit a preamble, or call any tool between the speaker's turns. # Canonical output -After the tool result arrives, speak only its response_text strings, in array order and verbatim. Do not add, remove, paraphrase, acknowledge, or explain anything. Never call another tool while speaking a tool result.`, - tools: [ - { - type: "function", - name: "continue_interview", - description: - "Submit the user's complete spoken answer to the authoritative Brunch interview.", - parameters: { - type: "object", - additionalProperties: false, - properties: { answer: { type: "string" } }, - required: ["answer"], - }, - }, - ], +When Petrinaut supplies response_text, speak only those strings, in array order and verbatim. Do not add, remove, paraphrase, acknowledge, or explain anything.`, + tools: [], audio: { input: { noise_reduction: { type: "far_field" }, @@ -100,8 +87,8 @@ After the tool result arrives, speak only its response_text strings, in array or turn_detection: { type: "semantic_vad", eagerness: "low", - create_response: true, - interrupt_response: true, + create_response: false, + interrupt_response: false, }, }, output: { voice: "marin" }, @@ -109,12 +96,17 @@ After the tool result arrives, speak only its response_text strings, in array or }); }); - test("allows no provider-owned interview decisions or unrestricted tools", () => { - const serializedPolicy = JSON.stringify(createOpenAIRealtimeSession()); + test("lets Realtime neither answer for the user nor call tools between turns", () => { + const policy = createOpenAIRealtimeSession(); + const serializedPolicy = JSON.stringify(policy); expect(serializedPolicy).not.toContain("response.create"); expect(serializedPolicy).not.toContain("gpt-realtime-1.5"); + expect(serializedPolicy).not.toContain("continue_interview"); expect(serializedPolicy).not.toContain('"tool_choice":"auto"'); - expect(createOpenAIRealtimeSession().tools).toHaveLength(1); + expect(serializedPolicy).not.toContain('"tool_choice":"required"'); + expect(policy.tools).toHaveLength(0); + expect(policy.audio.input.turn_detection.create_response).toBe(false); + expect(policy.audio.input.transcription.model).toBe("gpt-4o-transcribe"); }); }); diff --git a/apps/petrinaut-website/src/server/voice/openai-voice-policy.ts b/apps/petrinaut-website/src/server/voice/openai-voice-policy.ts index fc401fc0c7b..653b622dc3a 100644 --- a/apps/petrinaut-website/src/server/voice/openai-voice-policy.ts +++ b/apps/petrinaut-website/src/server/voice/openai-voice-policy.ts @@ -1,5 +1,5 @@ export const OPENAI_REALTIME_CONNECTION_TIMEOUT_MS = 15_000; -export const OPENAI_REALTIME_POLICY_VERSION = "brunch-control-plane-v1"; +export const OPENAI_REALTIME_POLICY_VERSION = "brunch-control-plane-v3"; interface VoiceEnvironment { readonly NODE_ENV?: string; @@ -24,7 +24,7 @@ export const getOpenAIVoiceAvailability = (environment: VoiceEnvironment) => ({ const REALTIME_INSTRUCTIONS = `# Role and objective -You are the realtime voice of an expert interviewer for process-model elicitation. The person speaking is the domain expert. Listen attentively, submit each complete spoken answer to Brunch, and deliver Brunch's next interview turn. +You are the realtime voice of an expert interviewer for process-model elicitation. The person speaking is the domain expert. Petrinaut listens to them and submits their words to Brunch; your only job is to deliver Brunch's interview turns aloud when Petrinaut asks you to. # Personality and delivery @@ -32,38 +32,31 @@ Sound warm, calm, curious, confident, concise, and professionally neutral. Speak # Authority -Brunch is the sole authority for interview state, questions, captures, completion, and business decisions. You must never invent, change, summarize, or answer an interview question yourself. +Brunch is the sole authority for interview state, questions, captures, completion, and business decisions. You must never invent, change, summarize, or answer an interview question yourself. You must never restate, guess, or fill in what the speaker said. # Turn handling -After semantic turn detection finds that the user has finished a complete spoken answer, call continue_interview exactly once with that answer. Do not speak, emit a preamble, or emit conversational text before calling the tool. +Never respond on your own after the speaker stops talking. Petrinaut transcribes their words and decides what happens next. Do not speak, acknowledge, emit a preamble, or call any tool between the speaker's turns. # Canonical output -After the tool result arrives, speak only its response_text strings, in array order and verbatim. Do not add, remove, paraphrase, acknowledge, or explain anything. Never call another tool while speaking a tool result.`; +When Petrinaut supplies response_text, speak only those strings, in array order and verbatim. Do not add, remove, paraphrase, acknowledge, or explain anything.`; +/** + * The completed input transcription is the only source of the user's answer. + * Semantic VAD therefore commits audio without creating a response or + * interrupting playback, and the Realtime model has no tools with which to + * manufacture an answer. + */ export const createOpenAIRealtimeSession = () => ({ type: "realtime" as const, model: "gpt-realtime-2", output_modalities: ["audio"] as const, reasoning: { effort: "low" as const }, parallel_tool_calls: false, - tool_choice: "required" as const, + tool_choice: "none" as const, instructions: REALTIME_INSTRUCTIONS, - tools: [ - { - type: "function" as const, - name: "continue_interview", - description: - "Submit the user's complete spoken answer to the authoritative Brunch interview.", - parameters: { - type: "object" as const, - additionalProperties: false, - properties: { answer: { type: "string" as const } }, - required: ["answer"] as const, - }, - }, - ], + tools: [] as const, audio: { input: { noise_reduction: { type: "far_field" as const }, @@ -76,8 +69,8 @@ export const createOpenAIRealtimeSession = () => ({ turn_detection: { type: "semantic_vad" as const, eagerness: "low" as const, - create_response: true, - interrupt_response: true, + create_response: false, + interrupt_response: false, }, }, output: { voice: "marin" as const }, diff --git a/libs/@hashintel/brunch-agent/MISSION.md b/libs/@hashintel/brunch-agent/MISSION.md index 468aad51347..b4a2d1638c1 100644 --- a/libs/@hashintel/brunch-agent/MISSION.md +++ b/libs/@hashintel/brunch-agent/MISSION.md @@ -1,7 +1,86 @@ -# No live Brunch mission on this branch +# Mission 6b — Reconcile Voice with resumable browser work ## Status -**Mission 4 closed by owner adjudication on 2026-09-03.** Its accepted implementation, bounded evidence, observed S4 failure, missing full-run candidate, and deferred concerns are preserved in [`4-core-plugin-elicitation-proof-of-life.md`](docs/mission-archive/4-core-plugin-elicitation-proof-of-life.md) and [`mission-4-closure-and-deferral-2026-09-03.md`](docs/evidence/decisions/mission-4-closure-and-deferral-2026-09-03.md). +**Accepted by Lu on 2026-09-07 with explicit limitations**, on `ln/fe-1580-reconcile-voice-resumable-workpiece`, [PR #9564](https://github.com/hashintel/hash/pull/9564), above Mission 6 and Mission 5. The accepted [owner witness](docs/evidence/implementations/voice-resumable-reconciliation/owner-witness-2026-09-07/witness.md) proved the local Voice → causal browser mutation → coherent resume → active-submission Stop/reopen path after repairing cross-step client-result accumulation and the fixture's non-causal prepared answer. Direct spoken-user Voice attribution after hydration, durable recovery of locally withheld post-settlement browser work, and comparative audible latency are explicitly deferred with narrowed claims; the full pre-registered telemetry bundle was not retained and is not inferred. -This file is a closure pointer, not execution authority. No implementation may begin here until an owner-authorized issue/branch mission is re-evaluated and installed. Future planning lives in [`MISSION.next.md`](MISSION.next.md). Voice reconciliation starts from [`mission-4-voice-integration-handoff.md`](docs/evidence/implementations/mission-4-voice-integration-handoff.md) without reopening Mission 4. Restacked commit navigation and the content-hash evidence rule are recorded in [`mission-4-final-restack-provenance-2026-09-03.md`](docs/evidence/decisions/mission-4-final-restack-provenance-2026-09-03.md). +KA's branch and [PR #9531](https://github.com/hashintel/hash/pull/9531) remain untouched. The replacement imports the contribution `58f75840804766a84ce85b9daab5b5194f3875ec..be56a18ff0244c5750a8702e9c7f45c0b607dc06` with attribution, never the distant merge-base delta. Its live `MISSION.md` is historical source, not imported authority. This is the explicit exception to one new issue per mission; FE-1580 was referenced without rewriting its issue. No Linear write or KA-record change is part of acceptance. + +**Accepted implementation and evidence:** the pre-witness restacked candidate passed 39 uncached scoped build/test/type/lint tasks (1,318 tests). Commits `1e238f498e` and `48e2b66666` repair causal client-result delivery and require explicit true-user fixture evidence. Focused post-repair checks and the sanitized canonical record are listed in the [owner witness](docs/evidence/implementations/voice-resumable-reconciliation/owner-witness-2026-09-07/witness.md); the earlier [verification](docs/evidence/implementations/voice-resumable-reconciliation/verification.md) retains the broader local suite and the exact accepted dispositions. Mission 7 may consume this narrowed accepted foundation after restack; its own integrated witnesses remain necessary. + +## Imperative + +Make KA's completed-transcript, half-duplex Voice experience work safely over Mission 6's resumable browser mutations and coherent workpiece/document recovery. Preserve both capabilities instead of replacing either. Distinguish committed prose, submission settlement, pending browser work/continuation, coherent document settlement and terminal provider output at the actual shared boundaries. Start from the parent's new busy/follow-up/Stop behavior rather than adding a parallel coordinator. + +**Release note:** speak to Brunch, let it change the prepared net, interrupt or stop safely, and reopen the same work without replaying speech or duplicating the change. Transcript, tool failures and stopped entries remain understandable. Direct spoken-user attribution on reopen is explicitly unsupported; Stop is durable for active Flue submissions, while browser work withheld after a settled tool-call step may reappear as pending after reopen. + +**Demo:** run `yarn dev:brunch`, open the honestly labelled crew-reservation fixture, make a typed turn followed by a spoken confirmation, and watch the single crew-reservation arc and coherent bundle settle. During another response use **Your turn**, wait for safe fresh capture, and speak again. Separately Stop before completion. Reopen in Tab B and inspect the conversation and net, then continue without duplicate preparation, mutation or autoplay. Inspect compact/expanded Voice, exact full-response and question replay, and a visible tool failure. This local demo and its acceptance gates, not merely a clean merge or green unit tests, define the visible advance. Vestera construction/explanation remain Mission 7. + +## Throughline + +```text +completed current-turn microphone transcript +→ shared panel submitVoiceInputWithAdmission/useChat admission +→ browser ChatTransport over the memoized FlueClient +→ same-origin /agents/chat/:instanceId and mounted Brunch ChatAgent +→ committed canonical prose, hidden server question marker, browser-tool requests +→ existing canonical browser validation and effects on the bound document +→ original call-id outputs resume the same conversation +→ canonical speech queue and acknowledged cancellation +→ coherent workpiece/document settlement +→ canonical history reopen and another real turn +``` + +### Departure and protected sources + +- Mission 5 `b1295ad454` holds composer status busy across automatic follow-up and permits Stop to withhold it. Mission 6 `976bb1c67c` repairs fixture routing, docs-reader catalogue retention, workpiece numbering, coherent persistence and mutation no-op honesty. These committed repairs satisfy the earlier wait-for-parent handoff. Recheck the combined deferred static-tool path rather than assuming that either source closes it. +- Read KA's pinned `MISSION.md` and the imported `docs/evidence/implementations/mission-5-voice-safety-parity/{donor-behavior-matrix,provenance-blocker,witness-blocker}.md` plus `docs/evidence/design/mission-5-question-marker-and-provenance-decision-2026-09-04.md`. Import their historical evidence without relabelling its tests or witnesses as this candidate's proof. Retain the latest repeated-output-cancellation regression from `db8184b2e6`. +- Mission 6's accepted authority is [archived](docs/mission-archive/6-resumable-workpiece-petrinaut.md). Its [implementation record](docs/evidence/implementations/fe-1575-resumable-workpiece-petrinaut.md) and `fe-1575-outer-browser-witness-2026-09-04{,-r2}` raw bundles establish the prepared document/workpiece path, not Voice/stopped-entry presentation: the inspected bundles have completed settlements and no recorded Voice origins. Preserve the historical owner close and raw records while correcting current interpretation. +- Trace `packages/transport-aisdk/src/{index,transcript,ui-stream,client-tool-history}.ts`, website `local-storage-demo/{brunch-panel-transport,use-flue-chat-history,use-crew-reservation-fixture-session,crew-reservation-settled-manifest}.ts`, Petrinaut `ai-assistant-panel.tsx` and mutation helper, and website `voice-interview/{openai-realtime-session,realtime-brunch-bridge,voice-turn-controller,canonical-speech,voice-interview-control}.ts*`. Matching source tests, installed SDK 2.0.3 types and [Flue routing](docs/reference/architecture/flue-routing.md) guide the smallest repair. + +### Import and reconciliation boundary + +Commit this authority separately, then a credited squashed source import with necessary conflict resolutions recorded, followed by focused reconciliation commits and verification evidence. Retain the existing launcher repair and fixture configuration. Reconcile the hidden question marker with the scoped browser catalogue and identical live/history normalization; a browser mutation cannot become server-executed through a missing catalogue entry. Reconcile deterministic user/tool keys with stable payload ordering, bounded keys, causal per-step result batches and admission outcomes; prefix selection alone is insufficient. Carry source output-insertion failure handling through the actual deferred automatic-tool path and preserve fixture refusal/coherent-bundle feedback in the new Voice presentation. + +## Proof + +The first milestone is a spoken fixture turn whose browser mutation returns through the shared route and produces canonical audio without duplication. Readiness additionally requires the following discriminators. Existing test locations are relative to their packages; scenario names describe required assertions, not pre-existing test claims. Evidence lives under `docs/evidence/implementations/voice-resumable-reconciliation/`, pinned to the final implementation, source and parent commits. + +1. **Canonical input and explicit half-duplex handoff.** Website `voice-interview/{openai-realtime-session,realtime-brunch-bridge,voice-turn-controller,voice-interview-control}.test.ts*` retain completed keyed transcripts, speech-request-before-audio invalidation, stale/duplicate/boundaryless rejection, queued-output ownership, latest mute preference, acknowledged cancellation and in-flight/repeated-cancel reuse. `voice-preview.integration.test.ts` proves actual shared panel/transport admission once, with model function arguments unable to submit. +2. **Browser continuations and Stop.** A test mounting the real `AiAssistantPanel` with the Voice bridge holds browser execution/output insertion and continuation at intermediate `ready`, both with preceding canonical prose and without it. Capture and replay must not become available prematurely. Stop before tool execution, during output insertion and before scheduled continuation prevents later work that has not been admitted; already-applied mutations stay inspectable without a rollback claim. Your turn cancels audio without durably aborting admitted Brunch work. Parent regression tests remain green. +3. **Tools and canonical projection.** Website `local-storage-demo/{brunch-panel-transport,use-flue-chat-history}.test.ts` and transport `test/{ui-stream,transcript}.test.ts` preserve fixture browser tools while hiding only the server marker; normalize the same client input live and from history; and fold continuations without losing surviving Voice origins. `canonical-speech.test.ts` and bridge/controller tests allow exact canonical segments only, seed history without autoplay, gate exact replay until all terminal conditions, and leave question replay disabled for absent/unmatched markers. +4. **Admission identity and failure.** Transport `test/chat-transport.test.ts` covers exact user retry, cumulative/reordered logical tool-result retries, changed-payload conflict retaining the original submission ID, bounded identity, ambiguous admission without automatic retry and local abort without durable abort. App `test/petrinaut-chat.test.ts`/its built-runtime integration verify deduplicated receipts. Petrinaut `ai-assistant-panel.test.tsx` covers matching per-tool output errors; combined panel/Voice tests cover textless browser-continuation failure. Distinguish input rejection, effect failure/no-op, output insertion rejection and continuation rejection. Partial failure cannot advance the prior coherent bundle or strand ownership. +5. **Supported reopen.** Transport/history tests reconstruct surviving client-tool Voice origins and each aborted assistant entry from canonical data without browser origin storage. Retain before/after/Tab-B snapshots and rendered stopped-entry evidence, including a later completed response so a global latest-status banner is not mistaken for per-message state. Direct spoken-user attribution has its own gate below. +6. **Real product/stock coexistence.** Human/browser witness of the demo retains `witness.md`, sanitized `voice-events.jsonl`, `network-routes.json`, canonical snapshots, settlements and commit/hash manifest. Verify original call/result IDs, one target arc, coherent bundle identity, fresh Tab-B continuation, no duplicate mutation/autoplay and same-origin routes. Panel/contents tests and rendered inspection cover compact/expanded Voice, persistent/copyable errors and stock behavior when Brunch is absent/unselected. Actual microphone/audible behavior cannot be claimed from simulation. +7. **Comparative latency.** Keep KA's gate: ten comparable real-audio donor #9496 trials at `c7fe8a2e68e8fdc37018b21ec2e9daf4e9ef7c82` and ten at the final candidate, same machine/browser/input/model and warm/cold policy, finalized speech to first audible canonical TTS. Candidate median must not regress and p95 regression must be below 20%. Retain raw sanitized samples, method, environment and pins. Earlier diagnostic turns with nearly zero text-to-settlement delay prove no improvement. No paid trials are authorized by this cut; Lu must first approve caller/model, bounded trials, ceiling and accounting owner. Mission 7's budget is unavailable here. +8. **Repository verification and docs.** Run root Yarn/Turbo `build test:unit lint:tsc lint:eslint` for `@hashintel/brunch-agent`, binding-flue, plugin-sdcpn, transport-aisdk, `@apps/brunch-agent`, `@hashintel/petrinaut`, and `@apps/petrinaut-website`; use narrow package tests first to discriminate failures. Check changed-file formatting, `git diff --check` and `yarn workspace @local/petrinaut-arch-docs lint:arch-docs`. User docs describe exact supported behavior and limits; exactly one source patch changeset covers this PR's published Petrinaut behavior. Report screenshot updates if needed. Prior counts are not a final run. + +**Direct-user provenance gate:** SDK 2.0.3's canonical user messages do not expose caller Voice metadata or idempotency keys. Supported signal/tool-result origin reconstruction is not direct-user provenance. The owner witness observed both live Voice chips disappear after Tab-B hydration. Lu explicitly deferred this chip with truthful presentation on 2026-09-07: canonical spoken text survives, but direct spoken-user origin is not claimed after reopen. No local Flue patch, sidecar/signal admission or text encoding is authorized. + +**Close:** Lu accepted the narrowed mission claim on 2026-09-07 after the owner witness. The real path and automated evidence passed as recorded; the three deferred claims and evidence-bundle limitation remain visible rather than being counted as proof. + +## Constraints + +- One conversation/log, memoized Flue client, shared `useChat` path-B admission and mounted route. No direct Voice send, separate mutable transcript, simplifier, live `brunch_ask`, or interactive question path. The core marker annotates exact existing prose without accepting answers. +- Realtime has no tools, `tool_choice: none`, and semantic VAD with `create_response: false`. Normalize completed transcript once in the bridge (trim/Unicode whitespace collapse), then enforce 32,000 code points. Generic panel validation must not mutate that normalized payload. +- Microphone closes from canonical speech request through queued/playing output, cancellation, pause, error and submission; invalidate unfinished input before sending `response.create`. Fresh capture needs explicit handoff, acknowledged provider cancellation and settled correlated conversation work. Automatic duplex remains rejected because playback can become authoritative user input. +- Only new durably completed, submission-correlated canonical segments may speak before settlement. Never deltas, unfinished text, reasoning, tool payloads, inferred prose, hydrated history or failed/aborted continuation segments. Exact full-response and marked-question replay remain gated by conversation/output/input terminal conditions; cancellation suppresses queued and later continuation speech. +- Keep local playback, observation, HTTP cancellation and durable conversation Stop distinct. Stable logical delivery identity plus stable payload ordering yields at most one admission; ambiguous outcomes never auto-retry. Preserve each surviving tool Voice origin independently. +- Preserve repaired fixture/conversation/document/workpiece identity, canonical browser schemas/callbacks, scoped catalogue, recovery, no-op honesty, prior-coherent-bundle refusal and automatic document persistence. Transient UI/audio state cannot bless durability. No cross-store atomicity or concurrency claim. +- Preserve KA's authorship and source records. Existing source policy excluding Mission 6 mutation work is superseded only for this explicit combined-path reconciliation; unrelated donor and stakeholder PRs remain untouched. Import source evidence as history, not candidate acceptance. + +## Fog-line + +The source-grounded intermediate-ready hazard may already be reduced by the parent fix; the deferred static-tool path must decide what remains. Output insertion rejection, textless continuation failure, retained idempotency compatibility and cancellation ordering need discriminators before mechanisms. Prefer existing SDK and local mechanisms; no parallel scheduler or generalized state machine merely to name a boundary. Source green suites and a textual merge do not prove these joins. + +Question-marker compliance remains a model limitation: missing/unmatched markers disable replay, never justify inference. The real microphone witness passed. Direct-user attribution and comparative latency were explicitly deferred with no corresponding claim. No unobserved evidence may be inferred from owner acceptance. + +## Stop or reorient + +Stop if source/parent pins move without inspection, another checkout's work would be disturbed, or the join requires another conversation route/authority, ambiguous automatic retry, rewritten speech, new batch/termination policy, local Flue patch or provenance store. Reorient if half-duplex cannot ensure fresh post-barrier capture, provider acknowledgement cannot bound cancellation, mutations duplicate, Stop allows withheld work to execute, failures disappear, or coherent settlement is falsely reported. Do not manufacture human/latency evidence or hide an unresolved gate to call the base verified. + +## Deferred + +Mission 7 consumes this accepted local reconciliation, not a new Vestera implementation. Amend its departure base and preserve the hidden/server marker versus browser-tool distinction, canonical identity, speech exclusions, causal per-step client results, continuation and cancellation contracts in A2/A3; re-pin the prompt/tool baseline before instrument freeze or paid runs. Its Step B genuine typed/Voice/stopped-entry witness remains necessary over new revision/basis semantics and cannot inherit Mission 6b's scenario evidence as its own. + +The [future spine](MISSION.next.md) retains construction/explanation, declared basis, workpiece revision tools, broad projection, orphan-code retirement, concurrent editing, remote durability/deployment and further UX policy changes with their existing owners. Direct-user Voice attribution, post-settlement durable withholding and comparative latency re-enter only under the conditions in the owner witness. The observed verbose negative-control answer and Stop discoverability strain are future UX inputs, not silent passes. Retirement of KA's original PR requires separate authorization. No Linear write is part of this close. diff --git a/libs/@hashintel/brunch-agent/MISSION.next.md b/libs/@hashintel/brunch-agent/MISSION.next.md index fc8c2c63533..16229e5e7d1 100644 --- a/libs/@hashintel/brunch-agent/MISSION.next.md +++ b/libs/@hashintel/brunch-agent/MISSION.next.md @@ -1,8 +1,10 @@ # Brunch future mission spine -> Canonical future-planning spine, shared frame, and backlog index only. This file is not execution authority and authorizes no implementation. [`MISSION.md`](MISSION.md) is currently a closure pointer; a future owner-authorized cut must replace it with the sole live authority. Detailed provisional clusters are context repositories, not missions; re-evaluate and convert one into `MISSION.md` before acting. +> Canonical future-planning spine, shared frame, and backlog index only. This file is not execution authority and authorizes no implementation. [`MISSION.md`](MISSION.md) is accepted Mission 6b, the owner-witnessed Voice reconciliation above repaired Mission 6. Mission 6 is [archived](docs/mission-archive/6-resumable-workpiece-petrinaut.md). Mission 7's Step A branch is restacked above this accepted narrowed foundation; its own scenario evidence remains required. Detailed provisional clusters are context repositories, not missions; re-evaluate and convert one into `MISSION.md` on its own branch before acting. -This spine and its six linked drafts form one future-planning record. Keep each consequential meaning in one authoritative planning home: shared contracts and unallocated concerns live here; mission-specific detail lives in its draft. A spine pointer is not a second contract. Material omitted from a future cut returns to this record at full fidelity, and the consumed draft is removed. +This spine, its four numbered mission drafts, and its linked design proposals form one future-planning record. Keep each consequential meaning in one authoritative planning home: shared contracts and unallocated concerns live here; mission-specific detail lives in its draft. A spine pointer is not a second contract. Material omitted from a future cut returns to this record at full fidelity, and the consumed draft is removed. + +The record was recut on 2026-09-04 around provenance by lineage with declared basis; the [2026-09-04 migration disposition](#2026-09-04-provenance-replanning-migration-disposition) maps every prior planning item to its surviving home. ## Current authority and accepted spine @@ -10,61 +12,50 @@ Mission 4 closed on this branch by owner adjudication on 2026-09-03. The accepte A future Mission 4 close-out addendum requires its own issue, branch, PR, and mission authority. It may stack on this closed branch and own broader reliability/hardening if warranted, browser parity, fixture/seed promotion contracts, topology-neutral case allocation, contract/readiness sweeps, archive subtraction, and Mission 8 preparation. It also owns the observed S4 report-versus-immediate-ask decision unless a later numbered mission first makes it load-bearing: re-enter only when a real review must continue immediately or repeated gap-only reports create visible friction; preserve S3 restraint while testing S4 activation and asking under a fresh instrument. Its exact issue/name and minimum scope remain owner decisions; do not create another Mission 4 draft. -Two successor missions are now independently cuttable from Mission 4 under separate issue, branch, PR, worktree, and mission authority. Mission 5 retires the Voice transport uncertainty: finalized speech enters canonical Flue directly and canonical Brunch output reaches TTS without the AI SDK chat composer or a secondary generative simplifier. Mission 6 retires the workpiece/projection uncertainty: one deliberately prepared, honestly labelled fixture joins canonical conversation, session history, Markdown workpiece, and Petrinaut document; one browser-backed read/write change saves and resumes across tabs. Neither requires a Mission 4 full-run candidate, and neither is the other's prerequisite. +Mission 6 closed on the FE-1575 branch under its [archived authority](docs/mission-archive/6-resumable-workpiece-petrinaut.md): one deliberately prepared, honestly labelled fixture joined canonical conversation, session history, Markdown workpiece, and Petrinaut document through a browser-backed read/write change and cross-tab resume. Its consumed draft remains removed; its product-manager litmus, demo script, proof, and explicit owner waiver remain in the closed authority. The owner closed despite not re-running Voice-origin provenance and aborted-assistant presentation in the fresh product-manager conversation; those future scenario obligations live under [Voice after the live transport cut](#voice-after-the-live-transport-cut). Mission 5 owns the direct Voice/Flue transport cut on the FE-1574 branch directly beneath this one; its full contract lives only in that branch's root `MISSION.md`. Neither tracer requires a Mission 4 full-run candidate. The two were cut as independent siblings, but Mission 5's recut made the browser Flue `ChatTransport` the only door into a Brunch conversation and removed the `/api/chat` path Mission 6 had named as its departure point; the owner therefore corrected Mission 6 to consume Mission 5's landed transport, and this branch stacks on Mission 5's committed typed-panel transport tracer. -The earlier capture-backed provenance, automatic-projection, revision, and optimisation drafts remain later readiness/product advances. They are renumbered around the historical Mission 8 deployment track rather than forcing the two uncertainty-retiring tracers to inherit its unproved remote boundary. +On 2026-09-04, while Mission 6 was closing, the owner and an agent reviewed the provenance design that Missions 7, 9, and 10 had assumed, and two independent adversarial reviews tested the result. The outcome, recorded in the [decision log](docs/evidence/design/provenance-and-tooling-decision-log-2026-09-04.md), [mini spec](docs/evidence/design/provenance-by-lineage-mini-spec-2026-09-04.md), [independent review](docs/evidence/design/provenance-by-lineage-independent-review-2026-09-04.md), and [follow-up review](docs/evidence/design/provenance-by-lineage-follow-up-review-2026-09-04.md), changed the spine in four ways. Provenance is no longer a capture-envelope and hand-authored derivation seam over a prepared pair; it is recovered lineage in the canonical Flue log (workpiece revisions and net mutations as tool calls) plus a constructor-declared basis carried on each mutation request, with passage evidence, element origin, current state, attempt history, and recorded roles kept as distinct relations. Construction and explanation are consolidated into Mission 7 on a genuine conversation, because lineage exists only when the model actually constructs and because the owner chose fully connected parts over thin tracers; Mission 7 closes the readiness of its own claim and hands only breadth to Mission 9. The prepared Mission 6 fixture is a viability proof and is not promoted; real fixtures come from persona interviews run to construction. Tool admission ends its deferral: the inherited six-tool subset is retired in favour of scenario-selected operations with canonically derived schemas over a repaired provider carrier. These are owner decisions expressed in conversation; they become authority only when the Mission 7 draft is cut. ```text M4 closed — core/plugin elicitation pattern accepted; S4 transition and full-run candidate deferred M4+ optional successor — broader hardening or source promotion only under separate authority -M5 direct Voice/Flue — one finalized spoken turn, canonical streamed reply, cancellation, and reopen -M6 resumable fixture tracer — conversation → Markdown workpiece → Petrinaut read/write → cross-tab resume -M7 capture-backed review — close selected-pair provenance breadth and visible why/refusal -M8 deployment handoff — historical branch stopped after local application proof, before infrastructure deployment -M9 automatic projection — broaden the proved fixture seam to repeatable traceable projection of one meaningful region -M10 revision — ship bounded authorized reviewer revision and a scoped patch -M11 optimisation — ship an accepted optimisation handoff after its consumer contract exists +M5 live on FE-1574, beneath this branch — direct Voice/Flue turn, canonical streamed reply, cancellation, and reopen +M6 closed on FE-1575 — conversation → Markdown workpiece → Petrinaut read/write → cross-tab resume proved; two fresh-human Voice/stopped checks waived and carried +M6b live reconciliation — KA's Voice behavior over repaired M6; human/latency and direct-user attribution gates remain explicit in root authority +M7 construct and explain — one genuine conversation builds and explains one real net region; two-step authority; closes its own readiness +M8 deployment handoff — historical branch stopped after local application proof, before infrastructure deployment; a successor must be scheduled before any remote claim +M9 repeatable projection breadth — unchanged repeat, changed input, retirement, concurrent change, schema classes over the M7 seam +M10 revision — ship bounded authorized reviewer revision and a scoped patch over basis, transition records, and epochs +M11 optimisation — ship an accepted optimisation handoff after its consumer contract exists; early non-binding consumer discovery before M9's region ``` -Every numbered product mission after the proof-of-life exception must pass the **product-manager litmus**: a product manager who did not watch the work must be able to notice that the product materially moved forward. Each mission therefore states, in its draft's visible-product-advance section, a release-note sentence, a demo script a product manager can run without an engineer, and the thing that was impossible before. Snapshots, manifests, event ledgers, and negative controls are oracles that belong in the evidence sections; they are not the visible advance. A mission is complete at its readiness gate, when the demo script works for the named scenario, not at the first green throughline tracer, which is an internal milestone inside the mission. Mission 5 names the Voice/Flue surface; Mission 6 names the stable fixture and browser Petrinaut document; Missions 7, 9, and 10 name the Petrinaut Brunch panel. Because Mission 8 stopped before remote deployment, those panel missions must name the deployment posture available at cut time, and a locally run panel is acceptable for the demo; a product-manager-noticeable claim must never depend on infrastructure that does not exist, while remote durability obligations stay in their readiness gates. Architecture, schema repair, fixtures, evaluation, rehearsal, and spikes may support the advance but cannot be the sole outcome. Parallel work means separate issue, branch, PR, worktree, and mission authority; it never means multiple live missions here. +Every numbered product mission after the proof-of-life exception must pass the **product-manager litmus**: a product manager who did not watch the work must be able to notice that the product materially moved forward. Each mission therefore states, in its draft's visible-product-advance section and then in its cut `MISSION.md` imperative, a release-note sentence, a demo script a product manager can run without an engineer, and the thing that was impossible before. Snapshots, manifests, event ledgers, and negative controls are oracles that belong in the evidence sections; they are not the visible advance. A mission is complete at its readiness gate, when the demo script works for the named scenario, not at the first green throughline tracer, which is an internal milestone inside the mission. Mission 5 names the Petrinaut Brunch panel's typed and Voice surface over one Flue route, with its litmus stated in the FE-1574 branch's `MISSION.md`; closed Mission 6 names the stable fixture and browser Petrinaut document, with its litmus retained in the [archive](docs/mission-archive/6-resumable-workpiece-petrinaut.md#visible-product-advance); Missions 7, 9, and 10 name the Petrinaut Brunch panel. Because Mission 8 stopped before remote deployment, those panel missions must name the deployment posture available at cut time, and a locally run panel is acceptable for the demo; a product-manager-noticeable claim must never depend on infrastructure that does not exist, while remote durability obligations stay in their readiness gates. Architecture, schema repair, fixtures, evaluation, rehearsal, and spikes may support the advance but cannot be the sole outcome. Parallel work means separate issue, branch, PR, worktree, and mission authority; it never means multiple live missions here. ## Successor mission précis -### M5 — Speak directly to canonical Brunch - -Tracker projection: [FE-1574](https://linear.app/hash/issue/FE-1574/let-voice-speak-through-canonical-brunch-conversations). - -A finalized spoken answer enters Flue exactly once and canonical Brunch text streams directly to visible Voice output and TTS, without the AI SDK chat composer or a secondary generative simplifier. This can be cut immediately and independently on the Voice reconciliation worktree. **Visible/usable proof:** [one spoken turn, cancellation, canonical snapshot, and reopen](docs/mission-drafts/5-direct-voice-flue-transport.md#throughline-proof-floor). - -### M6 — Prove the Markdown/workpiece/Petrinaut loop - -Tracker projection: [FE-1575](https://linear.app/hash/issue/FE-1575/resume-one-brunch-workpiece-and-petrinaut-document-across-tabs). - -One honestly prepared fixture links a canonical conversation, session history, Markdown workpiece, and Petrinaut document; Brunch updates the workpiece, performs one meaningful browser-backed document change, saves, and resumes from a second tab. This can be cut immediately and independently of Voice. **Product-manager litmus:** Brunch edits the net you are looking at from the conversation, and the work survives closing the tab. Demo: open the demo fixture, say one new thing about the process, watch the net change, save, reopen in a second tab and continue. Previously impossible: Brunch only produced off-canvas net JSON for manual load. Complete at the [readiness gate](docs/mission-drafts/6-resumable-workpiece-petrinaut-fixture.md#readiness-gate-after-the-new-throughline), not at the first green mutation; see the [visible product advance](docs/mission-drafts/6-resumable-workpiece-petrinaut-fixture.md#visible-product-advance). +### M7 — Construct and explain one real net region from a genuine conversation -### M7 — Make the demo net genuinely explainable +Tracker projection: [FE-1573](https://linear.app/hash/issue/FE-1573/explain-one-prepared-petrinaut-net-from-exact-conversation-evidence), advancing stakeholder outcome [FE-1478](https://linear.app/hash/issue/FE-1478/provide-provenance-from-a-generated-net-back-to-the-requirements-graph); the issue must be re-titled with owner approval before the cut because it still describes the superseded prepared-pair mission. -Tracker projection: [FE-1573](https://linear.app/hash/issue/FE-1573/explain-one-prepared-petrinaut-net-from-exact-conversation-evidence), advancing stakeholder outcome [FE-1478](https://linear.app/hash/issue/FE-1478/provide-provenance-from-a-generated-net-back-to-the-requirements-graph). +After M6 proves viability, run a genuine conversation on one proving scenario through the production agent, let Brunch revise the workpiece as first-class tool calls, build one real net region with a declared basis on every mutation, and answer why for every consequential element from recorded lineage, or refuse. **Product-manager litmus:** talk to Brunch about a process, watch it build that part of the net, then ask why any element exists and see the passage Brunch declared as its basis, the conversation behind it, and which recorded step did what. Demo: open the demo conversation and its net, watch the workpiece pane and its revision diff, type any element's name, read the answer; pick the hand-edited element and the basis-less element and watch Brunch refuse honestly. Previously impossible: Brunch had never built a region inside a real conversation, and nothing connected an element to what was said. Complete at the readiness gate, including the why operation's safety and utility gates; the adversarial tracer and the first constructed region are internal milestones. Authority is cut in two steps under one issue from the final Mission 6 close commit: a narrow first authority for the adversarial tracer and four probes with decision tables and an outcome classification, then an owner-gated, separately committed amendment into the construction-and-explanation body; until that amendment the Step B packet survives in the retitled draft, never in the live Proof. A readiness review on 2026-09-04 tightened oracles, identity semantics, and the pre-cut owner checklist without narrowing scope (decision log section H). Scope history and the full cut-level contract live in the [draft](docs/mission-drafts/7-explainable-construction.md). -After M6 proves viability, close exact capture-backed provenance across the selected prepared pair so a reviewer can ask why any consequential visible element exists and receive workpiece meaning, preparation rationale, and exact conversation evidence, or a visible refusal. **Product-manager litmus:** ask why about any element in the demo net and get the original conversation back. Demo: open the prebuilt demo net, pick any element, type its name, read the answer and its quoted evidence; pick the element known to have no support and watch Brunch decline. Previously impossible: nothing connected a net element to what the expert actually said. Complete when every consequential element in the demo net resolves or visibly declines, not when one element resolves; one element is the throughline tracer inside the mission. On 2026-09-03 the one-element cut was judged too small under the litmus and Mission 7 was expanded to the whole demo net rather than folded into Mission 6 or Mission 9; the reasoning is recorded in the [visible product advance](docs/mission-drafts/7-capture-backed-review.md#visible-product-advance). +### M9 — Make projection repeatable -### M9 — Make projection repeatable and traceable +Tracker projection: [FE-1438](https://linear.app/hash/issue/FE-1438/project-an-evidence-backed-workpiece-into-a-traceable-live-sdcpn); its description predates the 2026-09-04 recut and must be re-titled with owner approval. -Tracker projection: [FE-1438](https://linear.app/hash/issue/FE-1438/project-an-evidence-backed-workpiece-into-a-traceable-live-sdcpn). - -Broaden the viable M6 mutation seam into automatic projection of one meaningful workpiece region, with stable identities and derivations that M7's why route can resolve. Close repeat, changed-input, schema, partial-failure, and semantic-correspondence obligations for the named region rather than a whole-net platform. **Product-manager litmus:** Brunch builds a recognisable part of the net itself from the conversation, and can still explain every piece it built. Demo: from the demo workpiece, ask Brunch to model the named region, watch a non-empty region appear in the panel that matches what was discussed, then ask why about one generated element. Previously impossible: every net in the demo was prebuilt by a person. Provider-schema repair, the transaction probe, and the batching decision are internal to this mission and are not the advance; see the [visible product advance](docs/mission-drafts/9-traceable-projection.md#visible-product-advance). +Over the accepted M7 seam, close what "repeatable" first makes load-bearing: unchanged repeat without duplication or churn, changed input with a bounded impact set, deletion and retirement through identity epochs, concurrent or hand change refused and imported rather than overwritten, cross-conversation document access if the proving scenario needs it, the schema classes the extended region requires, and the per-action versus bounded-batch decision if M7 left it open. **Product-manager litmus:** ask Brunch to model the next part of the process and the net grows without disturbing what was built; ask again and nothing duplicates. Demo: extend the M7 net, repeat the request, change one fact, bring the net up to date, and ask why after the change. Previously impossible: building once was proved; doing it again safely was not. See the [visible product advance](docs/mission-drafts/9-traceable-projection.md#visible-product-advance). The construction half of the former M9 (carrier repair, first nested mutation, first meaningful region, stable ids, positive why) moved into M7 on 2026-09-04. ### M10 — Revise meaning without collateral rebuilding Tracker projection: [FE-1394](https://linear.app/hash/issue/FE-1394/revise-one-traceable-net-region-through-targeted-reviewer-elicitation). -A scenario-authorized reviewer supplies focused new evidence; Brunch preserves prior support, creates an inspectable workpiece revision, and applies a bounded net patch, justified widening, or refusal. **Product-manager litmus:** a second person corrects the model in conversation and only the relevant part of the net changes. Demo: a reviewer challenges one modelled fact in a few turns, sees that region update with the correction attributed to them, sees the rest of the net untouched, and sees Brunch decline a second change it is not entitled to make. Previously impossible: changing the net meant regenerating or hand-editing it. Complete when both the accepted correction and a visible refusal or qualification appear in the same demo; see the [visible product advance](docs/mission-drafts/10-bounded-reviewer-revision.md#visible-product-advance). +A scenario-authorized reviewer supplies focused new evidence; Brunch preserves prior support, creates an inspectable settled workpiece revision that cites the reviewer's message ids, and applies a bounded net patch with declared basis, justified widening, or refusal. Since 2026-09-04 this mission inherits basis, transition records, identity epochs, and the passage policy from M7 and M9 rather than a capture-envelope and derivation seam. **Product-manager litmus:** a second person corrects the model in conversation and only the relevant part of the net changes. Demo: a reviewer challenges one modelled fact in a few turns, sees that region update with the correction attributed to them, sees the rest of the net untouched, and sees Brunch decline a second change it is not entitled to make. Previously impossible: changing the net meant regenerating or hand-editing it. Complete when both the accepted correction and a visible refusal or qualification appear in the same demo; see the [visible product advance](docs/mission-drafts/10-bounded-reviewer-revision.md#visible-product-advance). ### M11 — Hand an accepted model to optimisation Tracker projection: [FE-1503](https://linear.app/hash/issue/FE-1503/hand-one-accepted-sdcpn-to-an-optimisation-experiment). -Only after Chris and Yannis define one concrete consumer contract, broaden the proven path to one selected complete SDCPN and deliver the semantic artifact package in the form they accept. **Product-manager litmus:** Chris and Yannis start an optimisation experiment on a model that came out of Brunch, without asking anyone to reconstruct it. Demo: the handoff package opens in the form they accepted and the experiment begins. Previously impossible: no Brunch output had an external consumer. This mission passes the litmus by construction; see the [visible product advance](docs/mission-drafts/11-optimisation-handoff.md#visible-product-advance). +Only after Chris and Yannis define one concrete consumer contract, broaden the proven path to one selected complete SDCPN and deliver the semantic artifact package in the form they accept. **Product-manager litmus:** Chris and Yannis start an optimisation experiment on a model that came out of Brunch, without asking anyone to reconstruct it. Demo: the handoff package opens in the form they accepted and the experiment begins. Previously impossible: no Brunch output had an external consumer. Since 2026-09-04 the mission has three distinct gates (consumer contract acceptance, working handoff throughline, readiness closure sufficient to begin the experiment) rather than treating the first handoff as completion, and it owes lightweight non-binding consumer discovery before M9 selects its region; see the [visible product advance](docs/mission-drafts/11-optimisation-handoff.md#visible-product-advance). ## FE-1476 product frame @@ -123,9 +114,11 @@ This is an expeditionary posture, not a defensive one. Survey only until the nex ### Evidence, workpiece, capture, and projection -Flue history is the canonical conversation log. Mechanical capture envelopes are immutable, exact-evidence, domain-opaque source records; the foreground Markdown workpiece owns semantic synthesis. Projection consumes the current workpiece. Petrinaut owns canonical net schemas, mutations, parsing, and simulation; Brunch imports or mechanically derives those contracts and never hand-copies their field shapes. +Flue history is the canonical conversation log. The foreground Markdown workpiece owns semantic synthesis and, from Mission 7, its revisions settle only as `update_workpiece` tool calls with revision id, SHA-256, and Markdown persisted in per-conversation state; the fenced `runbook-ir` block is retired for model-produced revisions and the tagged prepared signal is retained only for test-authored material. Projection consumes the current settled workpiece revision. Petrinaut owns canonical net schemas, mutations, parsing, and simulation; Brunch imports or mechanically derives those contracts and never hand-copies their field shapes. + +Mission 2 proved an idempotent model-free sweep: one envelope per user utterance, quote equal to source text, payload `{}`. The production path never invoked capture. On 2026-09-04 capture envelopes and sweep semantics were rejected for provenance: Flue history already carries message ids and exact text, and the store duplicated them under a second identity scheme (decision log C8, G20). Three things stay distinct: those rejected semantics; the existing session-log archive lane in `binding-flue`, which may be hardened only if Mission 7's compaction probe shows `history()` loses folded records; and any new immutable lineage projection actually required by compaction, relocation, or authorization. Task-local JSON is forbidden across any claimed process or task replacement boundary. -Mission 2 proved an idempotent model-free sweep: one envelope per user utterance, quote equal to source text, payload `{}`. The production runbook path still does not invoke capture. Mission 6 may use an explicitly prepared fixture without claiming capture-backed provenance; Mission 7 is the first planned consumer that turns capture into trustworthy product provenance, so capture must become durable before that claim is made. Task-local JSON is forbidden across any claimed process/task replacement boundary. +**Provenance relations lock (2026-09-04).** Lineage and basis are distinct contracts and neither is inferred from the other. Lineage is recovered from the log: settled revisions, mutation requests, and one independently verifiable transition record per browser mutation (requested base hash, observed pre-apply hash, post hash, outcome, disjoint derived effects, diff accounting, conflicting duplicates to unknown). Basis is declared by the constructor on each mutation request as `declared { revisionId, sha256, locators, rationale, scope }` or `absent { reason }`, operation-level unless an intended-effect mapping names elements, and the cited revision must already have settled; a mutation never shares a tool batch with `update_workpiece` and never cites "latest." Passage-to-conversation ranges are conversation context temporally associated with a revision, not evidence, unless `update_workpiece` carried a revision-time evidence relation (`{ locator, messageIds, kind }`). Element ids are never reused across identity epochs, and origin, current state, change history, and attempt history are distinct query semantics. Every why answer reconciles against the live document hash or labels itself "as of the last reconciled state"; external state is imported with dispositions and never laundered. Actors are recorded roles (assistant tool call, local browser executor, user under principal key, test-authored fixture author); human identity is unknown; "when" is canonical stream order. Passage identity is policy before probe: ids never reused after deletion, split and merge record predecessors and successors, ambiguous paraphrase refuses continuity, reintroduction starts a new identity unless declared, locators resolve to immutable revision-local spans. Rejected with reasons: temporal adjacency as causation, hash-only net-to-workpiece joins, provenance pointers in the Petrinaut document, and hand-authored derivation fixtures. Keep these epistemic levels separate: @@ -137,7 +130,9 @@ what projection actually represents Optional SDCPN mapping hints remain advisory, may be absent or plural, identify the prose they concern, and record whether projection accepted, rejected, or deferred them. They neither establish completeness nor copy Petrinaut payloads. -The smallest currently earned provenance seam is current workpiece revision/reference, capture evidence references, net-element ids, and projection rationale. Exact storage and identity shape remain fog for the real tracer. Stable ids must be exercised rather than assumed. Unsupported defaults, stale/partial state, identity churn, repeated projection, and visible partial failure stay explicit. +The smallest planned provenance seam, to be earned by Mission 7, is: settled workpiece revision identity (call id plus SHA-256), passage locator under the passage policy, optional revision-time evidence relation, stable net-element ids with identity epochs, declared basis per mutation request, and the transition record. Storage is the Flue log plus per-conversation state; the compaction probe decides whether an archive lane is needed. Stable ids must be exercised rather than assumed. Unsupported defaults, stale or partial state, identity churn, repeated projection, and visible partial failure stay explicit. + +**Tool admission lock (2026-09-04).** Deferral of Petrinaut tool wiring ended. The inherited six-tool and two-tool subsets are retired as product surfaces once Mission 6 archives. Operations are scenario-selected from the proving case with each class citing the requirement it discharges; their schemas are derived mechanically from Petrinaut's AI tool bundle over a repaired provider carrier (a JSON Schema to Valibot interpreter for the subset Petrinaut uses, or upstream Flue Standard Schema support; never a local copy). The 2026-09-04 case survey and the candidate table live in the mini spec section 3.8. Parity with the stock modeller remains a non-goal; expansion is by observed need with the case named. The `ask` and `sweep` client handling is retired from code under Mission 7 authority; their designs stay in the archives and the structured-question backlog below. Do not add a comprehensive process ontology, graph database, universal subject/predicate/value schema, deterministic capture-to-workpiece reducer, full regeneration engine, or typed completion algebra before observed consumer strain earns one. @@ -162,7 +157,7 @@ The extraction ladder remains: model-free stub envelopes (proved) → separate c ### Product and host boundary -The production door is Petrinaut panel → AI SDK `useChat`/`onToolCall` transport → long-running Flue `ChatAgent` → Anthropic, with client tools executed through the existing host route. Brunch is a selectable second assistant; stock remains functional when Brunch is absent or unselected. Never splice histories, steal the stock `/api/chat` contract, rewrite the panel onto `@flue/react`, or add a direct canvas/server bypass. +The production door is Petrinaut panel (`useChat`/`onToolCall`) → host-supplied browser `ChatTransport` over `@flue/sdk` → mounted `/agents/chat/:instanceId` behind the ownership guard → long-running Flue `ChatAgent` → Anthropic, with client tools executed in the host and returned as one `client-tool-result` signal send. The recut live Mission 5 landed that route and removed the earlier server-side Brunch `/api/chat` adapter; the stock Petrinaut `/api/chat` remains a separate fallback owned by the website. Brunch is a selectable second assistant; stock remains functional when Brunch is absent or unselected. Never splice histories, steal the stock `/api/chat` contract, rewrite the panel onto `@flue/react`, add a second server-side turn protocol, or add a direct canvas/server bypass. Core owns universal, context/domain/editor/formalism-independent elicitation semantics. Plugins pair one reusable domain typology with one target formalism and own that pairing's recognition/operations/coverage/verification guidance, never concrete scenario nouns. The app is the directive-marked registration and host-composition shell. Flue owns `useInstruction`, `useSkill`, `useTool`, static resource packaging, and runtime lifecycle; binding packages adapt generalized capture mechanics to a substrate. @@ -199,7 +194,7 @@ Landed application contract, retained for successor consumers: - active Flue conversation/submission/recovery/settlement state uses `@flue/postgres` with dedicated fields, verified TLS, RDS-IAM async fresh-token support and runtime-password fallback; URI-only and silent SQLite production fallback are rejected; - OTLP/gRPC is initialized before content-free Flue instrumentation and flushed on shutdown; local disposable collector receipt is proved; - local Docker/Postgres/collector smoke proved non-root execution, packaged resources, no `/repo` writes, TLS Postgres startup/refusal, and bounded graceful shutdown; -- public ingress denies `/`, `/assets/*`, and `/agents/chat/:id`; restricted product traffic uses `/api/chat`; one-live-owner policy remains desired-count one, stop-before-start until overlap safety is proved; +- public ingress denies `/`, `/assets/*`, and `/agents/chat/:id`; restricted product traffic used `/api/chat` at that commit. **Superseded by the recut live Mission 5 (2026-09-03):** `/agents/chat/:instanceId` becomes the only product route, so the restricted-ingress rule must be re-expressed as the FE-1423 gates (authentication, per-conversation authorization, telemetry, state versioning/backup, restart durability) applying directly to the mounted Flue route, with `/api/chat` no longer mounted by the Brunch app. The release/deployment gate owns that re-expression and its enforcement; one-live-owner policy remains desired-count one, stop-before-start until overlap safety is proved; - separate Brunch capture JSON is inactive and non-durable. Do not migrate it speculatively, but any mission that consumes capture must first give it durable owner refusal, atomicity, format validation, and session/capture consistency. Flue's Node target is a long-running service with an in-process coordinator and long-lived streams. Do not deploy it as Lambda, a short-lived function, or scale-to-zero. Shared Postgres does not establish active-active safety; keep one replica until ownership and routing through replacement overlap are proved. @@ -217,7 +212,7 @@ Old Mission 8 reconciliation: | Old subsection | Disposition | Surviving consequence/evidence | | --- | --- | --- | | Observed starting point; application-owned surface; runtime candidates; CI wiring | Superseded proposal where implemented; landed application contract where locally observed | The bullets above and deployment handoff replace the pre-implementation audit. Image slimming, Compose parity, and obsolete workflow cleanup have no surviving requirement without strain. | -| Service/communication contract | Landed locally at the application seam | Long-running `/api/chat` → Flue → Anthropic shape, Postgres state, liveness, restricted routes, and content-free OTel survive; remote crossing remains unproved. | +| Service/communication contract | Landed locally at the application seam; door superseded by recut Mission 5 | Long-running Flue → Anthropic shape, Postgres state, liveness, and content-free OTel survive. The `/api/chat` door that carried it is removed by the live mission in favor of the mounted Flue route; the restricted-route rule is re-expressed above. Remote crossing remains unproved. | | Infrastructure-owned surface | Still-open infrastructure gate | Provisioning and identifiers belong to infra; a deploy-catalog entry cannot create them. | | Restricted smoke/public release; identity; front door; rate limits; streaming/availability | Restricted-threshold proposal partly superseded by the stopped handoff; public decisions still open | No public release. Caller UUID, CORS, obscurity, or rate limiting are not authentication. Keep one replica; measure timeout/reconnect and ownership before widening. | | Persistence, migration, recovery | Flue Postgres application contract landed; replacement/backup and capture durability still open | Process-local proof is not ECS replacement proof. Capture remains inactive and must become durable when consumed. | @@ -232,30 +227,28 @@ These tracks may start only under their own issue, branch, PR, and mission autho | Track | Join gate under the accepted spine | Does not block | | --- | --- | --- | -| Frozen prospective baseline | The closed Mission 4 branch preserves it unchanged and makes no quality-improvement claim; because Mission 4 produced no full-run candidate, a successor may inspect this observed one-invalid/two-valid Mission 3 range only if it explicitly selects and promotes an eligible source | Mission 7's source selection and provenance-suitability decision, or the optional Mission 4 addendum | -| Direct Voice/Flue | One finalized spoken turn has one canonical Flue submission and canonical streamed TTS output without AI SDK chat transport or generative simplification | Mission 6 and later product-data work | -| Resumable fixture viability | One prepared fixture crosses conversation → Markdown workpiece → browser Petrinaut read/write → save/reopen | Mission 5 Voice transport work | +| Frozen prospective baseline | The closed Mission 4 branch preserves it unchanged and makes no quality-improvement claim; it is calibration only. Since 2026-09-04 no mission promotes a retained Mission 3 or Mission 4 source; genuine fixtures come from Mission 7's persona programme, labelled synthetic-persona, internal-human, or customer-derived | Mission 7's persona programme, or the optional Mission 4 addendum | +| Resumable fixture viability | One prepared fixture crosses conversation → Markdown workpiece → browser Petrinaut read/write → save/reopen | The live Mission 5 Voice transport work | | Inferential observer fold | Decide before Mission 10 whether observed foreground strain earns promotion; otherwise retain phase-boundary synthesis | Missions 4–9 | -| Provider-visible nested schema | Mission 6 tests only the least mutation needed by its meaningful fixture; Mission 9 closes the broader canonical projection classes after a crisp blocker or success | Mission 5 and non-construction Voice work | -| Provenance interaction fixture | Mission 6 establishes minimal fixture identity; freeze the broader derivation fixture before Mission 7 why and Mission 9 automatic projection diverge | Voice work and prepared-fixture viability | -| Host choice/session lifecycle | Mission 5 proves Flue conversation reopen; Mission 6 proves fixture save/reopen; later host/picker breadth waits for its visible consumer | Either independent tracer | -| Optimisation handoff contract | Chris/Yannis accept input/output contract and one fixture before Mission 11 is cut | Missions 4–10 | -| Simulation-backed semantic check | Promote only if cheap and discriminating for the selected revision | First provenance tracer | +| Provider-visible nested schema | Mission 6 tests only the least mutation needed by its fixture; Mission 7 repairs the carrier and proves one real nested mutation on its proving scenario before admitting classes; Mission 9 closes the classes its extended region adds | Mission 5 and non-construction Voice work | +| Fixture materialization | Mission 7 proves one tiny genuine conversation can be exported or retained, relocated, reopened, authorized, and queried before any paid persona breadth; the probe's branch selects the demo fixture route | Voice work and prepared-fixture viability | +| Compaction survival | Mission 7 forces compaction and reads `history()`; the branch decides whether the existing archive lane is hardened | Everything before Mission 7 | +| Host choice/session lifecycle | Mission 5 proves Flue conversation reopen; Mission 6 proves fixture save/reopen over Mission 5's landed browser transport; later host/picker breadth waits for its visible consumer | Mission 5 first, then Mission 6 | +| Optimisation handoff contract | Chris/Yannis accept input/output contract and one fixture before Mission 11 is cut; lightweight non-binding discovery happens before Mission 9 selects its region | Missions 4–8 | +| Behavioural discriminator | Mission 7 derives one executable check from the workpiece for its constructed region and carries it unchanged to Missions 9 and 10; broader simulation coverage waits for a discriminating need | The adversarial tracer | -The deliberately provisional shared-interface names remain `EvidenceBackedWorkpieceItem`, `DerivationRecord`, and `NetPatch`. Do not freeze richer names or field catalogs before two tracks genuinely share them. If fixture UI and projection cannot agree on the minimal derivation record, pause parallel work at that seam. +The provisional shared-interface names `EvidenceBackedWorkpieceItem`, `DerivationRecord`, and `NetPatch` were superseded on 2026-09-04: the revision identity, declared basis, transition record, and identity epoch named in the provenance relations lock are the shared seam, and Mission 7 earns their exact shapes. Do not freeze richer names or field catalogs before two missions genuinely share them. ## Detailed provisional clusters -Detailed mission-specific boundaries, tracer floors, readiness ratchets, risks, oracles, and stop conditions live only in these six context repositories: +Detailed mission-specific boundaries, tracer floors, readiness ratchets, risks, oracles, and stop conditions live only in these four context repositories: -- [Draft Mission 5 — direct Voice over canonical Flue transport](docs/mission-drafts/5-direct-voice-flue-transport.md) -- [Draft Mission 6 — resumable workpiece-to-Petrinaut fixture tracer](docs/mission-drafts/6-resumable-workpiece-petrinaut-fixture.md) -- [Draft Mission 7 — capture-backed review](docs/mission-drafts/7-capture-backed-review.md) -- [Draft Mission 9 — automatic traceable projection](docs/mission-drafts/9-traceable-projection.md) +- [Draft Mission 7 — construct and explain one real net region](docs/mission-drafts/7-explainable-construction.md), written at cut-level detail with a conversion map +- [Draft Mission 9 — repeatable projection breadth](docs/mission-drafts/9-traceable-projection.md) - [Draft Mission 10 — bounded reviewer revision](docs/mission-drafts/10-bounded-reviewer-revision.md) - [Draft Mission 11 — optimisation handoff](docs/mission-drafts/11-optimisation-handoff.md) -Do not create Mission 4 or Mission 8 drafts. Missions 5 and 6 are parallel, independent next cuts; each must become the sole live root `MISSION.md` in its own worktree. Mission 11 stays deliberately shallow until Chris and Yannis accept input artifacts, one optimisation question, scenario/parameter representation, execution boundary, expected result, and minimum credibility checks. +Do not create Mission 4 or Mission 8 drafts. Mission 5 is on the FE-1574 branch beneath this one and was Mission 6's transport prerequisite; Mission 6 is closed here and its execution record exists only in root `MISSION.md`. Mission 11 stays deliberately shallow until Chris and Yannis accept input artifacts, one optimisation question, scenario/parameter representation, execution boundary, expected result, and minimum credibility checks. ## Unallocated backlog @@ -305,6 +298,8 @@ Rejected mechanisms re-enter only under their named strain: closed kinds/slots/d The previous typed-map cluster—required fields and unresolved gaps mechanically deriving ask/construct/deliver—remains a recorded hypothesis, not the default. It re-enters only if the workpiece-to-projection tracer or construction-gap return shows that model-assisted judgment cannot reliably name the smallest next question without typed demands. +**2026-09-04 additions.** Passage identity is now a predeclared policy (see the provenance relations lock) tested by Mission 7's probe across rename, move, paraphrase, split, merge, deletion, and reintroduction; if the policy is too expensive the first claim is revision-local text. Revision cadence, unmeasured in every retained run (no retained persona run has more than one `runbook-ir` block), is the named strain for both the visible workpiece pane and blame grain; Mission 7 measures it in the adversarial tracer. Versioned assertion clusters remain the possible response only if the optional evidence relation proves insufficient under observed revision strain. + ### Capture/workpiece seam history and rejected mechanisms Four prior relationships retain distinct evidence: @@ -316,6 +311,8 @@ Four prior relationships retain distinct evidence: The optional offline shadow join runs Mission 2 capture over settled history, assigns temporary workpiece-statement ids, and grades evidence relation, epistemic treatment, lifecycle relation, and projection treatment separately; assumptions never count as evidence support. Measure support coverage, synthesis fan-in, capture utility, context dependence, correction integrity, path sensitivity, and revision link churn. A fold becomes plausible only if order perturbation preserves active meaning without loop latency or requiring elicitor consultation of every fold. FE-1476 supersedes independence only as a sufficient delivery posture; it proves no store fold, merger, live linker, or comprehensive identity system. +**2026-09-04 outcome.** Relationship B, support links only, was superseded rather than implemented: the link from a net element to workpiece meaning is now the constructor's declared basis at construction time, and the link from workpiece meaning to conversation evidence is the optional revision-time evidence relation on `update_workpiece`, with temporal context as the honest fallback. Both are creation-time relations authored by the actor who knows, not retrospective links, and neither is a capture envelope. A, C, and D remain rejected for the reasons above; the shadow join remains an optional offline measurement if basis quality proves poor. + ### Mission 3 split and construction evidence The surviving outcome is intentionally split: **runbook/workpiece path accepted; real-model semantic construction false on the exercised route**. Mission 3 locked one off-canvas PN JSON result, Petrinaut validation, manual load as inspection, and no canvas tools. The frozen prospective control has one invalid runtime member and two valid independently graded workpieces; historical runs are calibration only. @@ -356,6 +353,8 @@ The real proof must cross **model → binding → transport → frontend → cor Do not claim this from a model tool call or rendered widget alone. Exercise all layers, cancellation/topic redirect, replay/resume, correlation, no wake wart, and stock-assistant isolation before promotion. +On 2026-09-04 the owner decided that the orphaned `ask` and `sweep` client handling (core `client-tools.ts` names and the suspended ask contract, the website ask interactive tool and test, the sweep filter and output module in the panel transport, and the Voice references in `canonical-speech.ts` and `interview-coverage.ts`) is retired from code under Mission 7 authority, because no mounted server tool produces either and the MVP demo will not teach them. This section and the Mission 2 and 4 archives remain the design reference; re-entry follows the proof above. + ## Later and opportunistic concerns ### Host/session continuity and compaction @@ -366,19 +365,23 @@ Missions 5 and 6 may each use a fixed Brunch mode. Mission 11 owns only the broa Working session hypothesis: net id discriminates one Flue conversation per principal; save/load resumes it, new net creates another. Today localStorage maps conversation ids by `netId`, while capture keys principal + conversation id. If ids regenerate/collide, rekey. Locked: net id is only a discriminator, not a Brunch target-document ontology. Keep rejected alternatives rejected: “net equals target-document” and sweep into a throwaway store for later splicing. -Before claiming long-running provenance, prove panel/transcript/workpiece recovery across real Flue compaction (`compaction-vs-durable-history` / FE-1386). Current recovery scrapes the last `runbook-ir` fence; summary loss would break it. A short rehearsal may avoid compaction only if the handoff declares uncompacted-history dependence. Compaction is history reconstruction, not projection sequencing; control to compact/show summaries waits for evidence. +Before claiming long-running provenance, prove panel/transcript/workpiece recovery across real Flue compaction (`compaction-vs-durable-history` / FE-1386). Current recovery scrapes the last `runbook-ir` fence; summary loss would break it. Mission 7 replaces that recovery with `update_workpiece` state and runs the compaction probe as one of its four first probes, with a decision table in its draft; a short rehearsal may avoid compaction only if the handoff declares uncompacted-history dependence. Compaction is history reconstruction, not projection sequencing; control to compact/show summaries waits for evidence. + +### Voice after the live transport cut + +The [Voice runtime ownership and conversational delegation design](docs/mission-drafts/voice-runtime-ownership.md) is the provisional home for the 2026-09-07 split-ownership proposal and its pinned #9564 foundation. It separates call directions from subsequently proposed runtime mechanisms and does not amend live authority or authorize implementation. -### Voice +The [bounded conversion and gated implementation proposal](docs/mission-drafts/voice-runtime-ownership-conversion.md) re-pins the current PR foundation, records the supported-Flue recording blocker, and prepares the owner approval gate. It owns conversion sequencing and candidate checks, not a second architecture contract or execution authority. -Direct Voice/Flue transport is now Draft Mission 5 rather than an unallocated integration constraint. The observed remote stack remains `kostandin/fe-1570-voice-optimized-brunch-responses` → `kah-6763-temporary-brunch-ask` → `kah-6800-improve-petrinaut-voice-turn-taking-and-answer-provenance` (PRs #9496, #9507, and #9512), diverging before Mission 4's app/package restructuring. Reconciliation must preserve current `useBrunchAgent()` + `useSdcpnPlugin()` composition and port only the still-needed Voice behavior onto current seams; never restore the older app-local stub agent. +The Mission 5 contract, recut on 2026-09-03, owns the single-route consolidation: the typed panel's browser `ChatTransport` over `@flue/sdk`, removal of the server-side `/api/chat` door, repurposing `transport-aisdk` as the browser-side adapter, direct Voice/Flue reconciliation, its selected external-PR evidence, and the bounded local tracer. Its 2026-09-04 human witness passed typed and Voice admission, spoken playback, barge-in, and durable Stop, then failed faithful reopen: per-message typed/Voice provenance disappeared and the stopped entry returned as ordinary truncated content. On 2026-09-04 the owner explicitly waived the fresh-human re-check and closed Mission 6; its fresh product-manager conversation contained neither record. A subsequent source/artifact audit could not substantiate the earlier mechanical-coverage claim: both retained outer-witness bundles contain only completed settlements and no recorded Voice origins, and the analyzed history projector did not reconstruct either per-message property. Preserve the historical close and immutable records, but neither the waiver nor those bundles establish a presentation pass. Mission 6b's root authority owns the combined foundation check and distinguishes supported client-tool attribution from blocked direct-user attribution. -Mission 5 treats the AI SDK UI-message transport and existing Petrinaut assistant as optional consumers, not Voice authority. Voice should use supported Flue `send`/`read`/`observe`/`history`/`abort` semantics directly or through the thinnest authenticated protocol-preserving proxy. Brunch owns canonical response text; Voice owns STT, TTS, interruption/cancellation, finalized-answer provenance, and playback. Provisional transcription/audio remains ephemeral, finalized answers enter canonical Flue history once, and the first tracer speaks canonical output without a secondary generative simplifier. Adapter/UI deletion requires separate consumer proof. +A later mission that exercises Voice, exact conversation resume, or pre-release scenario breadth must include one reproducible scenario containing at least one typed-origin message, one Voice-origin message, and one durably aborted assistant entry. After closing and reopening in a second tab, the oracle must verify per-message typed/Voice provenance, render the aborted entry as stopped rather than ordinary truncated content, and distinguish local **Exit voice mode** from durable composer **Stop**. Fold this scenario into that mission's named test portfolio before closure; do not treat Mission 6's prepared fixture or mechanical witness as a permanent substitute for the skipped human check. -The complete inherited seam map is in [`mission-4-voice-integration-handoff.md`](docs/evidence/implementations/mission-4-voice-integration-handoff.md); the revised cut contract and proof target are in [`5-direct-voice-flue-transport.md`](docs/mission-drafts/5-direct-voice-flue-transport.md). +The small transcript reveal control remains observed discoverability strain for that surface. This future record otherwise retains only work beyond the direct cut: whether Petrinaut ever drops `useChat` itself is a Petrinaut product decision with no Brunch obligation; the structured-question route re-enters only after plain-turn strain and owner acceptance; broader barge-in, long-response, speech-selection, and accessibility quality require observations from the direct route; and trusted remote identity, origin policy, deployment, and spend controls remain release work. The inherited seam map remains in [`mission-4-voice-integration-handoff.md`](docs/evidence/implementations/mission-4-voice-integration-handoff.md). ### Observability and simulation viewing -Brunch has local content-free OTLP/gRPC export and graceful flush; hosted reachability and real normal/failure attributes remain open. Prove `gen_ai.conversation.id` equals Flue instance id and decide `traceparent` propagation. Keep prompt/response/tool content off until privacy/retention/access policy. Mission 5 needs only tracer latency/tool evidence; broad OTel remains a release gate. +Brunch has local content-free OTLP/gRPC export and graceful flush; hosted reachability and real normal/failure attributes remain open. Prove `gen_ai.conversation.id` equals Flue instance id and decide `traceparent` propagation. Keep prompt/response/tool content off until privacy/retention/access policy. The live Mission 5 contract owns only its bounded tracer latency evidence; broad OTel remains a release gate. Simulated-conversation viewing remains evaluation infrastructure, not a protocol rewrite. The 2026-09-02 [live-observable persona spike](docs/evidence/evaluations/live-observable-persona-spike/README.md) @@ -401,13 +404,53 @@ No evidence yet says a non-empty parser-valid net behaves like the workpiece. Ca ### Other substrate and product hypotheses -AI SDK 7 `HarnessAgent` is undecided: it is the converse of the current door, resuming a harness session by chat id. Flue already owns that session and `transport-aisdk` adapts UI. A Pi/Claude Code harness is another binding substrate or Flue replacement, not the simulation viewer. Re-enter only with a concrete consumer. +AI SDK 7 `HarnessAgent` is undecided: it is the converse of the current door, resuming a harness session by chat id. Flue already owns that session and `transport-aisdk` adapts the panel's `useChat` contract onto the public Flue client in the browser. A Pi/Claude Code harness is another binding substrate or Flue replacement, not the simulation viewer. Re-enter only with a concrete consumer. Exploded-view net prototypes belong on Petrinaut website host routes, not `:4321`. If `ChatAgent` leaves the app, put it under `packages//`; the app stays shell. HASH embed remains stock unless explicitly opted in. Historical Conditions 1/2/4/5 remain batch evidence; no TUI, retired SDCPN elicitor, generalized `useElicitation()` runtime, loader, workflow engine, or second model-facing agent. +## 2026-09-04 provenance replanning migration disposition + +This ledger satisfies the one-authoritative-home and no-silent-loss rules for the 2026-09-04 recut. Every planning item in the former Mission 7 draft (`7-capture-backed-review.md`, renamed with history to `7-explainable-construction.md`), the former Mission 9 draft, and the affected spine paragraphs maps to exactly one surviving destination. Nothing was removed without a named home or a recorded rejection with reason. + +| Former item | Surviving home | Disposition and consequence | +| --- | --- | --- | +| M7 visible advance: why over an honest prebuilt pair; whole-net expansion of 2026-09-03 | Draft 7, Visible product advance and Scope history | Superseded: prebuilt pair rejected as fixture-rigging (log A3, B4); construction and explanation consolidated (F12); whole-net completion preserved as the inventory rule (G13). | +| M7 contract stratum: capture envelopes, stable references, prebuilt SDCPN, derivation fixture, resolution operation | Draft 7, Contract stratum; spine provenance relations lock | Envelopes and derivation fixture rejected with reasons (C8, B4, G20); stable references become passage policy plus declared basis; resolution operation becomes the composed why operation. | +| M7 boundary crossings: harness sweep, capture store, prebuilder, `useChat`/`onToolCall` path | Draft 7, Boundary crossings | Sweep and store removed; prebuilder replaced by the constructing model with declared basis; host path retained. | +| M7 proof floor: one element resolves; one broken link refuses | Draft 7, Throughline proof floor Step A | Expanded to the adversarial tracer with eight required features and four probes with decision tables (G17). | +| M7 inherited closure: Mission 2, 3/4, prebuilt honesty, Mission 8 durable capture, product door | Draft 7, Inherited stratum closure | Mission 2 not consumed; Mission 8 local posture; product door consumed via Mission 5. | +| M7 readiness gate list (dispositions, duplicates, replay, cross-owner, negative states, deterministic context, coexistence, latency, compaction) | Draft 7, Readiness gate | Every item retained and re-expressed over lineage and basis; cross-owner narrowed to the single-principal limit (F11) with breadth to Mission 9 (G5). | +| M7 candidate evidence table and ORACLE GAPs | Draft 7, Candidate evidence and oracles | Existing tests re-cited; gaps re-expressed; capture-store tests retained as historical inner evidence only. | +| M7 inputs and joins (upstream source, Mission 2, prebuilt fixture, Mission 8, Petrinaut host, Mission 9 output) | Draft 7, Inputs and joins | Upstream source becomes the persona programme; Mission 2 join dropped with reason; Mission 8 join is local posture. | +| M7 risks table | Draft 7, Risks and assumptions | Rows on unique names, useful excerpts, compaction, model inventing links, and one-pair peer set carried; new rows for cadence, basis, materialization, carrier, effects, binding, representativeness, cost, and gate ordering. | +| M7 constraints: harness owns sweep; envelopes immutable; no observer; no typed ontology; no automatic projection; no transcript fallback; durability matches claim; ownership fails closed; Petrinaut owner; no content telemetry | Draft 7, Accepted constraints | Sweep and envelope items retired with reason; "no automatic projection" inverted because this mission constructs; all others retained. | +| M7 cross-cutting obligations and touched paths | Draft 7, Cross-cutting obligations and Expected touched paths | Retained and re-expressed; capture paths marked for retirement or archive-lane hardening. | +| M7 fog-line (source eligibility, exact range, derivation representation, inventory, names, durable owner, deployed host, compaction, latency, portfolio) | Draft 7, Fog-line and decision tables | Source eligibility replaced by source labelling; derivation representation replaced by basis and transition record; others retained. | +| M7 stop conditions | Draft 7, Stop or reorient | Retained and re-expressed; new stops for mixed batch, uncitable revisions, self-reported effects, id reuse, circular basis. | +| M7 carried evidence and rejected alternatives (Mission 2 pipe, Mission 3, Mission 4, Mission 8 handoff, A–D seam, assertion cards, typed payloads, observer, automatic projection to M9) | Draft 7, Carried evidence; spine capture seam history 2026-09-04 outcome | All retained; B superseded by declared basis; automatic projection now in M7 with breadth to M9. | +| M7 click-to-chat deferral; FE-1476 beats 1–3 framing | Draft 7, Carried evidence | Retained. | +| M9 visible advance: Brunch builds a recognisable region and explains it | Draft 7, Visible product advance | Moved: this is now Mission 7's advance. | +| M9 internal sequencing: carrier repair → single nested tracer → transaction probe → batch decision | Draft 7 (carrier probe, nested tracer); Draft 9 (transaction probe, batch decision) | Split: repair and first nested call in M7; batching decision in M9 unless M7's scenario forces it. | +| M9 contract stratum items: region identity, types, parameters, places/transitions/arcs, stable ids, derivations, rejection/repair, repeat/change, semantic correspondence, durable boundary | Draft 7 (first region, ids, basis, rejection/repair, correspondence); Draft 9 (repeat, change, retirement, concurrent, breadth) | Split by what each visible claim first makes load-bearing (G16). | +| M9 readiness gate list | Draft 9, Readiness gate; Draft 7, Readiness gate | Repeat, change, retirement, concurrent, batch, breadth in Draft 9; schema classes used, provider vs canonical rejection, repair budget, no-op honesty, unsupported defaults, correspondence, partial failure, isolation in Draft 7 for the proving scenario and in Draft 9 for the extension. | +| M9 candidate evidence and ORACLE GAPs | Draft 7 and Draft 9 tables | Split accordingly; existing tests re-cited in both. | +| M9 risks table | Draft 7 and Draft 9 tables | Carrier and conversion rows in Draft 7; repeat, ids, batch, bounded context, recomputation, retirement, discriminator rows in Draft 9. | +| M9 constraints, obligations, touched paths, fog, stops | Draft 9, corresponding sections; Draft 7 where they concern the first region | Retained; "no automatic projection" and "derivation" wording replaced by basis and transition record. | +| M9 carried evidence (Mission 3 fixture and 0-for-9, Standard Schema move, canonical authority, prebuilt-first, rejected ontology list, hints, stable ids, recomputation fog, 46-tool parity, `pn_read`/`pn_edit`, observer, Mission 11 breadth) | Draft 9, Carried evidence | All retained; prebuilt-first replaced by the 2026-09-04 rejection with reason. | +| Spine précis M7 and M9 | Spine, Successor mission précis | Rewritten; scope history preserved in Draft 7. | +| Spine capture paragraph: "Mission 7 turns capture into trustworthy product provenance" | Spine, Evidence, workpiece, capture, and projection | Superseded with reason; archive lane distinction added (G20). | +| Spine "smallest currently earned provenance seam" | Same section | Replaced by the planned seam and the tool admission lock. | +| Spine parallel tracks: provider-visible nested schema (M9 owner), provenance interaction fixture, simulation check; provisional interface names | Spine, Parallel and asynchronous proof tracks | Owners moved to M7; interaction fixture replaced by fixture materialization and compaction rows; names superseded. | +| Spine later concerns: compaction paragraph | Spine, Host/session continuity and compaction | Pointer to M7 probe added; content retained. | +| Spine backlog: capture seam history; workpiece hypotheses; structured questions | Same sections, 2026-09-04 additions | Outcomes appended; nothing removed. | +| Draft 10 sweep, capture ledger, derivation seam, durable capture oracle gap | Draft 10, edited in place | Re-expressed over settled revisions, reviewer message ids, basis, transition records; Mission 2 archive marked historical. | +| Draft 11 circular readiness statement | Draft 11, Throughline proof floor and Readiness ratchet | Three gates; early consumer discovery added (G21, F15). | + +Items added on 2026-09-04 with no former home: the settled-revision protocol, declared basis, revision-time evidence relation, transition record, identity epochs, document reconciliation and binding, recorded roles, passage policy, scenario-selected admission, safety and utility gates, runtime migration matrix, behavioural discriminator, two-step authority, and the probe decision tables. Their authoritative planning home is Draft 7; their rationale is the decision log. + ## Historical 2026-09-02 migration disposition -This section preserves the planning split as it was accepted on 2026-09-02. It is historical evidence, not the current draft inventory or numbering authority; the current six-draft topology is listed above. At that time, the candidate split had one live authority, one compact spine, four provisional drafts, and no Mission 4 or Mission 8 draft. Its source-to-destination ledger was: +This section preserves the planning split as it was accepted on 2026-09-02. It is historical evidence, not the current draft inventory or numbering authority; the then-current six-draft topology preceded the live Mission 5 cut. At that time, the candidate split had one live authority, one compact spine, four provisional drafts, and no Mission 4 or Mission 8 draft. Its source-to-destination ledger was: | Previous `MISSION.next.md` section | Surviving planning home | Disposition and consequence | | --- | --- | --- | @@ -498,4 +541,10 @@ The owner subsequently changed the integration premise: Voice should use canonic ## 2026-09-03 product-manager litmus reframing -Later on 2026-09-03 the owner replaced the "visible/usable proof" completion criterion with the product-manager litmus defined in the accepted spine above. The observed problem was that each précis pinned completion to an evidence bundle at the first green throughline tracer, which convinces a builder but is invisible to a product manager, and that Draft Mission 9 carried engineering internals in its visible-advance section. The change re-pins completion to each mission's readiness gate for the named demo scenario, moves oracles out of the visible-advance sections, expands Mission 7 from one element to every consequential element of the demo net, and names the deployment posture problem for Missions 7, 9, and 10. Mission 5 was live on its own branch and was not touched. Mission-specific detail lives in the affected drafts' `Visible product advance` and `Throughline proof floor` sections and in the [draft README](docs/mission-drafts/README.md). +Later on 2026-09-03 the owner replaced the "visible/usable proof" completion criterion with the product-manager litmus defined in the accepted spine above. The observed problem was that each précis pinned completion to an evidence bundle at the first green throughline tracer, which convinces a builder but is invisible to a product manager, and that Draft Mission 9 carried engineering internals in its visible-advance section. The change re-pins completion to each mission's readiness gate for the named demo scenario, moves oracles out of the visible-advance sections, expands Mission 7 from one element to every consequential element of the demo net, and names the deployment posture problem for Missions 7, 9, and 10. Mission 5 was live on its own branch and was not touched by that commit; on restack, the live branch adopted the litmus in [`MISSION.md`](MISSION.md#product-manager-litmus), naming Stop-that-really-stops and one shared typed/spoken conversation as its product-manager-noticeable advance and its single-route consolidation as internal sequencing. Mission-specific detail lives in the affected drafts' `Visible product advance` and `Throughline proof floor` sections and in the [draft README](docs/mission-drafts/README.md). + +Mission 6 had been cut into root [`MISSION.md`](MISSION.md) on the FE-1575 branch from the pre-litmus draft earlier the same day. That cut was recut on restack rather than left as it stood: its proof section had named the evidence bundle (selector, manifest, snapshots, revisions) as the visible proof artifact and read as if the first green two-tab pass were completion. The recut moves the release note, demo script, and previously-impossible statement into the imperative, names the readiness gate as the completion bar, keeps the seven discriminating oracles as builder evidence, and records the local-only demo posture explicitly. No Mission 6 draft remains here. + +## 2026-09-03 Mission 5 becomes Mission 6's transport prerequisite + +Missions 5 and 6 were cut as independent siblings on this spine. Mission 5's recut then made one browser Flue `ChatTransport` the only door into a Brunch conversation and removed the server-side `/api/chat` route, `createPetrinautChatHandler`, the `GET ?id=` history door, and the app-side UI-stream projector that Mission 6's throughline had named as its departure point. The owner corrected Mission 6 to consume Mission 5's landed transport rather than wire against the route being deleted or copy Mission 5's in-progress implementation. Mission 6 implemented and verified its transport-independent substrate (prepared-signal recovery, fixture-scoped read and `addArc`, correlated-result settlement refusal, stable selector, document seed, runtime manifest) and then stopped at that boundary. The owner first chose to keep Mission 6 a sibling branch and wait for Mission 5 to land, because Mission 5's committed state was then documentation only and every line Mission 6 needed sat uncommitted. Mission 5 then committed its typed-panel transport tracer as three commits (`Expose the Flue browser chat transport`, `Wire the Petrinaut panel to the Flue route`, `Remove the legacy Petrinaut chat route`) ahead of its Voice work, and the owner reversed the wait: this branch was moved onto `ln/fe-1574-direct-voice-flue` so Mission 6 consumes only Mission 5's committed public surface. Splitting the transport consolidation into a shared substrate branch was rejected because it would sever half of Mission 5's imperative from its authority. Consequences accepted with the move: this branch's root `MISSION.md` is Mission 6's, so Mission 5's live authority is visible only on its own branch; Mission 6 cannot merge before Mission 5; and when Mission 5 closes and archives its authority this branch will need another restack. The independence claims in the spine above were corrected to match. diff --git a/libs/@hashintel/brunch-agent/docs/adr/README.md b/libs/@hashintel/brunch-agent/docs/adr/README.md index a4100b80873..1aec2e1af60 100644 --- a/libs/@hashintel/brunch-agent/docs/adr/README.md +++ b/libs/@hashintel/brunch-agent/docs/adr/README.md @@ -8,4 +8,4 @@ re-earn before building further on them. Internal references to retired paths (`docs/control/`, `docs/agents/`, `docs/INDEX.md`) are historical and not maintained. -For the current accepted Brunch architecture, start at the root [`MISSION.md`](../../MISSION.md) closure pointer, [`MISSION.next.md`](../../MISSION.next.md), and the final [Mission 4 archive](../mission-archive/4-core-plugin-elicitation-proof-of-life.md). Mission 4 replaced the generalized YAML/repertoire/plugin machinery described in ADR-0002, ADR-0006, and ADR-0007 with a Flue-native independent core `elicitation` capability, target-pairing plugin job skills, and app-owned composition. Those ADRs remain useful design history, not an integration baseline. +For the current accepted Brunch architecture, start at the live root [`MISSION.md`](../../MISSION.md), [`MISSION.next.md`](../../MISSION.next.md), and the final [Mission 4 archive](../mission-archive/4-core-plugin-elicitation-proof-of-life.md). Mission 4 replaced the generalized YAML/repertoire/plugin machinery described in ADR-0002, ADR-0006, and ADR-0007 with a Flue-native independent core `elicitation` capability, target-pairing plugin job skills, and app-owned composition. Those ADRs remain useful design history, not an integration baseline. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/design/mission-5-question-marker-and-provenance-decision-2026-09-04.md b/libs/@hashintel/brunch-agent/docs/evidence/design/mission-5-question-marker-and-provenance-decision-2026-09-04.md new file mode 100644 index 00000000000..f664d2175f4 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/design/mission-5-question-marker-and-provenance-decision-2026-09-04.md @@ -0,0 +1,97 @@ +# Mission 5 question replay and direct-user provenance decision + +## Decision + +The owner approved two changes to the live FE-1580 authority on 2026-09-04: + +1. Brunch may expose a non-interactive, model-facing question-marker tool. The + marker identifies exact assistant-authored question text for Voice replay, + but it never suspends a response, renders an answer affordance, accepts an + answer, or changes Voice path B. +2. Direct-user Voice provenance must wait for an upstream Flue contract that + durably projects caller metadata on a canonical `kind: "user"` message. This + branch must not patch Flue locally or approximate provenance with a second + signal admission, browser storage, or encoded user text. + +## Exact question marker + +Brunch core owns a `brunch_mark_question` server tool and a +`data-brunch-question` client marker. Before asking the user a direct question, +the model calls the tool with the exact question text. The tool writes a durable +data part containing that text and its Flue `toolCallId`, then returns a small +acknowledgement. It does not terminate the response. Brunch instructions require +the same exact text to appear in ordinary assistant prose after the tool call. + +The browser transport hides the marker tool's implementation call while +retaining the data part. This keeps an internal annotation out of Petrinaut's +tool-activity UI without creating another conversation representation. Both the +live stream and canonical snapshot projection apply the same hidden-tool rule. + +Canonical speech accepts a question marker only when all of these facts hold: + +- the marker has a non-empty string question and non-empty `toolCallId`; +- it belongs to an assistant message; +- the same assistant message contains the exact marked string in finalized + ordinary text; and +- the marker data part is complete and canonical, not provisional Voice state. + +Malformed, unmatched, stale, or absent markers do not enable **Repeat +question**. The final text segment and punctuation are never used as fallback +question authority. The selected question segment derives stable identity from +the assistant message id, marker tool-call id, and exact-text hash. Full-response +speech remains the ordered ordinary text segments and is not rewritten or +duplicated by the marker. + +The Voice controller carries the selected question separately from the full +response. **Repeat question** reuses the existing exact canonical queue and the +same settlement, output-completion, idle-input, submission, cancellation, +capture, pause, and error gates as **Read full response**. The control remains +disabled when the settled response has no matching marker. + +## Production proof + +Tests are written and observed failing before implementation. Closing evidence +must cover: + +- Brunch's built Flue agent mounting `brunch_mark_question` while continuing to + omit `brunch_ask`; +- a real server-tool call writing a durable `data-brunch-question` part; +- live transport and snapshot projection hiding the implementation tool while + retaining the marker; +- canonical selection rejecting malformed and unmatched markers and preserving + exact text and stable identity for a valid marker; +- the production Voice host registering `repeatQuestion` and the panel invoking + it only when `canRepeatQuestion` is true; and +- controller and preview integration proving exact question-only replay after + correlated Brunch settlement and matching Realtime output completion, with + every existing replay exclusion still enforced. + +## Direct-user Voice provenance + +Flue 2.0.3 and current upstream `main` accept only `body` and image +`attachments` on `kind: "user"`. The caller's idempotency key is irreversibly +hashed into `submissionId`; canonical snapshots do not expose that key or +caller-authored user metadata. Agent-authored response metadata cannot annotate +the canonical user message. + +The accepted route is an upstream Flue extension that admits caller metadata on +the user delivery, persists it atomically with the canonical user record, and +projects it on live and historical user messages. FE-1580 can adopt that seam +only after a released dependency is available and the branch is explicitly +authorized to upgrade. The closing oracle is a snapshot-only fresh-process test +that restores the Voice marker without browser correlation state. + +Rejected alternatives: + +- a local Yarn patch to Flue, because it forks substrate persistence and wire + projection inside this product PR; +- a correlated provenance signal, because it is a second, non-atomic admission + that can independently fail or wake the agent; +- browser or application sidecar storage, because it becomes a second durable + authority; and +- hidden transcript, attachment, or visible-text encoding, because it changes + the canonical user representation or smuggles metadata through content. + +Until the upstream contract is released and adopted, direct spoken user text +remains canonically durable but its Voice chip after reopen remains blocked and +must not be reported as complete. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/design/provenance-and-tooling-decision-log-2026-09-04.md b/libs/@hashintel/brunch-agent/docs/evidence/design/provenance-and-tooling-decision-log-2026-09-04.md new file mode 100644 index 00000000000..58ac0e442ec --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/design/provenance-and-tooling-decision-log-2026-09-04.md @@ -0,0 +1,205 @@ +# Provenance, workpiece, and tooling decision log — 2026-09-04 + +> Design evidence, not execution authority. Compiled on 2026-09-04 from the owner conversation that reviewed the Mission 6 tie-off and the Mission 7 departure point. Every terrain claim below was checked against the checked-out code or the installed Flue 2.0.3 types during that conversation; each entry names what was inspected. Owner-settled items are policy accepted in conversation and must still be promoted into mission authority at the named cut before implementation. Recommendations are the agent's and remain open until the owner accepts them. The projection of this log into a reviewable design is [`provenance-by-lineage-mini-spec-2026-09-04.md`](provenance-by-lineage-mini-spec-2026-09-04.md). + +Legend: **Settled** = owner accepted in conversation. **Recommended** = agent recommendation, not yet accepted. **Open** = fog; a probe is named. + +## A. Mission 6 tie-off + +**A1. Mission 6 deterministic layers are closed; the outer witness was blocked by an environment fault, not a product defect.** Settled as observation. Inspected: `docs/evidence/implementations/fe-1575-resumable-workpiece-petrinaut.md`; the shell's `ANTHROPIC_API_KEY` was the five-character placeholder `dummy`, which explains the recorded HTTP 401. Consequence: the outer two-tab witness, the cold-reader adjudication, and the product-manager demo remain open; the two human gates depend on the outer rerun because the model-produced revision does not yet exist. The Mission 6 builder is performing the rerun in a parallel session (untracked `fe-1575-outer-browser-witness-2026-09-04-r2/` observed in the worktree). + +**A2. Mission 6 stacks on unmerged Mission 5.** Observation. `gt log short` shows `ln/fe-1574-direct-voice-flue` beneath this branch; GitHub PR 9528 is open awaiting review; Mission 5's human Voice witness is unrun per its evidence README. No PR exists yet for FE-1575. Consequence: Mission 6 cannot merge before Mission 5, and its close report needs a PR. + +**A3. The prepared fixture's "Current Petrinaut correspondence" section is fixture-rigging.** Settled. Inspected: `prepared-crew-reservation-fixture.ts` versus `plugin-sdcpn/src/skills/sdcpn-modelling/templates/workpiece.md`; no template heading or skill directive produces such a section. Consequence: the Mission 6 fixture is a viability proof of transport, mutation, and resume, and must not be promoted into the provenance pair. The close report must say so. + +**A4. The fenced-block workpiece source is a Mission 6 contract that Mission 7 will change.** Settled. The Mission 6 close report names the move from fenced `runbook-ir` blocks to an `update_workpiece` tool as a carried change so nobody treats latest-block selection as settled. Mission 6's implementation is not retrofitted mid-tie-off. + +## B. Terrain: what exists between conversation, workpiece, and net + +**B1. Flue history to workpiece revision: exists and is tested.** Inspected: `packages/core/src/workpiece.ts`. The resolver selects the tagged prepared signal or the latest assistant `runbook-ir` block, identified by source message id plus SHA-256. + +**B2. Flue history to capture store: exists as a stub that re-indexes user utterances.** Inspected: `apps/brunch-agent/src/capture/apply-sweep.ts`, `packages/core/src/evidence/capture-store.ts`, `session-log.ts`. One envelope per user entry, excerpt equals the whole utterance, payload `{}`; excerpts resolve to a pointer of session id plus entry ordinal by substring search over an archived copy of history; the store adds an owner key, dedup, and idempotent retry. Everything but the owner key duplicates what Flue history already carries, under a second identity scheme. The store is a JSON file beside the sqlite database (`db-path.ts`). + +**B3. Capture store to workpiece: does not exist.** Inspected: the workpiece template asks for "exact expert wording" as prose beside each claim and never names capture ids, message ids, or ordinals; Markdown has no passage identity. Settled: this is the central unresolved design tension, and it has been deferred as "later" without being stated in the spine. + +**B4. Workpiece to net: one prose sentence in the fixture; no derivation record anywhere.** Inspected: fixture and template as in A3. Settled: a hand-authored derivation fixture, as the Mission 7 draft proposes, is useless and rejected. + +**B5. Workpiece visibility: the workpiece is a black box during a conversation.** Inspected: the `runbook-ir` block streams as a fenced code block inside the assistant message; the only current view is the Mission 6 fixture banner's collapsed `
` element (`prepared-fixture-banner.tsx`). No pane, revision list, or diff exists. + +**B6. Retained persona runs contain no revision series.** Inspected: every run under `docs/evidence/evaluations/` has at most one `runbook-ir` block; `vestera-runbook-headless` emits once at the end; Mission 4 v2 runs stopped before substance. Consequence: the model's revision cadence is unmeasured. + +**B7. Petrinaut elements have no metadata slot; the file wrapper has only `title` and `meta.generator`.** Inspected: `petrinaut-core/src/schemas/entity-schemas.ts` (strict objects), `file-format/types.ts`. + +**B8. Flue offers four typed ways to put something in the canonical log.** Inspected: `@flue/runtime` and `@flue/sdk` 2.0.3 `.d.mts`. Tool call records (input, output, call id; surfaced as tool parts on the assistant message with `turnId` and `submissionId`); `useDataWriter` data parts on the current response; `usePersistentState` `state_write` records, atomic with the tool batch, server-side only, not in `history()`; and signals via external `dispatch()` or `ctx.append` in finish hooks, surfaced as system-role messages with `tagName` and string attributes. There is no arbitrary custom entry and no tool-context `append`. + +**B9. The construction tool schema carrier is still the one Mission 3 falsified.** Inspected: `plugin-sdcpn/src/tools/petrinaut-construction.ts` declares input as `v.looseObject({})` with a `rawTransform` that re-parses against Petrinaut's Zod schema, and pastes the canonical JSON Schema into the description text. Flue accepts Valibot only (`ToolInputSchema = v.GenericSchema`), converts via `@valibot/to-json-schema`, and rejects other Standard Schema vendors by checking `~standard.vendor === "valibot"`. The provider therefore sees an object with no fields. Flat `addArc` can survive on the description; nested `addType.elements` failed nine of nine in Mission 3. The spine already recorded "Flue Standard Schema support or a mechanical shape-preserving conversion" as the accepted next move; neither has been done. + +**B10. Mounted tools today.** Inspected: `chat-agent/agent.ts`, `plugin-sdcpn/src/flue.ts`, `core/src/flue.ts`, `core/src/client-tools.ts`, website `local-storage-demo/`, persona `client-tool-hosts.ts`. Server: `ping`, Flue's `activate_skill`, `readPetrinautDoc` (browser-deferred, all SDCPN conversations), six construction tools (headless mode only), two fixture tools (Mission 6 mode only). Core owns no model-facing tool by stated rule. Client: the Petrinaut panel client-tool host; an `ask` interactive tool and `sweep` result handling that no mounted server tool ever produces; the Voice bridge, which is a transport rather than a tool; persona hosts `none`, `mock`, `real-headless`. The stock Petrinaut assistant exposes about fifty canonical tools. + +## C. Design decisions + +**C1. Provenance is recovered from lineage in the canonical log, not stored in a typed IR, a capture store, or a hand-authored derivation.** Settled in principle. Rationale: the typed comprehensive IR chased a receding horizon and degraded model performance; the structural swing left no seam; both treated provenance as a property of the domain model when it is a property of who changed what, in response to what, when. Every such moment is already recorded in Flue history once workpiece revisions and net mutations are tool calls. + +**C2. The honest shape of a why answer is one creating call, one workpiece passage, one introducing revision, then either a quoted line or a short turn range.** Settled. The owner's correction: tool calls do not occur every turn and workpiece revisions do not occur every turn, so ranges enter at exactly one hop, the last. The verbatim quote check narrows a range to a line where the model quoted the expert. Elements changed several times show introducing and last-changing calls separately. + +**C3. The why tool returns structured ranges; the assistant interprets.** Settled. The user asking "why" implies an assistant interpretation anyway, so the tool never authors prose and never invents a link. It must accept multiple element ids and return potentially several ranges per element. + +**C4. Workpiece updates are tool calls, not fenced blocks in assistant text.** Settled. Tool: `update_workpiece`, input one Markdown string, `durable: true`, validates and hashes, writes the current-revision pointer with `usePersistentState` inside the same tool batch, returns revision and hash. Core owns the tool; plugins own the template. Rationale: structural revision identity (call id), write-time validation, agent access to its own current revision without model echo, lineage shared with mutation calls through `turnId`, and a clean UI split. Caveats recorded: token cost is unchanged and a structured-patch input is the later absorber; a model may call a tool less readily than it emits text, so cadence must be measured either way. + +**C5. The generic lookup is a core `query_workpiece` tool; the element lookup is plugin-owned.** Settled for the split, name provisional. Core knows revisions and history, not Petri nets; it takes a revision pointer or passage locator and returns turn ranges with user text. Plugin-sdcpn owns a `locate_elements`-style lookup because only it knows which calls are mutations and where ids sit in inputs. + +**C6. Net revisions join to workpiece revisions through the client-tool result, not through Petrinaut metadata.** Recommended. The browser returns the post-mutation document hash inside the client-tool result (Mission 6 already computes it for the settled manifest). A document hash no tool result explains is honestly "changed outside the conversation." A file-level pointer in Petrinaut `meta` is deferred until Mission 11 has a real consumer for a self-describing export. + +**C7. The workpiece becomes a visible, revisioned document in its own pane.** Settled. Chat projects `update_workpiece` parts out of assistant messages, leaving a one-line marker; the pane shows current revision, revision list, and diff, driven from Flue history through the Mission 5 transport. Rationale: the chat pane is too small for artifacts; a why answer resolves to a passage the reviewer must be able to see; per-turn emission for the pane is the same behaviour that gives blame its grain. Projection lives in the app or transport layer, not the Petrinaut library. + +**C8. The capture store and sweep earn no place in Mission 7.** Recommended. Flue history already carries message ids and exact text. Owner-key enforcement on evidence reads can be a check at answer time. The store re-enters only if verification strains under compaction or ownership. + +**C9. The `ask` and `sweep` client handling is retired from code.** Settled. Surfaces: the two names in core `client-tools.ts` and the suspended ask contract behind them; the website's ask interactive tool and its test; the sweep filter in the panel transport and the sweep output module; the Voice references in `canonical-speech.ts` and `interview-coverage.ts`. Archived mission records remain the design reference. Vehicle: a subtraction commit under Mission 7 authority. + +**C10. Petrinaut mutation tools are wired into ordinary conversation now, and admission is by evidence rather than by an inherited six-tool subset.** Settled as policy. The owner's judgement: continuing to defer tool wiring is a strategic mistake; the six were an unexamined side-quest set; the skill teaches concepts but not tool use. Terrain supports it: the subset lacks every `update*` and `remove*`, `getNetCompilationErrors`, `addScenario`, `applyAutoLayout`, metrics, subnets, and differential equations. Parity with the stock modeller is still not the goal. Mission 6's live constraint that construction tools stay out of ordinary conversations must be amended at the Mission 7 cut, not in the Mission 6 tie-off. + +**C11. The schema carrier must be fixed before tools are admitted.** Recommended as the first act of the next cut. Options: a mechanical JSON Schema to Valibot interpreter for the subset Petrinaut uses (local, reversible, satisfies "mechanically derived"), or upstream Flue Standard Schema support. Petrinaut's canonical tool descriptions were written for the stock assistant and become useful field-level guidance once the carrier carries fields. + +**C12. The skill must add construction posture, not just concepts.** Settled in principle. Read the definition first, mutate in small steps, check compilation errors, record each decision in Construction notes, call `update_workpiece` before and after construction. + +**C13. Mission 7's release note narrows to the honest framing.** Settled. "Ask why about any element and see the workpiece passage, who prepared it, and the exact conversation line it rests on, or an explicit refusal." Rejected: inventing a longer conversation to make "what the expert actually said" true for prepared elements. + +**C14. Mission 7 names local deployment posture; remote durability returns to Mission 8.** Settled. The owner reports the Postgres persistence move is slow and unresolved for local versus remote; it will not exist for Mission 7, so the sequence lines up with the original numbering. + +**C15. The workpiece passage-identity question is decided by probe, not in a draft.** Recommended. Candidates: heading path (readable, breaks on rename), Markdown anchors (stable, changes the surface), companion manifest (clean Markdown, second-artifact drift). Probe: prepare references for the elements of one real pair, revise one non-semantic line, observe which scheme survives. + +## D. Real honest fixtures through persona interviews + +**D1. Real conversations and real workpieces replace prepared fixtures as the provenance pair.** Settled. The Mission 6 fixture stays a viability proof. Multiple persona runs can proceed in parallel; six cases already exist under `evaluations/cases/`. + +**D2. Persistence during a run is the Flue store; retention is the harness's per-run evidence directory.** Observation. The harness's `--brunch-evidence-dir` already refreshes a canonical `snapshot.json` plus deterministic projections on every settled read. With `update_workpiece`, revisions become tool parts in that snapshot and the harness's workpiece recovery must read tool parts instead of fenced blocks. + +**D3. How a retained real conversation becomes a live fixture is the first fog item of the persona programme.** Open. Options: keep the genuine conversation live in a durable store shipped with the demo; restore retained genuine records into a fresh store through Flue's storage adapter (records are genuine, only relocated, but the adapter's record types are private and the routing doc warns against consuming them); or replay the materialized snapshot as prepared signals, which turns genuine history into a prepared projection and would make the why route fixture-only. Probe: whether Flue 2.0.3 exposes or tolerates a conversation export and restore at the storage boundary. + +**D4. Stop rule: a turn cap as budget plus a Brunch-side completion signal; ledger coverage grades afterwards.** Recommended. Today the turn budget lives only in the launch prompt and the persona is told never to end the interview. Proposed: cap per run (larger than the 6–10 used so far, cost accepted), stop early when Brunch itself declares construction handoff or delivery in its status section, and grade coverage against the hidden oracle ledger after the run rather than using it to stop. + +**D5. Runs go to construction, because the fixture must contain lineage.** Recommended. Sequencing follows: carrier fix and tool admission and `update_workpiece` land before construction runs. An elicitation-only campaign can run earlier to measure revision cadence. + +## E. Consequences for the planning record + +**E1.** State the provenance tension in the spine as an open design decision with C1 as the current hypothesis, the typed IR and hand-authored derivation as rejected with reasons, revision cadence as the named strain, and the visible workpiece as the precondition. + +**E2.** Re-cut the Mission 7 draft: drop the capture-store chain and Mission 2 inherited closure; make the carrier fix, orphan retirement, `update_workpiece`, the workpiece pane, tool admission and teaching, and the persona programme the mission's body; make the why route the last step over real lineage; name local posture. + +**E3.** Adjust the Mission 9 and 10 drafts: they inherit the seam from lineage (revision id equals call id, passage identity per C15, element id, document hash per C6) and no longer assume a derivation fixture or prebuilt pair. + +**E4.** Mission 6 close report: record A3 and A4 plainly, plus the credential cause in A1. + +**E5.** Decision-integrity: every Settled item here is an owner decision expressed in conversation. It becomes authority only when written into the cut `MISSION.md` for Mission 7; this log and the mini spec are neither authority nor a substitute for it. + +## F. Dispositions after the independent review (same day) + +The [independent review](provenance-by-lineage-independent-review-2026-09-04.md) was read in full and its terrain claims re-checked before these dispositions. Review item numbers are cited as R1 to R24. Entries here supersede the C, D, and E entries they name; the earlier entries stay as history. + +**F1. R11 confirmed from the Mission 6 r2 witness: the turn topology in C4 and the mini spec was wrong.** Inspected: `fe-1575-outer-browser-witness-2026-09-04-r2/flue-snapshot-tab-b.json`. User messages carry a submission id and no turn id; the mutation request sits in one assistant turn; the browser result arrives as a separate `client-tool-result` system dispatch under a new submission; the continuation is a new turn; cumulative result signals repeat earlier call ids (one call id appears three times). Consequence: correlation is by tool call id plus submission order, never by a shared `turnId`, and the lineage reader deduplicates results by call id. + +**F2. R13 confirmed from Flue's hook rules: hooks throw outside render, setters throw during render.** Inspected: `@flue/runtime/docs/reference/agent-hooks-api.md`, "Rendering and the rules of hooks"; `ToolContext` carries `toolCallId`. Consequence: `update_workpiece` captures the `usePersistentState` setter at render and calls it from `run`; revision numbering uses the updater form. + +**F3. R12, R14, R15 accepted.** The document hash in client-tool results is proposed work, not current behaviour; the Petrinaut wrapper carries version, the document arrays, title, and optional generator metadata, with no element-level or file-level provenance slot; `durable: true` protects only the server tool attempt, never the browser side effect. + +**F4. R7 is plausible and unverified by either party; it is the first probe.** Flue folds older history into a summary for the model, keeping 8000 recent tokens verbatim by default. Whether the public `history()` projection also drops folded messages is not stated in the installed docs; the database guide says reconnecting clients rebuild from the full stream. Probe: set `keepRecentTokens` low, run past threshold, read `history()`, and check whether old `update_workpiece` inputs, mutation parts, and user lines survive. C8's re-entry condition for independent retention is this probe's negative result. + +**F5. R1 to R3 accepted; the claim narrows and gains a declared basis.** Settled by the owner. "Latest revision before the mutation" is temporal adjacency and selects no passage. The constructor declares its basis when it constructs: one or more passage locators plus a one-line rationale carried with each mutation request. This is the actor who knows, at the moment they know; it types nothing about the domain and is not a retrospective hand-authored derivation. Where the basis is absent the answer degrades to the temporal range and says so. Workpiece author, evidence actor, requesting principal, and mutation actor are reported separately; a Flue `user` role is not actor identity. Supersedes the "nothing is inferred" wording in C1 to C3 and narrows C13 further. + +**F6. R2 accepted: passage identity is a prerequisite.** The C15 probe must cover rename, move, paraphrase, split, merge, deletion, and reintroduction. If no scheme survives, the first claim is revision-local text with no cross-revision "introduced by." + +**F7. R4 to R6 accepted: a mutation transition record replaces the hash-only join.** Per call: document identity, expected base hash, outcome (applied, no-op, failed, stale, unknown), confirmed post hash, affected element ids or retained pre and post definitions, one authoritative result per call with a duplicate rule. A transition no record explains is "not attributable from recorded transitions," and provenance for the affected state is refused until an explicit external revision is imported. Supersedes C6. + +**F8. R5 accepted: workpiece update and browser mutation are separate boundaries.** An operation protocol with requested, outcome, and reconciled or incomplete or unknown states replaces any implied shared batch. Retry identity, duplicate delivery, stale-base refusal, and lost-result behaviour are part of that protocol. + +**F9. R8 accepted: executable boundary for lookups.** Core owns formalism-independent revision and query semantics; plugin-sdcpn owns mutation names, inputs, outputs, and effects; binding and app own authorized acquisition of Flue history (the in-process fetch pattern the capture sweep already uses) and compose the model-facing tool. One or two model-facing tools follows interaction quality, not package seams. Supersedes the executable reading of C5. + +**F10. R9 accepted: persistent state holds the current Markdown, not only a pointer.** State is reduced from the record stream at render, independent of the model's context, so the current workpiece is always available to the agent regardless of compaction. Core validates non-empty and size; template conformance is plugin participation. Revision history still depends on F4. + +**F11. R10 accepted as a named limit.** Mission 7 states a single-principal local authorization limit and treats retrieved conversation text as untrusted evidence returned in the smallest range needed; the broader contract is deferred with that owner. + +**F12. R16 and R17: consolidate.** Settled by the owner. Construction and explanation ship in one mission; the following mission takes projection breadth, repeat and changed-input behaviour, and readiness closure. The owner's stated reason: resist the regression to thin tracers; build fully connected parts and real test beds rather than partial coverage with caveats. The reviewer's minimal adversarial tracer is the first act inside that mission: one genuine conversation, two distinguishable passages, two mutations, one no-op or failed mutation, one correction, one hand edit; deterministic answers or explicit refusals before breadth. Supersedes E2 and E3. + +**F13. R19: scenario-derived subset, enumerated now.** Settled by the owner with the condition that it must not become a deferral. The subset is derived mechanically from Petrinaut's AI tool bundle by the document entity classes the six persona cases exercise, surveyed on 2026-09-04 across `evaluations/cases/*` and `evaluations/oracles/*`: every case needs places, transitions, arcs, and scenarios (initial state); most name colours or token attributes and stochastic timing; industrial gas names parameters; vestera names metrics; data-centre thermal and pharma cold chain name temperature dynamics, so differential equations; only vestera mentions hierarchy, so subnets and component instances are excluded until a case needs them. Initial subset: add, update, and remove for places, transitions, arcs (including weight and type), types and type elements, parameters, scenarios, metrics, and differential equations; plus `getLatestNetDefinition`, `getNetCompilationErrors`, `applyAutoLayout`, and `setNetTitle`. Position updates are excluded because layout covers them. Expansion is by observed need with the case named. The six-tool and two-tool subsets are retired as product surfaces once Mission 6 archives. Supersedes C10. + +**F14. R18 accepted: fixture materialization before any paid campaign.** Export or retain, relocate, reopen, authorize, and query one tiny genuine conversation first, and record whether the product fixture is a retained live store, a supported relocation of genuine records, or an honestly labelled prepared projection. + +**F15. R20 to R24 accepted as additions.** Freeze the element inventory and consequential rule before grading; write the migration matrix (old history with new code, new history with old code, mixed revisions, mixed browser and server versions, Mission 6 fixture mode, retained evidence, tool manifest) with an explicit removal gate for any dual-read bridge; resolve deployment ordering explicitly rather than weakening "deployed"; do lightweight consumer discovery with Chris and Yannis before choosing the construction region; require one executable behavioural discriminator derived from the workpiece alongside human semantic review. + +**F16. Next sequence, merged.** (1) Adjudicate the claim as F5. (2) Paper adversarial tracer per F12. (3) Probes: compaction on `history()` (F4), export and reopen (F14), passage identity under semantic edits (F6), carrier repair for one real nested mutation from the F13 subset. (4) Correct the Flue topology model (F1) and define the transition record (F7) and operation protocol (F8). (5) Re-cut the mission topology from observed results (F12). (6) Then the persona construction campaign with frozen inventory and behavioural oracle (F15). + +## G. Dispositions after the follow-up review (same day) + +The [follow-up review](provenance-by-lineage-follow-up-review-2026-09-04.md) items are cited as S1 to S23. Its two Flue contradictions were re-verified against the installed 2.0.3 reference before disposition. Entries here supersede the F entries they name. + +**G1. S1 confirmed: a mixed tool batch does not reliably hand off to the browser.** Inspected: `@flue/runtime/docs/reference/agent-api.md`, `run` contract: "a multi-tool batch ends the turn only when every result in it terminates." The construction tools terminate; a non-terminating `update_workpiece` beside them would keep the turn alive. Consequence: `update_workpiece` and a Petrinaut mutation never share a batch. The revision protocol is: `update_workpiece` settles → the next render exposes the revision id and hash → the mutation request names that revision explicitly → the browser executes. Supersedes the sibling-call diagram in F1 and the spec. + +**G2. S2 accepted: "revision current at the request" is defined only by explicit citation.** A mutation request carries `revisionId` and `sha256` of an already-settled revision. "Latest" and sibling order are not admissible. The tool refuses a request citing an unknown or superseded revision unless the request marks the supersession as intended. + +**G3. S3 accepted: passage to evidence stays temporal unless a revision-time relation is declared.** The hop from a passage to conversation turns is labelled **conversation context temporally associated with the revision**, never "support" or "evidence for," unless `update_workpiece` carries an optional revision-time evidence relation. Decision for the cut: admit the least such relation as an optional field on `update_workpiece`, `evidence: [{ locator, messageIds[], kind }]` where kind is one of elicited, inference, default, formalism-constraint, external, correction, and where a passage carried forward unchanged inherits its prior relation. The adversarial tracer includes a carried-forward passage, non-adjacent evidence, a correction, and multi-source synthesis. Supersedes the unqualified range hop in F5. + +**G4. S4 accepted: a why query reconciles against the live document or labels its staleness.** Every why answer either acquires the current document identity and hash from the browser through the existing client-tool path before answering, or states "as of the last reconciled recorded state" with the hash it last saw. A hand edit after the last recorded transition therefore either surfaces as "not attributable" or is disclosed as unreconciled. + +**G5. S5 accepted: Mission 7 binds one conversation to one document incarnation.** The binding is recorded at fixture creation, checked on every mutation request and why query, and refused on mismatch. Cross-conversation and multi-conversation document access, and a document-scoped durable owner for shared lineage, are carried to the breadth mission with this as their re-entry gate. Inspected: `flue-routing.md` distinguishes per-conversation `usePersistentState` from cross-conversation target-document state. + +**G6. S6 and S7 accepted: actor and time claims narrow to what records carry.** Recorded roles only: "assistant tool call," "local browser executor," "prepared-fixture author (test-authored)," "user message under principal key." Human identity is reported as unknown. "When" means canonical stream order, not wall-clock time, unless a trusted timestamp is added to retained records. Inspected: `apps/brunch-agent/src/conversation/identity.ts` and `src/http/ownership.ts` carry a principal key and conversation id only. Supersedes the actor list in F5. + +**G7. S8 and S9 accepted: basis is typed, settled, and operation-level unless mapped.** Basis on a mutation request is `declared { revisionId, sha256, locators[], rationale, scope }` or `absent { reason }`. The cited revision must have settled. Construction notes are not a substitute for an absent basis. The answer labels the relation **constructor-declared**. The output distinguishes elicited evidence, constructor inference, default, formalism constraint, external source, and construction rationale. Request-level basis is **operation-level**; an actual effect without a specific intended-effect mapping is basis-absent or unanticipated and does not inherit the request's locators. Basis quality is graded for relevance, contradiction, granularity, and omitted dependencies, not presence alone. + +**G8. S10 accepted: four query semantics.** Origin (basis for the identity epoch's creation), current state (applied transitions composing the present definition), change history (all applied changes and corrections), attempt history (failed, no-op, stale, unknown requests, never causes). Element ids are never reused across identity epochs; delete and recreate opens a new epoch. + +**G9. S11 accepted: the transition record is independently verifiable.** Per call: requested base hash; independently observed pre-apply hash; canonical post-apply observation when available; mechanically derived, disjoint `created`, `updated`, `deleted`, `derived` sets; verification that those effects account for the canonical document diff; conflicting duplicate outcomes resolve to `unknown`, never winner-by-arrival; failed, no-op, stale, and unknown calls contribute only attempt history. Supersedes the "ids or definitions" alternative in F7. + +**G10. S12 accepted: external import does not launder.** An external revision records actor or unknown actor, principal, observed parent hash, canonical diff, and import reason. Every imported changed element or field keeps an `external/unsupported` disposition until a later recorded transition replaces it. Import resets continuity; it explains nothing retrospectively. + +**G11. S13 accepted: passage identity is policy first, probe second.** Predeclared invariants: passage ids are never reused after deletion; split and merge record predecessor and successor sets; ambiguous paraphrase refuses continuity; reintroduction starts a new identity unless continuity is declared; a locator resolves to an immutable revision-local span; duplicate headings and quotations are tested; an overbroad span fails basis quality when a materially narrower sufficient span exists. The F6 probe then tests ergonomics and model compliance against this policy. If the policy is too expensive, revision-local text with refused cross-revision claims remains the fallback. + +**G12. S14 accepted: fixture representativeness and on-path acceptance.** Sources are labelled synthetic-persona, internal-human, or customer-derived. Acceptance assertions run through the reopened authorized why operation the product uses; `snapshot.json` and projections are diagnostics only. At least one adversarial fixture includes duplicate wording, rejected quotations, constructor inference, a correction, and unrelated context. + +**G13. S15 accepted: the consequential rule is frozen before the run.** The inventory is generated mechanically from the final canonical document, includes every identity-bearing or behaviour-affecting entity or field the selected claim requires (parameters, scenarios, type elements, arc attributes, expressions, document-level settings, derived entities, identity epochs), receives exactly one disposition per item, and publishes numerator, denominator, and exclusions. + +**G14. S16 accepted: separate safety and utility gates.** Safety: no false attribution and correct required refusals. Utility: a predeclared nonzero proportion of consequential elements yields usable current-state answers, with minimum coverage across the selected entity classes, judged by a blinded reviewer task with a fixed rubric: identify the governing passage, distinguish elicited evidence from constructor inference, understand the current definition and latest correction, and decide whether the answer changes the review judgement. + +**G15. S17 accepted: "scenario-selected operations with canonically derived schemas."** Admission is interpretive; schemas are mechanical. Corrections to F13: "move element" is removed; metrics are conditional, admitted only when the proving scenario names a measurable objective that Petrinaut's `Metric` entity can express, because the Vestera case names scheduling objectives and prohibits invented weights but does not entail executable metrics. Each admitted class cites the case requirement it discharges. Breadth follows the selected proving scenario, not all six cases. + +**G16. S18 accepted: the consolidated mission closes the readiness of its own claim.** Mission 7's contract stratum is named and its identity, failure, durability, basis-quality, current-state, and oracle obligations close inside it. Only breadth first made load-bearing by the following visible advance (repeat, changed input, deletion and retirement, concurrent change, cross-conversation document access, broader schema classes) moves to Mission 9. Supersedes the readiness split wording in F12. The workpiece pane is an internal enabling surface inside Mission 7, not a second release claim. + +**G17. S19 accepted: every probe carries a decision table.** Pass continues under the named claim; partial narrows the claim or changes the mechanism; fail stops the cut or splits predecessor work; re-entry names the evidence to reopen the rejected route. The tables live in the Mission 7 draft. + +**G18. S20 decided: probes run under an initially narrow Mission 7 authority with an owner gate before amendment into construction breadth.** Rejected: a side quest under Mission 6 (Mission 6 is closing and the probes are not residual Mission 6 failures) and a separate probe mission (ceremony without a visible advance). The narrow first authority names the adversarial tracer and the four probes as its throughline; the owner gate is the readiness decision that admits the construction and explanation body. + +**G19. S21 accepted: a planning-content migration matrix accompanies the spine recut.** Every old hypothesis, accepted decision, rejected alternative, oracle gap, deferred item, and readiness obligation maps to exactly one surviving destination; the matrix lives in `MISSION.next.md`. + +**G20. S22 accepted: archive lane distinguished from capture semantics.** Three things are kept apart: capture envelopes and sweep semantics (rejected for Mission 7 provenance); the existing session-log archive in `binding-flue/src/history-reader.ts` and the capture storage contract's archive slot (an existing lane that may be hardened if the compaction probe is negative); and any new immutable lineage projection actually required by compaction, relocation, or authorization. Supersedes the F4 re-entry wording. + +**G21. S23 accepted: Mission 11's readiness is three distinct gates.** Consumer contract acceptance; a working handoff throughline; post-throughline readiness closure sufficient to begin the experiment without reconstruction. Artifact receipt is not an executable witnessed experiment start. + +**G22. Next sequence, merged and final for this replanning.** (1) Recut the planning record with the migration matrix (G19). (2) Cut a narrow Mission 7 authority whose throughline is the adversarial tracer and the four probes with decision tables (G17, G18). (3) On pass, owner gate amends the authority to the construction and explanation body with its own readiness closure (G16). (4) Mission 9 takes breadth; Mission 10 inherits basis, transition records, and passage policy; Mission 11 gains early consumer discovery and three-gate readiness (G21). + +## H. Dispositions after the readiness review of the recut (same day) + +A third review evaluated the recut planning record in the Mission 6 worktree and returned "no-go for cutting today, but close," with blockers in predecessor closure, cut-time owner decisions, authority lifecycle, and oracle precision rather than architecture. The owner accepted it with one standing qualification, recorded here as **H0**: this feedback may make Mission 7 more rigorous, never narrower or less ambitious. Where a probe outcome would once have been described as "narrowing the claim," the recorded branch is a rework path that preserves the consolidated construction-and-explanation shape; a terminal stop is reserved for outcomes that contradict that shape rather than merely delay it. Review items are cited as T1 to T5 (blockers) and U1 to U8 (corrections). + +**H1. T1: Mission 7 stacks on the final Mission 6 close commit.** Mission 6 was, at the time of the review, live with the cold-reader gate accepted and the product-manager demo unrecorded; the owner reports it is now almost closed with a few bugs being resolved in the same worktree. The Mission 7 branch is created from the accepted Mission 6 close commit, not from a pre-close head. The draft's cold-start reads say so. + +**H2. T2: cut-time owner decisions are enumerated as a pre-cut checklist, not left as fog.** Proving scenario; scenario-required Petrinaut operation classes with the case requirement each discharges; the consequential-element rule; the behavioural discriminator; the utility coverage threshold with per-class expectations; acceptance of the one-conversation-one-document-incarnation binding for Mission 7; provider model, maximum calls, and spend ceiling; the FE-1573 re-title (done on 2026-09-04) and description. The Chris and Yannis discovery prerequisite is either performed or explicitly dispositioned by the owner before the cut; it is not silently dropped and not silently blocking. + +**H3. T3: the two-step authority has a lawful document shape.** Decided: the initial `MISSION.md` authorizes Step A only and carries Step B nowhere as authority. At the cut, this draft is split rather than consumed whole: the Step A sections convert into the live contract, and the Step B sections remain in this file, retitled as the Step B amendment packet, with the non-authority warning, an explicit statement that Step A's content has been consumed and lives only in `MISSION.md`, and a no-loss comparison recorded in the spine's migration ledger. After the owner gate, the amendment converts the packet and removes the file. Rejected: carrying Step B inside the live Proof (would read as authorized) and carrying it only as Deferred prose (would lose its contract detail). + +**H4. T4: every Step A leaf names an exact prospective oracle.** The tests need not exist at the cut, but each leaf names a file path, a test name, a command, a frozen fixture, an evidence artifact path, or a named human adjudication. The draft's candidate-evidence table is rewritten to that standard, with prospective paths under `packages/*/test/`, `apps/*/test/`, and `docs/evidence/implementations/fe-1573-step-a//`. + +**H5. T5: Step A outcomes are classified, and "every probe produced a result" is not a pass.** Each probe and measurement outcome is classified as **eligible for Step B amendment**, **eligible after named rework**, or **terminal stop for this mission shape**. Under H0, rework branches keep the consolidated shape (for example: carrier fails locally → pursue the upstream Flue requirement while construction proceeds on carried classes; materialization fails → the demo runs on a retained live store while relocation is pursued; basis is sparse → skill and pane interaction are revised and the tracer rerun). Terminal stops are: no route to a genuine reopened conversation at all, effects that cannot be mechanically derived, or a basis that remains circular or absent after the rework round. The owner gate chooses only among explicitly allowed branches. + +**H6. U1: revision identity is fixed.** `revisionId` is the `update_workpiece` call's `ToolContext.toolCallId`; `sha256` is content identity; the ordinal `revision` is display metadata and never an identity. Supersedes looser wording in C4, F2, and the spec. + +**H7. U2: transition-record wording is made consistent.** `postHash` is optional and present only when a post-apply observation exists; an `unknown` outcome may lack it. "One authoritative result per call" means: the first well-formed outcome is authoritative unless a later delivery conflicts with it, in which case the record's outcome becomes `unknown` and both deliveries are retained as attempt history. Supersedes G9's phrasing. + +**H8. U3: an `elicited` evidence relation validates its message ids.** The referenced ids must resolve to authorized true-user messages in the same conversation (role `user`, purpose `user`, under the bound principal), reusing the existing non-user-evidence refusal in the session-log evidence resolver as the model. Ids that resolve to signals, assistant text, or prepared material are refused, not silently accepted. + +**H9. U4: the SHA-256 enrichment lives in the app today.** Inspected: `packages/core/src/workpiece.ts` selects source message and content with no hashing; `apps/brunch-agent/src/conversation/workpiece.ts` computes the SHA-256. Both are cited; the hashing moves into core with `update_workpiece`. + +**H10. U5: the `ask` and `sweep` disposition is an inventory, not a deletion.** Inspected: the names and types are still imported by `binding-flue/src/history-reader.ts` and `index.ts`, `core/src/evidence/capture-store.ts` and `index.ts`, `apps/brunch-agent/src/capture/apply-sweep.ts`, and in the website by `brunch-sweep-output.ts`, `brunch-client-tools.ts`, `brunch-ask-mapping.ts`, `brunch-ask-interactive-tool.tsx`, `brunch-panel-transport.ts`, and the Voice `canonical-speech` and `interview-coverage` modules and tests. The draft carries a keep/remove/archive inventory covering these and `ping`, `activate_skill`, and `readPetrinautDoc`; the compaction probe's branch decides whether the archive lane's sweep types survive. + +**H11. U6 to U8: verification filters, docs paths, and the Mission 8 read.** Add `@hashintel/brunch-agent-binding-flue` to the Turbo filters; cite `node_modules/@flue/runtime/docs/guide/models.md` for compaction and `docs/reference/` for the tool and hook contracts; keep the explicit `git show` instruction for the Mission 8 commit. + +**H12. Unresolved by design, and correctly so.** Compaction survival, relocation, passage scheme, carrier route, cadence, basis quality, one versus two why tools, and token cost remain Step A fog with exact oracles and classified consequences. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/design/provenance-by-lineage-follow-up-review-2026-09-04.md b/libs/@hashintel/brunch-agent/docs/evidence/design/provenance-by-lineage-follow-up-review-2026-09-04.md new file mode 100644 index 00000000000..6a7bab42d77 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/design/provenance-by-lineage-follow-up-review-2026-09-04.md @@ -0,0 +1,344 @@ +# Follow-up review of provenance-by-lineage replanning — 2026-09-04 + +> Review evidence, not execution authority. This document evaluates the revised [`provenance-and-tooling-decision-log-2026-09-04.md`](provenance-and-tooling-decision-log-2026-09-04.md) and [`provenance-by-lineage-mini-spec-2026-09-04.md`](provenance-by-lineage-mini-spec-2026-09-04.md) after dispositions F1–F16. It focuses on gaps that remain after the first [`independent review`](provenance-by-lineage-independent-review-2026-09-04.md), using checked-out code, installed Flue 2.0.3 documentation, the canonical future-planning record, and three additional adversarial reviews. It changes no owner-settled policy and authorizes no implementation. + +## Executive verdict + +The revised design is materially stronger. First-class workpiece revisions, constructor-declared mutation basis, canonical mutation transition records, explicit refusal under incomplete lineage, schema-carrier repair before construction breadth, and a genuine production-path fixture are sound directions. The revision correctly stopped treating temporal adjacency alone as causal provenance. + +The design is not ready to become Mission 7 authority. Two concrete Flue contradictions make the depicted update-and-mutate path unreliable, and several remaining semantic gaps permit complete-looking lineage to overstate what the records establish. Strategically, the consolidated mission cannot defer readiness closure for its own visible claim, and the required probes currently have neither result-conditioned stop branches nor an unambiguous execution-authority home. + +The most important correction is to treat the design as four distinct contracts: + +1. **Revision protocol:** a workpiece revision settles and becomes addressable before a mutation can cite it. +2. **Provenance semantics:** mutation basis, passage evidence, element origin, current-state history, and actor identity are distinct relations. +3. **Document reconciliation:** the current live Petrinaut state is compared with recorded transitions before provenance is reported. +4. **Mission readiness:** M7 closes the safety and utility obligations required by its own construction-and-explanation claim; only breadth first made load-bearing by the following visible advance moves later. + +## Critical factual and semantic gaps + +### 1. The depicted mixed tool batch will not reliably produce the browser handoff + +The mini spec depicts `update_workpiece` and a Petrinaut mutation as sibling calls in one assistant turn, followed by a separate `client-tool-result` submission: + +```text +assistant turn T1 + ├─ update_workpiece {markdown} + └─ addArc {…, basis} +submission S2 + system dispatch client-tool-result +``` + +The current Petrinaut client tools return `{ awaiting: "client" }` with `terminate: true` in [`packages/plugin-sdcpn/src/tools/petrinaut-construction.ts`](../../../packages/plugin-sdcpn/src/tools/petrinaut-construction.ts). The proposed `update_workpiece` specifies `durable: true` but does not specify termination. Flue 2.0.3 documents that a multi-tool batch ends the turn only when every result terminates. A non-terminating workpiece result alongside a terminating browser tool therefore does not guarantee the depicted handoff. + +**Required correction:** prohibit the mixed batch or define termination behavior that preserves the browser handoff. The safer contract is a completed workpiece update followed by mutation in a later render. + +### 2. “Revision current at the request” is undefined when update and mutation are sibling calls + +The mini spec says the mutation basis locates passages in “the workpiece revision current at the request,” while the topology makes the update and mutation siblings. Flue runs calls in one batch in parallel; persistent-state reads are render-time snapshots, writes do not cause a mid-run re-render, and the writes commit with the batch. Assistant-part order is therefore not a dependable state order. + +The mutation cannot reliably regard the sibling `update_workpiece` as current, and a model cannot name the new update call’s generated call ID before the call settles. + +**Required protocol:** + +```text +update_workpiece settles +→ next render exposes revisionId and sha256 +→ mutation request explicitly names that revisionId and sha256 +→ browser mutation executes +``` + +A mutation must cite an already-settled revision explicitly; “latest” or sibling order is insufficient. + +### 3. Declared basis repairs mutation → passage, but passage → evidence remains temporal + +F5 adds the missing mutation-to-passage declaration. The next hop still resolves a passage to “turns between it and the previous revision.” That range does not establish the evidence for a passage that: + +- survives unchanged from an older revision; +- synthesizes several non-adjacent ranges; +- reuses earlier evidence; +- incorporates a correction or qualification; +- records constructor inference, a default, an external source, or a formalism constraint. + +The design can honestly call this range **conversation context temporally associated with the revision**. It cannot call the range support for the passage without another relation. + +**Required decision:** either add the least revision-time passage-to-evidence relation, including multiple and inherited ranges, or consistently label this hop as temporal context rather than evidence or support. The adversarial tracer should include a carried-forward passage, non-adjacent evidence, a correction, and multi-source synthesis. + +### 4. Current-state provenance cannot be checked from history alone + +The adversarial tracer includes one hand edit, and the visible operation asks why an element in the current net exists. A transition history can establish the last reconciled recorded state, but a hand edit after the last recorded mutation leaves no Flue record. The server-side why resolver therefore cannot discover that the current element differs from its last attributable state unless it obtains a fresh observation from the browser. + +**Required decision:** every why query either: + +- acquires and reconciles the live document identity and hash before answering; or +- says explicitly that the answer is “as of the last reconciled recorded state.” + +Without this, a hand-edited element can receive stale but apparently authoritative provenance. + +### 5. Per-conversation workpiece state does not settle target-document ownership + +`usePersistentState` is per conversation. The current workpiece and mutation lineage concern a Petrinaut target document, which may be reopened, copied, reviewed from another conversation, or targeted by more than one conversation owned by the same principal. The design does not define the binding among conversation identity/incarnation, document identity/incarnation, and current workpiece revision. + +The repository’s [`Flue routing guidance`](../../reference/architecture/flue-routing.md) explicitly distinguishes per-conversation state from cross-conversation target-document state. + +**Required decision:** either constrain M7 to an immutable one-conversation ↔ one-document-incarnation binding or place shared current-workpiece and lineage indexes behind a document-scoped durable owner. A single-principal limit does not solve multiple conversations owned by that principal. + +### 6. “Who did what” has no implementable identity source + +The mini spec promises separate workpiece author, evidence actor, requesting principal, and mutation actor. The proposed records do not contain trusted values for those identities: + +- workpiece state contains call ID, hash, revision, and Markdown; +- the transition record contains document/hash/outcome/effects; +- the current client-result envelope contains call ID, tool name, and output; +- Flue message roles are not human identity, and agent-authored metadata is not authenticated identity. + +F11’s single-principal limitation narrows authorization but does not establish who spoke quoted material or which human or browser actor applied a mutation. + +**Required correction:** define the trusted source and persistence rule for each actor field, including restored fixtures, or narrow the release wording to recorded roles such as “assistant tool call” and “local browser executor,” with human identity explicitly unknown. + +### 7. “When” currently means stream order, not wall-clock time + +The intent defines lineage as who changed what, in response to what, when. The supported Flue snapshot and Brunch history projection provide canonical message order, message IDs, submission IDs, and optional turn IDs, but no authenticated operation timestamp. + +**Required correction:** say **in what canonical stream order** unless a trusted timestamp source is added to retained revision and transition records. + +## Provenance quality and Goodhart risks + +### 8. Declared basis can become circular provenance laundering + +The constructor authors both the workpiece and the basis relation. Under the current wording it may decide on a mutation, write a convenient Construction note, cite that note as the mutation’s basis, and present the cycle as provenance. A locator plus one-line rationale proves that the constructor asserted a relation; it does not prove relevance, compatibility, or evidentiary support. + +The escape saying a mutation without basis may be justified in Construction notes compounds the problem. + +**Minimum correction:** + +```text +basis = + | declared { revisionId, locators, rationale, scope } + | absent { reason } +``` + +Additionally: + +- the cited revision must already have settled; +- Construction notes are not a substitute for absent basis; +- the answer visibly labels the relation **constructor-declared**; +- the output distinguishes elicited evidence, constructor inference, default, formalism constraint, external source, and construction rationale; +- basis quality is graded for relevance, contradiction, granularity, and omitted dependencies, not only presence and readability. + +### 9. Request-level basis does not establish element-level basis + +One mutation can affect several explicit or derived elements, while the request carries one undifferentiated set of locators. Assigning every locator to every actual effect overstates provenance for batches, cascaded deletes, layout, generated entities, and unexpected side effects. + +**Required correction:** either carry an intended-effect-to-locator mapping or label the relation as **operation-level basis** only. An actual effect without a specific mapping is basis-absent or unanticipated; it does not inherit all request locators. + +### 10. Origin, current state, change history, and attempt history are conflated + +The resolver privileges the creating request, but after corrections the creation basis may explain an obsolete definition rather than the current element. Delete-and-recreate is more dangerous if an ID is reused. + +Define separate query semantics: + +- **origin:** basis for the identity epoch’s creation; +- **current state:** applied transitions whose effects compose the present definition; +- **change history:** all applied changes and corrections; +- **attempt history:** failed, no-op, stale, and unknown requests, never treated as causes. + +Element IDs must not be silently reused across identity epochs. + +### 11. The transition record permits unverifiable self-report + +The current proposal accepts affected element IDs **or** retained pre/post definitions. The first option lets the browser self-report a favorable affected set without enough evidence to prove that it accounts for the canonical document diff. An expected base hash can also merely echo the request rather than prove which base the browser observed. + +The outcome shape is internally strained as well: an `unknown` outcome cannot always have a confirmed post hash. + +**Safer minimum:** + +- requested base hash; +- independently observed pre-apply hash; +- canonical post-apply observation when available; +- mechanically derived, disjoint `created`, `updated`, `deleted`, and `derived` sets; +- verification that those effects account for the canonical document diff; +- conflicting duplicate outcomes resolve to `unknown`, never winner-by-arrival; +- failed, no-op, stale, and unknown calls contribute only attempt history. + +### 12. External import can wash away unexplained provenance + +The design permits provenance to resume after an explicit external revision is imported. A permissive import could make an unexplained current state the new clean baseline, erasing which elements or fields remain externally sourced. + +**Required correction:** an external revision records actor or unknown actor, principal, observed parent hash, canonical diff, and import reason. Every imported changed element or field retains an `external/unsupported` disposition until a later recorded transition replaces it. Import resets continuity; it does not explain imported content retrospectively. + +### 13. Passage identity is partly policy, not terrain discoverable by probe + +A probe can test whether a locator remains syntactically usable. It cannot decide whether a paraphrase preserves identity. Split, merge, deletion, and reintroduction require explicit lineage policy. An anchor can mechanically survive while denoting materially different meaning, and a whole-section locator can make every basis superficially stable. + +Predeclare the invariants: + +- passage IDs are never reused after deletion; +- split and merge record predecessor and successor sets; +- ambiguous paraphrase refuses continuity; +- reintroduction starts a new identity unless continuity is explicitly declared; +- a locator resolves to an immutable revision-local span; +- duplicate headings and quotations are tested; +- an overbroad span fails basis quality when a materially narrower sufficient span exists. + +If these semantics are too expensive, retain revision-local passage text and refuse cross-revision “introduced by” claims as F6 permits. + +### 14. A genuine fixture can still be unrepresentative or accepted off-path + +A synthetic persona can produce a genuine production-agent run with short, unique wording that makes provenance trivial. That proves the path, not performance on messy human conversation. Acceptance can also drift toward inspecting retained `snapshot.json` projections rather than exercising the reopened authorized product query. + +**Required correction:** + +- label sources as synthetic-persona, internal-human, or customer-derived; +- run acceptance assertions through the same reopened authorized why operation used by the product; +- treat snapshots and projections as diagnostics only; +- include duplicate wording, rejected quotations, constructor inference, correction, and unrelated context in at least one adversarial fixture. + +### 15. The consequential inventory can be gamed after generation + +Freezing the element inventory before grading still permits defining “consequential” after inspecting the generated artifact. Parameters, scenarios, type elements, arc attributes, expressions, document-level settings, derived entities, and deleted/recreated identity epochs can be excluded by a favorable rule. + +**Required correction:** freeze the consequential rule before the run, generate the inventory mechanically from the final canonical document, include every identity-bearing or behavior-affecting entity or field required by the selected claim, and assign exactly one disposition to every inventory item. Publish numerator, denominator, and exclusions. + +### 16. Refusal safety can satisfy the contract while destroying utility + +“Deterministic answer or explicit refusal” is a safety contract. An implementation that refuses every difficult query can satisfy the literal wording while providing no reviewer value. Basis absence has no threshold, and “judged by a human” has no fixed task or rubric. + +Separate two gates: + +1. **Safety:** no false attribution; required refusals are correct. +2. **Utility:** a predeclared nonzero proportion of consequential elements yields usable current-state answers, with minimum coverage across selected entity classes. + +Use a blinded reviewer task and a fixed rubric: can the reviewer identify the governing passage, distinguish elicited evidence from constructor inference, understand the current definition and latest correction, and decide whether the answer changes their review judgment? + +## Tool-admission factual gaps + +### 17. The subset is scenario-selected, not mechanically derived from scenario requirements + +Petrinaut schemas can be mechanically sourced from the canonical AI bundle. The choice of entity classes from natural-language cases is interpretive. The mini spec should say **scenario-selected operations with canonically derived schemas**, not that admission itself is mechanically generated. + +Two concrete discrepancies remain: + +- F13 lists add/update/remove for type elements, while the mini spec additionally admits “move element.” +- F13 says Vestera names metrics, but the Vestera case and oracle describe scheduling objectives and prohibit invented numerical objective weights; they do not clearly require Petrinaut executable `Metric` entities. A natural-language objective does not mechanically entail the formalism’s metric class. + +Remove unearned classes or cite the exact case requirement and Petrinaut operation each class discharges. Tool breadth should follow the selected mission scenario and observed need, even if the later persona programme spans six cases. + +## Strategic mission and planning gaps + +### 18. M7 cannot defer readiness closure for its own visible claim + +F12 says construction and explanation ship together while the following mission takes projection breadth, repeat and changed-input behavior, and readiness closure. This conflicts with [`AGENTS.md`](../../../AGENTS.md): the mission making a visible claim performs its readiness decision and closes the obligations required to trust that claim. A provisional line cannot silently become the following mission’s hardened departure base. + +The consolidated M7 also contains two product-manager-visible advances: the workpiece pane is called an advance in its own right, while construction-and-explanation is the mission release. + +**Required decision:** name M7’s exact contract stratum and close every identity, failure, durability, basis-quality, current-state, and oracle obligation required for its construction-and-explanation claim. Move only breadth first made load-bearing by the following visible advance into M9. + +### 19. The probe sequence lacks result-conditioned stop and reorientation branches + +The mini spec lists compaction, relocation, passage identity, carrier repair, revision cadence, basis quality, reviewer usefulness, and token-cost probes, but F16 orders them and then proceeds toward recutting and the persona campaign. It does not say what each negative result changes. + +Before cutting authority, give every probe a decision table: + +| Result | Consequence | +| --- | --- | +| Pass | Continue under the named claim | +| Partial | Narrow the claim or change the mechanism | +| Fail | Stop the cut or split predecessor work | +| Re-entry | Evidence required to reopen the rejected route | + +At minimum: + +- persistent unusable basis or reviewer-useless why answers stop the explainability claim; +- no supported relocation blocks the retained-live-fixture route and forces an explicitly labelled alternative; +- no passage-continuity policy narrows the release to revision-local text; +- carrier failure produces a crisp upstream blocker rather than a local schema copy; +- sparse revision cadence changes the blame claim or update interaction before persona breadth. + +### 20. F16’s executable probes have no unambiguous authority home + +F16 places probes before mission topology is recut, while the mini spec calls the adversarial tracer the first act inside the consolidated mission. Under the one-live-mission rule, executable probes still need authority. + +Choose explicitly among: + +- a bounded owner-authorized side quest under M6; +- a separate probe mission; +- an initially narrow M7 authority with an owner gate before amendment into construction breadth. + +Do not leave implementation-relevant probes in design evidence with no lawful execution home. + +### 21. The canonical future record still embodies the superseded topology + +The current planning record still says: + +- M7 is capture-backed review over a prepared pair; +- M9 is where automatic projection begins; +- Draft M7 requires a hand-authored derivation fixture; +- Draft M9 inherits a Mission 7 prebuilt pair and retains the obsolete same-turn client-result wording; +- Draft M10 still depends on the old capture/derivation seam. + +F15’s migration matrix concerns runtime and persisted-data compatibility. A separate **planning-content migration matrix** is needed to satisfy the one-authoritative-home and no-silent-loss rules. + +Before promotion, map every old hypothesis, accepted decision, rejected alternative, oracle gap, deferred item, and readiness obligation to exactly one surviving destination. Then update `MISSION.next.md` and drafts atomically, remove consumed drafts under the lifecycle rules, and compare before/after planning content for unexplained loss or duplication. + +### 22. Existing archival machinery is conflated with the rejected capture semantics + +The decision documents often speak of the capture store as though re-entry means reviving one-envelope-per-user semantic capture. The current binding already archives materialized Flue history through [`packages/binding-flue/src/history-reader.ts`](../../../packages/binding-flue/src/history-reader.ts) and the capture storage contract’s session-log archive. If the compaction probe is negative, the least response may be to harden or reposition that existing archive lane rather than revive sweep envelopes or invent a third log. + +The recut should distinguish: + +- capture envelopes and sweep semantics, which are rejected for M7 provenance; +- the existing session-log archive capability; +- any new immutable lineage projection actually required by compaction, relocation, or authorization. + +### 23. Mission 11 still has a circular readiness statement + +Draft M11 says the first accepted handoff is also the completion bar because consumer acceptance is the readiness decision, then says lateral package, transfer, execution, result, credibility, repeatability, access, and retention obligations are enumerated after the handoff works. + +Distinguish: + +1. consumer contract acceptance; +2. working handoff throughline; +3. post-throughline readiness closure sufficient to begin the experiment without reconstruction. + +Consumer enthusiasm or artifact receipt is not the same as an executable witnessed experiment start. + +## Recommended decision sequence before cutting Mission 7 + +1. **Correct the Flue protocol.** Require a settled `update_workpiece` revision before mutation; prohibit ambiguous mixed batching and bind every mutation to an explicit revision ID and hash. +2. **Settle document ownership and reconciliation.** Define conversation ↔ document-incarnation binding, observed pre-state, current-state checks for why queries, and external-import continuity. +3. **Separate provenance relations.** Distinguish operation basis, element basis, passage evidence, origin, current-state changes, attempts, and actor roles or identities. +4. **Define passage identity policy.** State invariants and refusal cases before using edit probes to test ergonomics and model compliance. +5. **Make effects independently verifiable.** Derive canonical effects from observed pre/post state and fail conflicting or unknown outcomes closed. +6. **Narrow tool admission.** Select classes from the actual proving scenario, mechanically source their schemas from Petrinaut, and remove metrics or movement operations unless exact case evidence earns them. +7. **Freeze safety and utility gates.** Predeclare the consequential rule, mechanical inventory, required dispositions, minimum useful coverage, reviewer task, and behavioral discriminator. +8. **Attach stop branches and authority to probes.** Decide where executable probes live and what each result permits, reshapes, or stops. +9. **Define M7’s own readiness stratum.** Do not defer trustworthiness of the construction-and-explanation release to M9. +10. **Perform a lossless planning migration.** Recut `MISSION.next.md` and drafts 7/9/10/11 only after the observed probe results, with one surviving home for every obligation. + +## Evidence consulted + +- [`provenance-and-tooling-decision-log-2026-09-04.md`](provenance-and-tooling-decision-log-2026-09-04.md) +- [`provenance-by-lineage-mini-spec-2026-09-04.md`](provenance-by-lineage-mini-spec-2026-09-04.md) +- [`provenance-by-lineage-independent-review-2026-09-04.md`](provenance-by-lineage-independent-review-2026-09-04.md) +- [`../../../AGENTS.md`](../../../AGENTS.md) +- [`../../../MISSION.next.md`](../../../MISSION.next.md) +- [`../../mission-drafts/7-capture-backed-review.md`](../../mission-drafts/7-capture-backed-review.md) +- [`../../mission-drafts/9-traceable-projection.md`](../../mission-drafts/9-traceable-projection.md) +- [`../../mission-drafts/10-bounded-reviewer-revision.md`](../../mission-drafts/10-bounded-reviewer-revision.md) +- [`../../mission-drafts/11-optimisation-handoff.md`](../../mission-drafts/11-optimisation-handoff.md) +- [`../../reference/architecture/flue-routing.md`](../../reference/architecture/flue-routing.md) +- [`../../../packages/plugin-sdcpn/src/tools/petrinaut-construction.ts`](../../../packages/plugin-sdcpn/src/tools/petrinaut-construction.ts) +- [`../../../packages/core/src/workpiece.ts`](../../../packages/core/src/workpiece.ts) +- [`../../../packages/core/src/evidence/capture-store.ts`](../../../packages/core/src/evidence/capture-store.ts) +- [`../../../packages/binding-flue/src/history-reader.ts`](../../../packages/binding-flue/src/history-reader.ts) +- [`../../../packages/transport-aisdk/src/client-tool-history.ts`](../../../packages/transport-aisdk/src/client-tool-history.ts) +- [`../../../../../../apps/brunch-agent/src/conversation/identity.ts`](../../../../../../apps/brunch-agent/src/conversation/identity.ts) +- [`../../../../../../apps/brunch-agent/src/http/ownership.ts`](../../../../../../apps/brunch-agent/src/http/ownership.ts) +- installed Flue 2.0.3 documentation under `node_modules/@flue/runtime/docs/reference/`, especially `agent-api.md`, `agent-behavior.md`, `agent-hooks-api.md`, and `streaming-protocol.md` +- Vestera case and oracle under `evaluations/cases/vestera-scheduling/` and `evaluations/oracles/vestera-scheduling/` +- Petrinaut metric schema under `libs/@hashintel/petrinaut-core/src/schemas/metric-schema.ts` + +## Review disposition + +Do not discard the lineage design. Its useful core is a visible revisioned workpiece, constructor-declared relations, and verifiable document transitions over a real production conversation. Before mission authority is cut, make revision ordering explicit, separate declaration from evidence, reconcile against current document state, and define M7’s own safety and utility readiness gates. The next design move should remove ambiguity from the protocol and claim, not add a broader provenance platform. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/design/provenance-by-lineage-independent-review-2026-09-04.md b/libs/@hashintel/brunch-agent/docs/evidence/design/provenance-by-lineage-independent-review-2026-09-04.md new file mode 100644 index 00000000000..c96ae7fc06e --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/design/provenance-by-lineage-independent-review-2026-09-04.md @@ -0,0 +1,392 @@ +# Independent review of provenance-by-lineage replanning — 2026-09-04 + +> Review evidence, not execution authority. This document evaluates [`provenance-and-tooling-decision-log-2026-09-04.md`](provenance-and-tooling-decision-log-2026-09-04.md) and [`provenance-by-lineage-mini-spec-2026-09-04.md`](provenance-by-lineage-mini-spec-2026-09-04.md) against the checked-out Brunch and Petrinaut code, the installed Flue 2.0.3 documentation and types, the current future mission record, and three independent adversarial reviews. It identifies factual corrections, semantic gaps, and strategic blind spots. It changes no owner-settled policy and authorizes no implementation. + +## Executive verdict + +The replanning is directionally strong. Making the workpiece visible, making revisions first-class tool calls, refusing to turn the capture store into semantic IR, repairing the provider schema carrier before trusting construction, and deriving audit information from the canonical conversation record are all sound moves. + +The central claim is nevertheless overstated. The proposed mechanism establishes **temporal audit lineage**, not yet **motivational or causal provenance**. It can show which workpiece revision was current when an assistant requested a mutation and which conversation context preceded that revision. It cannot deterministically establish that a particular workpiece passage motivated a particular element. Passage selection, element-effect attribution, actor identity, and durable exact evidence each require information or contracts that the described lineage does not contain. + +The defensible near-term claim is: + +> Show the logged assistant mutation request, its later browser outcome, the workpiece revision temporally current for that request, and the intervening authorized conversation context, with explicit warnings where motivation, causal derivation, actor attribution, or exact historical evidence is not established. + +Anything stronger requires reopening C1–C3, C5, C6, C8, C10, C13, and C15 before Mission 7 authority is cut. The proposed Mission 7 also absorbs the central automatic-construction advance currently assigned to Mission 9 and is too large to remain a bounded explainability mission without an explicit recut. + +## Critical semantic gaps + +### 1. “Latest workpiece before mutation” is correlation, not causation + +The decisive unsupported traversal is: + +```text +element id + → mutation call + → latest update_workpiece at or before that call + → the passage in that revision +``` + +The conversation log contains no deterministic relation from a mutation to the passage that motivated it. A workpiece can contain many claims; one call can realize several claims; several mutations can be made while the same multi-topic workpiece is current; and a mutation can arise from formalism constraints, model inference, an external source, or a mistake. A post-construction workpiece update may contain the actual rationale but is excluded by the backward-selection rule. + +The proposed `locate_elements` returns mutation calls and the workpiece revision current at each. The proposed `query_workpiece` begins from a passage locator. No mechanism produces that locator from the mutation. Therefore the mini spec's statement that “every hop is a lookup in the canonical log; nothing is stored elsewhere and nothing is inferred” is false as written: selecting the relevant passage necessarily requires semantic inference or an explicit relation. + +This is not repaired merely by sharing a `turnId`. Shared temporal correlation still does not establish motivation, and the current client-tool result does not in fact share the mutation request's turn, as described below. + +**Required decision:** choose explicitly between: + +1. **Temporal-lineage claim:** report the workpiece revision current for the mutation and a broader conversation range, without saying that one passage motivated the element; or +2. **Small creation-time association:** carry a revision identifier and one or more passage locators with the mutation request or with a thin construction-operation envelope. + +A small creation-time relation is not the comprehensive typed IR previously rejected, and it differs materially from a retrospective hand-authored derivation fixture. If neither is acceptable, the system must return a broader range or refuse rather than invent a point passage. + +### 2. Passage identity and blame are prerequisites, not downstream fog + +The intent promises one workpiece passage, the revision that introduced it, and blame across revisions while passage identity remains undecided. Heading paths fail under rename or movement; exact text fails under edits; ordinary line blame fails under reformatting; anchors remain stable only if their lifecycle is defined; and a companion manifest can drift from the Markdown. + +The proposed C15 probe changes one non-semantic line. That is too weak to establish the promised semantics. It does not test: + +- heading rename or movement; +- passage split or merge; +- paraphrase that preserves meaning; +- deletion and reintroduction; +- a passage accumulating evidence from several non-adjacent periods; +- duplicate quotations or repeated headings; or +- correction, qualification, contextual coexistence, and conflict. + +For split, merge, paraphrase, and reintroduction there may be no unique mechanically discoverable “introducing revision” without explicit successor/predecessor semantics. + +**Required decision:** either define durable passage identifiers and their edit lifecycle before promising blame, or narrow the first claim to revision-local text and refuse cross-revision “introduced by” answers. The passage-identity probe should cover rename, move, paraphrase, split, merge, deletion, and reintroduction, not only a non-semantic line edit. + +### 3. User-turn ranges are not attribution and do not establish “who prepared it” + +The range between two workpiece revisions can contain unrelated statements and can omit older evidence reused in the new revision. A verbatim match proves string occurrence, not endorsement, origin, authority, or causation. A user may quote another person, reject the quoted proposition, or repeat wording supplied by the assistant. Non-verbatim synthesis, declared defaults, formalism constraints, assumptions, external sources, and construction-opened losses require distinct treatment. + +The proposed answer also collapses several different actors: + +- the assistant that authored the workpiece revision; +- the expert whose evidence supports a claim; +- the person who requested construction; +- the browser principal that applied the mutation; +- a later reviewer; and +- the owner or authority that permits canonical change. + +A Flue `role: "user"` is not sufficient actor identity. The release note's promise to show “who prepared it” is therefore unsupported by the described records. + +**Required contract:** represent and report workpiece author, source/evidence actor, mutation actor, requesting principal, and authorization context separately. Conversation ranges may be supporting context; they are not, by themselves, authorship or authority. + +### 4. Element IDs in tool inputs do not establish actual mutation effects + +Seeing an element ID in a mutation input does not prove that the call created or changed that element. Calls can fail, no-op, apply against stale state, affect several entities, create derived entities, delete an entity, replace or recreate an ID, or be successfully applied while their result delivery is lost. Commands such as layout can affect many elements without identifying them individually in the input. + +The current `clientToolHistoryFrom` projection treats results as opaque correlated outputs. It does not establish canonical effect semantics or reconcile conflicting and repeated results. + +**Minimum settled mutation evidence:** + +- mutation call or operation identity; +- target document identity or incarnation; +- expected base document hash; +- applied, no-op, failed, stale, or unknown outcome; +- confirmed post-document hash; +- exact created, updated, deleted, and derived element IDs, or retained canonical pre/post definitions from which those effects are mechanically derived; and +- one authoritative result per call with duplicate-result rules. + +Without this, the honest statement is “the assistant attempted this mutation,” not “this call created this element.” Deleted and recreated elements also need explicit lifecycle semantics; “creating call and last-changing call” is not sufficient when identity can be retired and reused. + +### 5. The browser mutation and workpiece update do not share one atomic boundary + +`update_workpiece` would be a server-side Flue tool. Its `usePersistentState` setter can commit atomically with that server tool's unit of work. Petrinaut mutation executes later in the browser and its result returns as a separate `client-tool-result` system dispatch. The workpiece update and the browser mutation therefore do not share durability or a transaction. + +A workpiece update can settle while a browser mutation fails, times out, applies against stale state, or is manually superseded. A browser mutation can apply while its result is lost. Two tabs or two conversations can target the same document. A later result can arrive after another mutation or hand edit. + +Atomicity across these boundaries is not necessarily required, but observable incomplete states and deterministic reconciliation are. The design should model an operation protocol rather than imply a shared batch: + +```text +mutation requested(callId, documentId, baseDocumentHash, workpieceRevision, intended scope) + → browser outcome(applied | no-op | failed | stale, postDocumentHash, effects) + → reconciled | incomplete | unknown +``` + +This protocol must define retry identity, duplicate delivery, stale-base refusal, lost-result behavior, and what provenance is safe to report for an incomplete or unknown operation. + +### 6. A post-document hash is not an adequate join + +A whole-document SHA-256 is a content fingerprint, not a mutation lineage record. It does not identify the pre-state, the transition, the actor, or the affected elements. Identical hashes can recur after revert and reapply. A hand edit followed by a logged mutation can yield a post-hash that appears “explained” by the tool result even though the resulting document includes an outside-conversation change. Serialization changes or a missing client-tool result can produce the opposite false classification. + +Consequently, “a document hash that no tool result explains is changed outside the conversation” is too strong. The safe classification is “not attributable from the recorded transitions.” Reliable attribution needs at least document identity, expected base hash, serialized operation order, result hash, operation ID, and confirmed effects. + +After an unexplained transition, the system should refuse provenance for the affected state—or for the entire document when no trustworthy diff can isolate the effects—and begin a new explicitly imported external revision if lineage is to continue. + +## Critical durability and access gaps + +### 7. Flue's supported history projection does not preserve exact lineage across compaction + +The design conflates Flue's append-only canonical storage with the public `history()` projection. Flue's underlying `ConversationStreamStore` is an ordered append-only canonical record, but its record types are not the supported application read surface. Brunch reads `createFlueClient(...).history()`, which returns a materialized conversation snapshot. + +Flue 2.0.3 explicitly compacts older messages into a summary while retaining only recent history verbatim. After compaction, the supported materialized history may no longer contain: + +- exact old user lines; +- old `update_workpiece` inputs; +- old mutation tool parts and results; +- the full workpiece revision series; or +- the exact text needed for quote verification. + +Brunch's current Flue history reader consumes only `snapshot.messages`; it has no supported access to the private pre-compaction records. This breaks the exact-line answer, workpiece revision pane, passage blame, and mutation lookup at once. + +C8 therefore understates the re-entry condition for independent retention. Compaction is already a known behavior, not merely hypothetical future strain. + +**Required decision:** either scope Mission 7 explicitly to uncompacted local conversations and visibly refuse once required evidence has compacted, or retain an immutable, authorized, compaction-independent lineage projection before compaction. That projection need not resurrect the current one-envelope-per-user-utterance capture design, but some stable retained evidence is required for the longer Mission 9 and Mission 10 story. + +Retention, export, audit, revocation, and migration are additional reasons a canonical operational conversation store may not be sufficient as the product's evidentiary archive. + +### 8. `query_workpiece` and `locate_elements` have no specified executable history-access boundary + +The ownership split is conceptually plausible but omits the runtime boundary. Inside a Flue agent there is no history hook. The supported read path is `createFlueClient(...).history()`, which requires a host-resolved conversation URL and transport. The current Brunch architecture deliberately places this absorption in the binding and app layer. + +Therefore “core knows revisions and history” is not currently true as an executable capability. A core server tool cannot silently self-HTTP without host composition, and a plugin-owned server tool cannot inspect Flue history without acquiring a substrate dependency or an injected history service. + +**Recommended boundary:** + +- core owns pure formalism-independent workpiece revision and query semantics; +- plugin-sdcpn owns interpretation of Petrinaut mutation names, inputs, outputs, and element effects; +- the binding/app owns authorized acquisition of the Flue materialized history or retained lineage projection; and +- the app composes the model-facing query tool from those capabilities. + +Whether there is one composed why tool or two model-facing tools should follow the minimum useful product interaction; package ownership does not require exposing package seams to the model. + +### 9. The proposed persistent-state pointer does not give the model the current workpiece + +The proposed state contains only `{ callId, sha256, revision }`. It contains no Markdown, and `usePersistentState` values are server-side; they are not automatically shown to the model. The statement that “the next render reads the current pointer without the model echoing it” does not explain how the model obtains the current workpiece content. + +Reading the content back from `history()` reintroduces the unavailable-history and compaction problems. A pointer alone also cannot validate or recover the current document after old tool parts disappear from the materialized projection. + +**Required mechanism:** persist the current Markdown with the pointer, or provide a retrieval capability backed by a compaction-independent store. The design must also distinguish generic core validation from plugin-specific validation. Core can check non-empty Markdown and generic size/integrity constraints, but it cannot validate conformance to the SDCPN workpiece template without plugin participation. + +### 10. Authorization, disclosure, retention, and untrusted-history handling are absent + +Returning coarse ranges “with the user text” can expose unrelated material and supplies old conversation content to the model as untrusted input. Answer-time equality with one owner key is insufficient for: + +- a second authorized reviewer; +- partial disclosure; +- revocation; +- restored fixtures; +- cross-conversation document access; +- a document whose owner changes; +- sensitive or deleted evidence; and +- later Mission 10 authority distinctions. + +The lineage must bind principal or actor identity, conversation identity or incarnation, document identity, and authorization context. Restoring or relocating a fixture must preserve those identities or explicitly establish replacements. Reads must fail without leaking the existence or content of unauthorized evidence. + +Retrieved conversation text should be treated as untrusted evidence rather than fresh instructions. The why operation should return only the smallest authorized range necessary for the answer and preserve a clear boundary between quoted evidence and model-authored interpretation. + +## Factual corrections to the mini spec and decision log + +### 11. The depicted client-tool turn topology is incorrect + +The mini spec depicts a user message, assistant response, mutation request, and mutation result as sharing one `turnId`. In current Flue history: + +- user messages commonly carry a `submissionId` but no `turnId`; +- the assistant mutation request carries the model turn's `turnId`; +- the construction tool's immediate Flue output is only `{ awaiting: "client" }` and terminates that response; +- the browser's actual output arrives later in a separate `client-tool-result` system dispatch under another submission; and +- the assistant continuation has a new model turn. + +Correlation is by `toolCallId`, plus submission and record order where needed—not by assigning the same `turnId` to the original user message and later browser result. Conversation-range resolution must join user deliveries, assistant turns, client-result signals, and continuations through their actual submission/order semantics. + +The retained Mission 6 witness also shows cumulative client-tool-result signals that repeat earlier call IDs. The lineage reader must deduplicate and reconcile by call ID rather than treating every signal occurrence as a new result. + +### 12. Current browser mutation results do not contain `documentSha256` + +The current construction tool settles server-side with `{ awaiting: "client" }`. The retained Mission 6 `addArc` browser result contains title, detail, target, and `applied`, but no document hash. Mission 6 computes the document hash separately in its settled manifest. + +Accordingly, the sentence “the browser returns the post-mutation document SHA-256 inside each client-tool result” describes proposed work, not observed current behavior. The browser result contract, its caller, and the production routing must be changed and tested before C6 exists. + +### 13. `usePersistentState` cannot be called inside the tool's `run` + +Flue hooks must be called while the agent function renders. The implementable pattern is: + +1. call `usePersistentState` during agent render; +2. capture the returned setter in the tool closure; and +3. invoke that setter from the tool callback, where `toolCallId` is available in the tool context. + +The mechanism table's pseudocode is therefore technically wrong or materially ambiguous. It should describe a render-time hook and tool closure, including how the revision number is computed with updater semantics and how the returned revision is kept consistent with the buffered state write. + +### 14. The Petrinaut file-wrapper description is imprecise + +The versioned Petrinaut file wrapper carries more than `title` and `meta.generator`: it also includes `version`, the SDCPN document arrays, and optional generator-version metadata. Runtime entity schemas use strict objects in important places, but the file import schemas are not uniformly strict. + +The narrower conclusion remains sound: there is no currently supported provenance metadata slot on individual elements, and no established file-level provenance field. The documents should state that directly rather than claiming that the wrapper has only two fields or that every relevant file-level object is strict. + +### 15. “Durable tool” does not make the browser side effect exactly once + +`durable: true` can protect the server-side tool attempt and its recorded Flue state effects. It does not make an external browser mutation exactly once. The browser can apply a mutation and lose its result; a retry can encounter changed state; signal admission can be deduplicated while the external side effect has already happened more than once. + +The durability statement must be scoped to the server workpiece tool. Browser mutation idempotency, base-state checking, and unknown outcomes require their own contract. + +## Strategic gaps in the mission sequence + +### 16. The proposed Mission 7 absorbs Mission 9's central product advance + +The recut Mission 7 now includes: + +- provider schema-carrier repair; +- broad ordinary-conversation mutation-tool admission; +- construction teaching; +- `update_workpiece` and persistent revision mechanics; +- a workpiece revision/diff pane; +- retirement of old client-tool surfaces; +- several real persona interviews through construction; +- production of a real constructed net; and +- the final why route over that lineage. + +Mission 9's current release note is that Brunch constructs a recognizable net region itself. If Mission 7's real persona run constructs the provenance pair, that advance has already been crossed. M7 becomes a large multi-front construction, UI, evaluation, persistence, and explainability mission whose user value arrives last, while M9 later repeats the same terrain under a different completion bar. + +**Required recut:** choose explicitly between: + +1. consolidate the real construction and explanation advance, then give the following mission projection breadth, repeat/change behavior, and readiness closure; or +2. make the visible revisioned workpiece a smaller precursor mission, followed by one mission that constructs and explains a real bounded region. + +At minimum, carrier repair plus one canonical production-path mutation should be an early go/no-go tracer before committing to the pane, persona campaign, and whole-net coverage. + +### 17. M7 is not bounded around one coherent visible advance + +Even if one branch may contain several tracer bullets, the proposed M7 has too many independent failure fronts: schema conversion, model tool selection, workpiece cadence, history access, passage identity, browser mutation effects, new UI, fixture restoration, persona quality, and reviewer usefulness. Several can invalidate the architecture after substantial unrelated implementation has landed. + +The first working line should answer the disputed semantic question with the least mechanism: one genuine conversation, at least two distinguishable workpiece passages, at least two mutations, one failed or no-op mutation, one correction, and one hand edit. If the why resolver cannot distinguish those cases without guessing, the architecture should stop before whole-net breadth. + +### 18. Fixture restoration is unresolved but lies on the critical path + +The mini spec accurately marks a `???` between a genuine persona run and a live demo fixture. Keeping a dev store, importing private Flue records, and replaying a materialized snapshot each make a different product claim. Replaying signals creates a prepared projection rather than preserving the original live lineage. + +Running several paid persona construction campaigns before proving that one minimal genuine conversation can be exported or retained, relocated, reopened, authorized, and queried risks producing evidence that cannot power the demo. + +**Recommended order:** run the export/restore/reopen probe on one tiny genuine conversation before the broader persona programme. Record whether the product fixture is a retained live store, a supported relocation of genuine records, or an honestly labelled prepared projection. + +### 19. Broad canonical-tool admission contradicts the stated restraint + +The mini spec says to admit Petrinaut's canonical mutation, query, and command tools by default and scope down only after observed misbehavior, while saying stock-modeller parity remains a non-goal. That is parity-first admission in practice. It also conflicts with the current Mission 9 record's rejection of broad tool parity and risks a large provider tool-definition cost, selection ambiguity, inappropriate commands, and a much larger failure surface before any scenario requires metrics, subnets, differential equations, scenarios, removals, and layout together. + +Rejecting the inherited arbitrary six-tool subset does not require admitting everything. Replace it with a **scenario-derived canonical subset**, mechanically generated from Petrinaut's authority, and expand it when the selected scenario or observed failure requires another mutation class. Measure schema size, prompt-cache effects, tool-selection behavior, latency, correction behavior, and provider errors before making a broad bundle the ordinary default. + +### 20. The completion criterion remains underdefined + +“Any element” and “consequential element” lack a mechanical inventory rule. The old M7 draft at least required a frozen element inventory and explicit supported or unsupported dispositions. That obligation should survive the mechanism change. + +Before a run is graded, freeze: + +- the selected document and workpiece revisions; +- the element inventory; +- the rule distinguishing consequential elements from presentation-only artifacts; +- expected supported, partially supported, externally changed, and refused dispositions; and +- what happens to deleted or recreated elements. + +Without this, whole-net completion can be gamed by excluding difficult elements after the fact. + +### 21. Migration and rollback are missing + +The plan changes persisted workpiece representation from fenced assistant text to tool parts and state, changes ordinary-conversation tool admission, removes `ask` and `sweep` handling, and changes the lineage expected by future missions. Existing conversations and retained runs contain only the old representation. Rollback after new state records and new tool calls is unspecified. + +A migration matrix should cover: + +- old history with new code; +- new history with rolled-back code; +- conversations containing both fenced and tool revisions; +- mixed-version browser and server; +- Mission 6 fixture mode; +- retained evidence restoration; and +- tool-manifest rollback. + +Given the prototype posture, a permanent compatibility layer is not warranted, but the transition crosses persisted data and separately deployed browser/server boundaries. An additive introduction with a bounded dual-read period may therefore be the least safe mechanism. The bridge should have an explicit removal gate. + +### 22. Deployment ordering is inconsistent + +C14 moves remote durability back to Mission 8, but current Mission 9 and Mission 10 drafts still require deployed or replacement-safe inherited state. Historical Mission 8 stopped before remote deployment, and no new executable M8 is yet scheduled. This leaves later missions either blocked on an unscheduled dependency or tempted to silently weaken “deployed.” + +Choose explicitly between: + +- scheduling a real Mission 8 persistence/deployment mission before the first remote claim; or +- making M9 and M10 explicitly local-product missions and naming a pre-M11 remote release gate. + +“Locally run panel,” “locally verified application image,” and “remote replacement-safe service” must remain distinct claims. + +### 23. Consumer discovery may be too late + +Deferring self-describing export and optimization-consumer discovery until Mission 11 risks choosing an M9 region and M10 correction that do not exercise the scenario, parameter, metric, executable, or behavioral semantics Chris and Yannis actually need. Mission 11 could then become an unexpectedly large rebuild rather than a handoff. + +Do lightweight, non-binding consumer discovery before selecting the M9 region: one optimization question, minimum scenario and parameter semantics, expected execution boundary, required outputs, and minimum credibility checks. Keep implementation in M11, but use the real consumer to select a representative proving case and decide whether file-level provenance is load-bearing earlier. + +### 24. Semantic and behavioral proof is too visual until the optimization handoff + +A visually plausible, parser-valid SDCPN can still have incorrect enabling, resource conservation, timing, scenarios, or stochastic behavior. Human semantic review is necessary but insufficient for operational behavior. + +When selecting the first meaningful generated region, require at least one executable discriminator derived from the workpiece—for example resource reservation and release, reachability, token conservation, or one scenario outcome—and carry it unchanged through the reviewer-revision mission. This need not become broad simulation coverage; it should be the cheapest check capable of catching a plausible but behaviorally wrong projection. + +## Items that should be reopened before Mission 7 authority + +### Reopen C1–C3: lineage and the honest why answer + +Decide whether the product promises temporal audit context or causal provenance. If causal provenance remains the intent, identify the smallest explicit mutation-to-passage relation and separate authorship, evidence, rationale, and authority. + +### Reopen C5: lookup ownership and execution + +Keep semantic package ownership, but assign supported Flue history acquisition, authorization, and tool composition to the binding/app boundary. Decide whether the model needs two tools or one composed why operation based on interaction quality rather than package topology. + +### Reopen C6: hash-only net/workpiece join + +Replace the post-hash-only proposal with a transition and effect contract, or narrow the claim to unattributed state correlation. + +### Reopen C8: excluding capture or another retained evidence projection + +Known Flue compaction already threatens exact evidence and revision recovery. Decide the uncompacted limitation or the minimal compaction-independent retention mechanism before promising exact historical lines. + +### Reopen C10: full-bundle default admission + +Retire the inherited arbitrary six, but choose a scenario-derived canonical subset and expand from observed need rather than mounting near-parity by default. + +### Reopen C13: release wording + +“Who prepared it” and “the exact conversation line it rests on” exceed the represented identity and causality. Narrow the release note until actor identity, evidence retention, and causal association are established. + +### Reopen C15: passage identity + +Treat passage identity as a prerequisite to point-passage provenance and blame. Strengthen the probe to semantic edits, or defer blame and report only revision-local text. + +### Reopen D1, D3, and D5: real fixtures and construction sequencing + +Prove one genuine conversation can become an authorized live fixture before the persona campaign, and resolve whether construction in M7 intentionally consumes M9's visible advance. + +## Recommended next sequence + +1. **Adjudicate the product claim.** Decide causal provenance versus temporal audit lineage and amend the release wording accordingly. +2. **Build one adversarial tracer on paper or in the smallest executable harness.** Use one conversation with two workpiece passages, two mutations, one failed or no-op mutation, one correction, and one hand edit. Require deterministic answers or explicit refusals. +3. **Correct the Flue topology model.** Represent user delivery, assistant mutation request, later client-result signal, continuation, duplicate result delivery, and server-state writes using their real identities. +4. **Define the minimum mutation transition/effect record.** Include document identity, base state, outcome, post state, affected elements, and unknown-result behavior. +5. **Force compaction.** Verify which exact user text, workpiece revisions, and tool records remain available through the supported public surface; choose an explicit limitation or retained projection. +6. **Export or retain and reopen the tracer conversation.** Exercise authorization and why resolution after relocation or restart before launching paid persona breadth. +7. **Probe passage identity under semantic edits.** Include rename, move, paraphrase, split, merge, deletion, and reintroduction. +8. **Repair the provider schema carrier for the smallest scenario-derived mutation subset.** Prove one real nested call before broad admission. +9. **Re-cut the mission topology from the observed results.** Explicitly resolve the M7/M9 overlap, deployment order, migration boundary, and consumer-driven proving scenario. +10. **Only then run the broader persona construction campaign.** Freeze the consequential-element inventory and behavioral oracle before grading. + +## Evidence consulted + +- [`provenance-and-tooling-decision-log-2026-09-04.md`](provenance-and-tooling-decision-log-2026-09-04.md) +- [`provenance-by-lineage-mini-spec-2026-09-04.md`](provenance-by-lineage-mini-spec-2026-09-04.md) +- [`../../../MISSION.next.md`](../../../MISSION.next.md) +- [`../../mission-drafts/7-capture-backed-review.md`](../../mission-drafts/7-capture-backed-review.md) +- [`../../mission-drafts/9-traceable-projection.md`](../../mission-drafts/9-traceable-projection.md) +- [`../../mission-drafts/10-bounded-reviewer-revision.md`](../../mission-drafts/10-bounded-reviewer-revision.md) +- [`../../specs/petrinaut-batched-construction-tools.md`](../../specs/petrinaut-batched-construction-tools.md) +- [`../../../packages/core/src/workpiece.ts`](../../../packages/core/src/workpiece.ts) +- [`../../../packages/plugin-sdcpn/src/flue.ts`](../../../packages/plugin-sdcpn/src/flue.ts) +- [`../../../packages/plugin-sdcpn/src/tools/petrinaut-construction.ts`](../../../packages/plugin-sdcpn/src/tools/petrinaut-construction.ts) +- [`../../../packages/binding-flue/src/history-reader.ts`](../../../packages/binding-flue/src/history-reader.ts) +- [`../../../packages/transport-aisdk/src/client-tool-history.ts`](../../../packages/transport-aisdk/src/client-tool-history.ts) +- [`../../../../../../apps/brunch-agent/src/agents/chat-agent/agent.ts`](../../../../../../apps/brunch-agent/src/agents/chat-agent/agent.ts) +- [`../implementations/fe-1575-outer-browser-witness-2026-09-04-r2/witness.md`](../implementations/fe-1575-outer-browser-witness-2026-09-04-r2/witness.md) +- Installed Flue 2.0.3 documentation for agent hooks, public conversation history, compaction, streaming, and conversation persistence under `node_modules/@flue/runtime/docs/` and `node_modules/@flue/sdk/docs/` +- Petrinaut canonical AI, action, entity, and file-format schemas under `libs/@hashintel/petrinaut-core/src/` + +## Review disposition + +The design should not be discarded. Its useful core is a first-class revisioned workpiece plus mutation-call audit history. The correction is to stop calling temporal adjacency a complete provenance relation, then add only the smallest identities, effects, retention, and authorization contracts that the real why answer requires. The mission sequence should be recut after those disputed seams are probed, not before. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/design/provenance-by-lineage-mini-spec-2026-09-04.md b/libs/@hashintel/brunch-agent/docs/evidence/design/provenance-by-lineage-mini-spec-2026-09-04.md new file mode 100644 index 00000000000..69dff8a487a --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/design/provenance-by-lineage-mini-spec-2026-09-04.md @@ -0,0 +1,195 @@ +# Provenance by lineage with declared basis — mini spec, 2026-09-04 (third state) + +> Design evidence, not execution authority. This document projects the [decision log of 2026-09-04](provenance-and-tooling-decision-log-2026-09-04.md), including dispositions F1 to F16 and G1 to G22, into one reviewable statement of intent, design, and consequences for the Brunch mission spine. Two review passes shaped it: the [independent review](provenance-by-lineage-independent-review-2026-09-04.md) corrected the turn topology, hook pattern, and claim strength and added the declared basis and transition record; the [follow-up review](provenance-by-lineage-follow-up-review-2026-09-04.md) corrected the revision protocol, separated the provenance relations, added document reconciliation and readiness ownership, and hardened the gates. Nothing here may be implemented until it is re-evaluated and cut into a live `MISSION.md`; the planning projection is the Mission 7 draft. + +## 1. Intent + +Brunch must be able to say, for any consequential element of a Petri net it helped build, what it rests on: the workpiece passage the constructor declared as its basis, the settled revision that carried that passage, the conversation context associated with that revision and, where declared, the evidence relation behind the passage, and the recorded roles that did each thing, or an honest refusal. It must do this without a comprehensive typed domain model, without a second conversation log, and without anyone authoring links after the fact. + +Two earlier approaches failed in opposite directions. A comprehensive typed intermediate representation tried to make provenance a property of the domain model; the typology receded as it grew and the model worked worse with it. The structural Markdown workpiece that replaced it is legible and cheap but has no seam to either the conversation or the net, and provenance was deferred without the tension being named in the planning record. + +The corrected resolution treats provenance as four distinct contracts, none of which is inferred from the others: + +1. **Revision protocol.** A workpiece revision settles and becomes addressable before any mutation can cite it. +2. **Provenance semantics.** Mutation basis, passage evidence, element origin, current-state history, attempt history, and recorded actor roles are distinct relations, each with its own source. +3. **Document reconciliation.** The live Petrinaut state is compared with recorded transitions before provenance is reported. +4. **Mission readiness.** The mission making the construction-and-explanation claim closes the safety and utility obligations that claim depends on; only breadth first made load-bearing by the next visible advance moves later. + +## 2. The lineage model, as the log actually records it + +```text +submission S1 user message (submissionId S1, no turnId) + assistant turn T1 + ├─ update_workpiece { markdown, evidence? } revision R: identity = callId, sha256 + └─ tool result { revisionId, sha256, revision } + state_write workpiece = { revisionId, sha256, revision, markdown } +submission S2 user message or continuation + assistant turn T2 (render exposes revision R from state) + └─ addArc { …, basis: declared{ revisionId R, sha256, locators, rationale, scope } } + server output = awaiting client; turn terminates +submission S3 system dispatch client-tool-result [{ toolCallId, output: transition record }] + assistant turn T3 continuation +``` + +Rules the diagram encodes: + +- `update_workpiece` and a Petrinaut mutation never share a tool batch, because a batch ends the turn only when every result terminates and construction tools terminate (G1). +- A mutation cites a settled revision by id and hash; "latest" and sibling order are inadmissible (G2). +- Correlation is by `toolCallId` plus submission order; cumulative result signals repeat earlier ids and are deduplicated (F1). +- "When" means canonical stream order (G6). + +Resolution from an element, with the relation each hop actually is: + +```text +element id + → identity epoch, then transition records naming it origin | current state | change history | attempt history (G8, G9) + → operation-level basis on the creating and changing calls constructor-declared, or absent{reason} (G7) + └─ mapped to this element only if an intended-effect mapping names it; else operation-level only + → the locator's immutable span in the cited settled revision passage (G11) + → declared evidence relation on that revision, if any elicited | inference | default | formalism | external | correction (G3) + └─ otherwise: conversation context temporally associated with the revision, labelled as such + → recorded roles assistant tool call · local browser executor · user under principal · test-authored fixture (G6) + → live document reconciliation current hash matches last reconciled state, or answer is labelled "as of …" (G4) +``` + +What the model does: it calls the lookup tools and interprets structured results in prose. What it may not do: author a basis after the fact, promote temporal context to evidence, reread the transcript as provenance, or explain an element the records mark unsupported, not attributable, or external (C3, G7, G10). + +## 3. Mechanisms + +### 3.1 `update_workpiece` (core, server-side) — C4, F2, F10, G1, G3 + +| Aspect | Decision | +| --- | --- | +| Input | `markdown` (full document) and optional `evidence: [{ locator, messageIds[], kind }]` | +| Hook pattern | `usePersistentState('workpiece', …)` at render; setter captured in the tool closure; called from `run`, which receives `toolCallId` | +| Identity | `revisionId` is the call's `ToolContext.toolCallId`; `sha256` is content identity; the ordinal `revision` is display metadata, never an identity (H6) | +| State value | `{ revisionId, sha256, revision, markdown }`, updater form; the Markdown lives in state so the agent has its current workpiece at render regardless of compaction | +| Output | `{ revisionId, sha256, revision }`; the model must use these in later basis declarations | +| Termination | non-terminating; never batched with a terminating construction tool | +| Validation | core: non-empty, size; plugin: template conformance | +| Durability | `durable: true`, server attempt only | +| Ownership | core owns the tool; plugins own the template | + +The fenced `runbook-ir` block is retired as the model-produced revision source. The prepared-signal route stays for test-authored revision zero, tagged as such. + +### 3.2 Declared basis on mutation requests — F5, G2, G7 + +```text +basis = + | declared { revisionId, sha256, locators: [span], rationale, scope: operation | { intendedEffects: [{ elementId, locators }] } } + | absent { reason } +``` + +The cited revision must have settled and match the current state pointer unless supersession is marked intended. Construction notes are not a substitute for an absent basis. The plugin strips `basis` before forwarding the canonical input to Petrinaut, so Petrinaut's contract is unchanged, and the full request is retained in the log as the tool-call input. Basis quality is graded for relevance, contradiction, granularity, and omitted dependencies. + +### 3.3 Mutation transition record and operation protocol — F7, F8, G4, G5, G9, G10 + +The browser returns one authoritative transition record per call: + +```text +{ toolCallId, documentId, documentIncarnation, + requestedBaseHash, observedPreHash, postHash?, + outcome: applied | no-op | failed | stale | unknown, + effects: { created[], updated[], deleted[], derived[] } disjoint, mechanically derived from pre/post + diffAccounted: boolean } +``` + +Protocol: `requested → outcome → reconciled | incomplete | unknown`. `postHash` is present only when a post-apply observation exists, so an `unknown` outcome may lack it. The first well-formed outcome is authoritative unless a later delivery conflicts with it, in which case the outcome becomes `unknown` and both deliveries remain as attempt history (H7). An `elicited` evidence relation on `update_workpiece` is refused unless every referenced message id resolves to an authorized true-user message in the bound conversation (H8). Failed, no-op, stale, and unknown calls contribute only attempt history. Mission 7 binds one conversation to one document incarnation, recorded at fixture creation and checked on every mutation and why query (G5). A document hash no record explains is "not attributable from recorded transitions"; an external revision may be imported with actor or unknown, principal, parent hash, canonical diff, and reason, and every imported changed element keeps an `external/unsupported` disposition until a later recorded transition replaces it (G10). Every why answer reconciles against the live document hash through the existing client-tool path or labels itself "as of the last reconciled recorded state" (G4). + +### 3.4 Lookups and their executable boundary — C5, F9 + +Core owns revision and query semantics. Plugin-sdcpn owns mutation names, inputs, outputs, and effect interpretation. Binding and app own authorized acquisition of Flue history through the in-process fetch pattern the capture sweep already uses, and compose the model-facing why operation. One or two model-facing tools follows interaction quality. Retrieved conversation text is untrusted evidence returned in the smallest range needed; the single-principal local limit is stated (F11). + +### 3.5 The visible workpiece — C7, G16 + +Chat projects `update_workpiece` parts out of assistant messages and leaves a one-line marker. A pane in the Petrinaut Brunch panel shows the current revision, the revision list, and a diff, derived from Flue history through the Mission 5 transport. The why answer renders into the same pane. The projection lives in the app or transport layer, not the Petrinaut library. Inside Mission 7 the pane is an enabling surface for the construction-and-explanation claim, not a second release. + +### 3.6 Schema carrier repair — B9, C11 + +Precondition for admitting any nested tool. Flue accepts Valibot only and rejects other Standard Schema vendors; the construction factory declares an empty loose object with the JSON Schema pasted into the description. Fix by a mechanical JSON Schema to Valibot interpreter for the subset Petrinaut uses, or upstream Flue Standard Schema support. Prove one real nested call before broad admission. Carrier failure is a crisp upstream blocker, never a local schema copy. + +### 3.7 Passage identity — F6, G11 + +Policy first: passage ids are never reused after deletion; split and merge record predecessor and successor sets; ambiguous paraphrase refuses continuity; reintroduction starts a new identity unless continuity is declared; a locator resolves to an immutable revision-local span; duplicate headings and quotations are tested; an overbroad span fails basis quality when a materially narrower sufficient span exists. Then the probe tests ergonomics and model compliance on one real workpiece under rename, move, paraphrase, split, merge, deletion, and reintroduction. Fallback if the policy proves too expensive: revision-local text and refused cross-revision "introduced by" claims. + +### 3.8 Scenario-selected tool admission with canonically derived schemas — F13, G15 + +The inherited six-tool subset is retired. Operations are selected from the proving scenario; their schemas are derived mechanically from Petrinaut's AI tool bundle. The 2026-09-04 survey of the six persona cases gives the candidate set; the cut names the proving scenario and admits only the classes it needs, citing the case requirement each discharges. + +| Entity class | Case evidence | Operations (add, update, remove unless noted) | Admission | +| --- | --- | --- | --- | +| places, transitions, arcs | every case | including arc weight and type | default | +| scenarios (initial state) | every case | | default | +| types and type elements | most cases name colours or token attributes | | default when the scenario has typed tokens | +| parameters | industrial gas | | when the scenario names a tunable quantity | +| differential equations | data-centre thermal, pharma cold chain | | when the scenario has continuous dynamics | +| metrics | Vestera names scheduling objectives but forbids invented weights | | only when the scenario names a measurable objective Petrinaut's `Metric` can express | +| queries and commands | all | `getLatestNetDefinition`, `getNetCompilationErrors`, `applyAutoLayout`, `setNetTitle` | default | +| excluded | only Vestera hints at hierarchy | subnets, component instances, position updates, type-element move | until a case needs them | + +Expansion is by observed need with the case named. Parity with the stock modeller is not the goal; ending deferral is. + +### 3.9 Teaching and subtraction — C9, C12, G20 + +The skill gains construction posture: read the definition first, call `update_workpiece` and wait for its settled revision, mutate in small steps each citing that revision with a declared basis, check compilation errors, record decisions in Construction notes without treating them as basis, and call `update_workpiece` again after construction. The `ask` and `sweep` client handling is retired from code. Three things stay distinct: capture envelopes and sweep semantics, rejected for Mission 7 provenance; the existing session-log archive lane in `binding-flue`, which may be hardened if the compaction probe is negative; and any new immutable lineage projection required by compaction, relocation, or authorization. + +## 4. Tool inventory after this design + +| Tool | Owner | Executes | Status | +| --- | --- | --- | --- | +| `ping`, `activate_skill`, `readPetrinautDoc` | app, Flue, plugin | server, server, browser | keep | +| scenario-selected Petrinaut operations (3.8) | plugin-sdcpn, schemas derived | browser | admit after carrier repair, per proving scenario | +| `update_workpiece` | core | server | new | +| why operation (one or two model-facing tools) | composed at app from core and plugin | server, with a browser read for reconciliation | new | +| `ask`, `sweep` client handling | core, website | browser | retire | +| six-tool and two-tool subsets | plugin-sdcpn | browser | retire once Mission 6 archives | + +## 5. Real honest fixtures — D1 to D5, F14, G12, G13, G14 + +The provenance pair is a real conversation with a real revisioned workpiece and a real constructed net, produced by persona interviews against the production agent. The Mission 6 prepared fixture stays a viability proof. + +```text +probe: one tiny genuine conversation → export or retain → relocate → reopen → authorize → query (F14, first) +then: persona runs (Pi harness, production ChatAgent, real-headless host), several cases in parallel + → Flue store holds conversation, settled revisions, mutations with basis, transition records + → harness retains snapshot.json + projections per settled read (diagnostics only) + → consequential rule frozen before the run; inventory generated from the final canonical document + → acceptance assertions run through the reopened authorized why operation the product uses + → safety gate, then utility gate with a blinded reviewer task and fixed rubric +``` + +Sources are labelled synthetic-persona, internal-human, or customer-derived. At least one adversarial fixture includes duplicate wording, rejected quotations, constructor inference, a correction, unrelated context, a carried-forward passage, non-adjacent evidence, and multi-source synthesis. Stop rule: a turn cap as budget, early stop when Brunch declares construction handoff, ledger coverage as the post-hoc grade (D4). Runs go to construction so the fixture contains lineage and basis (D5). + +## 6. Mission topology — F12, G16, G18 + +Construction and explanation ship in one mission, Mission 7, which also closes the readiness of its own claim. Its authority is cut in two steps under one issue and branch, based on the final Mission 6 close commit: a narrow first authority whose throughline is the adversarial tracer and the four probes with decision tables and an outcome classification (eligible for amendment, eligible after named rework, terminal stop); then, on an allowed branch and the owner gate, a separately committed amendment admitting the construction-and-explanation body with its readiness gate. The Step B packet survives in the retitled draft, never in the live Proof, until that amendment (H3, H5). Under the owner's qualification H0, rework branches preserve the consolidated shape; only outcomes that contradict it are terminal. Mission 9 takes breadth first made load-bearing by "repeatable": unchanged repeat, changed input, deletion and retirement, concurrent user change, cross-conversation document access, broader schema classes, and the per-action versus batch decision if Mission 7 has not settled it. Mission 10 inherits basis, transition records, passage policy, and identity epochs. Mission 11 gains early consumer discovery and three-gate readiness (G21). Local posture is named; remote durability goes to a scheduled Mission 8 or an explicit pre-handoff release gate, and "locally run," "locally verified image," and "remote replacement-safe" stay distinct claims. + +Release wording (C13, F5, G6): "Ask why about any element in a net Brunch built with you, and see the workpiece passage the constructor declared as its basis, the conversation context behind it, and which recorded step did what, or an explicit refusal." Causal and identity wording strengthen only as the records do. + +## 7. Consequences for the planning record — G19 + +1. **Name the tension** in the spine: lineage plus declared basis as the hypothesis; typed IR, hand-authored derivation, and temporal adjacency as causation rejected with reasons; revision cadence, compaction survival, passage identity, and basis quality as named strains; the visible workpiece as the precondition. +2. **Recut the drafts**: Mission 7 becomes the consolidated construction-and-explanation mission at cut-level detail; Mission 9 becomes breadth and repeat behaviour; Mission 10 inherits the new seam; Mission 11 gets early consumer discovery and three-gate readiness. +3. **Planning-content migration matrix** in `MISSION.next.md`: one surviving destination per old item. +4. **Mission 6 close report**: fixture-rigging admission, the carried fenced-block-to-tool change, the credential cause of the blocked witness. +5. **Runtime migration matrix** with a removal gate for any dual-read bridge (F15). +6. **Authority**: every settled item becomes authority only when written into the cut Mission 7 `MISSION.md`, with Mission 6's construction-tool constraint amended there. + +## 8. Probes with decision tables — G17 + +| Probe | Pass | Partial | Fail | Re-entry | +| --- | --- | --- | --- | --- | +| Compaction: does `history()` keep folded `update_workpiece` inputs, mutation parts, and user lines? | Lineage reads from `history()` | Current revision from state; history claims limited to the uncompacted window and disclosed | Harden the existing session-log archive lane into an immutable lineage projection before any exact-line claim | Flue exposes a supported pre-compaction read | +| Fixture materialization: export, relocate, reopen, authorize, query one tiny genuine conversation | Retained live store or supported relocation is the fixture route | Relocation works but identities must be re-bound; record the binding rule | The demo runs on the retained live store where the conversation was produced; relocation is filed upstream; the prepared-projection route is not used for the why claim (H5) | Flue adds a supported export or import surface | +| Passage identity under the G11 policy | Locator scheme selected | Some edit classes refuse continuity; refusals become part of the claim | Revision-local text only; no cross-revision "introduced by" | Cheaper anchor lifecycle appears in the workpiece template | +| Carrier repair for one real nested mutation from the proving scenario | Admit the scenario's classes | Flat classes only; nested classes refused with a named blocker | Crisp upstream Flue requirement; no local schema copy | Flue accepts Standard Schema or supplied JSON Schema | +| Revision cadence and basis quality in the adversarial tracer | Blame and basis have grain | Coarser ranges disclosed; skill wording and pane interaction adjusted before breadth | Explainability claim stops at "which revision, which turns"; construction proceeds without the why release | Cadence improves under the revised interaction | +| Reviewer utility under the blinded rubric | Utility gate passes | Coverage below threshold on named classes; scope the claim to passing classes | Explainability release withheld; construction release stands on its own gates | Rubric passes on a later fixture | + +## 9. Questions for the next reviewer + +1. Does the two-step Mission 7 authority satisfy the one-live-mission rule without becoming a thin tracer by another name? +2. Is the optional revision-time evidence relation on `update_workpiece` the least mechanism that makes passage evidence honest, or does it drift toward assertion cards? +3. Is the transition record now independently verifiable, and does the one-conversation-one-document binding leave Mission 9 a clean re-entry? +4. Is any admitted class in 3.8 unearned by the proving scenario? +5. Which decision-table rows are terminal stops rather than rework branches, and does any rework branch quietly reduce the mission's ambition against H0? diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/SHA256SUMS b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/SHA256SUMS new file mode 100644 index 00000000000..f97c0ae270f --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/SHA256SUMS @@ -0,0 +1,21 @@ +6807ecb0e76a2e90193281fb48c3c5c69158f45e04ad55055b75600533fce367 call-result-correlation.json +183ea07ea977ed9a121da7a38f04cdb165d87533ba94de0034d85c07a4efa5db cold-reader-gate.md +c6c49657c8b40f552a4d829f8089027ac4538cff1fe0e5f1f0f58c533138748e cold-reader-records.json +c17ae80cc22939f0af6c2675f6bcc20b025b17a5b7bfb9e8029813bcef9ad736 definition-after.json +0ec2b0c9bb82787602c359b41e6c1663001f8e42425ad2ab7f84ac019944766b definition-before.json +c17ae80cc22939f0af6c2675f6bcc20b025b17a5b7bfb9e8029813bcef9ad736 definition-tab-b.json +64d50737a22eed36ca5d5605a414ba80d30c5bc776e6d2a0d90b454ecd2b7d9b flue-snapshot-after.json +1a8ed1a7463511807bc2f6b796a272bcc279b412fc4306701b9a12b7f9d15f81 flue-snapshot-before.json +b05b8def1ff005df8131f6a486c2f9f68d5e41455c2732fe83d36187dc28e824 flue-snapshot-tab-b.json +6df15e3e1f95a1df9bb0567a84e6808abfebcd089e9b2c0d95b5d3c39b0412f1 latest-workpiece.md +17f99f53f8cf93285a7344f5e9687d94e5f59011e6895ce11a9722fde2e77511 prepared-workpiece.md +9f7148397ddde657157199428147971cbde59a751d8ffc13e5ce9624b74e6bf7 route-evidence.json +9ac14c680bbf962e528fb18826737a61174a3e42aaaeab85745fee2aa923d7ec run-metadata.json +8d5c9ccde97fa2058ba12adf9b37ab911ed02b24ffa4f8175a3633b3d6a42c25 screenshot-tab-a-after.png +ae6811c466fa0f918dc74166f155ad0239ffe37b1ce9c7d27beec5d1ed92a72d screenshot-tab-a-before.png +772ad1314906a2fc67f34b1ca5ccf7c179c8b76751a03b1a3544b7ce289d756d screenshot-tab-b-after.png +ec0af35e2018e72dfb2b10df4be944bdb645c649dcda66685d868c1d33d71f60 settled-manifest-after.json +a29c4a8d3453298285e1b210eb816a2a5636587ecb3fe367a8646d3c02da4e86 settled-manifest-before.json +ec0af35e2018e72dfb2b10df4be944bdb645c649dcda66685d868c1d33d71f60 settled-manifest-tab-b.json +ac10a63dc246af73c123ca81fb24ba1d5b680ff33d21efda930156a36f16e02a tab-b-correlation.json +d5d8211d376ccb334879c52bc7fff6360696c3166ca8903695d99bbe0b75d26d witness.md diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/call-result-correlation.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/call-result-correlation.json new file mode 100644 index 00000000000..04bad3673e9 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/call-result-correlation.json @@ -0,0 +1,84 @@ +{ + "calls": [ + { + "messageId": "entry_01M1NV6ARKVMJTM74GVBKS6VW4", + "submissionId": "sub_ik_a38b1133b7c7c65bf8f07814d23bcbcb", + "toolCallId": "toolu_01BQukCZTAhJ64VNE7oC1CWG", + "state": "output-available", + "rawInput": { + "transitionId": "start-final-inspection", + "arcDirection": "input", + "placeId": "dispatch-crew-available", + "weight": "1", + "type": "standard" + }, + "parsedInput": { + "transitionId": "start-final-inspection", + "arcDirection": "input", + "placeId": "dispatch-crew-available", + "weight": 1, + "type": "standard" + } + } + ], + "resultDeliveries": [ + { + "messageId": "entry_direct_c3ViX2lrX2FmOWNjY2IxZTk1NzI5ZjkyNDk0NDA2NTE0NTE3Y2Nl", + "submissionId": "sub_ik_af9cccb1e95729f92494406514517cce", + "result": { + "toolCallId": "toolu_01BQukCZTAhJ64VNE7oC1CWG", + "toolName": "addArc", + "output": { + "title": "Added input arc", + "detail": "Dispatch crew available <-> Start final inspection", + "target": { + "kind": "selection", + "item": { + "type": "arc", + "id": "$A_place:dispatch-crew-available___start-final-inspection" + } + }, + "applied": true + } + } + }, + { + "messageId": "entry_direct_c3ViX2lrX2Q3OTdiNGM2MDUzZTVkMGExNDRlYzE1NDdhMjJlMGNh", + "submissionId": "sub_ik_d797b4c6053e5d0a144ec1547a22e0ca", + "result": { + "toolCallId": "toolu_01BQukCZTAhJ64VNE7oC1CWG", + "toolName": "addArc", + "output": { + "title": "Added input arc", + "detail": "Dispatch crew available <-> Start final inspection", + "target": { + "kind": "selection", + "item": { + "type": "arc", + "id": "$A_place:dispatch-crew-available___start-final-inspection" + } + }, + "applied": true + } + } + } + ], + "uniqueResults": [ + { + "toolCallId": "toolu_01BQukCZTAhJ64VNE7oC1CWG", + "toolName": "addArc", + "output": { + "title": "Added input arc", + "detail": "Dispatch crew available <-> Start final inspection", + "target": { + "kind": "selection", + "item": { + "type": "arc", + "id": "$A_place:dispatch-crew-available___start-final-inspection" + } + }, + "applied": true + } + } + ] +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/cold-reader-gate.md b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/cold-reader-gate.md new file mode 100644 index 00000000000..0beb540a721 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/cold-reader-gate.md @@ -0,0 +1,108 @@ +# Mission 6 cold-reader gate + +Reviewer qualification: a human who did not watch the implementation or outer witness. Do not give the reviewer `witness.md`, screenshots, implementation files, or this mission's expected conclusions. + +Give the reviewer only: + +- [prepared-workpiece.md](prepared-workpiece.md) +- [latest-workpiece.md](latest-workpiece.md) +- [cold-reader-records.json](cold-reader-records.json) + +Ask for a written response to these questions: + +1. Who authored each workpiece revision, and what in the supplied Flue records establishes that attribution? +2. What exact dispatch-crew quantity or resource policy is recorded? +3. What operation reserves the crew, and what operation returns it? +4. List every unresolved timing, failure, and recovery point. +5. What behavioral execution or operational-provenance claims, if any, can be made from these materials alone? + +Acceptance requires the human response to: + +- attribute revision zero to test preparation, not the model; +- attribute the later assistant record to model production; +- recover the exactly-one-crew policy and the intended reservation/return; +- preserve every timing, failure, and recovery unknown; and +- avoid inferring behavioral execution or capture provenance. + +Record the reviewer's identity, date, verbatim response, and explicit accept/reject decision below only after the review occurs. + +## Human verdict + +- Reviewer identity: friend +- Review date: 2026-09-04 +- Explicit decision: **ACCEPT** + +### Verbatim response + +```text +1. Authorship of each revision + + prepared-workpiece.md — test/harness-authored, not model-produced. + Discriminators in cold-reader-records.json → preparedRecord: + - role: "system", purpose: "dispatch", display: "diagnostic" — a system-injected diagnostic entry, not an assistant turn. No turnId. + - signal.tagName: "prepared-fixture" with attributes.authorship: "test-authored" and claimBoundary: "prepared-not-model-produced". + - The text part opens "Fixture authorship: test-authored preparation for Mission 6" and its runbook-ir block is content-identical to prepared-workpiece.md. + - The entry id entry_direct_c3ViX2lr… is entry_direct_ + base64 of its own submissionId (sub_ik_f24939…), consistent with a directly-inserted record rather + than a generated turn. + + latest-workpiece.md — assistant (model) authored. + Discriminators in revisedRecord: + - role: "assistant", purpose: "assistant", display: "visible", and a turnId (turn_01M1NQGQ…) — a model turn under a distinct submission (sub_ik_6dbc18…). + - The runbook-ir block inside that record is content-identical to latest-workpiece.md. + - No signal block / authorship attribute exists on this record; attribution rests on role alone. + + Two caveats a reader should hold: + - The assistant-authored revision's own Claim boundary still says "This is test-authored diagnostic material." That sentence is inherited prose and is wrong + for this revision per the record's role. The record, not the in-text sentence, is the discriminator. + - Neither record carries a timestamp, model identifier, or provider. The prepared→revised ordering is inferred from content ("Revised", "has been added") + and from the differing submission ids, not from metadata. Nothing in these records links the two submissions causally. + + 2. Recorded quantity / resource policy + + Both revisions: exactly one dispatch crew. "Starting final inspection consumes that one available crew; sign-off returns it." + + Differences between revisions: + - Prepared qualifies it "in this fixture"; revised drops the qualifier. + - Revised adds the general firing rule "No transition fires without sufficient tokens in all input places" and describes dispatch-crew-available as "(1 + token when free)". + + Note: the "exactly one" is stated as policy in prose. No initial marking appears in any of the three files (the assistant's JSON excerpt shows inputArcs + only), so the quantity is asserted, not shown. + + 3. Reserve / return operations + + - Reserves: Start final inspection / start-final-inspection, via a weight-1 standard input arc from dispatch-crew-available. + - Returns: Sign-off / sign-off, via an output arc to dispatch-crew-available. + + Evidence status within the packet: the prepared workpiece says the reserving arc is deliberately absent; the revised says it "has been added and verified." + The only support in these files is the assistant's self-quoted inputArcs snippet inside its own text — no tool result, snapshot, or hash. The sign-off→crew + return arc is asserted in prose in both revisions and never shown as data in any of the three files. + + 4. Unresolved timing, failure, and recovery points + + From the prepared revision (one sentence): inspection and sign-off timing, failure modes, recovery behavior. + + From the revised revision (enumerated): + 1. Inspection timing — duration, stochasticity, determinism. + 2. Sign-off timing — duration, stochasticity, determinism. + 3. Failure modes — whether inspection can fail, halt, or reject a batch. + 4. Recovery behavior — how failures/rejections affect batch state or crew availability. + + Also excluded by the revised Claim boundary (unresolved by omission): failure handling, full process projection, integration with upstream/downstream + operations. + + Reviewer observation (inference from the described net, not a stated unknown): as specified, the crew token is consumed by start-final-inspection and + returned only by sign-off. Any failure/reject path that does not pass through sign-off would leave the single crew permanently unavailable — i.e., items 3 + and 4 above are not independent; unresolved failure modes imply a potential deadlock in the sole-crew resource. Neither revision names this. + + 5. Behavioral-execution or operational-provenance claims supportable from these materials alone + + None. + - Both workpieces explicitly disclaim capture provenance and behavioral execution. + - No firing sequence, marking trace, simulation output, or tool-call result appears in any of the three files. + - The revised record's "Verification successful" / "verified in the live Petrinaut definition" is an assistant assertion supported only by the assistant's + own quoted JSON. From these files you can say the model claimed verification; you cannot say verification occurred, nor that the live definition contains + the arc. + - Operational provenance of the prepared fixture is established only to the extent "a system-role record with a test-authored signal exists" — not who/what + produced it, or when. +``` diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/cold-reader-records.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/cold-reader-records.json new file mode 100644 index 00000000000..75fd835682f --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/cold-reader-records.json @@ -0,0 +1,46 @@ +{ + "records": [ + { + "id": "entry_direct_c3ViX2lrXzI4ODYzMWVhYWQ3OThjYzY5MDcwZTMzMTNlOTUxYmNi", + "role": "system", + "purpose": "dispatch", + "display": "diagnostic", + "submissionId": "sub_ik_288631eaad798cc69070e3313e951bcb", + "signal": { + "tagName": "prepared-fixture", + "attributes": { + "fixtureId": "crew-reservation-v1", + "authorship": "test-authored", + "claimBoundary": "prepared-not-model-produced" + } + }, + "parts": [ + { + "type": "text", + "text": "Fixture authorship: test-authored preparation for Mission 6.\nNon-claims: not a Mission 4 candidate, not model-produced evidence, not capture-backed provenance, and not proof of automatic full-net projection.\n\n```runbook-ir\n# Final inspection and dispatch workpiece\n\n## Purpose and posture\nMaintain the narrow batch path from final inspection to dispatch readiness and test one evidence-backed correction against the live Petrinaut document.\n\n## Operational account\n- A batch that is ready enters final inspection.\n- Final inspection reserves the sole available dispatch crew.\n- Sign-off releases that crew and makes the batch ready for dispatch.\n\n## Quantity and resource policy\nExactly one dispatch crew is available in this fixture. Starting final inspection consumes that one available crew; sign-off returns it.\n\n## Current Petrinaut correspondence\nThe prepared non-empty net contains the batch path and the crew return from sign-off. It deliberately lacks the standard weight-1 input arc from `Dispatch crew available` to `Start final inspection`.\n\n## Explicit unknowns\nInspection and sign-off timing, failure modes, and recovery behavior remain unresolved.\n\n## Claim boundary\nThis prepared revision is test-authored diagnostic material. It is not model-produced evidence and does not establish capture provenance, behavioral execution, or broad projection quality.\n```", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NV6M4SBXB2WA46SM1B8QM3", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_d797b4c6053e5d0a144ec1547a22e0ca", + "turnId": "turn_01M1NV6KB8F7QJTRYHX0WT8AG5", + "parts": [ + { + "type": "reasoning", + "text": "Good! The arc has been successfully added. Looking at the final net definition, I can confirm:\n\n1. The arc was added successfully: `addArc` returned `\"applied\":true` with detail \"Dispatch crew available <-> Start final inspection\"\n\n2. In the final `getLatestNetDefinition` result, I can see that the `start-final-inspection` transition now has TWO input arcs:\n - `{\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"}`\n - `{\"type\":\"standard\",\"placeId\":\"dispatch-crew-available\",\"weight\":1\"}`\n\nThis confirms the missing arc from `Dispatch crew available` (weight 1, standard type) to `Start final inspection` is now in place.\n\nThe net structure is now:\n- **Places**: batch-ready, under-final-inspection, ready-for-dispatch, dispatch-crew-available\n- **Transitions**:\n - `start-final-inspection`: Takes a batch from batch-ready AND a crew token from dispatch-crew-available, produces under-final-inspection\n - `sign-off`: Takes under-final-inspection, produces both ready-for-dispatch AND returns dispatch-crew-available (crew token)\n\nThis correctly models the resource constraint: the single dispatch crew is reserved during inspection (consumed by start-final-inspection) and released at sign-off (produced by sign-off).\n\nNow I need to emit the revised runbook-ir workpiece, marking the revision as model-produced from test-authored revision zero.", + "state": "done" + }, + { + "type": "text", + "text": "✓ **Arc added successfully.** The Petrinaut tool confirms: `\"applied\":true` with detail \"Dispatch crew available ↔ Start final inspection\".\n\n**Verification of revised net structure:**\n- `Start final inspection` transition now has two standard input arcs (weight 1 each):\n 1. From `Batch ready` (original)\n 2. From `Dispatch crew available` (added, evidence-backed correction)\n- `Sign-off` transition correctly returns the crew token to `Dispatch crew available` (weight 1, output arc)\n\nThis enforces the resource constraint: the single dispatch crew is consumed when final inspection begins and restored at sign-off.\n\n---\n\n## Revised Workpiece (Model-Produced from Test-Authored Revision Zero)\n\n```runbook-ir\n# Final inspection and dispatch batch path\n\n## Purpose and posture\nModel the narrow batch path from final inspection to dispatch readiness with single-crew resource constraint. This revision incorporates the evidence-backed correction of the missing crew-availability input arc.\n\n## Operational account\n- A batch that is ready enters final inspection.\n- Final inspection requires and reserves the sole available dispatch crew.\n- Sign-off releases that crew and marks the batch ready for dispatch.\n\n## Quantity and resource policy\nExactly one dispatch crew is available in this system. Starting final inspection consumes that one available crew token; sign-off returns it. At most one batch can be under final inspection at a time because the sole crew is needed and cannot be in two places simultaneously.\n\n## Net structure (model-produced)\n**Places:**\n- `Batch ready`: batches waiting for inspection\n- `Under final inspection`: batches currently being inspected\n- `Ready for dispatch`: batches completed and awaiting dispatch\n- `Dispatch crew available`: availability token for the single crew (capacity 1)\n\n**Transitions:**\n- `Start final inspection`: consumes 1 batch token from `Batch ready` AND 1 crew token from `Dispatch crew available`; produces 1 token in `Under final inspection`\n- `Sign-off`: consumes 1 token from `Under final inspection`; produces 1 token each in `Ready for dispatch` and `Dispatch crew available` (returns the crew)\n\n**Arcs:**\n- `Batch ready` → `Start final inspection` (standard, weight 1) — original\n- `Dispatch crew available` → `Start final inspection` (standard, weight 1) — added in revision\n- `Start final inspection` → `Under final inspection` (standard, weight 1) — original\n- `Under final inspection` → `Sign-off` (standard, weight 1) — original\n- `Sign-off` → `Ready for dispatch` (standard, weight 1) — original\n- `Sign-off` → `Dispatch crew available` (standard, weight 1) — original\n\n## Explicit unknowns\n- Inspection and sign-off timing and duration\n- Failure modes, defect outcomes, and recovery behavior\n- Initial batch population and crew availability state\n- Repeat or recycling scenarios\n\n## Revision record\n**Revision 0** (test-authored): Prepared fixture identified missing standard weight-1 input arc from `Dispatch crew available` to `Start final inspection`.\n\n**Revision 1** (model-produced): Arc added via Petrinaut `addArc` tool and verified in net definition. Crew-availability constraint now enforced at net semantics level.\n\n## Claim boundary\nThis revision is model-produced evidence of arc correction applied to the test-authored source. It does not establish timing behavior, failure recovery, execution performance, or projection beyond this narrow batch-crew-inspection path.\n```", + "state": "done" + } + ] + } + ] +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/definition-after.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/definition-after.json new file mode 100644 index 00000000000..c92ed16c454 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/definition-after.json @@ -0,0 +1,98 @@ +{ + "places": [ + { + "id": "batch-ready", + "name": "Batch ready", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 80, + "y": 100 + }, + { + "id": "under-final-inspection", + "name": "Under final inspection", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 420, + "y": 100 + }, + { + "id": "ready-for-dispatch", + "name": "Ready for dispatch", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 760, + "y": 100 + }, + { + "id": "dispatch-crew-available", + "name": "Dispatch crew available", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 420, + "y": 360 + } + ], + "transitions": [ + { + "id": "start-final-inspection", + "name": "Start final inspection", + "inputArcs": [ + { + "placeId": "batch-ready", + "weight": 1, + "type": "standard" + }, + { + "type": "standard", + "placeId": "dispatch-crew-available", + "weight": 1 + } + ], + "outputArcs": [ + { + "placeId": "under-final-inspection", + "weight": 1 + } + ], + "lambdaType": "predicate", + "lambdaCode": "", + "transitionKernelCode": "", + "x": 250, + "y": 100 + }, + { + "id": "sign-off", + "name": "Sign-off", + "inputArcs": [ + { + "placeId": "under-final-inspection", + "weight": 1, + "type": "standard" + } + ], + "outputArcs": [ + { + "placeId": "ready-for-dispatch", + "weight": 1 + }, + { + "placeId": "dispatch-crew-available", + "weight": 1 + } + ], + "lambdaType": "predicate", + "lambdaCode": "", + "transitionKernelCode": "", + "x": 590, + "y": 100 + } + ], + "types": [], + "differentialEquations": [], + "parameters": [] +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/definition-before.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/definition-before.json new file mode 100644 index 00000000000..5803556bfe8 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/definition-before.json @@ -0,0 +1,93 @@ +{ + "places": [ + { + "id": "batch-ready", + "name": "Batch ready", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 80, + "y": 100 + }, + { + "id": "under-final-inspection", + "name": "Under final inspection", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 420, + "y": 100 + }, + { + "id": "ready-for-dispatch", + "name": "Ready for dispatch", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 760, + "y": 100 + }, + { + "id": "dispatch-crew-available", + "name": "Dispatch crew available", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 420, + "y": 360 + } + ], + "transitions": [ + { + "id": "start-final-inspection", + "name": "Start final inspection", + "inputArcs": [ + { + "placeId": "batch-ready", + "type": "standard", + "weight": 1 + } + ], + "outputArcs": [ + { + "placeId": "under-final-inspection", + "weight": 1 + } + ], + "lambdaType": "predicate", + "lambdaCode": "", + "transitionKernelCode": "", + "x": 250, + "y": 100 + }, + { + "id": "sign-off", + "name": "Sign-off", + "inputArcs": [ + { + "placeId": "under-final-inspection", + "type": "standard", + "weight": 1 + } + ], + "outputArcs": [ + { + "placeId": "ready-for-dispatch", + "weight": 1 + }, + { + "placeId": "dispatch-crew-available", + "weight": 1 + } + ], + "lambdaType": "predicate", + "lambdaCode": "", + "transitionKernelCode": "", + "x": 590, + "y": 100 + } + ], + "types": [], + "parameters": [], + "differentialEquations": [] +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/definition-tab-b.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/definition-tab-b.json new file mode 100644 index 00000000000..c92ed16c454 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/definition-tab-b.json @@ -0,0 +1,98 @@ +{ + "places": [ + { + "id": "batch-ready", + "name": "Batch ready", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 80, + "y": 100 + }, + { + "id": "under-final-inspection", + "name": "Under final inspection", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 420, + "y": 100 + }, + { + "id": "ready-for-dispatch", + "name": "Ready for dispatch", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 760, + "y": 100 + }, + { + "id": "dispatch-crew-available", + "name": "Dispatch crew available", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 420, + "y": 360 + } + ], + "transitions": [ + { + "id": "start-final-inspection", + "name": "Start final inspection", + "inputArcs": [ + { + "placeId": "batch-ready", + "weight": 1, + "type": "standard" + }, + { + "type": "standard", + "placeId": "dispatch-crew-available", + "weight": 1 + } + ], + "outputArcs": [ + { + "placeId": "under-final-inspection", + "weight": 1 + } + ], + "lambdaType": "predicate", + "lambdaCode": "", + "transitionKernelCode": "", + "x": 250, + "y": 100 + }, + { + "id": "sign-off", + "name": "Sign-off", + "inputArcs": [ + { + "placeId": "under-final-inspection", + "weight": 1, + "type": "standard" + } + ], + "outputArcs": [ + { + "placeId": "ready-for-dispatch", + "weight": 1 + }, + { + "placeId": "dispatch-crew-available", + "weight": 1 + } + ], + "lambdaType": "predicate", + "lambdaCode": "", + "transitionKernelCode": "", + "x": 590, + "y": 100 + } + ], + "types": [], + "differentialEquations": [], + "parameters": [] +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/flue-snapshot-after.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/flue-snapshot-after.json new file mode 100644 index 00000000000..b35e84df234 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/flue-snapshot-after.json @@ -0,0 +1,287 @@ +{ + "v": 1, + "conversationId": "conv_01M1NV5WZETMYEGGMFXNYDSTRS", + "offset": "0000000000000000_0000000000000092", + "messages": [ + { + "id": "entry_direct_c3ViX2lrXzI4ODYzMWVhYWQ3OThjYzY5MDcwZTMzMTNlOTUxYmNi", + "role": "system", + "purpose": "dispatch", + "display": "diagnostic", + "submissionId": "sub_ik_288631eaad798cc69070e3313e951bcb", + "signal": { + "tagName": "prepared-fixture", + "attributes": { + "fixtureId": "crew-reservation-v1", + "authorship": "test-authored", + "claimBoundary": "prepared-not-model-produced" + } + }, + "parts": [ + { + "type": "text", + "text": "Fixture authorship: test-authored preparation for Mission 6.\nNon-claims: not a Mission 4 candidate, not model-produced evidence, not capture-backed provenance, and not proof of automatic full-net projection.\n\n```runbook-ir\n# Final inspection and dispatch workpiece\n\n## Purpose and posture\nMaintain the narrow batch path from final inspection to dispatch readiness and test one evidence-backed correction against the live Petrinaut document.\n\n## Operational account\n- A batch that is ready enters final inspection.\n- Final inspection reserves the sole available dispatch crew.\n- Sign-off releases that crew and makes the batch ready for dispatch.\n\n## Quantity and resource policy\nExactly one dispatch crew is available in this fixture. Starting final inspection consumes that one available crew; sign-off returns it.\n\n## Current Petrinaut correspondence\nThe prepared non-empty net contains the batch path and the crew return from sign-off. It deliberately lacks the standard weight-1 input arc from `Dispatch crew available` to `Start final inspection`.\n\n## Explicit unknowns\nInspection and sign-off timing, failure modes, and recovery behavior remain unresolved.\n\n## Claim boundary\nThis prepared revision is test-authored diagnostic material. It is not model-produced evidence and does not establish capture provenance, behavioral execution, or broad projection quality.\n```", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NV5XQCBVP3FC4JW5FH1WZJ", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_288631eaad798cc69070e3313e951bcb", + "turnId": "turn_01M1NV5WZH2J0S74S1Q24556EP", + "parts": [ + { + "type": "reasoning", + "text": "This is a prepared fixture for a conversation about operational process modeling using SDCPN (stochastic dynamic coloured Petri nets) in Petrinaut. Let me understand what's being presented:\n\nThe fixture describes a batch processing system with final inspection and dispatch:\n- Batches enter final inspection when ready\n- Final inspection reserves the sole available dispatch crew\n- Sign-off releases the crew and marks the batch as ready for dispatch\n- There's exactly one dispatch crew available\n\nThe fixture notes that the current Petrinaut document has a deliberate gap: it's missing the standard weight-1 input arc from \"Dispatch crew available\" to \"Start final inspection\".\n\nThe task seems to be to:\n1. Maintain this narrow batch path from final inspection to dispatch readiness\n2. Test one evidence-backed correction against the live Petrinaut document\n3. This means likely adding that missing arc\n\nThe explicit unknowns are:\n- Inspection and sign-off timing\n- Failure modes and recovery behavior\n\nThis is a test-authored diagnostic material, not model-produced evidence.\n\nBefore I proceed, I should:\n1. Activate the `sdcpn-modelling` skill since this is about SDCPN modeling\n2. Get the current Petrinaut net definition to see what we're working with\n3. Understand the current state and the specific correction needed\n\nLet me start by activating the skill and getting the current net state.", + "state": "done" + }, + { + "type": "text", + "text": "I'll help you maintain and test this final inspection and dispatch workpiece. Let me start by activating the SDCPN modelling skill and examining the current Petrinaut net definition.", + "state": "done" + }, + { + "type": "dynamic-tool", + "toolName": "activate_skill", + "toolCallId": "toolu_01Y9HuAi2cvi16UD9bTvcvfS", + "state": "output-available", + "input": { + "name": "sdcpn-modelling" + }, + "output": "Run the skill named \"sdcpn-modelling\".\n\n\n# Capability-aware lifecycle\n\nUse one conceptual lifecycle: orient, elicit or revise, maintain the workpiece, construct when supported, check, and deliver. The current conversation may expose only one branch of that lifecycle. Do not claim that an unavailable transition occurred.\n\n## Select the runtime branch\n\n### Interactive elicitation or revision\n\nInterview in the person's operational vocabulary. Activate the `elicitation` skill and read `references/profile.md` before substantive questions or revision. Read `templates/workpiece.md` when creating or materially revising the shared workpiece. Construct only when the mounted capabilities actually permit construction in this conversation.\n\n### Construct-only execution\n\nUse the supplied workpiece as the complete modelling input. Do not interview. Read `references/pn-construction.md` and `references/checks.md`, then use the mounted construction tools. If a consequential workpiece gap prevents faithful construction, report the gap and the smallest question a later interactive elicitation must answer; do not ask it or invent an answer in this conversation.\n\n## Procedure\n\n### Orient\n\nEstablish enough purpose and context to select one focused next action: the intended question or decision, audience, boundary, horizon, accuracy need, and available time. Orientation need not settle every concern before elicitation begins.\n\n### Elicit or revise\n\nFor a new account, follow one concrete case and re-evaluate the active gap after each useful answer. For an existing account, first locate the disputed or changed material and its consequence for the objective. Use the `elicitation` skill's universal guidance and `references/profile.md` for detailed operations and coverage; do not turn their register order into question order.\n\n### Maintain the workpiece\n\nTreat the workpiece as the recoverable account construction will consume. Update it after a useful stretch rather than waiting until the end. Preserve unrelated material unless new evidence affects it.\n\nWhenever the workpiece changes substantially, emit the full current document in a fenced block whose language tag is exactly `runbook-ir`. Emit it again before construction and before workpiece-only delivery. A delta or prose promise is not a recoverable workpiece.\n\n### Construct\n\nConstruct only from the current workpiece. Read `references/pn-construction.md` and `references/checks.md` before beginning. Use mounted Petrinaut tools for every net change and inspect the resulting definition rather than emitting free-form net JSON. If the required tools are absent, limit the result to the workpiece and construction-ready notes.\n\nConstruction may infer a representation from recorded operational meaning; it may not invent operational facts. Record construction inferences, approximations, defaults, and target losses in the workpiece.\n\n### Check and deliver\n\nApply `references/checks.md` whenever construction is prepared or attempted. Deliver the current workpiece in every branch. Deliver a net only when the mounted tool path has produced and checked one. State what the result can support, what remains open, what was assumed or simplified, and what the target or current tools could not represent.\n\nAn explicit stop opens no new topic. In an interactive conversation, emit the best current workpiece and any already-checked net with limitations visible. In construct-only execution, report a blocking gap rather than opening an interview.\n\n## Resource discipline\n\nRead resources directly from this skill's advertised resource list, using the exact `/.flue/packaged-skills/...` path shown in the activation briefing; the relative name is a label only. Do not treat Markdown links as includes, follow references recursively, or read construction material merely to frame ordinary interview questions.\n\n\nSupporting skill resources are available but are not loaded into context unless needed:\n\n- references/checks.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/references/checks.md\n- references/pn-construction.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/references/pn-construction.md\n- references/profile.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/references/profile.md\n- templates/workpiece.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/templates/workpiece.md\n", + "durationMs": 1 + }, + { + "type": "dynamic-tool", + "toolName": "getLatestNetDefinition", + "toolCallId": "toolu_018ayLcg31aA5nZjvPe3VLEz", + "state": "output-available", + "input": {}, + "output": { + "awaiting": "client" + }, + "durationMs": 1 + }, + { + "type": "reasoning", + "text": "The getLatestNetDefinition returned awaiting client signal, meaning the client needs to load the current document. I should wait for that and then proceed. But let me think about what to do next.\n\nThe skill has been activated successfully. Now I need to:\n1. Wait for the net definition from the client\n2. Read the workpiece template to understand how to structure the workpiece\n3. Understand the current gaps and what needs to be corrected\n\nBased on the prepared fixture, the key issue is:\n- The current Petrinaut document is missing the weight-1 input arc from \"Dispatch crew available\" to \"Start final inspection\"\n- This is a deliberate gap that we need to test correcting\n\nLet me wait for the client signal and then proceed with getting the live document and understanding what needs to be corrected.", + "state": "done" + }, + { + "type": "text", + "text": "The skill is now active. I'm awaiting the current Petrinaut net definition from the client. Once that arrives, I'll examine the current state and identify the specific gap mentioned in the fixture—the missing input arc from `Dispatch crew available` to `Start final inspection`—and we can verify the evidence-backed correction.\n\nThe fixture establishes a clear scope:\n- **Operational focus**: The narrow batch path from final inspection through dispatch readiness\n- **Resource constraint**: Exactly one dispatch crew available, reserved during inspection, returned at sign-off\n- **Known gap**: Missing standard weight-1 arc from crew availability to the start of inspection\n- **Boundary**: Timing, failure modes, and recovery are explicitly unresolved\n\nI'm ready to proceed once the net definition loads. What would you like to examine or correct first?", + "state": "done" + } + ] + }, + { + "id": "entry_direct_c3ViX2lrXzIzMzcwMWRlZDcxMDVkNWQ0M2M0YjhhZTI1MTRlYzhi", + "role": "user", + "purpose": "user", + "display": "visible", + "submissionId": "sub_ik_233701ded7105d5d43c4b8ae2514ec8b", + "parts": [ + { + "type": "text", + "text": "Confirmed: final inspection uses the single dispatch crew and sign-off releases it; timing, failure, and recovery remain unknown. Read the live Petrinaut definition, add the missing standard weight-1 input arc from Dispatch crew available to Start final inspection, verify it, and emit the full revised runbook-ir workpiece. In that revised workpiece, identify the revision itself as model-produced from test-authored revision zero; do not call the revised workpiece test-authored.", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NV68Q36Q2ZMVFVMR3A2J1D", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_233701ded7105d5d43c4b8ae2514ec8b", + "turnId": "turn_01M1NV67W787NJDB98B4DVTMA1", + "parts": [ + { + "type": "reasoning", + "text": "The user wants me to:\n1. Read the live Petrinaut net definition\n2. Add the missing standard weight-1 input arc from \"Dispatch crew available\" to \"Start final inspection\"\n3. Verify the change\n4. Emit the full revised runbook-ir workpiece\n5. Label the revised workpiece as model-produced from test-authored revision zero (not test-authored itself)\n\nLet me start by reading the live definition, then adding the arc, then verifying it, and finally emitting the revised workpiece.", + "state": "done" + }, + { + "type": "dynamic-tool", + "toolName": "getLatestNetDefinition", + "toolCallId": "toolu_016Jkt4shRUg8hmtq6YyfcFB", + "state": "output-available", + "input": {}, + "output": { + "awaiting": "client" + }, + "durationMs": 1 + } + ] + }, + { + "id": "entry_direct_c3ViX2lrX2EzOGIxMTMzYjdjN2M2NWJmOGYwNzgxNGQyM2JjYmNi", + "role": "system", + "purpose": "dispatch", + "display": "diagnostic", + "submissionId": "sub_ik_a38b1133b7c7c65bf8f07814d23bcbcb", + "signal": { + "tagName": "client-tool-result", + "attributes": { + "toolCallIds": "toolu_016Jkt4shRUg8hmtq6YyfcFB" + } + }, + "parts": [ + { + "type": "text", + "text": "[{\"toolCallId\":\"toolu_016Jkt4shRUg8hmtq6YyfcFB\",\"toolName\":\"getLatestNetDefinition\",\"output\":{\"title\":\"Prepared final inspection and dispatch\",\"definition\":{\"places\":[{\"id\":\"batch-ready\",\"name\":\"Batch ready\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":80,\"y\":100},{\"id\":\"under-final-inspection\",\"name\":\"Under final inspection\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":100},{\"id\":\"ready-for-dispatch\",\"name\":\"Ready for dispatch\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":760,\"y\":100},{\"id\":\"dispatch-crew-available\",\"name\":\"Dispatch crew available\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":360}],\"transitions\":[{\"id\":\"start-final-inspection\",\"name\":\"Start final inspection\",\"inputArcs\":[{\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":250,\"y\":100},{\"id\":\"sign-off\",\"name\":\"Sign-off\",\"inputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"ready-for-dispatch\",\"weight\":1},{\"placeId\":\"dispatch-crew-available\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":590,\"y\":100}],\"types\":[],\"differentialEquations\":[],\"parameters\":[]},\"extensions\":{\"colors\":true,\"stochasticity\":true,\"dynamics\":true,\"parameters\":true,\"subnets\":true}}}]", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NV6ARKVMJTM74GVBKS6VW4", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_a38b1133b7c7c65bf8f07814d23bcbcb", + "turnId": "turn_01M1NV6A1766CSNYQR9H1HEBKH", + "parts": [ + { + "type": "reasoning", + "text": "The net definition has been loaded. Let me analyze the current state:\n\n**Current state:**\n- Places:\n - `batch-ready`: Batch waiting for final inspection\n - `under-final-inspection`: Batch undergoing final inspection\n - `ready-for-dispatch`: Batch ready for dispatch\n - `dispatch-crew-available`: Dispatch crew available (resource)\n\n- Transitions:\n - `start-final-inspection`: Takes a batch from `batch-ready` to `under-final-inspection`. It has one input arc from `batch-ready` with weight 1.\n - `sign-off`: Takes a batch from `under-final-inspection` to `ready-for-dispatch` and returns the crew to `dispatch-crew-available`. Has input arc from `under-final-inspection` (weight 1) and output arcs to both `ready-for-dispatch` and `dispatch-crew-available`.\n\n**The missing arc:**\nThe fixture states that the missing arc is: standard weight-1 input arc from `Dispatch crew available` to `Start final inspection`.\n\nCurrently, `start-final-inspection` only has one input arc from `batch-ready`. It needs an additional input arc from `dispatch-crew-available` with weight 1 and type \"standard\".\n\n**What needs to happen:**\n1. Add an input arc to the `start-final-inspection` transition from the `dispatch-crew-available` place with weight 1 and type \"standard\"\n2. Verify the result\n3. Emit the full revised workpiece with the identification that this is model-produced from test-authored revision zero\n\nLet me use the addArc function to add this arc.\n\nThe parameters for addArc based on the schema:\n- transitionId: \"start-final-inspection\"\n- arcDirection: \"input\"\n- placeId: \"dispatch-crew-available\" (since we're using the legacy shorthand)\n- weight: 1\n- type: \"standard\"\n- targetSubnetId omitted, since this operates on the root net", + "state": "done" + }, + { + "type": "dynamic-tool", + "toolName": "addArc", + "toolCallId": "toolu_01BQukCZTAhJ64VNE7oC1CWG", + "state": "output-available", + "input": { + "transitionId": "start-final-inspection", + "arcDirection": "input", + "placeId": "dispatch-crew-available", + "weight": "1", + "type": "standard" + }, + "output": { + "awaiting": "client" + }, + "durationMs": 0 + } + ] + }, + { + "id": "entry_direct_c3ViX2lrX2FmOWNjY2IxZTk1NzI5ZjkyNDk0NDA2NTE0NTE3Y2Nl", + "role": "system", + "purpose": "dispatch", + "display": "diagnostic", + "submissionId": "sub_ik_af9cccb1e95729f92494406514517cce", + "signal": { + "tagName": "client-tool-result", + "attributes": { + "toolCallIds": "toolu_016Jkt4shRUg8hmtq6YyfcFB,toolu_01BQukCZTAhJ64VNE7oC1CWG" + } + }, + "parts": [ + { + "type": "text", + "text": "[{\"toolCallId\":\"toolu_016Jkt4shRUg8hmtq6YyfcFB\",\"toolName\":\"getLatestNetDefinition\",\"output\":{\"title\":\"Prepared final inspection and dispatch\",\"definition\":{\"places\":[{\"id\":\"batch-ready\",\"name\":\"Batch ready\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":80,\"y\":100},{\"id\":\"under-final-inspection\",\"name\":\"Under final inspection\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":100},{\"id\":\"ready-for-dispatch\",\"name\":\"Ready for dispatch\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":760,\"y\":100},{\"id\":\"dispatch-crew-available\",\"name\":\"Dispatch crew available\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":360}],\"transitions\":[{\"id\":\"start-final-inspection\",\"name\":\"Start final inspection\",\"inputArcs\":[{\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":250,\"y\":100},{\"id\":\"sign-off\",\"name\":\"Sign-off\",\"inputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"ready-for-dispatch\",\"weight\":1},{\"placeId\":\"dispatch-crew-available\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":590,\"y\":100}],\"types\":[],\"differentialEquations\":[],\"parameters\":[]},\"extensions\":{\"colors\":true,\"stochasticity\":true,\"dynamics\":true,\"parameters\":true,\"subnets\":true}}},{\"toolCallId\":\"toolu_01BQukCZTAhJ64VNE7oC1CWG\",\"toolName\":\"addArc\",\"output\":{\"title\":\"Added input arc\",\"detail\":\"Dispatch crew available <-> Start final inspection\",\"target\":{\"kind\":\"selection\",\"item\":{\"type\":\"arc\",\"id\":\"$A_place:dispatch-crew-available___start-final-inspection\"}},\"applied\":true}}]", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NV6HRWJHSZ3QD2V8RZEWV3", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_af9cccb1e95729f92494406514517cce", + "turnId": "turn_01M1NV6GV7Q0BAMD0S09EEAY1E", + "parts": [ + { + "type": "reasoning", + "text": "Good! The arc has been added successfully. The tool output shows:\n- \"Applied: true\" - the arc was successfully added\n- Detail: \"Dispatch crew available <-> Start final inspection\"\n- The arc ID is \"$A_place:dispatch-crew-available___start-final-inspection\"\n\nNow I need to read the live net definition again to verify the change was applied correctly, then emit the revised workpiece with the full Markdown document showing the state of the net with the arc now in place.", + "state": "done" + }, + { + "type": "dynamic-tool", + "toolName": "getLatestNetDefinition", + "toolCallId": "toolu_017Ze5BnyBGXdaw7DJSGxZQb", + "state": "output-available", + "input": {}, + "output": { + "awaiting": "client" + }, + "durationMs": 0 + } + ] + }, + { + "id": "entry_direct_c3ViX2lrX2Q3OTdiNGM2MDUzZTVkMGExNDRlYzE1NDdhMjJlMGNh", + "role": "system", + "purpose": "dispatch", + "display": "diagnostic", + "submissionId": "sub_ik_d797b4c6053e5d0a144ec1547a22e0ca", + "signal": { + "tagName": "client-tool-result", + "attributes": { + "toolCallIds": "toolu_016Jkt4shRUg8hmtq6YyfcFB,toolu_01BQukCZTAhJ64VNE7oC1CWG,toolu_017Ze5BnyBGXdaw7DJSGxZQb" + } + }, + "parts": [ + { + "type": "text", + "text": "[{\"toolCallId\":\"toolu_016Jkt4shRUg8hmtq6YyfcFB\",\"toolName\":\"getLatestNetDefinition\",\"output\":{\"title\":\"Prepared final inspection and dispatch\",\"definition\":{\"places\":[{\"id\":\"batch-ready\",\"name\":\"Batch ready\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":80,\"y\":100},{\"id\":\"under-final-inspection\",\"name\":\"Under final inspection\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":100},{\"id\":\"ready-for-dispatch\",\"name\":\"Ready for dispatch\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":760,\"y\":100},{\"id\":\"dispatch-crew-available\",\"name\":\"Dispatch crew available\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":360}],\"transitions\":[{\"id\":\"start-final-inspection\",\"name\":\"Start final inspection\",\"inputArcs\":[{\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":250,\"y\":100},{\"id\":\"sign-off\",\"name\":\"Sign-off\",\"inputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"ready-for-dispatch\",\"weight\":1},{\"placeId\":\"dispatch-crew-available\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":590,\"y\":100}],\"types\":[],\"differentialEquations\":[],\"parameters\":[]},\"extensions\":{\"colors\":true,\"stochasticity\":true,\"dynamics\":true,\"parameters\":true,\"subnets\":true}}},{\"toolCallId\":\"toolu_01BQukCZTAhJ64VNE7oC1CWG\",\"toolName\":\"addArc\",\"output\":{\"title\":\"Added input arc\",\"detail\":\"Dispatch crew available <-> Start final inspection\",\"target\":{\"kind\":\"selection\",\"item\":{\"type\":\"arc\",\"id\":\"$A_place:dispatch-crew-available___start-final-inspection\"}},\"applied\":true}},{\"toolCallId\":\"toolu_017Ze5BnyBGXdaw7DJSGxZQb\",\"toolName\":\"getLatestNetDefinition\",\"output\":{\"title\":\"Prepared final inspection and dispatch\",\"definition\":{\"places\":[{\"id\":\"batch-ready\",\"name\":\"Batch ready\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":80,\"y\":100},{\"id\":\"under-final-inspection\",\"name\":\"Under final inspection\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":100},{\"id\":\"ready-for-dispatch\",\"name\":\"Ready for dispatch\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":760,\"y\":100},{\"id\":\"dispatch-crew-available\",\"name\":\"Dispatch crew available\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":360}],\"transitions\":[{\"id\":\"start-final-inspection\",\"name\":\"Start final inspection\",\"inputArcs\":[{\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"},{\"type\":\"standard\",\"placeId\":\"dispatch-crew-available\",\"weight\":1}],\"outputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":250,\"y\":100},{\"id\":\"sign-off\",\"name\":\"Sign-off\",\"inputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"ready-for-dispatch\",\"weight\":1},{\"placeId\":\"dispatch-crew-available\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":590,\"y\":100}],\"types\":[],\"differentialEquations\":[],\"parameters\":[]},\"extensions\":{\"colors\":true,\"stochasticity\":true,\"dynamics\":true,\"parameters\":true,\"subnets\":true}}}]", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NV6M4SBXB2WA46SM1B8QM3", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_d797b4c6053e5d0a144ec1547a22e0ca", + "turnId": "turn_01M1NV6KB8F7QJTRYHX0WT8AG5", + "parts": [ + { + "type": "reasoning", + "text": "Good! The arc has been successfully added. Looking at the final net definition, I can confirm:\n\n1. The arc was added successfully: `addArc` returned `\"applied\":true` with detail \"Dispatch crew available <-> Start final inspection\"\n\n2. In the final `getLatestNetDefinition` result, I can see that the `start-final-inspection` transition now has TWO input arcs:\n - `{\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"}`\n - `{\"type\":\"standard\",\"placeId\":\"dispatch-crew-available\",\"weight\":1\"}`\n\nThis confirms the missing arc from `Dispatch crew available` (weight 1, standard type) to `Start final inspection` is now in place.\n\nThe net structure is now:\n- **Places**: batch-ready, under-final-inspection, ready-for-dispatch, dispatch-crew-available\n- **Transitions**:\n - `start-final-inspection`: Takes a batch from batch-ready AND a crew token from dispatch-crew-available, produces under-final-inspection\n - `sign-off`: Takes under-final-inspection, produces both ready-for-dispatch AND returns dispatch-crew-available (crew token)\n\nThis correctly models the resource constraint: the single dispatch crew is reserved during inspection (consumed by start-final-inspection) and released at sign-off (produced by sign-off).\n\nNow I need to emit the revised runbook-ir workpiece, marking the revision as model-produced from test-authored revision zero.", + "state": "done" + }, + { + "type": "text", + "text": "✓ **Arc added successfully.** The Petrinaut tool confirms: `\"applied\":true` with detail \"Dispatch crew available ↔ Start final inspection\".\n\n**Verification of revised net structure:**\n- `Start final inspection` transition now has two standard input arcs (weight 1 each):\n 1. From `Batch ready` (original)\n 2. From `Dispatch crew available` (added, evidence-backed correction)\n- `Sign-off` transition correctly returns the crew token to `Dispatch crew available` (weight 1, output arc)\n\nThis enforces the resource constraint: the single dispatch crew is consumed when final inspection begins and restored at sign-off.\n\n---\n\n## Revised Workpiece (Model-Produced from Test-Authored Revision Zero)\n\n```runbook-ir\n# Final inspection and dispatch batch path\n\n## Purpose and posture\nModel the narrow batch path from final inspection to dispatch readiness with single-crew resource constraint. This revision incorporates the evidence-backed correction of the missing crew-availability input arc.\n\n## Operational account\n- A batch that is ready enters final inspection.\n- Final inspection requires and reserves the sole available dispatch crew.\n- Sign-off releases that crew and marks the batch ready for dispatch.\n\n## Quantity and resource policy\nExactly one dispatch crew is available in this system. Starting final inspection consumes that one available crew token; sign-off returns it. At most one batch can be under final inspection at a time because the sole crew is needed and cannot be in two places simultaneously.\n\n## Net structure (model-produced)\n**Places:**\n- `Batch ready`: batches waiting for inspection\n- `Under final inspection`: batches currently being inspected\n- `Ready for dispatch`: batches completed and awaiting dispatch\n- `Dispatch crew available`: availability token for the single crew (capacity 1)\n\n**Transitions:**\n- `Start final inspection`: consumes 1 batch token from `Batch ready` AND 1 crew token from `Dispatch crew available`; produces 1 token in `Under final inspection`\n- `Sign-off`: consumes 1 token from `Under final inspection`; produces 1 token each in `Ready for dispatch` and `Dispatch crew available` (returns the crew)\n\n**Arcs:**\n- `Batch ready` → `Start final inspection` (standard, weight 1) — original\n- `Dispatch crew available` → `Start final inspection` (standard, weight 1) — added in revision\n- `Start final inspection` → `Under final inspection` (standard, weight 1) — original\n- `Under final inspection` → `Sign-off` (standard, weight 1) — original\n- `Sign-off` → `Ready for dispatch` (standard, weight 1) — original\n- `Sign-off` → `Dispatch crew available` (standard, weight 1) — original\n\n## Explicit unknowns\n- Inspection and sign-off timing and duration\n- Failure modes, defect outcomes, and recovery behavior\n- Initial batch population and crew availability state\n- Repeat or recycling scenarios\n\n## Revision record\n**Revision 0** (test-authored): Prepared fixture identified missing standard weight-1 input arc from `Dispatch crew available` to `Start final inspection`.\n\n**Revision 1** (model-produced): Arc added via Petrinaut `addArc` tool and verified in net definition. Crew-availability constraint now enforced at net semantics level.\n\n## Claim boundary\nThis revision is model-produced evidence of arc correction applied to the test-authored source. It does not establish timing behavior, failure recovery, execution performance, or projection beyond this narrow batch-crew-inspection path.\n```", + "state": "done" + } + ] + } + ], + "settlements": [ + { + "submissionId": "sub_ik_288631eaad798cc69070e3313e951bcb", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_288631eaad798cc69070e3313e951bcb" + }, + { + "submissionId": "sub_ik_233701ded7105d5d43c4b8ae2514ec8b", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_233701ded7105d5d43c4b8ae2514ec8b" + }, + { + "submissionId": "sub_ik_a38b1133b7c7c65bf8f07814d23bcbcb", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_a38b1133b7c7c65bf8f07814d23bcbcb" + }, + { + "submissionId": "sub_ik_af9cccb1e95729f92494406514517cce", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_af9cccb1e95729f92494406514517cce" + }, + { + "submissionId": "sub_ik_d797b4c6053e5d0a144ec1547a22e0ca", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_d797b4c6053e5d0a144ec1547a22e0ca" + } + ], + "incarnation": "inc_01M1NV5WZD6VQ76Z7C3JJRFFBA" +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/flue-snapshot-before.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/flue-snapshot-before.json new file mode 100644 index 00000000000..ab6482d39be --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/flue-snapshot-before.json @@ -0,0 +1,89 @@ +{ + "v": 1, + "conversationId": "conv_01M1NV5WZETMYEGGMFXNYDSTRS", + "offset": "0000000000000000_0000000000000032", + "messages": [ + { + "id": "entry_direct_c3ViX2lrXzI4ODYzMWVhYWQ3OThjYzY5MDcwZTMzMTNlOTUxYmNi", + "role": "system", + "purpose": "dispatch", + "display": "diagnostic", + "submissionId": "sub_ik_288631eaad798cc69070e3313e951bcb", + "signal": { + "tagName": "prepared-fixture", + "attributes": { + "fixtureId": "crew-reservation-v1", + "authorship": "test-authored", + "claimBoundary": "prepared-not-model-produced" + } + }, + "parts": [ + { + "type": "text", + "text": "Fixture authorship: test-authored preparation for Mission 6.\nNon-claims: not a Mission 4 candidate, not model-produced evidence, not capture-backed provenance, and not proof of automatic full-net projection.\n\n```runbook-ir\n# Final inspection and dispatch workpiece\n\n## Purpose and posture\nMaintain the narrow batch path from final inspection to dispatch readiness and test one evidence-backed correction against the live Petrinaut document.\n\n## Operational account\n- A batch that is ready enters final inspection.\n- Final inspection reserves the sole available dispatch crew.\n- Sign-off releases that crew and makes the batch ready for dispatch.\n\n## Quantity and resource policy\nExactly one dispatch crew is available in this fixture. Starting final inspection consumes that one available crew; sign-off returns it.\n\n## Current Petrinaut correspondence\nThe prepared non-empty net contains the batch path and the crew return from sign-off. It deliberately lacks the standard weight-1 input arc from `Dispatch crew available` to `Start final inspection`.\n\n## Explicit unknowns\nInspection and sign-off timing, failure modes, and recovery behavior remain unresolved.\n\n## Claim boundary\nThis prepared revision is test-authored diagnostic material. It is not model-produced evidence and does not establish capture provenance, behavioral execution, or broad projection quality.\n```", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NV5XQCBVP3FC4JW5FH1WZJ", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_288631eaad798cc69070e3313e951bcb", + "turnId": "turn_01M1NV5WZH2J0S74S1Q24556EP", + "parts": [ + { + "type": "reasoning", + "text": "This is a prepared fixture for a conversation about operational process modeling using SDCPN (stochastic dynamic coloured Petri nets) in Petrinaut. Let me understand what's being presented:\n\nThe fixture describes a batch processing system with final inspection and dispatch:\n- Batches enter final inspection when ready\n- Final inspection reserves the sole available dispatch crew\n- Sign-off releases the crew and marks the batch as ready for dispatch\n- There's exactly one dispatch crew available\n\nThe fixture notes that the current Petrinaut document has a deliberate gap: it's missing the standard weight-1 input arc from \"Dispatch crew available\" to \"Start final inspection\".\n\nThe task seems to be to:\n1. Maintain this narrow batch path from final inspection to dispatch readiness\n2. Test one evidence-backed correction against the live Petrinaut document\n3. This means likely adding that missing arc\n\nThe explicit unknowns are:\n- Inspection and sign-off timing\n- Failure modes and recovery behavior\n\nThis is a test-authored diagnostic material, not model-produced evidence.\n\nBefore I proceed, I should:\n1. Activate the `sdcpn-modelling` skill since this is about SDCPN modeling\n2. Get the current Petrinaut net definition to see what we're working with\n3. Understand the current state and the specific correction needed\n\nLet me start by activating the skill and getting the current net state.", + "state": "done" + }, + { + "type": "text", + "text": "I'll help you maintain and test this final inspection and dispatch workpiece. Let me start by activating the SDCPN modelling skill and examining the current Petrinaut net definition.", + "state": "done" + }, + { + "type": "dynamic-tool", + "toolName": "activate_skill", + "toolCallId": "toolu_01Y9HuAi2cvi16UD9bTvcvfS", + "state": "output-available", + "input": { + "name": "sdcpn-modelling" + }, + "output": "Run the skill named \"sdcpn-modelling\".\n\n\n# Capability-aware lifecycle\n\nUse one conceptual lifecycle: orient, elicit or revise, maintain the workpiece, construct when supported, check, and deliver. The current conversation may expose only one branch of that lifecycle. Do not claim that an unavailable transition occurred.\n\n## Select the runtime branch\n\n### Interactive elicitation or revision\n\nInterview in the person's operational vocabulary. Activate the `elicitation` skill and read `references/profile.md` before substantive questions or revision. Read `templates/workpiece.md` when creating or materially revising the shared workpiece. Construct only when the mounted capabilities actually permit construction in this conversation.\n\n### Construct-only execution\n\nUse the supplied workpiece as the complete modelling input. Do not interview. Read `references/pn-construction.md` and `references/checks.md`, then use the mounted construction tools. If a consequential workpiece gap prevents faithful construction, report the gap and the smallest question a later interactive elicitation must answer; do not ask it or invent an answer in this conversation.\n\n## Procedure\n\n### Orient\n\nEstablish enough purpose and context to select one focused next action: the intended question or decision, audience, boundary, horizon, accuracy need, and available time. Orientation need not settle every concern before elicitation begins.\n\n### Elicit or revise\n\nFor a new account, follow one concrete case and re-evaluate the active gap after each useful answer. For an existing account, first locate the disputed or changed material and its consequence for the objective. Use the `elicitation` skill's universal guidance and `references/profile.md` for detailed operations and coverage; do not turn their register order into question order.\n\n### Maintain the workpiece\n\nTreat the workpiece as the recoverable account construction will consume. Update it after a useful stretch rather than waiting until the end. Preserve unrelated material unless new evidence affects it.\n\nWhenever the workpiece changes substantially, emit the full current document in a fenced block whose language tag is exactly `runbook-ir`. Emit it again before construction and before workpiece-only delivery. A delta or prose promise is not a recoverable workpiece.\n\n### Construct\n\nConstruct only from the current workpiece. Read `references/pn-construction.md` and `references/checks.md` before beginning. Use mounted Petrinaut tools for every net change and inspect the resulting definition rather than emitting free-form net JSON. If the required tools are absent, limit the result to the workpiece and construction-ready notes.\n\nConstruction may infer a representation from recorded operational meaning; it may not invent operational facts. Record construction inferences, approximations, defaults, and target losses in the workpiece.\n\n### Check and deliver\n\nApply `references/checks.md` whenever construction is prepared or attempted. Deliver the current workpiece in every branch. Deliver a net only when the mounted tool path has produced and checked one. State what the result can support, what remains open, what was assumed or simplified, and what the target or current tools could not represent.\n\nAn explicit stop opens no new topic. In an interactive conversation, emit the best current workpiece and any already-checked net with limitations visible. In construct-only execution, report a blocking gap rather than opening an interview.\n\n## Resource discipline\n\nRead resources directly from this skill's advertised resource list, using the exact `/.flue/packaged-skills/...` path shown in the activation briefing; the relative name is a label only. Do not treat Markdown links as includes, follow references recursively, or read construction material merely to frame ordinary interview questions.\n\n\nSupporting skill resources are available but are not loaded into context unless needed:\n\n- references/checks.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/references/checks.md\n- references/pn-construction.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/references/pn-construction.md\n- references/profile.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/references/profile.md\n- templates/workpiece.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/templates/workpiece.md\n", + "durationMs": 1 + }, + { + "type": "dynamic-tool", + "toolName": "getLatestNetDefinition", + "toolCallId": "toolu_018ayLcg31aA5nZjvPe3VLEz", + "state": "output-available", + "input": {}, + "output": { + "awaiting": "client" + }, + "durationMs": 1 + }, + { + "type": "reasoning", + "text": "The getLatestNetDefinition returned awaiting client signal, meaning the client needs to load the current document. I should wait for that and then proceed. But let me think about what to do next.\n\nThe skill has been activated successfully. Now I need to:\n1. Wait for the net definition from the client\n2. Read the workpiece template to understand how to structure the workpiece\n3. Understand the current gaps and what needs to be corrected\n\nBased on the prepared fixture, the key issue is:\n- The current Petrinaut document is missing the weight-1 input arc from \"Dispatch crew available\" to \"Start final inspection\"\n- This is a deliberate gap that we need to test correcting\n\nLet me wait for the client signal and then proceed with getting the live document and understanding what needs to be corrected.", + "state": "done" + }, + { + "type": "text", + "text": "The skill is now active. I'm awaiting the current Petrinaut net definition from the client. Once that arrives, I'll examine the current state and identify the specific gap mentioned in the fixture—the missing input arc from `Dispatch crew available` to `Start final inspection`—and we can verify the evidence-backed correction.\n\nThe fixture establishes a clear scope:\n- **Operational focus**: The narrow batch path from final inspection through dispatch readiness\n- **Resource constraint**: Exactly one dispatch crew available, reserved during inspection, returned at sign-off\n- **Known gap**: Missing standard weight-1 arc from crew availability to the start of inspection\n- **Boundary**: Timing, failure modes, and recovery are explicitly unresolved\n\nI'm ready to proceed once the net definition loads. What would you like to examine or correct first?", + "state": "done" + } + ] + } + ], + "settlements": [ + { + "submissionId": "sub_ik_288631eaad798cc69070e3313e951bcb", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_288631eaad798cc69070e3313e951bcb" + } + ], + "incarnation": "inc_01M1NV5WZD6VQ76Z7C3JJRFFBA" +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/flue-snapshot-tab-b.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/flue-snapshot-tab-b.json new file mode 100644 index 00000000000..c0f8e5b5153 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/flue-snapshot-tab-b.json @@ -0,0 +1,326 @@ +{ + "v": 1, + "conversationId": "conv_01M1NV5WZETMYEGGMFXNYDSTRS", + "offset": "0000000000000000_0000000000000110", + "messages": [ + { + "id": "entry_direct_c3ViX2lrXzI4ODYzMWVhYWQ3OThjYzY5MDcwZTMzMTNlOTUxYmNi", + "role": "system", + "purpose": "dispatch", + "display": "diagnostic", + "submissionId": "sub_ik_288631eaad798cc69070e3313e951bcb", + "signal": { + "tagName": "prepared-fixture", + "attributes": { + "fixtureId": "crew-reservation-v1", + "authorship": "test-authored", + "claimBoundary": "prepared-not-model-produced" + } + }, + "parts": [ + { + "type": "text", + "text": "Fixture authorship: test-authored preparation for Mission 6.\nNon-claims: not a Mission 4 candidate, not model-produced evidence, not capture-backed provenance, and not proof of automatic full-net projection.\n\n```runbook-ir\n# Final inspection and dispatch workpiece\n\n## Purpose and posture\nMaintain the narrow batch path from final inspection to dispatch readiness and test one evidence-backed correction against the live Petrinaut document.\n\n## Operational account\n- A batch that is ready enters final inspection.\n- Final inspection reserves the sole available dispatch crew.\n- Sign-off releases that crew and makes the batch ready for dispatch.\n\n## Quantity and resource policy\nExactly one dispatch crew is available in this fixture. Starting final inspection consumes that one available crew; sign-off returns it.\n\n## Current Petrinaut correspondence\nThe prepared non-empty net contains the batch path and the crew return from sign-off. It deliberately lacks the standard weight-1 input arc from `Dispatch crew available` to `Start final inspection`.\n\n## Explicit unknowns\nInspection and sign-off timing, failure modes, and recovery behavior remain unresolved.\n\n## Claim boundary\nThis prepared revision is test-authored diagnostic material. It is not model-produced evidence and does not establish capture provenance, behavioral execution, or broad projection quality.\n```", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NV5XQCBVP3FC4JW5FH1WZJ", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_288631eaad798cc69070e3313e951bcb", + "turnId": "turn_01M1NV5WZH2J0S74S1Q24556EP", + "parts": [ + { + "type": "reasoning", + "text": "This is a prepared fixture for a conversation about operational process modeling using SDCPN (stochastic dynamic coloured Petri nets) in Petrinaut. Let me understand what's being presented:\n\nThe fixture describes a batch processing system with final inspection and dispatch:\n- Batches enter final inspection when ready\n- Final inspection reserves the sole available dispatch crew\n- Sign-off releases the crew and marks the batch as ready for dispatch\n- There's exactly one dispatch crew available\n\nThe fixture notes that the current Petrinaut document has a deliberate gap: it's missing the standard weight-1 input arc from \"Dispatch crew available\" to \"Start final inspection\".\n\nThe task seems to be to:\n1. Maintain this narrow batch path from final inspection to dispatch readiness\n2. Test one evidence-backed correction against the live Petrinaut document\n3. This means likely adding that missing arc\n\nThe explicit unknowns are:\n- Inspection and sign-off timing\n- Failure modes and recovery behavior\n\nThis is a test-authored diagnostic material, not model-produced evidence.\n\nBefore I proceed, I should:\n1. Activate the `sdcpn-modelling` skill since this is about SDCPN modeling\n2. Get the current Petrinaut net definition to see what we're working with\n3. Understand the current state and the specific correction needed\n\nLet me start by activating the skill and getting the current net state.", + "state": "done" + }, + { + "type": "text", + "text": "I'll help you maintain and test this final inspection and dispatch workpiece. Let me start by activating the SDCPN modelling skill and examining the current Petrinaut net definition.", + "state": "done" + }, + { + "type": "dynamic-tool", + "toolName": "activate_skill", + "toolCallId": "toolu_01Y9HuAi2cvi16UD9bTvcvfS", + "state": "output-available", + "input": { + "name": "sdcpn-modelling" + }, + "output": "Run the skill named \"sdcpn-modelling\".\n\n\n# Capability-aware lifecycle\n\nUse one conceptual lifecycle: orient, elicit or revise, maintain the workpiece, construct when supported, check, and deliver. The current conversation may expose only one branch of that lifecycle. Do not claim that an unavailable transition occurred.\n\n## Select the runtime branch\n\n### Interactive elicitation or revision\n\nInterview in the person's operational vocabulary. Activate the `elicitation` skill and read `references/profile.md` before substantive questions or revision. Read `templates/workpiece.md` when creating or materially revising the shared workpiece. Construct only when the mounted capabilities actually permit construction in this conversation.\n\n### Construct-only execution\n\nUse the supplied workpiece as the complete modelling input. Do not interview. Read `references/pn-construction.md` and `references/checks.md`, then use the mounted construction tools. If a consequential workpiece gap prevents faithful construction, report the gap and the smallest question a later interactive elicitation must answer; do not ask it or invent an answer in this conversation.\n\n## Procedure\n\n### Orient\n\nEstablish enough purpose and context to select one focused next action: the intended question or decision, audience, boundary, horizon, accuracy need, and available time. Orientation need not settle every concern before elicitation begins.\n\n### Elicit or revise\n\nFor a new account, follow one concrete case and re-evaluate the active gap after each useful answer. For an existing account, first locate the disputed or changed material and its consequence for the objective. Use the `elicitation` skill's universal guidance and `references/profile.md` for detailed operations and coverage; do not turn their register order into question order.\n\n### Maintain the workpiece\n\nTreat the workpiece as the recoverable account construction will consume. Update it after a useful stretch rather than waiting until the end. Preserve unrelated material unless new evidence affects it.\n\nWhenever the workpiece changes substantially, emit the full current document in a fenced block whose language tag is exactly `runbook-ir`. Emit it again before construction and before workpiece-only delivery. A delta or prose promise is not a recoverable workpiece.\n\n### Construct\n\nConstruct only from the current workpiece. Read `references/pn-construction.md` and `references/checks.md` before beginning. Use mounted Petrinaut tools for every net change and inspect the resulting definition rather than emitting free-form net JSON. If the required tools are absent, limit the result to the workpiece and construction-ready notes.\n\nConstruction may infer a representation from recorded operational meaning; it may not invent operational facts. Record construction inferences, approximations, defaults, and target losses in the workpiece.\n\n### Check and deliver\n\nApply `references/checks.md` whenever construction is prepared or attempted. Deliver the current workpiece in every branch. Deliver a net only when the mounted tool path has produced and checked one. State what the result can support, what remains open, what was assumed or simplified, and what the target or current tools could not represent.\n\nAn explicit stop opens no new topic. In an interactive conversation, emit the best current workpiece and any already-checked net with limitations visible. In construct-only execution, report a blocking gap rather than opening an interview.\n\n## Resource discipline\n\nRead resources directly from this skill's advertised resource list, using the exact `/.flue/packaged-skills/...` path shown in the activation briefing; the relative name is a label only. Do not treat Markdown links as includes, follow references recursively, or read construction material merely to frame ordinary interview questions.\n\n\nSupporting skill resources are available but are not loaded into context unless needed:\n\n- references/checks.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/references/checks.md\n- references/pn-construction.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/references/pn-construction.md\n- references/profile.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/references/profile.md\n- templates/workpiece.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/templates/workpiece.md\n", + "durationMs": 1 + }, + { + "type": "dynamic-tool", + "toolName": "getLatestNetDefinition", + "toolCallId": "toolu_018ayLcg31aA5nZjvPe3VLEz", + "state": "output-available", + "input": {}, + "output": { + "awaiting": "client" + }, + "durationMs": 1 + }, + { + "type": "reasoning", + "text": "The getLatestNetDefinition returned awaiting client signal, meaning the client needs to load the current document. I should wait for that and then proceed. But let me think about what to do next.\n\nThe skill has been activated successfully. Now I need to:\n1. Wait for the net definition from the client\n2. Read the workpiece template to understand how to structure the workpiece\n3. Understand the current gaps and what needs to be corrected\n\nBased on the prepared fixture, the key issue is:\n- The current Petrinaut document is missing the weight-1 input arc from \"Dispatch crew available\" to \"Start final inspection\"\n- This is a deliberate gap that we need to test correcting\n\nLet me wait for the client signal and then proceed with getting the live document and understanding what needs to be corrected.", + "state": "done" + }, + { + "type": "text", + "text": "The skill is now active. I'm awaiting the current Petrinaut net definition from the client. Once that arrives, I'll examine the current state and identify the specific gap mentioned in the fixture—the missing input arc from `Dispatch crew available` to `Start final inspection`—and we can verify the evidence-backed correction.\n\nThe fixture establishes a clear scope:\n- **Operational focus**: The narrow batch path from final inspection through dispatch readiness\n- **Resource constraint**: Exactly one dispatch crew available, reserved during inspection, returned at sign-off\n- **Known gap**: Missing standard weight-1 arc from crew availability to the start of inspection\n- **Boundary**: Timing, failure modes, and recovery are explicitly unresolved\n\nI'm ready to proceed once the net definition loads. What would you like to examine or correct first?", + "state": "done" + } + ] + }, + { + "id": "entry_direct_c3ViX2lrXzIzMzcwMWRlZDcxMDVkNWQ0M2M0YjhhZTI1MTRlYzhi", + "role": "user", + "purpose": "user", + "display": "visible", + "submissionId": "sub_ik_233701ded7105d5d43c4b8ae2514ec8b", + "parts": [ + { + "type": "text", + "text": "Confirmed: final inspection uses the single dispatch crew and sign-off releases it; timing, failure, and recovery remain unknown. Read the live Petrinaut definition, add the missing standard weight-1 input arc from Dispatch crew available to Start final inspection, verify it, and emit the full revised runbook-ir workpiece. In that revised workpiece, identify the revision itself as model-produced from test-authored revision zero; do not call the revised workpiece test-authored.", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NV68Q36Q2ZMVFVMR3A2J1D", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_233701ded7105d5d43c4b8ae2514ec8b", + "turnId": "turn_01M1NV67W787NJDB98B4DVTMA1", + "parts": [ + { + "type": "reasoning", + "text": "The user wants me to:\n1. Read the live Petrinaut net definition\n2. Add the missing standard weight-1 input arc from \"Dispatch crew available\" to \"Start final inspection\"\n3. Verify the change\n4. Emit the full revised runbook-ir workpiece\n5. Label the revised workpiece as model-produced from test-authored revision zero (not test-authored itself)\n\nLet me start by reading the live definition, then adding the arc, then verifying it, and finally emitting the revised workpiece.", + "state": "done" + }, + { + "type": "dynamic-tool", + "toolName": "getLatestNetDefinition", + "toolCallId": "toolu_016Jkt4shRUg8hmtq6YyfcFB", + "state": "output-available", + "input": {}, + "output": { + "awaiting": "client" + }, + "durationMs": 1 + } + ] + }, + { + "id": "entry_direct_c3ViX2lrX2EzOGIxMTMzYjdjN2M2NWJmOGYwNzgxNGQyM2JjYmNi", + "role": "system", + "purpose": "dispatch", + "display": "diagnostic", + "submissionId": "sub_ik_a38b1133b7c7c65bf8f07814d23bcbcb", + "signal": { + "tagName": "client-tool-result", + "attributes": { + "toolCallIds": "toolu_016Jkt4shRUg8hmtq6YyfcFB" + } + }, + "parts": [ + { + "type": "text", + "text": "[{\"toolCallId\":\"toolu_016Jkt4shRUg8hmtq6YyfcFB\",\"toolName\":\"getLatestNetDefinition\",\"output\":{\"title\":\"Prepared final inspection and dispatch\",\"definition\":{\"places\":[{\"id\":\"batch-ready\",\"name\":\"Batch ready\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":80,\"y\":100},{\"id\":\"under-final-inspection\",\"name\":\"Under final inspection\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":100},{\"id\":\"ready-for-dispatch\",\"name\":\"Ready for dispatch\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":760,\"y\":100},{\"id\":\"dispatch-crew-available\",\"name\":\"Dispatch crew available\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":360}],\"transitions\":[{\"id\":\"start-final-inspection\",\"name\":\"Start final inspection\",\"inputArcs\":[{\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":250,\"y\":100},{\"id\":\"sign-off\",\"name\":\"Sign-off\",\"inputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"ready-for-dispatch\",\"weight\":1},{\"placeId\":\"dispatch-crew-available\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":590,\"y\":100}],\"types\":[],\"differentialEquations\":[],\"parameters\":[]},\"extensions\":{\"colors\":true,\"stochasticity\":true,\"dynamics\":true,\"parameters\":true,\"subnets\":true}}}]", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NV6ARKVMJTM74GVBKS6VW4", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_a38b1133b7c7c65bf8f07814d23bcbcb", + "turnId": "turn_01M1NV6A1766CSNYQR9H1HEBKH", + "parts": [ + { + "type": "reasoning", + "text": "The net definition has been loaded. Let me analyze the current state:\n\n**Current state:**\n- Places:\n - `batch-ready`: Batch waiting for final inspection\n - `under-final-inspection`: Batch undergoing final inspection\n - `ready-for-dispatch`: Batch ready for dispatch\n - `dispatch-crew-available`: Dispatch crew available (resource)\n\n- Transitions:\n - `start-final-inspection`: Takes a batch from `batch-ready` to `under-final-inspection`. It has one input arc from `batch-ready` with weight 1.\n - `sign-off`: Takes a batch from `under-final-inspection` to `ready-for-dispatch` and returns the crew to `dispatch-crew-available`. Has input arc from `under-final-inspection` (weight 1) and output arcs to both `ready-for-dispatch` and `dispatch-crew-available`.\n\n**The missing arc:**\nThe fixture states that the missing arc is: standard weight-1 input arc from `Dispatch crew available` to `Start final inspection`.\n\nCurrently, `start-final-inspection` only has one input arc from `batch-ready`. It needs an additional input arc from `dispatch-crew-available` with weight 1 and type \"standard\".\n\n**What needs to happen:**\n1. Add an input arc to the `start-final-inspection` transition from the `dispatch-crew-available` place with weight 1 and type \"standard\"\n2. Verify the result\n3. Emit the full revised workpiece with the identification that this is model-produced from test-authored revision zero\n\nLet me use the addArc function to add this arc.\n\nThe parameters for addArc based on the schema:\n- transitionId: \"start-final-inspection\"\n- arcDirection: \"input\"\n- placeId: \"dispatch-crew-available\" (since we're using the legacy shorthand)\n- weight: 1\n- type: \"standard\"\n- targetSubnetId omitted, since this operates on the root net", + "state": "done" + }, + { + "type": "dynamic-tool", + "toolName": "addArc", + "toolCallId": "toolu_01BQukCZTAhJ64VNE7oC1CWG", + "state": "output-available", + "input": { + "transitionId": "start-final-inspection", + "arcDirection": "input", + "placeId": "dispatch-crew-available", + "weight": "1", + "type": "standard" + }, + "output": { + "awaiting": "client" + }, + "durationMs": 0 + } + ] + }, + { + "id": "entry_direct_c3ViX2lrX2FmOWNjY2IxZTk1NzI5ZjkyNDk0NDA2NTE0NTE3Y2Nl", + "role": "system", + "purpose": "dispatch", + "display": "diagnostic", + "submissionId": "sub_ik_af9cccb1e95729f92494406514517cce", + "signal": { + "tagName": "client-tool-result", + "attributes": { + "toolCallIds": "toolu_016Jkt4shRUg8hmtq6YyfcFB,toolu_01BQukCZTAhJ64VNE7oC1CWG" + } + }, + "parts": [ + { + "type": "text", + "text": "[{\"toolCallId\":\"toolu_016Jkt4shRUg8hmtq6YyfcFB\",\"toolName\":\"getLatestNetDefinition\",\"output\":{\"title\":\"Prepared final inspection and dispatch\",\"definition\":{\"places\":[{\"id\":\"batch-ready\",\"name\":\"Batch ready\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":80,\"y\":100},{\"id\":\"under-final-inspection\",\"name\":\"Under final inspection\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":100},{\"id\":\"ready-for-dispatch\",\"name\":\"Ready for dispatch\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":760,\"y\":100},{\"id\":\"dispatch-crew-available\",\"name\":\"Dispatch crew available\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":360}],\"transitions\":[{\"id\":\"start-final-inspection\",\"name\":\"Start final inspection\",\"inputArcs\":[{\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":250,\"y\":100},{\"id\":\"sign-off\",\"name\":\"Sign-off\",\"inputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"ready-for-dispatch\",\"weight\":1},{\"placeId\":\"dispatch-crew-available\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":590,\"y\":100}],\"types\":[],\"differentialEquations\":[],\"parameters\":[]},\"extensions\":{\"colors\":true,\"stochasticity\":true,\"dynamics\":true,\"parameters\":true,\"subnets\":true}}},{\"toolCallId\":\"toolu_01BQukCZTAhJ64VNE7oC1CWG\",\"toolName\":\"addArc\",\"output\":{\"title\":\"Added input arc\",\"detail\":\"Dispatch crew available <-> Start final inspection\",\"target\":{\"kind\":\"selection\",\"item\":{\"type\":\"arc\",\"id\":\"$A_place:dispatch-crew-available___start-final-inspection\"}},\"applied\":true}}]", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NV6HRWJHSZ3QD2V8RZEWV3", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_af9cccb1e95729f92494406514517cce", + "turnId": "turn_01M1NV6GV7Q0BAMD0S09EEAY1E", + "parts": [ + { + "type": "reasoning", + "text": "Good! The arc has been added successfully. The tool output shows:\n- \"Applied: true\" - the arc was successfully added\n- Detail: \"Dispatch crew available <-> Start final inspection\"\n- The arc ID is \"$A_place:dispatch-crew-available___start-final-inspection\"\n\nNow I need to read the live net definition again to verify the change was applied correctly, then emit the revised workpiece with the full Markdown document showing the state of the net with the arc now in place.", + "state": "done" + }, + { + "type": "dynamic-tool", + "toolName": "getLatestNetDefinition", + "toolCallId": "toolu_017Ze5BnyBGXdaw7DJSGxZQb", + "state": "output-available", + "input": {}, + "output": { + "awaiting": "client" + }, + "durationMs": 0 + } + ] + }, + { + "id": "entry_direct_c3ViX2lrX2Q3OTdiNGM2MDUzZTVkMGExNDRlYzE1NDdhMjJlMGNh", + "role": "system", + "purpose": "dispatch", + "display": "diagnostic", + "submissionId": "sub_ik_d797b4c6053e5d0a144ec1547a22e0ca", + "signal": { + "tagName": "client-tool-result", + "attributes": { + "toolCallIds": "toolu_016Jkt4shRUg8hmtq6YyfcFB,toolu_01BQukCZTAhJ64VNE7oC1CWG,toolu_017Ze5BnyBGXdaw7DJSGxZQb" + } + }, + "parts": [ + { + "type": "text", + "text": "[{\"toolCallId\":\"toolu_016Jkt4shRUg8hmtq6YyfcFB\",\"toolName\":\"getLatestNetDefinition\",\"output\":{\"title\":\"Prepared final inspection and dispatch\",\"definition\":{\"places\":[{\"id\":\"batch-ready\",\"name\":\"Batch ready\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":80,\"y\":100},{\"id\":\"under-final-inspection\",\"name\":\"Under final inspection\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":100},{\"id\":\"ready-for-dispatch\",\"name\":\"Ready for dispatch\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":760,\"y\":100},{\"id\":\"dispatch-crew-available\",\"name\":\"Dispatch crew available\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":360}],\"transitions\":[{\"id\":\"start-final-inspection\",\"name\":\"Start final inspection\",\"inputArcs\":[{\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":250,\"y\":100},{\"id\":\"sign-off\",\"name\":\"Sign-off\",\"inputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"ready-for-dispatch\",\"weight\":1},{\"placeId\":\"dispatch-crew-available\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":590,\"y\":100}],\"types\":[],\"differentialEquations\":[],\"parameters\":[]},\"extensions\":{\"colors\":true,\"stochasticity\":true,\"dynamics\":true,\"parameters\":true,\"subnets\":true}}},{\"toolCallId\":\"toolu_01BQukCZTAhJ64VNE7oC1CWG\",\"toolName\":\"addArc\",\"output\":{\"title\":\"Added input arc\",\"detail\":\"Dispatch crew available <-> Start final inspection\",\"target\":{\"kind\":\"selection\",\"item\":{\"type\":\"arc\",\"id\":\"$A_place:dispatch-crew-available___start-final-inspection\"}},\"applied\":true}},{\"toolCallId\":\"toolu_017Ze5BnyBGXdaw7DJSGxZQb\",\"toolName\":\"getLatestNetDefinition\",\"output\":{\"title\":\"Prepared final inspection and dispatch\",\"definition\":{\"places\":[{\"id\":\"batch-ready\",\"name\":\"Batch ready\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":80,\"y\":100},{\"id\":\"under-final-inspection\",\"name\":\"Under final inspection\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":100},{\"id\":\"ready-for-dispatch\",\"name\":\"Ready for dispatch\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":760,\"y\":100},{\"id\":\"dispatch-crew-available\",\"name\":\"Dispatch crew available\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":360}],\"transitions\":[{\"id\":\"start-final-inspection\",\"name\":\"Start final inspection\",\"inputArcs\":[{\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"},{\"type\":\"standard\",\"placeId\":\"dispatch-crew-available\",\"weight\":1}],\"outputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":250,\"y\":100},{\"id\":\"sign-off\",\"name\":\"Sign-off\",\"inputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"ready-for-dispatch\",\"weight\":1},{\"placeId\":\"dispatch-crew-available\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":590,\"y\":100}],\"types\":[],\"differentialEquations\":[],\"parameters\":[]},\"extensions\":{\"colors\":true,\"stochasticity\":true,\"dynamics\":true,\"parameters\":true,\"subnets\":true}}}]", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NV6M4SBXB2WA46SM1B8QM3", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_d797b4c6053e5d0a144ec1547a22e0ca", + "turnId": "turn_01M1NV6KB8F7QJTRYHX0WT8AG5", + "parts": [ + { + "type": "reasoning", + "text": "Good! The arc has been successfully added. Looking at the final net definition, I can confirm:\n\n1. The arc was added successfully: `addArc` returned `\"applied\":true` with detail \"Dispatch crew available <-> Start final inspection\"\n\n2. In the final `getLatestNetDefinition` result, I can see that the `start-final-inspection` transition now has TWO input arcs:\n - `{\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"}`\n - `{\"type\":\"standard\",\"placeId\":\"dispatch-crew-available\",\"weight\":1\"}`\n\nThis confirms the missing arc from `Dispatch crew available` (weight 1, standard type) to `Start final inspection` is now in place.\n\nThe net structure is now:\n- **Places**: batch-ready, under-final-inspection, ready-for-dispatch, dispatch-crew-available\n- **Transitions**:\n - `start-final-inspection`: Takes a batch from batch-ready AND a crew token from dispatch-crew-available, produces under-final-inspection\n - `sign-off`: Takes under-final-inspection, produces both ready-for-dispatch AND returns dispatch-crew-available (crew token)\n\nThis correctly models the resource constraint: the single dispatch crew is reserved during inspection (consumed by start-final-inspection) and released at sign-off (produced by sign-off).\n\nNow I need to emit the revised runbook-ir workpiece, marking the revision as model-produced from test-authored revision zero.", + "state": "done" + }, + { + "type": "text", + "text": "✓ **Arc added successfully.** The Petrinaut tool confirms: `\"applied\":true` with detail \"Dispatch crew available ↔ Start final inspection\".\n\n**Verification of revised net structure:**\n- `Start final inspection` transition now has two standard input arcs (weight 1 each):\n 1. From `Batch ready` (original)\n 2. From `Dispatch crew available` (added, evidence-backed correction)\n- `Sign-off` transition correctly returns the crew token to `Dispatch crew available` (weight 1, output arc)\n\nThis enforces the resource constraint: the single dispatch crew is consumed when final inspection begins and restored at sign-off.\n\n---\n\n## Revised Workpiece (Model-Produced from Test-Authored Revision Zero)\n\n```runbook-ir\n# Final inspection and dispatch batch path\n\n## Purpose and posture\nModel the narrow batch path from final inspection to dispatch readiness with single-crew resource constraint. This revision incorporates the evidence-backed correction of the missing crew-availability input arc.\n\n## Operational account\n- A batch that is ready enters final inspection.\n- Final inspection requires and reserves the sole available dispatch crew.\n- Sign-off releases that crew and marks the batch ready for dispatch.\n\n## Quantity and resource policy\nExactly one dispatch crew is available in this system. Starting final inspection consumes that one available crew token; sign-off returns it. At most one batch can be under final inspection at a time because the sole crew is needed and cannot be in two places simultaneously.\n\n## Net structure (model-produced)\n**Places:**\n- `Batch ready`: batches waiting for inspection\n- `Under final inspection`: batches currently being inspected\n- `Ready for dispatch`: batches completed and awaiting dispatch\n- `Dispatch crew available`: availability token for the single crew (capacity 1)\n\n**Transitions:**\n- `Start final inspection`: consumes 1 batch token from `Batch ready` AND 1 crew token from `Dispatch crew available`; produces 1 token in `Under final inspection`\n- `Sign-off`: consumes 1 token from `Under final inspection`; produces 1 token each in `Ready for dispatch` and `Dispatch crew available` (returns the crew)\n\n**Arcs:**\n- `Batch ready` → `Start final inspection` (standard, weight 1) — original\n- `Dispatch crew available` → `Start final inspection` (standard, weight 1) — added in revision\n- `Start final inspection` → `Under final inspection` (standard, weight 1) — original\n- `Under final inspection` → `Sign-off` (standard, weight 1) — original\n- `Sign-off` → `Ready for dispatch` (standard, weight 1) — original\n- `Sign-off` → `Dispatch crew available` (standard, weight 1) — original\n\n## Explicit unknowns\n- Inspection and sign-off timing and duration\n- Failure modes, defect outcomes, and recovery behavior\n- Initial batch population and crew availability state\n- Repeat or recycling scenarios\n\n## Revision record\n**Revision 0** (test-authored): Prepared fixture identified missing standard weight-1 input arc from `Dispatch crew available` to `Start final inspection`.\n\n**Revision 1** (model-produced): Arc added via Petrinaut `addArc` tool and verified in net definition. Crew-availability constraint now enforced at net semantics level.\n\n## Claim boundary\nThis revision is model-produced evidence of arc correction applied to the test-authored source. It does not establish timing behavior, failure recovery, execution performance, or projection beyond this narrow batch-crew-inspection path.\n```", + "state": "done" + } + ] + }, + { + "id": "entry_direct_c3ViX2lrX2IyZjk2ZmQ2MmI4MGE2ZGNmOTgwMzI5YWQ2MWY3MGU5", + "role": "user", + "purpose": "user", + "display": "visible", + "submissionId": "sub_ik_b2f96fd62b80a6dcf980329ad61f70e9", + "parts": [ + { + "type": "text", + "text": "From the resumed workpiece, list the unresolved timing, failure, and recovery questions. Do not change the Petrinaut net.", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NV73Z110CY393GEB8T02SH", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_b2f96fd62b80a6dcf980329ad61f70e9", + "turnId": "turn_01M1NV7343YW19DZKMTGEDCWTF", + "parts": [ + { + "type": "reasoning", + "text": "The user is asking me to list the unresolved timing, failure, and recovery questions from the workpiece I just provided. They explicitly say not to change the Petrinaut net, so this is purely an analytical question about what remains open in the model.\n\nLet me look at the \"Explicit unknowns\" section I provided:\n- Inspection and sign-off timing and duration\n- Failure modes, defect outcomes, and recovery behavior\n- Initial batch population and crew availability state\n- Repeat or recycling scenarios\n\nBut the user wants me to be more specific about the timing, failure, and recovery questions. I should expand these into actual concrete questions that would need to be answered to make the model complete. Let me think about what operational questions are unresolved:\n\n**Timing questions:**\n- How long does final inspection take?\n- How long does sign-off take?\n- Are inspection and sign-off separate durations or combined?\n- Can inspection occur in parallel for multiple batches if crew were available?\n\n**Failure questions:**\n- What happens if a batch fails inspection?\n- Can inspection fail entirely or does sign-off always succeed?\n- Are there defect categories (reject, rework, accept)?\n- Does a failed batch consume the crew resource?\n\n**Recovery questions:**\n- If a batch fails inspection, where does it go? (Back to ready? To a separate fail queue? Removed entirely?)\n- Does failed inspection release the crew immediately, or after some remediation?\n- Can a reworked batch re-enter the inspection process?\n- What is the relationship between failed batches and crew availability?\n\nLet me provide a structured list of these unresolved questions organized by category.", + "state": "done" + }, + { + "type": "text", + "text": "## Unresolved Timing, Failure, and Recovery Questions\n\n### Timing\n1. **Inspection duration**: What is the stochastic or deterministic duration of the final inspection phase (from \"Start final inspection\" to \"Sign-off\")?\n2. **Sign-off duration**: Does \"Sign-off\" occur instantaneously, or does it have its own duration separate from inspection?\n3. **Crew engagement horizon**: Is the crew occupied only during the inspection phase, or does it remain engaged during batches' time in \"Ready for dispatch\"?\n4. **Parallel inspection capacity**: If additional crews became available, could multiple batches be inspected concurrently, or is there a single-batch constraint in the process?\n\n### Failure and Defect Outcomes\n1. **Inspection failure mode**: Can a batch fail inspection? If so, under what conditions?\n2. **Failure rate**: Is there a known or modeled probability that inspection produces a defect or rejection?\n3. **Defect categories**: Are there multiple outcomes (accept, reject, rework required)? If so, what distinguishes them?\n4. **Sign-off contingency**: Can sign-off always succeed after inspection, or can sign-off itself reject a batch?\n5. **Scrap or return**: What happens to batches that fail? Are they removed from the system, returned to \"Batch ready,\" sent to a separate rework queue, or diverted elsewhere?\n\n### Recovery and Rework Behavior\n1. **Failed batch crew release**: When a batch fails inspection, is the crew released immediately, or must it complete additional work before returning to availability?\n2. **Rework entry point**: If a batch requires rework, does it re-enter \"Batch ready,\" or is there a separate rework-staging place?\n3. **Rework limit**: Is there a maximum number of rework cycles, or can a batch cycle indefinitely?\n4. **Crew allocation to rework**: Does rework use the same dispatch crew, a different crew, or no dedicated crew?\n5. **Initial state**: How many batches start in \"Batch ready\" and how is \"Dispatch crew available\" initialized (1 token, or variable)?", + "state": "done" + } + ] + } + ], + "settlements": [ + { + "submissionId": "sub_ik_288631eaad798cc69070e3313e951bcb", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_288631eaad798cc69070e3313e951bcb" + }, + { + "submissionId": "sub_ik_233701ded7105d5d43c4b8ae2514ec8b", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_233701ded7105d5d43c4b8ae2514ec8b" + }, + { + "submissionId": "sub_ik_a38b1133b7c7c65bf8f07814d23bcbcb", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_a38b1133b7c7c65bf8f07814d23bcbcb" + }, + { + "submissionId": "sub_ik_af9cccb1e95729f92494406514517cce", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_af9cccb1e95729f92494406514517cce" + }, + { + "submissionId": "sub_ik_d797b4c6053e5d0a144ec1547a22e0ca", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_d797b4c6053e5d0a144ec1547a22e0ca" + }, + { + "submissionId": "sub_ik_b2f96fd62b80a6dcf980329ad61f70e9", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_b2f96fd62b80a6dcf980329ad61f70e9" + } + ], + "incarnation": "inc_01M1NV5WZD6VQ76Z7C3JJRFFBA" +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/latest-workpiece.md b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/latest-workpiece.md new file mode 100644 index 00000000000..4c89055d2b5 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/latest-workpiece.md @@ -0,0 +1,45 @@ +# Final inspection and dispatch batch path + +## Purpose and posture +Model the narrow batch path from final inspection to dispatch readiness with single-crew resource constraint. This revision incorporates the evidence-backed correction of the missing crew-availability input arc. + +## Operational account +- A batch that is ready enters final inspection. +- Final inspection requires and reserves the sole available dispatch crew. +- Sign-off releases that crew and marks the batch ready for dispatch. + +## Quantity and resource policy +Exactly one dispatch crew is available in this system. Starting final inspection consumes that one available crew token; sign-off returns it. At most one batch can be under final inspection at a time because the sole crew is needed and cannot be in two places simultaneously. + +## Net structure (model-produced) +**Places:** +- `Batch ready`: batches waiting for inspection +- `Under final inspection`: batches currently being inspected +- `Ready for dispatch`: batches completed and awaiting dispatch +- `Dispatch crew available`: availability token for the single crew (capacity 1) + +**Transitions:** +- `Start final inspection`: consumes 1 batch token from `Batch ready` AND 1 crew token from `Dispatch crew available`; produces 1 token in `Under final inspection` +- `Sign-off`: consumes 1 token from `Under final inspection`; produces 1 token each in `Ready for dispatch` and `Dispatch crew available` (returns the crew) + +**Arcs:** +- `Batch ready` → `Start final inspection` (standard, weight 1) — original +- `Dispatch crew available` → `Start final inspection` (standard, weight 1) — added in revision +- `Start final inspection` → `Under final inspection` (standard, weight 1) — original +- `Under final inspection` → `Sign-off` (standard, weight 1) — original +- `Sign-off` → `Ready for dispatch` (standard, weight 1) — original +- `Sign-off` → `Dispatch crew available` (standard, weight 1) — original + +## Explicit unknowns +- Inspection and sign-off timing and duration +- Failure modes, defect outcomes, and recovery behavior +- Initial batch population and crew availability state +- Repeat or recycling scenarios + +## Revision record +**Revision 0** (test-authored): Prepared fixture identified missing standard weight-1 input arc from `Dispatch crew available` to `Start final inspection`. + +**Revision 1** (model-produced): Arc added via Petrinaut `addArc` tool and verified in net definition. Crew-availability constraint now enforced at net semantics level. + +## Claim boundary +This revision is model-produced evidence of arc correction applied to the test-authored source. It does not establish timing behavior, failure recovery, execution performance, or projection beyond this narrow batch-crew-inspection path. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/prepared-workpiece.md b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/prepared-workpiece.md new file mode 100644 index 00000000000..fa01def8c11 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/prepared-workpiece.md @@ -0,0 +1,21 @@ +# Final inspection and dispatch workpiece + +## Purpose and posture +Maintain the narrow batch path from final inspection to dispatch readiness and test one evidence-backed correction against the live Petrinaut document. + +## Operational account +- A batch that is ready enters final inspection. +- Final inspection reserves the sole available dispatch crew. +- Sign-off releases that crew and makes the batch ready for dispatch. + +## Quantity and resource policy +Exactly one dispatch crew is available in this fixture. Starting final inspection consumes that one available crew; sign-off returns it. + +## Current Petrinaut correspondence +The prepared non-empty net contains the batch path and the crew return from sign-off. It deliberately lacks the standard weight-1 input arc from `Dispatch crew available` to `Start final inspection`. + +## Explicit unknowns +Inspection and sign-off timing, failure modes, and recovery behavior remain unresolved. + +## Claim boundary +This prepared revision is test-authored diagnostic material. It is not model-produced evidence and does not establish capture provenance, behavioral execution, or broad projection quality. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/product-manager-gate.md b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/product-manager-gate.md new file mode 100644 index 00000000000..ff35ac61969 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/product-manager-gate.md @@ -0,0 +1,23 @@ +# Mission 6 product-manager gate — 2026-09-04 + +## Result + +The product manager accepted the visible two-tab conversation, workpiece, and Petrinaut document path after independently operating the local fixture. The fresh Tab A run advanced from settled revision 0 with the target arc absent to settled revision 1 with the target arc visible. Tab B reopened the same fixture at revision 1, retained the arc and conversation content, and answered `What remains unresolved in this workpiece?` without another mutation or prepared-fixture delivery. + +The fresh run did not contain a Voice-origin message or an aborted assistant entry, so it did not independently exercise the Voice-provenance and stopped-entry presentation clauses in the full `MISSION.md` demo script. Those behaviors remain covered by the retained outer witness, not by this human run; this record does not substitute one for the other. The owner explicitly waived those two fresh-human checks, closed Mission 6 anyway, and carried them into `MISSION.next.md` as required scenarios for a later Voice, resume, or pre-release testing mission. The waiver is not a pass. + +## Durable correlation + +The accepted run used agent-session instance `5e8c6ca5c0acc8f0b9aa28a770b7cfdf8d15c64dffe27e6c13016af291c63c02` and canonical conversation `conv_01M1PHZEGGERDMJJRAYZA74S1S`. + +- Sequence 114 delivered the sole `brunch.fixture.prepared` signal. +- Sequence 115 delivered the product manager's crew-reservation fact. +- Sequences 116–118 delivered the cumulative browser results for `getLatestNetDefinition`, the single applied `addArc`, and the verification `getLatestNetDefinition` call. +- Sequence 119 delivered the non-mutating Tab B follow-up and settled with a completed assistant response. +- All six submissions settled without a recorded error. +- The durable stream contains exactly one distinct `addArc` call for the accepted session. +- The accepted session contains one prepared signal, two user messages, and one canonical conversation identity. + +## Diagnosis resolved during the gate + +Earlier attempts stranded browser results because AI SDK's implicit `addToolOutput` continuation raced its internal stream-to-ready cleanup. The accepted run used the repaired explicit chain: await browser output insertion, suppress the competing implicit continuation, coalesce same-turn outputs, then invoke the public no-message `sendMessage()` continuation. The uninterrupted accepted run required no reload between its user message and revision-1 settlement. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/route-evidence.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/route-evidence.json new file mode 100644 index 00000000000..85b3c90305b --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/route-evidence.json @@ -0,0 +1,6 @@ +{ + "fixtureUrl": "http://127.0.0.1:4915/?brunch-fixture=crew-reservation-v1", + "mountedRoute": "/agents/chat/", + "sameMountedInstanceAcrossTabs": true, + "browserErrors": [] +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/run-metadata.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/run-metadata.json new file mode 100644 index 00000000000..28615dac8f1 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/run-metadata.json @@ -0,0 +1,8 @@ +{ + "implementationCommit": "8ef9cd967d", + "prompt": "Confirmed: final inspection uses the single dispatch crew and sign-off releases it; timing, failure, and recovery remain unknown. Read the live Petrinaut definition, add the missing standard weight-1 input arc from Dispatch crew available to Start final inspection, verify it, and emit the full revised runbook-ir workpiece. In that revised workpiece, identify the revision itself as model-produced from test-authored revision zero; do not call the revised workpiece test-authored.", + "followup": "From the resumed workpiece, list the unresolved timing, failure, and recovery questions. Do not change the Petrinaut net.", + "beforeOffset": "0000000000000000_0000000000000032", + "afterOffset": "0000000000000000_0000000000000092", + "tabBOffset": "0000000000000000_0000000000000110" +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/screenshot-tab-a-after.png b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/screenshot-tab-a-after.png new file mode 100644 index 00000000000..4e06ff085e7 Binary files /dev/null and b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/screenshot-tab-a-after.png differ diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/screenshot-tab-a-before.png b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/screenshot-tab-a-before.png new file mode 100644 index 00000000000..082e16eb0be Binary files /dev/null and b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/screenshot-tab-a-before.png differ diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/screenshot-tab-b-after.png b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/screenshot-tab-b-after.png new file mode 100644 index 00000000000..6e3f3f75b88 Binary files /dev/null and b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/screenshot-tab-b-after.png differ diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/settled-manifest-after.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/settled-manifest-after.json new file mode 100644 index 00000000000..435e88a58ad --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/settled-manifest-after.json @@ -0,0 +1,25 @@ +{ + "version": 1, + "fixtureId": "crew-reservation-v1", + "revision": 1, + "settledAt": "2026-09-04T09:15:22.339Z", + "conversation": { + "logicalId": "mission-6-crew-reservation-conversation-v1", + "canonicalId": "conv_01M1NV5WZETMYEGGMFXNYDSTRS", + "offset": "0000000000000000_0000000000000092" + }, + "latestWorkpiece": { + "authorship": "model-produced", + "contentSha256": "1d250465b7c9ee930c21581c2b6715ad01915e50e5a66b4348ea7970eac9f78c", + "sourceKind": "assistant", + "sourceMessageId": "entry_01M1NV6M4SBXB2WA46SM1B8QM3", + "sourceMessageSha256": "56a6b415da3c596af168165c1f95eb2c586a758ab9f37dc63dffcd0869a84815", + "sourceSubmissionId": "sub_ik_d797b4c6053e5d0a144ec1547a22e0ca" + }, + "document": { + "id": "mission-6-crew-reservation-document-v1", + "sha256": "3c47961d02296c00131644d1aea0dac16a017f470a66aea919fcf324a2bc9e37", + "targetArc": "present" + }, + "manifestId": "d16b26c12d81a2f961d428d8062fce2a7755c3a6342715f8c85b054546d330b7" +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/settled-manifest-before.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/settled-manifest-before.json new file mode 100644 index 00000000000..af88d6180b3 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/settled-manifest-before.json @@ -0,0 +1,25 @@ +{ + "version": 1, + "fixtureId": "crew-reservation-v1", + "revision": 0, + "settledAt": "2026-09-04T09:14:55.934Z", + "conversation": { + "logicalId": "mission-6-crew-reservation-conversation-v1", + "canonicalId": "conv_01M1NV5WZETMYEGGMFXNYDSTRS", + "offset": "0000000000000000_0000000000000032" + }, + "latestWorkpiece": { + "authorship": "test-authored", + "contentSha256": "1cc7a1b5d961f9f6327b458cf8292703ced5627fe26ee3f7b878f6375e51501a", + "sourceKind": "prepared-signal", + "sourceMessageId": "entry_direct_c3ViX2lrXzI4ODYzMWVhYWQ3OThjYzY5MDcwZTMzMTNlOTUxYmNi", + "sourceMessageSha256": "bfff373d94057ad6715fafff05a58db24c6c47c583497bfb965cb37ce3e5879e", + "sourceSubmissionId": "sub_ik_288631eaad798cc69070e3313e951bcb" + }, + "document": { + "id": "mission-6-crew-reservation-document-v1", + "sha256": "8dfa723b8dabadad790d2552de8e191e4227b07fe6c4d4e9d8e2d365e6ec4abd", + "targetArc": "absent" + }, + "manifestId": "45662458cb5d01dd3ecb4daeefed12f1fd699fa972cc6101565da10330f421f5" +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/settled-manifest-tab-b.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/settled-manifest-tab-b.json new file mode 100644 index 00000000000..435e88a58ad --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/settled-manifest-tab-b.json @@ -0,0 +1,25 @@ +{ + "version": 1, + "fixtureId": "crew-reservation-v1", + "revision": 1, + "settledAt": "2026-09-04T09:15:22.339Z", + "conversation": { + "logicalId": "mission-6-crew-reservation-conversation-v1", + "canonicalId": "conv_01M1NV5WZETMYEGGMFXNYDSTRS", + "offset": "0000000000000000_0000000000000092" + }, + "latestWorkpiece": { + "authorship": "model-produced", + "contentSha256": "1d250465b7c9ee930c21581c2b6715ad01915e50e5a66b4348ea7970eac9f78c", + "sourceKind": "assistant", + "sourceMessageId": "entry_01M1NV6M4SBXB2WA46SM1B8QM3", + "sourceMessageSha256": "56a6b415da3c596af168165c1f95eb2c586a758ab9f37dc63dffcd0869a84815", + "sourceSubmissionId": "sub_ik_d797b4c6053e5d0a144ec1547a22e0ca" + }, + "document": { + "id": "mission-6-crew-reservation-document-v1", + "sha256": "3c47961d02296c00131644d1aea0dac16a017f470a66aea919fcf324a2bc9e37", + "targetArc": "present" + }, + "manifestId": "d16b26c12d81a2f961d428d8062fce2a7755c3a6342715f8c85b054546d330b7" +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/tab-b-correlation.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/tab-b-correlation.json new file mode 100644 index 00000000000..ade0492b67c --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/tab-b-correlation.json @@ -0,0 +1,21 @@ +{ + "sameCanonicalConversation": true, + "sameManifestId": true, + "sameDocumentHash": true, + "sameWorkpieceHash": true, + "preparedSourceCountAfter": 1, + "preparedSourceCountTabB": 1, + "addArcCallCountAfter": 1, + "addArcCallCountTabB": 1, + "newMessageIds": [ + "entry_direct_c3ViX2lrX2IyZjk2ZmQ2MmI4MGE2ZGNmOTgwMzI5YWQ2MWY3MGU5", + "entry_01M1NV73Z110CY393GEB8T02SH" + ], + "newSettlements": [ + { + "submissionId": "sub_ik_b2f96fd62b80a6dcf980329ad61f70e9", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_b2f96fd62b80a6dcf980329ad61f70e9" + } + ] +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/witness.md b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/witness.md new file mode 100644 index 00000000000..d9eed05f6f4 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04-r2/witness.md @@ -0,0 +1,48 @@ +# FE-1575 corrected outer browser witness — 2026-09-04 + +## Scope + +This is the retained outer mechanical witness for Mission 6 at implementation commit `8ef9cd967d`. It supersedes the first witness for acceptance because that run's model-produced revision incorrectly described itself as test-authored. This run used a fresh Playwright browser context, the stable `crew-reservation-v1` fixture route, the local Brunch Flue mount, and a real configured provider credential. Credentials, authorization headers, the browser principal, the Flue instance route component, and provider request payloads are not retained. + +The provider serialized the `addArc` weight as `"1"`. The witnessed build normalized only that observed finite numeric string at the Petrinaut tool boundary before canonical validation and browser execution. [`call-result-correlation.json`](call-result-correlation.json) retains both the raw provider input and parsed canonical input; the resulting definition retains numeric weight `1`. + +## Protocol and result + +1. Started the production dev processes underlying `yarn dev:brunch` after loading `.env.local` without printing it. The root wrapper's prerequisite build could not run in this sandbox because `tsx` was denied its `/tmp` IPC socket; all affected package builds had already passed, so the Brunch server and Petrinaut panel processes were started directly with their normal Vite entrypoints. +2. Opened `http://127.0.0.1:4915/?brunch-fixture=crew-reservation-v1` in a fresh browser context and waited for settled revision zero. +3. Retained the before Flue snapshot, canonical definition, runtime manifest, and Tab A screenshot. +4. Submitted one confirmation/construction turn instructing Brunch to preserve timing/failure/recovery unknowns, add the missing standard weight-1 input arc, and identify the new assistant workpiece as model-produced from test-authored revision zero. +5. Observed one `addArc` call and one unique correlated successful client-tool result, `toolu_01BQukCZTAhJ64VNE7oC1CWG`. Flue history materialized that result in two cumulative client-tool-result signal deliveries as later read verification completed; the repeated call ID remained one logical result and the browser retained exactly one arc. +6. Verified that the only semantic definition delta was one standard weight-1 input arc from `dispatch-crew-available` to `start-final-inspection`. +7. Observed runtime manifest revision 1 selecting the model-produced workpiece and changed document, with target arc `present`. +8. Opened Tab B in the same browser context. It selected the same manifest, workpiece hash, document hash, and canonical conversation, with exactly one prepared source and one `addArc` call. +9. Submitted a non-mutating follow-up in Tab B asking for the unresolved timing, failure, and recovery questions without changing the net. +10. Observed completed submission `sub_ik_b2f96fd62b80a6dcf980329ad61f70e9` and correlated response `entry_01M1NV73Z110CY393GEB8T02SH`. The document and settled manifest remained unchanged. + +## Retained identities and invariants + +- Canonical conversation: `conv_01M1NV5WZETMYEGGMFXNYDSTRS` +- Before/after/Tab-B offsets: `0000000000000000_0000000000000032`, `0000000000000000_0000000000000092`, `0000000000000000_0000000000000110` +- Settled manifest revision: `1` +- Settled manifest ID: `d16b26c12d81a2f961d428d8062fce2a7755c3a6342715f8c85b054546d330b7` +- Document SHA-256: `3c47961d02296c00131644d1aea0dac16a017f470a66aea919fcf324a2bc9e37` +- Workpiece SHA-256: `1d250465b7c9ee930c21581c2b6715ad01915e50e5a66b4348ea7970eac9f78c` +- Prepared source count after Tab B: `1` +- `addArc` call count after Tab B: `1` +- Unique successful `addArc` result count: `1` across `2` cumulative signal deliveries +- Tab B follow-up outcome: `completed` +- The selected model-produced workpiece explicitly distinguishes itself from test-authored revision zero. +- `definition-after.json` and `definition-tab-b.json` have the same SHA-256. +- `settled-manifest-after.json` and `settled-manifest-tab-b.json` have the same SHA-256. + +## Artifacts + +- Before state: [Flue](flue-snapshot-before.json), [definition](definition-before.json), [manifest](settled-manifest-before.json), [screenshot](screenshot-tab-a-before.png) +- Settled Tab A state: [Flue](flue-snapshot-after.json), [definition](definition-after.json), [manifest](settled-manifest-after.json), [call/result correlation with parsed input](call-result-correlation.json), [screenshot](screenshot-tab-a-after.png) +- Tab B continuation: [Flue](flue-snapshot-tab-b.json), [definition](definition-tab-b.json), [manifest](settled-manifest-tab-b.json), [correlation](tab-b-correlation.json), [screenshot](screenshot-tab-b-after.png) +- Semantic inputs: [prepared workpiece](prepared-workpiece.md), [latest model-produced workpiece](latest-workpiece.md), [cold-reader records](cold-reader-records.json) +- Redacted route observation: [route evidence](route-evidence.json) +- Run metadata: [run-metadata.json](run-metadata.json) +- Integrity: [SHA256SUMS](SHA256SUMS) + +This witness proves the bounded browser protocol above. It does not establish capture provenance, timing behavior, failure/recovery behavior, simulation validity, or broad automatic projection quality. Cold-reader adjudication and the product-manager demo remain human-owned gates. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/SHA256SUMS b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/SHA256SUMS new file mode 100644 index 00000000000..1d9c9bd912c --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/SHA256SUMS @@ -0,0 +1,20 @@ +6c3a075636a5df23667c58c4ca005cc7da6b1927e13bfc54939f5e4416e5059f call-result-correlation.json +1d37d87803edd25905098bc957a1557ea7250a243b689c62c1d58ebc463135d0 cold-reader-gate.md +e5393930c436fac7bcb5f30b610ca4d28174a027f0b3fe8eab0045076379ce29 cold-reader-records.json +c17ae80cc22939f0af6c2675f6bcc20b025b17a5b7bfb9e8029813bcef9ad736 definition-after.json +0ec2b0c9bb82787602c359b41e6c1663001f8e42425ad2ab7f84ac019944766b definition-before.json +c17ae80cc22939f0af6c2675f6bcc20b025b17a5b7bfb9e8029813bcef9ad736 definition-tab-b.json +4fe368ef206e71e63173c1876ac9ca54e8b0d0971066be74dae5f78d4b612b0a flue-snapshot-after.json +ea20487150d8a329f4c2a6e0ac32e22de39d0d655646581ad2c56768a3591d1a flue-snapshot-before.json +7aaa993b395bc4ac84625fb2f472645ba13428bc39faac1f0f4ba948bfb3d9f5 flue-snapshot-tab-b.json +a384aa803085d3ff350a347e18080503a78305f87eb5d91eec1ad1141b941eb3 latest-workpiece.md +17f99f53f8cf93285a7344f5e9687d94e5f59011e6895ce11a9722fde2e77511 prepared-workpiece.md +cfb79c8f52fc8f1758b1a61f67e520c67a31d2f19f561017899d0724b776100a route-evidence.json +a9bd4a4a18f52ebd5c0f0e9c7c5d80b1c37e85823bfa6a03bd9c1d329b4b4267 screenshot-tab-a-after.png +eaf49081a6ab7acba746f337fdb85e3829d473818dc7c96f83a40acd3cb6f383 screenshot-tab-a-before.png +d39ea91fc69fa049af169c6ebcfe1a09c5b085d350d5eb6f9020c31095549943 screenshot-tab-b-after.png +caf83c79b2526587794faf4ed8c59c0d3f4bb9ed88e3d547679efe429197797c settled-manifest-after.json +5b302df73ccd6ac0cec777c9e4ade15ac7318dca7023ed79e3bceaa0604c3ec0 settled-manifest-before.json +caf83c79b2526587794faf4ed8c59c0d3f4bb9ed88e3d547679efe429197797c settled-manifest-tab-b.json +08afa5150f33b8b19641118524880eca9b13f4e7a94a55eca7b76775cfa30770 tab-b-correlation.json +935fa33c714b6441622cb1c50f2ff5e7f8e56c434a5365f5857c2eb6a1ffd830 witness.md diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/call-result-correlation.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/call-result-correlation.json new file mode 100644 index 00000000000..bdc346ad17c --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/call-result-correlation.json @@ -0,0 +1,51 @@ +{ + "calls": [ + { + "messageId": "entry_01M1NQGD1NRR36CBAX78EA666J", + "submissionId": "sub_ik_dd2eb7be21980998b89ae9a9da085fb2", + "toolCallId": "toolu_01KLHzRE7gbPbFfPaXe3RTry", + "state": "output-available", + "input": { + "transitionId": "start-final-inspection", + "arcDirection": "input", + "placeId": "dispatch-crew-available", + "weight": "1", + "type": "standard" + } + } + ], + "results": [ + { + "toolCallId": "toolu_01KLHzRE7gbPbFfPaXe3RTry", + "toolName": "addArc", + "output": { + "title": "Added input arc", + "detail": "Dispatch crew available <-> Start final inspection", + "target": { + "kind": "selection", + "item": { + "type": "arc", + "id": "$A_place:dispatch-crew-available___start-final-inspection" + } + }, + "applied": true + } + }, + { + "toolCallId": "toolu_01KLHzRE7gbPbFfPaXe3RTry", + "toolName": "addArc", + "output": { + "title": "Added input arc", + "detail": "Dispatch crew available <-> Start final inspection", + "target": { + "kind": "selection", + "item": { + "type": "arc", + "id": "$A_place:dispatch-crew-available___start-final-inspection" + } + }, + "applied": true + } + } + ] +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/cold-reader-gate.md b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/cold-reader-gate.md new file mode 100644 index 00000000000..1d00d3e13f8 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/cold-reader-gate.md @@ -0,0 +1,36 @@ +# Mission 6 cold-reader gate + +Reviewer qualification: a human who did not watch the implementation or outer +witness. Do not give the reviewer `witness.md`, screenshots, implementation +files, or this mission's expected conclusions. + +Give the reviewer only: + +- [prepared-workpiece.md](prepared-workpiece.md) +- [latest-workpiece.md](latest-workpiece.md) +- [cold-reader-records.json](cold-reader-records.json) + +Ask for a written response to these questions: + +1. Who authored each workpiece revision, and what in the supplied Flue records + establishes that attribution? +2. What exact dispatch-crew quantity or resource policy is recorded? +3. What operation reserves the crew, and what operation returns it? +4. List every unresolved timing, failure, and recovery point. +5. What behavioral execution or operational-provenance claims, if any, can be + made from these materials alone? + +Acceptance requires the human response to: + +- attribute revision zero to test preparation, not the model; +- attribute the later assistant record to model production; +- recover the exactly-one-crew policy and the intended reservation/return; +- preserve every timing, failure, and recovery unknown; and +- avoid inferring behavioral execution or capture provenance. + +Record the reviewer's identity, date, verbatim response, and explicit +accept/reject decision below only after the review occurs. + +## Human verdict + +Pending. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/cold-reader-records.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/cold-reader-records.json new file mode 100644 index 00000000000..a5efc6ff2eb --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/cold-reader-records.json @@ -0,0 +1,39 @@ +{ + "preparedRecord": { + "id": "entry_direct_c3ViX2lrX2YyNDkzOWJlYmI4NDFmZmUxNDY5YTdmM2E0YTA2OTE1", + "role": "system", + "purpose": "dispatch", + "display": "diagnostic", + "submissionId": "sub_ik_f24939bebb841ffe1469a7f3a4a06915", + "signal": { + "tagName": "prepared-fixture", + "attributes": { + "fixtureId": "crew-reservation-v1", + "authorship": "test-authored", + "claimBoundary": "prepared-not-model-produced" + } + }, + "parts": [ + { + "type": "text", + "text": "Fixture authorship: test-authored preparation for Mission 6.\nNon-claims: not a Mission 4 candidate, not model-produced evidence, not capture-backed provenance, and not proof of automatic full-net projection.\n\n```runbook-ir\n# Final inspection and dispatch workpiece\n\n## Purpose and posture\nMaintain the narrow batch path from final inspection to dispatch readiness and test one evidence-backed correction against the live Petrinaut document.\n\n## Operational account\n- A batch that is ready enters final inspection.\n- Final inspection reserves the sole available dispatch crew.\n- Sign-off releases that crew and makes the batch ready for dispatch.\n\n## Quantity and resource policy\nExactly one dispatch crew is available in this fixture. Starting final inspection consumes that one available crew; sign-off returns it.\n\n## Current Petrinaut correspondence\nThe prepared non-empty net contains the batch path and the crew return from sign-off. It deliberately lacks the standard weight-1 input arc from `Dispatch crew available` to `Start final inspection`.\n\n## Explicit unknowns\nInspection and sign-off timing, failure modes, and recovery behavior remain unresolved.\n\n## Claim boundary\nThis prepared revision is test-authored diagnostic material. It is not model-produced evidence and does not establish capture provenance, behavioral execution, or broad projection quality.\n```", + "state": "done" + } + ] + }, + "revisedRecord": { + "id": "entry_01M1NQGRAKWG69MWYMPYTCFXCZ", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_6dbc187e4e72793b7539c02387d04715", + "turnId": "turn_01M1NQGQH38A3MMGGEWKN4VCDP", + "parts": [ + { + "type": "text", + "text": "**Verification successful.** The `start-final-inspection` transition now contains the corrected input arcs:\n```json\n\"inputArcs\":[\n {\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"},\n {\"type\":\"standard\",\"placeId\":\"dispatch-crew-available\",\"weight\":1}\n]\n```\n\nThe resource constraint is now satisfied: firing `start-final-inspection` requires both a ready batch AND an available crew token. The `sign-off` transition releases that crew back to `dispatch-crew-available`.\n\n---\n\n## Revised workpiece (runbook-ir)\n\n```runbook-ir\n# Final inspection and dispatch workpiece — Revised\n\n## Purpose and posture\nModel the batch path from final inspection to dispatch readiness with explicit crew resource management. This revision adds the missing crew-consumption arc to enforce the resource constraint.\n\n## Operational account\n- A batch that is ready enters final inspection.\n- Starting final inspection requires both a ready batch AND the sole available dispatch crew.\n- Starting final inspection consumes that crew token.\n- Sign-off releases that crew and makes the batch ready for dispatch.\n\n## Quantity and resource policy\nExactly one dispatch crew is available. Starting final inspection consumes that one available crew; sign-off returns it. No transition fires without sufficient tokens in all input places.\n\n## Petrinaut correspondence\nThe net contains four places:\n- `batch-ready`: batches awaiting final inspection\n- `under-final-inspection`: batches currently in inspection\n- `ready-for-dispatch`: batches cleared for dispatch\n- `dispatch-crew-available`: crew availability (1 token when free)\n\nTransitions:\n- `start-final-inspection`: requires 1 token from batch-ready AND 1 token from dispatch-crew-available; produces 1 token to under-final-inspection\n- `sign-off`: requires 1 token from under-final-inspection; produces 1 token to ready-for-dispatch AND 1 token to dispatch-crew-available\n\nThe missing standard weight-1 input arc from `dispatch-crew-available` to `start-final-inspection` has been **added and verified** in the live Petrinaut definition.\n\n## Explicit unknowns\n- Inspection timing: duration, stochasticity, or determinism remain unresolved\n- Sign-off timing: duration, stochasticity, or determinism remain unresolved\n- Failure modes: whether inspection can fail, halt, or reject a batch\n- Recovery behavior: how failures or rejections affect batch state or crew availability\n\n## Claim boundary\nThis workpiece and the corrected net establish only:\n- The crew-consumption constraint at start of inspection\n- The crew-release at sign-off completion\n- Token flow from ready batch through inspection to dispatch readiness\n\nThis is test-authored diagnostic material for the narrow final-inspection–to-dispatch path. It does not establish capture provenance, behavioral execution, failure handling, full process projection, or integration with upstream or downstream operations.\n```\n\nThe correction is complete and verified in the live Petrinaut definition.", + "state": "done" + } + ] + } +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/definition-after.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/definition-after.json new file mode 100644 index 00000000000..c92ed16c454 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/definition-after.json @@ -0,0 +1,98 @@ +{ + "places": [ + { + "id": "batch-ready", + "name": "Batch ready", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 80, + "y": 100 + }, + { + "id": "under-final-inspection", + "name": "Under final inspection", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 420, + "y": 100 + }, + { + "id": "ready-for-dispatch", + "name": "Ready for dispatch", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 760, + "y": 100 + }, + { + "id": "dispatch-crew-available", + "name": "Dispatch crew available", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 420, + "y": 360 + } + ], + "transitions": [ + { + "id": "start-final-inspection", + "name": "Start final inspection", + "inputArcs": [ + { + "placeId": "batch-ready", + "weight": 1, + "type": "standard" + }, + { + "type": "standard", + "placeId": "dispatch-crew-available", + "weight": 1 + } + ], + "outputArcs": [ + { + "placeId": "under-final-inspection", + "weight": 1 + } + ], + "lambdaType": "predicate", + "lambdaCode": "", + "transitionKernelCode": "", + "x": 250, + "y": 100 + }, + { + "id": "sign-off", + "name": "Sign-off", + "inputArcs": [ + { + "placeId": "under-final-inspection", + "weight": 1, + "type": "standard" + } + ], + "outputArcs": [ + { + "placeId": "ready-for-dispatch", + "weight": 1 + }, + { + "placeId": "dispatch-crew-available", + "weight": 1 + } + ], + "lambdaType": "predicate", + "lambdaCode": "", + "transitionKernelCode": "", + "x": 590, + "y": 100 + } + ], + "types": [], + "differentialEquations": [], + "parameters": [] +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/definition-before.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/definition-before.json new file mode 100644 index 00000000000..5803556bfe8 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/definition-before.json @@ -0,0 +1,93 @@ +{ + "places": [ + { + "id": "batch-ready", + "name": "Batch ready", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 80, + "y": 100 + }, + { + "id": "under-final-inspection", + "name": "Under final inspection", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 420, + "y": 100 + }, + { + "id": "ready-for-dispatch", + "name": "Ready for dispatch", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 760, + "y": 100 + }, + { + "id": "dispatch-crew-available", + "name": "Dispatch crew available", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 420, + "y": 360 + } + ], + "transitions": [ + { + "id": "start-final-inspection", + "name": "Start final inspection", + "inputArcs": [ + { + "placeId": "batch-ready", + "type": "standard", + "weight": 1 + } + ], + "outputArcs": [ + { + "placeId": "under-final-inspection", + "weight": 1 + } + ], + "lambdaType": "predicate", + "lambdaCode": "", + "transitionKernelCode": "", + "x": 250, + "y": 100 + }, + { + "id": "sign-off", + "name": "Sign-off", + "inputArcs": [ + { + "placeId": "under-final-inspection", + "type": "standard", + "weight": 1 + } + ], + "outputArcs": [ + { + "placeId": "ready-for-dispatch", + "weight": 1 + }, + { + "placeId": "dispatch-crew-available", + "weight": 1 + } + ], + "lambdaType": "predicate", + "lambdaCode": "", + "transitionKernelCode": "", + "x": 590, + "y": 100 + } + ], + "types": [], + "parameters": [], + "differentialEquations": [] +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/definition-tab-b.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/definition-tab-b.json new file mode 100644 index 00000000000..c92ed16c454 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/definition-tab-b.json @@ -0,0 +1,98 @@ +{ + "places": [ + { + "id": "batch-ready", + "name": "Batch ready", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 80, + "y": 100 + }, + { + "id": "under-final-inspection", + "name": "Under final inspection", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 420, + "y": 100 + }, + { + "id": "ready-for-dispatch", + "name": "Ready for dispatch", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 760, + "y": 100 + }, + { + "id": "dispatch-crew-available", + "name": "Dispatch crew available", + "colorId": null, + "dynamicsEnabled": false, + "differentialEquationId": null, + "x": 420, + "y": 360 + } + ], + "transitions": [ + { + "id": "start-final-inspection", + "name": "Start final inspection", + "inputArcs": [ + { + "placeId": "batch-ready", + "weight": 1, + "type": "standard" + }, + { + "type": "standard", + "placeId": "dispatch-crew-available", + "weight": 1 + } + ], + "outputArcs": [ + { + "placeId": "under-final-inspection", + "weight": 1 + } + ], + "lambdaType": "predicate", + "lambdaCode": "", + "transitionKernelCode": "", + "x": 250, + "y": 100 + }, + { + "id": "sign-off", + "name": "Sign-off", + "inputArcs": [ + { + "placeId": "under-final-inspection", + "weight": 1, + "type": "standard" + } + ], + "outputArcs": [ + { + "placeId": "ready-for-dispatch", + "weight": 1 + }, + { + "placeId": "dispatch-crew-available", + "weight": 1 + } + ], + "lambdaType": "predicate", + "lambdaCode": "", + "transitionKernelCode": "", + "x": 590, + "y": 100 + } + ], + "types": [], + "differentialEquations": [], + "parameters": [] +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/flue-snapshot-after.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/flue-snapshot-after.json new file mode 100644 index 00000000000..ba4e176112e --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/flue-snapshot-after.json @@ -0,0 +1,321 @@ +{ + "v": 1, + "conversationId": "conv_01M1NQEXM3CAPPTXM33ZE1YSRG", + "offset": "0000000000000000_0000000000000108", + "messages": [ + { + "id": "entry_direct_c3ViX2lrX2YyNDkzOWJlYmI4NDFmZmUxNDY5YTdmM2E0YTA2OTE1", + "role": "system", + "purpose": "dispatch", + "display": "diagnostic", + "submissionId": "sub_ik_f24939bebb841ffe1469a7f3a4a06915", + "signal": { + "tagName": "prepared-fixture", + "attributes": { + "fixtureId": "crew-reservation-v1", + "authorship": "test-authored", + "claimBoundary": "prepared-not-model-produced" + } + }, + "parts": [ + { + "type": "text", + "text": "Fixture authorship: test-authored preparation for Mission 6.\nNon-claims: not a Mission 4 candidate, not model-produced evidence, not capture-backed provenance, and not proof of automatic full-net projection.\n\n```runbook-ir\n# Final inspection and dispatch workpiece\n\n## Purpose and posture\nMaintain the narrow batch path from final inspection to dispatch readiness and test one evidence-backed correction against the live Petrinaut document.\n\n## Operational account\n- A batch that is ready enters final inspection.\n- Final inspection reserves the sole available dispatch crew.\n- Sign-off releases that crew and makes the batch ready for dispatch.\n\n## Quantity and resource policy\nExactly one dispatch crew is available in this fixture. Starting final inspection consumes that one available crew; sign-off returns it.\n\n## Current Petrinaut correspondence\nThe prepared non-empty net contains the batch path and the crew return from sign-off. It deliberately lacks the standard weight-1 input arc from `Dispatch crew available` to `Start final inspection`.\n\n## Explicit unknowns\nInspection and sign-off timing, failure modes, and recovery behavior remain unresolved.\n\n## Claim boundary\nThis prepared revision is test-authored diagnostic material. It is not model-produced evidence and does not establish capture provenance, behavioral execution, or broad projection quality.\n```", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NQEYF9W60J2JVDYB2BJXK1", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_f24939bebb841ffe1469a7f3a4a06915", + "turnId": "turn_01M1NQEXM7MHJ94PF52Q54VAY4", + "parts": [ + { + "type": "reasoning", + "text": "The user has provided a prepared-fixture for SDCPN modelling work. This is test-authored material that is:\n- Part of a Mission 6 exercise\n- Focused on a narrow batch path from final inspection to dispatch readiness\n- Aimed at testing one evidence-backed correction against the live Petrinaut document\n- Not model-produced evidence, not a capture-backed provenance, not proof of automatic full-net projection\n\nThe operational account describes:\n1. A batch that is ready enters final inspection\n2. Final inspection reserves the sole available dispatch crew\n3. Sign-off releases that crew and makes the batch ready for dispatch\n\nThe key policy: Exactly one dispatch crew is available. Starting final inspection consumes it; sign-off returns it.\n\nThe current state: The prepared non-empty net contains the batch path and the crew return from sign-off, but deliberately LACKS the standard weight-1 input arc from \"Dispatch crew available\" to \"Start final inspection\".\n\nThe purpose is to test one evidence-backed correction against the live Petrinaut document.\n\nMy role here is:\n1. First, activate the sdcpn-modelling skill since this is a process-modelling task\n2. Understand the current state of the Petrinaut net\n3. Help verify the operational account against the net\n4. Work with the user to identify and potentially implement the missing arc correction\n5. Maintain the workpiece with clear documentation of what is known, what is missing, and what has been tested\n\nLet me start by activating the skill and getting the current net state.", + "state": "done" + }, + { + "type": "text", + "text": "I'll help you with this prepared-fixture exercise. Let me start by activating the SDCPN modelling skill and then retrieving the current state of the Petrinaut net to understand what we're working with.", + "state": "done" + }, + { + "type": "dynamic-tool", + "toolName": "activate_skill", + "toolCallId": "toolu_01WQaZveys8joHtboYvGQiuA", + "state": "output-available", + "input": { + "name": "sdcpn-modelling" + }, + "output": "Run the skill named \"sdcpn-modelling\".\n\n\n# Capability-aware lifecycle\n\nUse one conceptual lifecycle: orient, elicit or revise, maintain the workpiece, construct when supported, check, and deliver. The current conversation may expose only one branch of that lifecycle. Do not claim that an unavailable transition occurred.\n\n## Select the runtime branch\n\n### Interactive elicitation or revision\n\nInterview in the person's operational vocabulary. Activate the `elicitation` skill and read `references/profile.md` before substantive questions or revision. Read `templates/workpiece.md` when creating or materially revising the shared workpiece. Construct only when the mounted capabilities actually permit construction in this conversation.\n\n### Construct-only execution\n\nUse the supplied workpiece as the complete modelling input. Do not interview. Read `references/pn-construction.md` and `references/checks.md`, then use the mounted construction tools. If a consequential workpiece gap prevents faithful construction, report the gap and the smallest question a later interactive elicitation must answer; do not ask it or invent an answer in this conversation.\n\n## Procedure\n\n### Orient\n\nEstablish enough purpose and context to select one focused next action: the intended question or decision, audience, boundary, horizon, accuracy need, and available time. Orientation need not settle every concern before elicitation begins.\n\n### Elicit or revise\n\nFor a new account, follow one concrete case and re-evaluate the active gap after each useful answer. For an existing account, first locate the disputed or changed material and its consequence for the objective. Use the `elicitation` skill's universal guidance and `references/profile.md` for detailed operations and coverage; do not turn their register order into question order.\n\n### Maintain the workpiece\n\nTreat the workpiece as the recoverable account construction will consume. Update it after a useful stretch rather than waiting until the end. Preserve unrelated material unless new evidence affects it.\n\nWhenever the workpiece changes substantially, emit the full current document in a fenced block whose language tag is exactly `runbook-ir`. Emit it again before construction and before workpiece-only delivery. A delta or prose promise is not a recoverable workpiece.\n\n### Construct\n\nConstruct only from the current workpiece. Read `references/pn-construction.md` and `references/checks.md` before beginning. Use mounted Petrinaut tools for every net change and inspect the resulting definition rather than emitting free-form net JSON. If the required tools are absent, limit the result to the workpiece and construction-ready notes.\n\nConstruction may infer a representation from recorded operational meaning; it may not invent operational facts. Record construction inferences, approximations, defaults, and target losses in the workpiece.\n\n### Check and deliver\n\nApply `references/checks.md` whenever construction is prepared or attempted. Deliver the current workpiece in every branch. Deliver a net only when the mounted tool path has produced and checked one. State what the result can support, what remains open, what was assumed or simplified, and what the target or current tools could not represent.\n\nAn explicit stop opens no new topic. In an interactive conversation, emit the best current workpiece and any already-checked net with limitations visible. In construct-only execution, report a blocking gap rather than opening an interview.\n\n## Resource discipline\n\nRead resources directly from this skill's advertised resource list, using the exact `/.flue/packaged-skills/...` path shown in the activation briefing; the relative name is a label only. Do not treat Markdown links as includes, follow references recursively, or read construction material merely to frame ordinary interview questions.\n\n\nSupporting skill resources are available but are not loaded into context unless needed:\n\n- references/checks.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/references/checks.md\n- references/pn-construction.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/references/pn-construction.md\n- references/profile.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/references/profile.md\n- templates/workpiece.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/templates/workpiece.md\n", + "durationMs": 3 + }, + { + "type": "dynamic-tool", + "toolName": "getLatestNetDefinition", + "toolCallId": "toolu_01FjSrPHir7RNkmV1PUpZ1qu", + "state": "output-available", + "input": {}, + "output": { + "awaiting": "client" + }, + "durationMs": 3 + }, + { + "type": "reasoning", + "text": "The skill is activated. The net definition call shows `{\"awaiting\":\"client\"}` which means the browser needs to fetch it. Let me wait a moment for that result to come through via the client-tool-result signal, or I should ask the user about the current state. \n\nActually, I should ping first to confirm the server is in the loop, then proceed to understand what we have.", + "state": "done" + }, + { + "type": "text", + "text": "Let me confirm the server connection and then retrieve the current net definition:", + "state": "done" + }, + { + "type": "dynamic-tool", + "toolName": "ping", + "toolCallId": "toolu_01NpMVdLYpu7PeSDCfJqjwqA", + "state": "output-available", + "input": { + "note": "Confirming server ready for crew-reservation-v1 prepared-fixture work" + }, + "output": { + "ok": true, + "note": "Confirming server ready for crew-reservation-v1 prepared-fixture work" + }, + "durationMs": 1 + }, + { + "type": "reasoning", + "text": "Good, the server is ready. Now I should wait for the net definition from the browser. The getLatestNetDefinition returned `{\"awaiting\":\"client\"}` which means it's waiting for a client tool result. I should describe what I'm going to do next and wait for that result.", + "state": "done" + }, + { + "type": "text", + "text": "Good. Now let me work with the prepared-fixture material you've provided. \n\n## Understanding the prepared fixture\n\nYou've provided a **test-authored diagnostic workpiece** focused on the **final inspection → dispatch path** with one specific correction to test:\n\n**Operational account:**\n- A batch ready for dispatch enters final inspection\n- Starting final inspection *reserves* the single available dispatch crew\n- Sign-off *releases* that crew and marks the batch ready for dispatch\n\n**Current net state:**\n- Contains the batch path and the crew return from sign-off\n- **Deliberately omits** the weight-1 input arc from \"Dispatch crew available\" to \"Start final inspection\" \n\n**Purpose:** Test one evidence-backed correction against the live Petrinaut document.\n\n---\n\n## Next step\n\nThe Petrinaut net definition is being retrieved. Once I see the current structure, I can:\n\n1. **Verify** the operational account against what's in the net\n2. **Identify** the missing arc precisely \n3. **Test the correction** by adding that arc and confirming it satisfies the resource constraint (exactly one crew consumed at start, returned at sign-off)\n\nI'm waiting for the live net definition to come through. What I'll be looking for:\n- The places representing the batch states (ready, in-inspection, ready-for-dispatch)\n- The places for crew availability\n- The transitions for \"Start final inspection\" and \"Sign-off\"\n- Which arcs are already present and which are missing\n\nDoes this match your intention for this exercise?", + "state": "done" + } + ] + }, + { + "id": "entry_direct_c3ViX2lrX2I3YTI3NGI3YzI4MjVkNGMwOTE0ZGE0NDBlMjQxY2I2", + "role": "user", + "purpose": "user", + "display": "visible", + "submissionId": "sub_ik_b7a274b7c2825d4c0914da440e241cb6", + "parts": [ + { + "type": "text", + "text": "Confirmed: final inspection uses the single dispatch crew and sign-off releases it; timing, failure, and recovery remain unknown. Read the live Petrinaut definition, add the missing standard weight-1 input arc from Dispatch crew available to Start final inspection, verify it, and emit the full revised runbook-ir workpiece.", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NQGAVZ00RTNPHG4MM610XE", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_b7a274b7c2825d4c0914da440e241cb6", + "turnId": "turn_01M1NQGA4WJ01NC2MS1JJB0QWJ", + "parts": [ + { + "type": "reasoning", + "text": "The user has confirmed the operational intent and is asking me to:\n1. Read the live Petrinaut definition\n2. Add the missing standard weight-1 input arc from \"Dispatch crew available\" to \"Start final inspection\"\n3. Verify it\n4. Emit the full revised runbook-ir workpiece\n\nI need to call getLatestNetDefinition again to get the actual net definition since the previous call returned {\"awaiting\":\"client\"}.", + "state": "done" + }, + { + "type": "dynamic-tool", + "toolName": "getLatestNetDefinition", + "toolCallId": "toolu_01BqoDEZeq7HTqu3S8p6ZLA6", + "state": "output-available", + "input": {}, + "output": { + "awaiting": "client" + }, + "durationMs": 0 + } + ] + }, + { + "id": "entry_direct_c3ViX2lrX2RkMmViN2JlMjE5ODA5OThiODlhZTlhOWRhMDg1ZmIy", + "role": "system", + "purpose": "dispatch", + "display": "diagnostic", + "submissionId": "sub_ik_dd2eb7be21980998b89ae9a9da085fb2", + "signal": { + "tagName": "client-tool-result", + "attributes": { + "toolCallIds": "toolu_01BqoDEZeq7HTqu3S8p6ZLA6" + } + }, + "parts": [ + { + "type": "text", + "text": "[{\"toolCallId\":\"toolu_01BqoDEZeq7HTqu3S8p6ZLA6\",\"toolName\":\"getLatestNetDefinition\",\"output\":{\"title\":\"Prepared final inspection and dispatch\",\"definition\":{\"places\":[{\"id\":\"batch-ready\",\"name\":\"Batch ready\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":80,\"y\":100},{\"id\":\"under-final-inspection\",\"name\":\"Under final inspection\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":100},{\"id\":\"ready-for-dispatch\",\"name\":\"Ready for dispatch\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":760,\"y\":100},{\"id\":\"dispatch-crew-available\",\"name\":\"Dispatch crew available\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":360}],\"transitions\":[{\"id\":\"start-final-inspection\",\"name\":\"Start final inspection\",\"inputArcs\":[{\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":250,\"y\":100},{\"id\":\"sign-off\",\"name\":\"Sign-off\",\"inputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"ready-for-dispatch\",\"weight\":1},{\"placeId\":\"dispatch-crew-available\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":590,\"y\":100}],\"types\":[],\"differentialEquations\":[],\"parameters\":[]},\"extensions\":{\"colors\":true,\"stochasticity\":true,\"dynamics\":true,\"parameters\":true,\"subnets\":true}}}]", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NQGD1NRR36CBAX78EA666J", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_dd2eb7be21980998b89ae9a9da085fb2", + "turnId": "turn_01M1NQGC2ZFFFC5MFXN2949H93", + "parts": [ + { + "type": "reasoning", + "text": "Good! Now I have the live Petrinaut definition. Let me analyze it:\n\n**Current places:**\n1. `batch-ready` - batch waiting to enter inspection\n2. `under-final-inspection` - batch in inspection\n3. `ready-for-dispatch` - batch ready for dispatch (output state)\n4. `dispatch-crew-available` - represents availability of the single dispatch crew\n\n**Current transitions:**\n1. `start-final-inspection` - takes 1 batch from `batch-ready`, outputs 1 to `under-final-inspection`\n - Input arcs: `batch-ready` (weight 1, standard)\n - Output arcs: `under-final-inspection` (weight 1)\n\n2. `sign-off` - takes 1 batch from `under-final-inspection`, outputs 1 to `ready-for-dispatch` AND 1 to `dispatch-crew-available`\n - Input arcs: `under-final-inspection` (weight 1, standard)\n - Output arcs: `ready-for-dispatch` (weight 1), `dispatch-crew-available` (weight 1)\n\n**What's missing:**\nThe `start-final-inspection` transition is missing an input arc from `dispatch-crew-available`. When a batch starts final inspection, it should consume one crew token.\n\nAccording to the prepared fixture, this should be:\n- Arc direction: **input**\n- Source place: `dispatch-crew-available`\n- Weight: 1\n- Type: standard\n\nSo I need to add an input arc to `start-final-inspection` with:\n- placeId: `dispatch-crew-available`\n- weight: 1\n- type: `standard`\n\nLet me use the `addArc` function to add this arc.", + "state": "done" + }, + { + "type": "text", + "text": "Perfect. I can see the live net structure. Let me analyze it:\n\n**Current structure:**\n- **Places:** Batch-ready → Under-final-inspection → Ready-for-dispatch, plus Dispatch-crew-available\n- **start-final-inspection transition:** Currently has only one input arc (from batch-ready)\n- **sign-off transition:** Takes batch from inspection and outputs both the batch (to ready-for-dispatch) AND returns 1 crew token to dispatch-crew-available\n\n**Missing element:** The `start-final-inspection` transition lacks the input arc from `dispatch-crew-available`. This means the model currently allows inspection to begin without consuming the crew resource—violating the \"exactly one crew reserved\" constraint.\n\nNow I'll add the missing standard weight-1 input arc from `dispatch-crew-available` to `start-final-inspection`:", + "state": "done" + }, + { + "type": "dynamic-tool", + "toolName": "addArc", + "toolCallId": "toolu_01KLHzRE7gbPbFfPaXe3RTry", + "state": "output-available", + "input": { + "transitionId": "start-final-inspection", + "arcDirection": "input", + "placeId": "dispatch-crew-available", + "weight": "1", + "type": "standard" + }, + "output": { + "awaiting": "client" + }, + "durationMs": 0 + } + ] + }, + { + "id": "entry_direct_c3ViX2lrXzAwOGZhNmQ3MzU0NzQ5YTFjYjNmNjc0MTg0ZTdjYjFi", + "role": "system", + "purpose": "dispatch", + "display": "diagnostic", + "submissionId": "sub_ik_008fa6d7354749a1cb3f674184e7cb1b", + "signal": { + "tagName": "client-tool-result", + "attributes": { + "toolCallIds": "toolu_01BqoDEZeq7HTqu3S8p6ZLA6,toolu_01KLHzRE7gbPbFfPaXe3RTry" + } + }, + "parts": [ + { + "type": "text", + "text": "[{\"toolCallId\":\"toolu_01BqoDEZeq7HTqu3S8p6ZLA6\",\"toolName\":\"getLatestNetDefinition\",\"output\":{\"title\":\"Prepared final inspection and dispatch\",\"definition\":{\"places\":[{\"id\":\"batch-ready\",\"name\":\"Batch ready\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":80,\"y\":100},{\"id\":\"under-final-inspection\",\"name\":\"Under final inspection\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":100},{\"id\":\"ready-for-dispatch\",\"name\":\"Ready for dispatch\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":760,\"y\":100},{\"id\":\"dispatch-crew-available\",\"name\":\"Dispatch crew available\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":360}],\"transitions\":[{\"id\":\"start-final-inspection\",\"name\":\"Start final inspection\",\"inputArcs\":[{\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":250,\"y\":100},{\"id\":\"sign-off\",\"name\":\"Sign-off\",\"inputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"ready-for-dispatch\",\"weight\":1},{\"placeId\":\"dispatch-crew-available\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":590,\"y\":100}],\"types\":[],\"differentialEquations\":[],\"parameters\":[]},\"extensions\":{\"colors\":true,\"stochasticity\":true,\"dynamics\":true,\"parameters\":true,\"subnets\":true}}},{\"toolCallId\":\"toolu_01KLHzRE7gbPbFfPaXe3RTry\",\"toolName\":\"addArc\",\"output\":{\"title\":\"Added input arc\",\"detail\":\"Dispatch crew available <-> Start final inspection\",\"target\":{\"kind\":\"selection\",\"item\":{\"type\":\"arc\",\"id\":\"$A_place:dispatch-crew-available___start-final-inspection\"}},\"applied\":true}}]", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NQGMV82KXETG8X23QZHPM3", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_008fa6d7354749a1cb3f674184e7cb1b", + "turnId": "turn_01M1NQGKXT0H69NP5JFRYQJ2J7", + "parts": [ + { + "type": "reasoning", + "text": "Good! The arc has been added successfully. Let me verify by checking the live definition again to confirm the arc is now present in the start-final-inspection transition.\n\nLooking at the addArc output, it says \"Applied: true\" and created an arc with ID \"$A_place:dispatch-crew-available___start-final-inspection\". This is the confirmation.\n\nHowever, I notice that the getLatestNetDefinition result that came back still shows the old structure—the start-final-inspection transition still shows only one inputArc (from batch-ready). This might be a timing issue in how the results came back, or the definition might not have refreshed yet.\n\nLet me read the live definition one more time to verify the arc was actually applied and is visible in the current state.", + "state": "done" + }, + { + "type": "text", + "text": "Excellent! The arc addition was successful: `\"applied\":true`. Let me verify the updated net definition:", + "state": "done" + }, + { + "type": "dynamic-tool", + "toolName": "getLatestNetDefinition", + "toolCallId": "toolu_01LuBH9HSYSzvkCMq5E3PN57", + "state": "output-available", + "input": {}, + "output": { + "awaiting": "client" + }, + "durationMs": 0 + } + ] + }, + { + "id": "entry_direct_c3ViX2lrXzZkYmMxODdlNGU3Mjc5M2I3NTM5YzAyMzg3ZDA0NzE1", + "role": "system", + "purpose": "dispatch", + "display": "diagnostic", + "submissionId": "sub_ik_6dbc187e4e72793b7539c02387d04715", + "signal": { + "tagName": "client-tool-result", + "attributes": { + "toolCallIds": "toolu_01BqoDEZeq7HTqu3S8p6ZLA6,toolu_01KLHzRE7gbPbFfPaXe3RTry,toolu_01LuBH9HSYSzvkCMq5E3PN57" + } + }, + "parts": [ + { + "type": "text", + "text": "[{\"toolCallId\":\"toolu_01BqoDEZeq7HTqu3S8p6ZLA6\",\"toolName\":\"getLatestNetDefinition\",\"output\":{\"title\":\"Prepared final inspection and dispatch\",\"definition\":{\"places\":[{\"id\":\"batch-ready\",\"name\":\"Batch ready\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":80,\"y\":100},{\"id\":\"under-final-inspection\",\"name\":\"Under final inspection\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":100},{\"id\":\"ready-for-dispatch\",\"name\":\"Ready for dispatch\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":760,\"y\":100},{\"id\":\"dispatch-crew-available\",\"name\":\"Dispatch crew available\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":360}],\"transitions\":[{\"id\":\"start-final-inspection\",\"name\":\"Start final inspection\",\"inputArcs\":[{\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":250,\"y\":100},{\"id\":\"sign-off\",\"name\":\"Sign-off\",\"inputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"ready-for-dispatch\",\"weight\":1},{\"placeId\":\"dispatch-crew-available\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":590,\"y\":100}],\"types\":[],\"differentialEquations\":[],\"parameters\":[]},\"extensions\":{\"colors\":true,\"stochasticity\":true,\"dynamics\":true,\"parameters\":true,\"subnets\":true}}},{\"toolCallId\":\"toolu_01KLHzRE7gbPbFfPaXe3RTry\",\"toolName\":\"addArc\",\"output\":{\"title\":\"Added input arc\",\"detail\":\"Dispatch crew available <-> Start final inspection\",\"target\":{\"kind\":\"selection\",\"item\":{\"type\":\"arc\",\"id\":\"$A_place:dispatch-crew-available___start-final-inspection\"}},\"applied\":true}},{\"toolCallId\":\"toolu_01LuBH9HSYSzvkCMq5E3PN57\",\"toolName\":\"getLatestNetDefinition\",\"output\":{\"title\":\"Prepared final inspection and dispatch\",\"definition\":{\"places\":[{\"id\":\"batch-ready\",\"name\":\"Batch ready\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":80,\"y\":100},{\"id\":\"under-final-inspection\",\"name\":\"Under final inspection\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":100},{\"id\":\"ready-for-dispatch\",\"name\":\"Ready for dispatch\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":760,\"y\":100},{\"id\":\"dispatch-crew-available\",\"name\":\"Dispatch crew available\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":360}],\"transitions\":[{\"id\":\"start-final-inspection\",\"name\":\"Start final inspection\",\"inputArcs\":[{\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"},{\"type\":\"standard\",\"placeId\":\"dispatch-crew-available\",\"weight\":1}],\"outputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":250,\"y\":100},{\"id\":\"sign-off\",\"name\":\"Sign-off\",\"inputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"ready-for-dispatch\",\"weight\":1},{\"placeId\":\"dispatch-crew-available\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":590,\"y\":100}],\"types\":[],\"differentialEquations\":[],\"parameters\":[]},\"extensions\":{\"colors\":true,\"stochasticity\":true,\"dynamics\":true,\"parameters\":true,\"subnets\":true}}}]", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NQGRAKWG69MWYMPYTCFXCZ", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_6dbc187e4e72793b7539c02387d04715", + "turnId": "turn_01M1NQGQH38A3MMGGEWKN4VCDP", + "parts": [ + { + "type": "reasoning", + "text": "Perfect! The verification confirms the arc has been successfully added. Looking at the final definition:\n\nThe `start-final-inspection` transition now has two input arcs:\n1. `{\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"}`\n2. `{\"type\":\"standard\",\"placeId\":\"dispatch-crew-available\",\"weight\":1}`\n\nThis means:\n- Starting final inspection requires 1 token from \"batch-ready\" AND 1 token from \"dispatch-crew-available\"\n- It produces 1 token to \"under-final-inspection\"\n- The sign-off transition consumes the batch from inspection and returns 1 crew token\n\nThis satisfies the operational constraint: exactly one dispatch crew is consumed when inspection begins and released when sign-off completes.\n\nNow I need to emit the full revised runbook-ir workpiece as requested. I should update the prepared fixture material with:\n1. The operational account (confirmed)\n2. The current Petrinaut correspondence (UPDATED - the missing arc has been added)\n3. Explicit unknowns (unchanged)\n4. The claim boundary (adjusted to reflect what this correction establishes)", + "state": "done" + }, + { + "type": "text", + "text": "**Verification successful.** The `start-final-inspection` transition now contains the corrected input arcs:\n```json\n\"inputArcs\":[\n {\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"},\n {\"type\":\"standard\",\"placeId\":\"dispatch-crew-available\",\"weight\":1}\n]\n```\n\nThe resource constraint is now satisfied: firing `start-final-inspection` requires both a ready batch AND an available crew token. The `sign-off` transition releases that crew back to `dispatch-crew-available`.\n\n---\n\n## Revised workpiece (runbook-ir)\n\n```runbook-ir\n# Final inspection and dispatch workpiece — Revised\n\n## Purpose and posture\nModel the batch path from final inspection to dispatch readiness with explicit crew resource management. This revision adds the missing crew-consumption arc to enforce the resource constraint.\n\n## Operational account\n- A batch that is ready enters final inspection.\n- Starting final inspection requires both a ready batch AND the sole available dispatch crew.\n- Starting final inspection consumes that crew token.\n- Sign-off releases that crew and makes the batch ready for dispatch.\n\n## Quantity and resource policy\nExactly one dispatch crew is available. Starting final inspection consumes that one available crew; sign-off returns it. No transition fires without sufficient tokens in all input places.\n\n## Petrinaut correspondence\nThe net contains four places:\n- `batch-ready`: batches awaiting final inspection\n- `under-final-inspection`: batches currently in inspection\n- `ready-for-dispatch`: batches cleared for dispatch\n- `dispatch-crew-available`: crew availability (1 token when free)\n\nTransitions:\n- `start-final-inspection`: requires 1 token from batch-ready AND 1 token from dispatch-crew-available; produces 1 token to under-final-inspection\n- `sign-off`: requires 1 token from under-final-inspection; produces 1 token to ready-for-dispatch AND 1 token to dispatch-crew-available\n\nThe missing standard weight-1 input arc from `dispatch-crew-available` to `start-final-inspection` has been **added and verified** in the live Petrinaut definition.\n\n## Explicit unknowns\n- Inspection timing: duration, stochasticity, or determinism remain unresolved\n- Sign-off timing: duration, stochasticity, or determinism remain unresolved\n- Failure modes: whether inspection can fail, halt, or reject a batch\n- Recovery behavior: how failures or rejections affect batch state or crew availability\n\n## Claim boundary\nThis workpiece and the corrected net establish only:\n- The crew-consumption constraint at start of inspection\n- The crew-release at sign-off completion\n- Token flow from ready batch through inspection to dispatch readiness\n\nThis is test-authored diagnostic material for the narrow final-inspection–to-dispatch path. It does not establish capture provenance, behavioral execution, failure handling, full process projection, or integration with upstream or downstream operations.\n```\n\nThe correction is complete and verified in the live Petrinaut definition.", + "state": "done" + } + ] + } + ], + "settlements": [ + { + "submissionId": "sub_ik_f24939bebb841ffe1469a7f3a4a06915", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_f24939bebb841ffe1469a7f3a4a06915" + }, + { + "submissionId": "sub_ik_b7a274b7c2825d4c0914da440e241cb6", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_b7a274b7c2825d4c0914da440e241cb6" + }, + { + "submissionId": "sub_ik_dd2eb7be21980998b89ae9a9da085fb2", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_dd2eb7be21980998b89ae9a9da085fb2" + }, + { + "submissionId": "sub_ik_008fa6d7354749a1cb3f674184e7cb1b", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_008fa6d7354749a1cb3f674184e7cb1b" + }, + { + "submissionId": "sub_ik_6dbc187e4e72793b7539c02387d04715", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_6dbc187e4e72793b7539c02387d04715" + } + ], + "incarnation": "inc_01M1NQEXM24JHNYN40Q8RA5DH5" +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/flue-snapshot-before.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/flue-snapshot-before.json new file mode 100644 index 00000000000..a584f125feb --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/flue-snapshot-before.json @@ -0,0 +1,113 @@ +{ + "v": 1, + "conversationId": "conv_01M1NQEXM3CAPPTXM33ZE1YSRG", + "offset": "0000000000000000_0000000000000043", + "messages": [ + { + "id": "entry_direct_c3ViX2lrX2YyNDkzOWJlYmI4NDFmZmUxNDY5YTdmM2E0YTA2OTE1", + "role": "system", + "purpose": "dispatch", + "display": "diagnostic", + "submissionId": "sub_ik_f24939bebb841ffe1469a7f3a4a06915", + "signal": { + "tagName": "prepared-fixture", + "attributes": { + "fixtureId": "crew-reservation-v1", + "authorship": "test-authored", + "claimBoundary": "prepared-not-model-produced" + } + }, + "parts": [ + { + "type": "text", + "text": "Fixture authorship: test-authored preparation for Mission 6.\nNon-claims: not a Mission 4 candidate, not model-produced evidence, not capture-backed provenance, and not proof of automatic full-net projection.\n\n```runbook-ir\n# Final inspection and dispatch workpiece\n\n## Purpose and posture\nMaintain the narrow batch path from final inspection to dispatch readiness and test one evidence-backed correction against the live Petrinaut document.\n\n## Operational account\n- A batch that is ready enters final inspection.\n- Final inspection reserves the sole available dispatch crew.\n- Sign-off releases that crew and makes the batch ready for dispatch.\n\n## Quantity and resource policy\nExactly one dispatch crew is available in this fixture. Starting final inspection consumes that one available crew; sign-off returns it.\n\n## Current Petrinaut correspondence\nThe prepared non-empty net contains the batch path and the crew return from sign-off. It deliberately lacks the standard weight-1 input arc from `Dispatch crew available` to `Start final inspection`.\n\n## Explicit unknowns\nInspection and sign-off timing, failure modes, and recovery behavior remain unresolved.\n\n## Claim boundary\nThis prepared revision is test-authored diagnostic material. It is not model-produced evidence and does not establish capture provenance, behavioral execution, or broad projection quality.\n```", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NQEYF9W60J2JVDYB2BJXK1", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_f24939bebb841ffe1469a7f3a4a06915", + "turnId": "turn_01M1NQEXM7MHJ94PF52Q54VAY4", + "parts": [ + { + "type": "reasoning", + "text": "The user has provided a prepared-fixture for SDCPN modelling work. This is test-authored material that is:\n- Part of a Mission 6 exercise\n- Focused on a narrow batch path from final inspection to dispatch readiness\n- Aimed at testing one evidence-backed correction against the live Petrinaut document\n- Not model-produced evidence, not a capture-backed provenance, not proof of automatic full-net projection\n\nThe operational account describes:\n1. A batch that is ready enters final inspection\n2. Final inspection reserves the sole available dispatch crew\n3. Sign-off releases that crew and makes the batch ready for dispatch\n\nThe key policy: Exactly one dispatch crew is available. Starting final inspection consumes it; sign-off returns it.\n\nThe current state: The prepared non-empty net contains the batch path and the crew return from sign-off, but deliberately LACKS the standard weight-1 input arc from \"Dispatch crew available\" to \"Start final inspection\".\n\nThe purpose is to test one evidence-backed correction against the live Petrinaut document.\n\nMy role here is:\n1. First, activate the sdcpn-modelling skill since this is a process-modelling task\n2. Understand the current state of the Petrinaut net\n3. Help verify the operational account against the net\n4. Work with the user to identify and potentially implement the missing arc correction\n5. Maintain the workpiece with clear documentation of what is known, what is missing, and what has been tested\n\nLet me start by activating the skill and getting the current net state.", + "state": "done" + }, + { + "type": "text", + "text": "I'll help you with this prepared-fixture exercise. Let me start by activating the SDCPN modelling skill and then retrieving the current state of the Petrinaut net to understand what we're working with.", + "state": "done" + }, + { + "type": "dynamic-tool", + "toolName": "activate_skill", + "toolCallId": "toolu_01WQaZveys8joHtboYvGQiuA", + "state": "output-available", + "input": { + "name": "sdcpn-modelling" + }, + "output": "Run the skill named \"sdcpn-modelling\".\n\n\n# Capability-aware lifecycle\n\nUse one conceptual lifecycle: orient, elicit or revise, maintain the workpiece, construct when supported, check, and deliver. The current conversation may expose only one branch of that lifecycle. Do not claim that an unavailable transition occurred.\n\n## Select the runtime branch\n\n### Interactive elicitation or revision\n\nInterview in the person's operational vocabulary. Activate the `elicitation` skill and read `references/profile.md` before substantive questions or revision. Read `templates/workpiece.md` when creating or materially revising the shared workpiece. Construct only when the mounted capabilities actually permit construction in this conversation.\n\n### Construct-only execution\n\nUse the supplied workpiece as the complete modelling input. Do not interview. Read `references/pn-construction.md` and `references/checks.md`, then use the mounted construction tools. If a consequential workpiece gap prevents faithful construction, report the gap and the smallest question a later interactive elicitation must answer; do not ask it or invent an answer in this conversation.\n\n## Procedure\n\n### Orient\n\nEstablish enough purpose and context to select one focused next action: the intended question or decision, audience, boundary, horizon, accuracy need, and available time. Orientation need not settle every concern before elicitation begins.\n\n### Elicit or revise\n\nFor a new account, follow one concrete case and re-evaluate the active gap after each useful answer. For an existing account, first locate the disputed or changed material and its consequence for the objective. Use the `elicitation` skill's universal guidance and `references/profile.md` for detailed operations and coverage; do not turn their register order into question order.\n\n### Maintain the workpiece\n\nTreat the workpiece as the recoverable account construction will consume. Update it after a useful stretch rather than waiting until the end. Preserve unrelated material unless new evidence affects it.\n\nWhenever the workpiece changes substantially, emit the full current document in a fenced block whose language tag is exactly `runbook-ir`. Emit it again before construction and before workpiece-only delivery. A delta or prose promise is not a recoverable workpiece.\n\n### Construct\n\nConstruct only from the current workpiece. Read `references/pn-construction.md` and `references/checks.md` before beginning. Use mounted Petrinaut tools for every net change and inspect the resulting definition rather than emitting free-form net JSON. If the required tools are absent, limit the result to the workpiece and construction-ready notes.\n\nConstruction may infer a representation from recorded operational meaning; it may not invent operational facts. Record construction inferences, approximations, defaults, and target losses in the workpiece.\n\n### Check and deliver\n\nApply `references/checks.md` whenever construction is prepared or attempted. Deliver the current workpiece in every branch. Deliver a net only when the mounted tool path has produced and checked one. State what the result can support, what remains open, what was assumed or simplified, and what the target or current tools could not represent.\n\nAn explicit stop opens no new topic. In an interactive conversation, emit the best current workpiece and any already-checked net with limitations visible. In construct-only execution, report a blocking gap rather than opening an interview.\n\n## Resource discipline\n\nRead resources directly from this skill's advertised resource list, using the exact `/.flue/packaged-skills/...` path shown in the activation briefing; the relative name is a label only. Do not treat Markdown links as includes, follow references recursively, or read construction material merely to frame ordinary interview questions.\n\n\nSupporting skill resources are available but are not loaded into context unless needed:\n\n- references/checks.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/references/checks.md\n- references/pn-construction.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/references/pn-construction.md\n- references/profile.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/references/profile.md\n- templates/workpiece.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/templates/workpiece.md\n", + "durationMs": 3 + }, + { + "type": "dynamic-tool", + "toolName": "getLatestNetDefinition", + "toolCallId": "toolu_01FjSrPHir7RNkmV1PUpZ1qu", + "state": "output-available", + "input": {}, + "output": { + "awaiting": "client" + }, + "durationMs": 3 + }, + { + "type": "reasoning", + "text": "The skill is activated. The net definition call shows `{\"awaiting\":\"client\"}` which means the browser needs to fetch it. Let me wait a moment for that result to come through via the client-tool-result signal, or I should ask the user about the current state. \n\nActually, I should ping first to confirm the server is in the loop, then proceed to understand what we have.", + "state": "done" + }, + { + "type": "text", + "text": "Let me confirm the server connection and then retrieve the current net definition:", + "state": "done" + }, + { + "type": "dynamic-tool", + "toolName": "ping", + "toolCallId": "toolu_01NpMVdLYpu7PeSDCfJqjwqA", + "state": "output-available", + "input": { + "note": "Confirming server ready for crew-reservation-v1 prepared-fixture work" + }, + "output": { + "ok": true, + "note": "Confirming server ready for crew-reservation-v1 prepared-fixture work" + }, + "durationMs": 1 + }, + { + "type": "reasoning", + "text": "Good, the server is ready. Now I should wait for the net definition from the browser. The getLatestNetDefinition returned `{\"awaiting\":\"client\"}` which means it's waiting for a client tool result. I should describe what I'm going to do next and wait for that result.", + "state": "done" + }, + { + "type": "text", + "text": "Good. Now let me work with the prepared-fixture material you've provided. \n\n## Understanding the prepared fixture\n\nYou've provided a **test-authored diagnostic workpiece** focused on the **final inspection → dispatch path** with one specific correction to test:\n\n**Operational account:**\n- A batch ready for dispatch enters final inspection\n- Starting final inspection *reserves* the single available dispatch crew\n- Sign-off *releases* that crew and marks the batch ready for dispatch\n\n**Current net state:**\n- Contains the batch path and the crew return from sign-off\n- **Deliberately omits** the weight-1 input arc from \"Dispatch crew available\" to \"Start final inspection\" \n\n**Purpose:** Test one evidence-backed correction against the live Petrinaut document.\n\n---\n\n## Next step\n\nThe Petrinaut net definition is being retrieved. Once I see the current structure, I can:\n\n1. **Verify** the operational account against what's in the net\n2. **Identify** the missing arc precisely \n3. **Test the correction** by adding that arc and confirming it satisfies the resource constraint (exactly one crew consumed at start, returned at sign-off)\n\nI'm waiting for the live net definition to come through. What I'll be looking for:\n- The places representing the batch states (ready, in-inspection, ready-for-dispatch)\n- The places for crew availability\n- The transitions for \"Start final inspection\" and \"Sign-off\"\n- Which arcs are already present and which are missing\n\nDoes this match your intention for this exercise?", + "state": "done" + } + ] + } + ], + "settlements": [ + { + "submissionId": "sub_ik_f24939bebb841ffe1469a7f3a4a06915", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_f24939bebb841ffe1469a7f3a4a06915" + } + ], + "incarnation": "inc_01M1NQEXM24JHNYN40Q8RA5DH5" +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/flue-snapshot-tab-b.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/flue-snapshot-tab-b.json new file mode 100644 index 00000000000..4cb95e7516d --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/flue-snapshot-tab-b.json @@ -0,0 +1,360 @@ +{ + "v": 1, + "conversationId": "conv_01M1NQEXM3CAPPTXM33ZE1YSRG", + "offset": "0000000000000000_0000000000000123", + "messages": [ + { + "id": "entry_direct_c3ViX2lrX2YyNDkzOWJlYmI4NDFmZmUxNDY5YTdmM2E0YTA2OTE1", + "role": "system", + "purpose": "dispatch", + "display": "diagnostic", + "submissionId": "sub_ik_f24939bebb841ffe1469a7f3a4a06915", + "signal": { + "tagName": "prepared-fixture", + "attributes": { + "fixtureId": "crew-reservation-v1", + "authorship": "test-authored", + "claimBoundary": "prepared-not-model-produced" + } + }, + "parts": [ + { + "type": "text", + "text": "Fixture authorship: test-authored preparation for Mission 6.\nNon-claims: not a Mission 4 candidate, not model-produced evidence, not capture-backed provenance, and not proof of automatic full-net projection.\n\n```runbook-ir\n# Final inspection and dispatch workpiece\n\n## Purpose and posture\nMaintain the narrow batch path from final inspection to dispatch readiness and test one evidence-backed correction against the live Petrinaut document.\n\n## Operational account\n- A batch that is ready enters final inspection.\n- Final inspection reserves the sole available dispatch crew.\n- Sign-off releases that crew and makes the batch ready for dispatch.\n\n## Quantity and resource policy\nExactly one dispatch crew is available in this fixture. Starting final inspection consumes that one available crew; sign-off returns it.\n\n## Current Petrinaut correspondence\nThe prepared non-empty net contains the batch path and the crew return from sign-off. It deliberately lacks the standard weight-1 input arc from `Dispatch crew available` to `Start final inspection`.\n\n## Explicit unknowns\nInspection and sign-off timing, failure modes, and recovery behavior remain unresolved.\n\n## Claim boundary\nThis prepared revision is test-authored diagnostic material. It is not model-produced evidence and does not establish capture provenance, behavioral execution, or broad projection quality.\n```", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NQEYF9W60J2JVDYB2BJXK1", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_f24939bebb841ffe1469a7f3a4a06915", + "turnId": "turn_01M1NQEXM7MHJ94PF52Q54VAY4", + "parts": [ + { + "type": "reasoning", + "text": "The user has provided a prepared-fixture for SDCPN modelling work. This is test-authored material that is:\n- Part of a Mission 6 exercise\n- Focused on a narrow batch path from final inspection to dispatch readiness\n- Aimed at testing one evidence-backed correction against the live Petrinaut document\n- Not model-produced evidence, not a capture-backed provenance, not proof of automatic full-net projection\n\nThe operational account describes:\n1. A batch that is ready enters final inspection\n2. Final inspection reserves the sole available dispatch crew\n3. Sign-off releases that crew and makes the batch ready for dispatch\n\nThe key policy: Exactly one dispatch crew is available. Starting final inspection consumes it; sign-off returns it.\n\nThe current state: The prepared non-empty net contains the batch path and the crew return from sign-off, but deliberately LACKS the standard weight-1 input arc from \"Dispatch crew available\" to \"Start final inspection\".\n\nThe purpose is to test one evidence-backed correction against the live Petrinaut document.\n\nMy role here is:\n1. First, activate the sdcpn-modelling skill since this is a process-modelling task\n2. Understand the current state of the Petrinaut net\n3. Help verify the operational account against the net\n4. Work with the user to identify and potentially implement the missing arc correction\n5. Maintain the workpiece with clear documentation of what is known, what is missing, and what has been tested\n\nLet me start by activating the skill and getting the current net state.", + "state": "done" + }, + { + "type": "text", + "text": "I'll help you with this prepared-fixture exercise. Let me start by activating the SDCPN modelling skill and then retrieving the current state of the Petrinaut net to understand what we're working with.", + "state": "done" + }, + { + "type": "dynamic-tool", + "toolName": "activate_skill", + "toolCallId": "toolu_01WQaZveys8joHtboYvGQiuA", + "state": "output-available", + "input": { + "name": "sdcpn-modelling" + }, + "output": "Run the skill named \"sdcpn-modelling\".\n\n\n# Capability-aware lifecycle\n\nUse one conceptual lifecycle: orient, elicit or revise, maintain the workpiece, construct when supported, check, and deliver. The current conversation may expose only one branch of that lifecycle. Do not claim that an unavailable transition occurred.\n\n## Select the runtime branch\n\n### Interactive elicitation or revision\n\nInterview in the person's operational vocabulary. Activate the `elicitation` skill and read `references/profile.md` before substantive questions or revision. Read `templates/workpiece.md` when creating or materially revising the shared workpiece. Construct only when the mounted capabilities actually permit construction in this conversation.\n\n### Construct-only execution\n\nUse the supplied workpiece as the complete modelling input. Do not interview. Read `references/pn-construction.md` and `references/checks.md`, then use the mounted construction tools. If a consequential workpiece gap prevents faithful construction, report the gap and the smallest question a later interactive elicitation must answer; do not ask it or invent an answer in this conversation.\n\n## Procedure\n\n### Orient\n\nEstablish enough purpose and context to select one focused next action: the intended question or decision, audience, boundary, horizon, accuracy need, and available time. Orientation need not settle every concern before elicitation begins.\n\n### Elicit or revise\n\nFor a new account, follow one concrete case and re-evaluate the active gap after each useful answer. For an existing account, first locate the disputed or changed material and its consequence for the objective. Use the `elicitation` skill's universal guidance and `references/profile.md` for detailed operations and coverage; do not turn their register order into question order.\n\n### Maintain the workpiece\n\nTreat the workpiece as the recoverable account construction will consume. Update it after a useful stretch rather than waiting until the end. Preserve unrelated material unless new evidence affects it.\n\nWhenever the workpiece changes substantially, emit the full current document in a fenced block whose language tag is exactly `runbook-ir`. Emit it again before construction and before workpiece-only delivery. A delta or prose promise is not a recoverable workpiece.\n\n### Construct\n\nConstruct only from the current workpiece. Read `references/pn-construction.md` and `references/checks.md` before beginning. Use mounted Petrinaut tools for every net change and inspect the resulting definition rather than emitting free-form net JSON. If the required tools are absent, limit the result to the workpiece and construction-ready notes.\n\nConstruction may infer a representation from recorded operational meaning; it may not invent operational facts. Record construction inferences, approximations, defaults, and target losses in the workpiece.\n\n### Check and deliver\n\nApply `references/checks.md` whenever construction is prepared or attempted. Deliver the current workpiece in every branch. Deliver a net only when the mounted tool path has produced and checked one. State what the result can support, what remains open, what was assumed or simplified, and what the target or current tools could not represent.\n\nAn explicit stop opens no new topic. In an interactive conversation, emit the best current workpiece and any already-checked net with limitations visible. In construct-only execution, report a blocking gap rather than opening an interview.\n\n## Resource discipline\n\nRead resources directly from this skill's advertised resource list, using the exact `/.flue/packaged-skills/...` path shown in the activation briefing; the relative name is a label only. Do not treat Markdown links as includes, follow references recursively, or read construction material merely to frame ordinary interview questions.\n\n\nSupporting skill resources are available but are not loaded into context unless needed:\n\n- references/checks.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/references/checks.md\n- references/pn-construction.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/references/pn-construction.md\n- references/profile.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/references/profile.md\n- templates/workpiece.md → read_skill_resource /.flue/packaged-skills/skill%3Asdcpn-modelling%3A99a447ec4bcbf6c0/templates/workpiece.md\n", + "durationMs": 3 + }, + { + "type": "dynamic-tool", + "toolName": "getLatestNetDefinition", + "toolCallId": "toolu_01FjSrPHir7RNkmV1PUpZ1qu", + "state": "output-available", + "input": {}, + "output": { + "awaiting": "client" + }, + "durationMs": 3 + }, + { + "type": "reasoning", + "text": "The skill is activated. The net definition call shows `{\"awaiting\":\"client\"}` which means the browser needs to fetch it. Let me wait a moment for that result to come through via the client-tool-result signal, or I should ask the user about the current state. \n\nActually, I should ping first to confirm the server is in the loop, then proceed to understand what we have.", + "state": "done" + }, + { + "type": "text", + "text": "Let me confirm the server connection and then retrieve the current net definition:", + "state": "done" + }, + { + "type": "dynamic-tool", + "toolName": "ping", + "toolCallId": "toolu_01NpMVdLYpu7PeSDCfJqjwqA", + "state": "output-available", + "input": { + "note": "Confirming server ready for crew-reservation-v1 prepared-fixture work" + }, + "output": { + "ok": true, + "note": "Confirming server ready for crew-reservation-v1 prepared-fixture work" + }, + "durationMs": 1 + }, + { + "type": "reasoning", + "text": "Good, the server is ready. Now I should wait for the net definition from the browser. The getLatestNetDefinition returned `{\"awaiting\":\"client\"}` which means it's waiting for a client tool result. I should describe what I'm going to do next and wait for that result.", + "state": "done" + }, + { + "type": "text", + "text": "Good. Now let me work with the prepared-fixture material you've provided. \n\n## Understanding the prepared fixture\n\nYou've provided a **test-authored diagnostic workpiece** focused on the **final inspection → dispatch path** with one specific correction to test:\n\n**Operational account:**\n- A batch ready for dispatch enters final inspection\n- Starting final inspection *reserves* the single available dispatch crew\n- Sign-off *releases* that crew and marks the batch ready for dispatch\n\n**Current net state:**\n- Contains the batch path and the crew return from sign-off\n- **Deliberately omits** the weight-1 input arc from \"Dispatch crew available\" to \"Start final inspection\" \n\n**Purpose:** Test one evidence-backed correction against the live Petrinaut document.\n\n---\n\n## Next step\n\nThe Petrinaut net definition is being retrieved. Once I see the current structure, I can:\n\n1. **Verify** the operational account against what's in the net\n2. **Identify** the missing arc precisely \n3. **Test the correction** by adding that arc and confirming it satisfies the resource constraint (exactly one crew consumed at start, returned at sign-off)\n\nI'm waiting for the live net definition to come through. What I'll be looking for:\n- The places representing the batch states (ready, in-inspection, ready-for-dispatch)\n- The places for crew availability\n- The transitions for \"Start final inspection\" and \"Sign-off\"\n- Which arcs are already present and which are missing\n\nDoes this match your intention for this exercise?", + "state": "done" + } + ] + }, + { + "id": "entry_direct_c3ViX2lrX2I3YTI3NGI3YzI4MjVkNGMwOTE0ZGE0NDBlMjQxY2I2", + "role": "user", + "purpose": "user", + "display": "visible", + "submissionId": "sub_ik_b7a274b7c2825d4c0914da440e241cb6", + "parts": [ + { + "type": "text", + "text": "Confirmed: final inspection uses the single dispatch crew and sign-off releases it; timing, failure, and recovery remain unknown. Read the live Petrinaut definition, add the missing standard weight-1 input arc from Dispatch crew available to Start final inspection, verify it, and emit the full revised runbook-ir workpiece.", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NQGAVZ00RTNPHG4MM610XE", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_b7a274b7c2825d4c0914da440e241cb6", + "turnId": "turn_01M1NQGA4WJ01NC2MS1JJB0QWJ", + "parts": [ + { + "type": "reasoning", + "text": "The user has confirmed the operational intent and is asking me to:\n1. Read the live Petrinaut definition\n2. Add the missing standard weight-1 input arc from \"Dispatch crew available\" to \"Start final inspection\"\n3. Verify it\n4. Emit the full revised runbook-ir workpiece\n\nI need to call getLatestNetDefinition again to get the actual net definition since the previous call returned {\"awaiting\":\"client\"}.", + "state": "done" + }, + { + "type": "dynamic-tool", + "toolName": "getLatestNetDefinition", + "toolCallId": "toolu_01BqoDEZeq7HTqu3S8p6ZLA6", + "state": "output-available", + "input": {}, + "output": { + "awaiting": "client" + }, + "durationMs": 0 + } + ] + }, + { + "id": "entry_direct_c3ViX2lrX2RkMmViN2JlMjE5ODA5OThiODlhZTlhOWRhMDg1ZmIy", + "role": "system", + "purpose": "dispatch", + "display": "diagnostic", + "submissionId": "sub_ik_dd2eb7be21980998b89ae9a9da085fb2", + "signal": { + "tagName": "client-tool-result", + "attributes": { + "toolCallIds": "toolu_01BqoDEZeq7HTqu3S8p6ZLA6" + } + }, + "parts": [ + { + "type": "text", + "text": "[{\"toolCallId\":\"toolu_01BqoDEZeq7HTqu3S8p6ZLA6\",\"toolName\":\"getLatestNetDefinition\",\"output\":{\"title\":\"Prepared final inspection and dispatch\",\"definition\":{\"places\":[{\"id\":\"batch-ready\",\"name\":\"Batch ready\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":80,\"y\":100},{\"id\":\"under-final-inspection\",\"name\":\"Under final inspection\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":100},{\"id\":\"ready-for-dispatch\",\"name\":\"Ready for dispatch\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":760,\"y\":100},{\"id\":\"dispatch-crew-available\",\"name\":\"Dispatch crew available\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":360}],\"transitions\":[{\"id\":\"start-final-inspection\",\"name\":\"Start final inspection\",\"inputArcs\":[{\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":250,\"y\":100},{\"id\":\"sign-off\",\"name\":\"Sign-off\",\"inputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"ready-for-dispatch\",\"weight\":1},{\"placeId\":\"dispatch-crew-available\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":590,\"y\":100}],\"types\":[],\"differentialEquations\":[],\"parameters\":[]},\"extensions\":{\"colors\":true,\"stochasticity\":true,\"dynamics\":true,\"parameters\":true,\"subnets\":true}}}]", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NQGD1NRR36CBAX78EA666J", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_dd2eb7be21980998b89ae9a9da085fb2", + "turnId": "turn_01M1NQGC2ZFFFC5MFXN2949H93", + "parts": [ + { + "type": "reasoning", + "text": "Good! Now I have the live Petrinaut definition. Let me analyze it:\n\n**Current places:**\n1. `batch-ready` - batch waiting to enter inspection\n2. `under-final-inspection` - batch in inspection\n3. `ready-for-dispatch` - batch ready for dispatch (output state)\n4. `dispatch-crew-available` - represents availability of the single dispatch crew\n\n**Current transitions:**\n1. `start-final-inspection` - takes 1 batch from `batch-ready`, outputs 1 to `under-final-inspection`\n - Input arcs: `batch-ready` (weight 1, standard)\n - Output arcs: `under-final-inspection` (weight 1)\n\n2. `sign-off` - takes 1 batch from `under-final-inspection`, outputs 1 to `ready-for-dispatch` AND 1 to `dispatch-crew-available`\n - Input arcs: `under-final-inspection` (weight 1, standard)\n - Output arcs: `ready-for-dispatch` (weight 1), `dispatch-crew-available` (weight 1)\n\n**What's missing:**\nThe `start-final-inspection` transition is missing an input arc from `dispatch-crew-available`. When a batch starts final inspection, it should consume one crew token.\n\nAccording to the prepared fixture, this should be:\n- Arc direction: **input**\n- Source place: `dispatch-crew-available`\n- Weight: 1\n- Type: standard\n\nSo I need to add an input arc to `start-final-inspection` with:\n- placeId: `dispatch-crew-available`\n- weight: 1\n- type: `standard`\n\nLet me use the `addArc` function to add this arc.", + "state": "done" + }, + { + "type": "text", + "text": "Perfect. I can see the live net structure. Let me analyze it:\n\n**Current structure:**\n- **Places:** Batch-ready → Under-final-inspection → Ready-for-dispatch, plus Dispatch-crew-available\n- **start-final-inspection transition:** Currently has only one input arc (from batch-ready)\n- **sign-off transition:** Takes batch from inspection and outputs both the batch (to ready-for-dispatch) AND returns 1 crew token to dispatch-crew-available\n\n**Missing element:** The `start-final-inspection` transition lacks the input arc from `dispatch-crew-available`. This means the model currently allows inspection to begin without consuming the crew resource—violating the \"exactly one crew reserved\" constraint.\n\nNow I'll add the missing standard weight-1 input arc from `dispatch-crew-available` to `start-final-inspection`:", + "state": "done" + }, + { + "type": "dynamic-tool", + "toolName": "addArc", + "toolCallId": "toolu_01KLHzRE7gbPbFfPaXe3RTry", + "state": "output-available", + "input": { + "transitionId": "start-final-inspection", + "arcDirection": "input", + "placeId": "dispatch-crew-available", + "weight": "1", + "type": "standard" + }, + "output": { + "awaiting": "client" + }, + "durationMs": 0 + } + ] + }, + { + "id": "entry_direct_c3ViX2lrXzAwOGZhNmQ3MzU0NzQ5YTFjYjNmNjc0MTg0ZTdjYjFi", + "role": "system", + "purpose": "dispatch", + "display": "diagnostic", + "submissionId": "sub_ik_008fa6d7354749a1cb3f674184e7cb1b", + "signal": { + "tagName": "client-tool-result", + "attributes": { + "toolCallIds": "toolu_01BqoDEZeq7HTqu3S8p6ZLA6,toolu_01KLHzRE7gbPbFfPaXe3RTry" + } + }, + "parts": [ + { + "type": "text", + "text": "[{\"toolCallId\":\"toolu_01BqoDEZeq7HTqu3S8p6ZLA6\",\"toolName\":\"getLatestNetDefinition\",\"output\":{\"title\":\"Prepared final inspection and dispatch\",\"definition\":{\"places\":[{\"id\":\"batch-ready\",\"name\":\"Batch ready\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":80,\"y\":100},{\"id\":\"under-final-inspection\",\"name\":\"Under final inspection\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":100},{\"id\":\"ready-for-dispatch\",\"name\":\"Ready for dispatch\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":760,\"y\":100},{\"id\":\"dispatch-crew-available\",\"name\":\"Dispatch crew available\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":360}],\"transitions\":[{\"id\":\"start-final-inspection\",\"name\":\"Start final inspection\",\"inputArcs\":[{\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":250,\"y\":100},{\"id\":\"sign-off\",\"name\":\"Sign-off\",\"inputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"ready-for-dispatch\",\"weight\":1},{\"placeId\":\"dispatch-crew-available\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":590,\"y\":100}],\"types\":[],\"differentialEquations\":[],\"parameters\":[]},\"extensions\":{\"colors\":true,\"stochasticity\":true,\"dynamics\":true,\"parameters\":true,\"subnets\":true}}},{\"toolCallId\":\"toolu_01KLHzRE7gbPbFfPaXe3RTry\",\"toolName\":\"addArc\",\"output\":{\"title\":\"Added input arc\",\"detail\":\"Dispatch crew available <-> Start final inspection\",\"target\":{\"kind\":\"selection\",\"item\":{\"type\":\"arc\",\"id\":\"$A_place:dispatch-crew-available___start-final-inspection\"}},\"applied\":true}}]", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NQGMV82KXETG8X23QZHPM3", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_008fa6d7354749a1cb3f674184e7cb1b", + "turnId": "turn_01M1NQGKXT0H69NP5JFRYQJ2J7", + "parts": [ + { + "type": "reasoning", + "text": "Good! The arc has been added successfully. Let me verify by checking the live definition again to confirm the arc is now present in the start-final-inspection transition.\n\nLooking at the addArc output, it says \"Applied: true\" and created an arc with ID \"$A_place:dispatch-crew-available___start-final-inspection\". This is the confirmation.\n\nHowever, I notice that the getLatestNetDefinition result that came back still shows the old structure—the start-final-inspection transition still shows only one inputArc (from batch-ready). This might be a timing issue in how the results came back, or the definition might not have refreshed yet.\n\nLet me read the live definition one more time to verify the arc was actually applied and is visible in the current state.", + "state": "done" + }, + { + "type": "text", + "text": "Excellent! The arc addition was successful: `\"applied\":true`. Let me verify the updated net definition:", + "state": "done" + }, + { + "type": "dynamic-tool", + "toolName": "getLatestNetDefinition", + "toolCallId": "toolu_01LuBH9HSYSzvkCMq5E3PN57", + "state": "output-available", + "input": {}, + "output": { + "awaiting": "client" + }, + "durationMs": 0 + } + ] + }, + { + "id": "entry_direct_c3ViX2lrXzZkYmMxODdlNGU3Mjc5M2I3NTM5YzAyMzg3ZDA0NzE1", + "role": "system", + "purpose": "dispatch", + "display": "diagnostic", + "submissionId": "sub_ik_6dbc187e4e72793b7539c02387d04715", + "signal": { + "tagName": "client-tool-result", + "attributes": { + "toolCallIds": "toolu_01BqoDEZeq7HTqu3S8p6ZLA6,toolu_01KLHzRE7gbPbFfPaXe3RTry,toolu_01LuBH9HSYSzvkCMq5E3PN57" + } + }, + "parts": [ + { + "type": "text", + "text": "[{\"toolCallId\":\"toolu_01BqoDEZeq7HTqu3S8p6ZLA6\",\"toolName\":\"getLatestNetDefinition\",\"output\":{\"title\":\"Prepared final inspection and dispatch\",\"definition\":{\"places\":[{\"id\":\"batch-ready\",\"name\":\"Batch ready\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":80,\"y\":100},{\"id\":\"under-final-inspection\",\"name\":\"Under final inspection\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":100},{\"id\":\"ready-for-dispatch\",\"name\":\"Ready for dispatch\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":760,\"y\":100},{\"id\":\"dispatch-crew-available\",\"name\":\"Dispatch crew available\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":360}],\"transitions\":[{\"id\":\"start-final-inspection\",\"name\":\"Start final inspection\",\"inputArcs\":[{\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":250,\"y\":100},{\"id\":\"sign-off\",\"name\":\"Sign-off\",\"inputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"ready-for-dispatch\",\"weight\":1},{\"placeId\":\"dispatch-crew-available\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":590,\"y\":100}],\"types\":[],\"differentialEquations\":[],\"parameters\":[]},\"extensions\":{\"colors\":true,\"stochasticity\":true,\"dynamics\":true,\"parameters\":true,\"subnets\":true}}},{\"toolCallId\":\"toolu_01KLHzRE7gbPbFfPaXe3RTry\",\"toolName\":\"addArc\",\"output\":{\"title\":\"Added input arc\",\"detail\":\"Dispatch crew available <-> Start final inspection\",\"target\":{\"kind\":\"selection\",\"item\":{\"type\":\"arc\",\"id\":\"$A_place:dispatch-crew-available___start-final-inspection\"}},\"applied\":true}},{\"toolCallId\":\"toolu_01LuBH9HSYSzvkCMq5E3PN57\",\"toolName\":\"getLatestNetDefinition\",\"output\":{\"title\":\"Prepared final inspection and dispatch\",\"definition\":{\"places\":[{\"id\":\"batch-ready\",\"name\":\"Batch ready\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":80,\"y\":100},{\"id\":\"under-final-inspection\",\"name\":\"Under final inspection\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":100},{\"id\":\"ready-for-dispatch\",\"name\":\"Ready for dispatch\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":760,\"y\":100},{\"id\":\"dispatch-crew-available\",\"name\":\"Dispatch crew available\",\"colorId\":null,\"dynamicsEnabled\":false,\"differentialEquationId\":null,\"x\":420,\"y\":360}],\"transitions\":[{\"id\":\"start-final-inspection\",\"name\":\"Start final inspection\",\"inputArcs\":[{\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"},{\"type\":\"standard\",\"placeId\":\"dispatch-crew-available\",\"weight\":1}],\"outputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":250,\"y\":100},{\"id\":\"sign-off\",\"name\":\"Sign-off\",\"inputArcs\":[{\"placeId\":\"under-final-inspection\",\"weight\":1,\"type\":\"standard\"}],\"outputArcs\":[{\"placeId\":\"ready-for-dispatch\",\"weight\":1},{\"placeId\":\"dispatch-crew-available\",\"weight\":1}],\"lambdaType\":\"predicate\",\"lambdaCode\":\"\",\"transitionKernelCode\":\"\",\"x\":590,\"y\":100}],\"types\":[],\"differentialEquations\":[],\"parameters\":[]},\"extensions\":{\"colors\":true,\"stochasticity\":true,\"dynamics\":true,\"parameters\":true,\"subnets\":true}}}]", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NQGRAKWG69MWYMPYTCFXCZ", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_6dbc187e4e72793b7539c02387d04715", + "turnId": "turn_01M1NQGQH38A3MMGGEWKN4VCDP", + "parts": [ + { + "type": "reasoning", + "text": "Perfect! The verification confirms the arc has been successfully added. Looking at the final definition:\n\nThe `start-final-inspection` transition now has two input arcs:\n1. `{\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"}`\n2. `{\"type\":\"standard\",\"placeId\":\"dispatch-crew-available\",\"weight\":1}`\n\nThis means:\n- Starting final inspection requires 1 token from \"batch-ready\" AND 1 token from \"dispatch-crew-available\"\n- It produces 1 token to \"under-final-inspection\"\n- The sign-off transition consumes the batch from inspection and returns 1 crew token\n\nThis satisfies the operational constraint: exactly one dispatch crew is consumed when inspection begins and released when sign-off completes.\n\nNow I need to emit the full revised runbook-ir workpiece as requested. I should update the prepared fixture material with:\n1. The operational account (confirmed)\n2. The current Petrinaut correspondence (UPDATED - the missing arc has been added)\n3. Explicit unknowns (unchanged)\n4. The claim boundary (adjusted to reflect what this correction establishes)", + "state": "done" + }, + { + "type": "text", + "text": "**Verification successful.** The `start-final-inspection` transition now contains the corrected input arcs:\n```json\n\"inputArcs\":[\n {\"placeId\":\"batch-ready\",\"weight\":1,\"type\":\"standard\"},\n {\"type\":\"standard\",\"placeId\":\"dispatch-crew-available\",\"weight\":1}\n]\n```\n\nThe resource constraint is now satisfied: firing `start-final-inspection` requires both a ready batch AND an available crew token. The `sign-off` transition releases that crew back to `dispatch-crew-available`.\n\n---\n\n## Revised workpiece (runbook-ir)\n\n```runbook-ir\n# Final inspection and dispatch workpiece — Revised\n\n## Purpose and posture\nModel the batch path from final inspection to dispatch readiness with explicit crew resource management. This revision adds the missing crew-consumption arc to enforce the resource constraint.\n\n## Operational account\n- A batch that is ready enters final inspection.\n- Starting final inspection requires both a ready batch AND the sole available dispatch crew.\n- Starting final inspection consumes that crew token.\n- Sign-off releases that crew and makes the batch ready for dispatch.\n\n## Quantity and resource policy\nExactly one dispatch crew is available. Starting final inspection consumes that one available crew; sign-off returns it. No transition fires without sufficient tokens in all input places.\n\n## Petrinaut correspondence\nThe net contains four places:\n- `batch-ready`: batches awaiting final inspection\n- `under-final-inspection`: batches currently in inspection\n- `ready-for-dispatch`: batches cleared for dispatch\n- `dispatch-crew-available`: crew availability (1 token when free)\n\nTransitions:\n- `start-final-inspection`: requires 1 token from batch-ready AND 1 token from dispatch-crew-available; produces 1 token to under-final-inspection\n- `sign-off`: requires 1 token from under-final-inspection; produces 1 token to ready-for-dispatch AND 1 token to dispatch-crew-available\n\nThe missing standard weight-1 input arc from `dispatch-crew-available` to `start-final-inspection` has been **added and verified** in the live Petrinaut definition.\n\n## Explicit unknowns\n- Inspection timing: duration, stochasticity, or determinism remain unresolved\n- Sign-off timing: duration, stochasticity, or determinism remain unresolved\n- Failure modes: whether inspection can fail, halt, or reject a batch\n- Recovery behavior: how failures or rejections affect batch state or crew availability\n\n## Claim boundary\nThis workpiece and the corrected net establish only:\n- The crew-consumption constraint at start of inspection\n- The crew-release at sign-off completion\n- Token flow from ready batch through inspection to dispatch readiness\n\nThis is test-authored diagnostic material for the narrow final-inspection–to-dispatch path. It does not establish capture provenance, behavioral execution, failure handling, full process projection, or integration with upstream or downstream operations.\n```\n\nThe correction is complete and verified in the live Petrinaut definition.", + "state": "done" + } + ] + }, + { + "id": "entry_direct_c3ViX2lrXzg4NDFkMzZmMWUyZTRiYTlmMzk4NTJiZTU0ZDJlMTc0", + "role": "user", + "purpose": "user", + "display": "visible", + "submissionId": "sub_ik_8841d36f1e2e4ba9f39852be54d2e174", + "parts": [ + { + "type": "text", + "text": "From the resumed workpiece, list the unresolved timing, failure, and recovery questions. Do not change the Petrinaut net.", + "state": "done" + } + ] + }, + { + "id": "entry_01M1NQJG7GRPC479PRF826T6F3", + "role": "assistant", + "purpose": "assistant", + "display": "visible", + "submissionId": "sub_ik_8841d36f1e2e4ba9f39852be54d2e174", + "turnId": "turn_01M1NQJFBBXYRZE472GFGHQF4K", + "parts": [ + { + "type": "reasoning", + "text": "The user wants me to extract and list the unresolved questions from the \"Explicit unknowns\" and \"Claim boundary\" sections of the workpiece I just delivered. They explicitly don't want me to change the Petrinaut net, just to articulate the open questions.\n\nLet me pull out the specific questions that remain unresolved:\n\nFrom \"Explicit unknowns\":\n1. Inspection timing: duration, stochasticity, or determinism remain unresolved\n2. Sign-off timing: duration, stochasticity, or determinism remain unresolved\n3. Failure modes: whether inspection can fail, halt, or reject a batch\n4. Recovery behavior: how failures or rejections affect batch state or crew availability\n\nI should unpack these into concrete questions that would need answering in a real operational investigation.", + "state": "done" + }, + { + "type": "text", + "text": "## Unresolved questions from the workpiece\n\n### Inspection timing\n1. How long does final inspection take—is it a fixed duration or variable?\n2. If variable, what distribution describes inspection duration (exponential, log-normal, empirical)?\n3. Does inspection timing depend on batch characteristics (size, composition, prior history)?\n4. Is inspection deterministic or does it include randomness?\n\n### Sign-off timing\n1. How long does sign-off take after inspection completes—is it immediate, fixed, or variable?\n2. If variable, what distribution describes sign-off duration?\n3. Does sign-off timing depend on inspection outcome or batch properties?\n4. Is sign-off deterministic or does it include randomness?\n\n### Failure modes\n1. Can a batch fail final inspection? If so, what triggers failure?\n2. Can inspection halt or pause without completing (e.g., awaiting additional information)?\n3. Can a batch be rejected at sign-off after passing inspection?\n4. Can the crew become unavailable during inspection (unavoidable absence, equipment failure, reassignment)?\n\n### Recovery behavior\n1. If a batch fails inspection, where does it go—back to ready, to a separate rework queue, or discarded?\n2. If a batch fails, does the crew become available immediately or does recovery consume crew time?\n3. If inspection halts mid-process, does the crew remain locked or become available?\n4. If rejected at sign-off, does the batch cycle back through inspection or follow a different path?\n5. If the crew becomes unavailable mid-inspection, what happens to the batch and the crew state?\n\nThese questions determine whether timing needs stochastic transitions, whether the batch path branches on failure, and how crew availability and batch state interact under exceptions. The current net cannot represent any of these behaviors.", + "state": "done" + } + ] + } + ], + "settlements": [ + { + "submissionId": "sub_ik_f24939bebb841ffe1469a7f3a4a06915", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_f24939bebb841ffe1469a7f3a4a06915" + }, + { + "submissionId": "sub_ik_b7a274b7c2825d4c0914da440e241cb6", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_b7a274b7c2825d4c0914da440e241cb6" + }, + { + "submissionId": "sub_ik_dd2eb7be21980998b89ae9a9da085fb2", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_dd2eb7be21980998b89ae9a9da085fb2" + }, + { + "submissionId": "sub_ik_008fa6d7354749a1cb3f674184e7cb1b", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_008fa6d7354749a1cb3f674184e7cb1b" + }, + { + "submissionId": "sub_ik_6dbc187e4e72793b7539c02387d04715", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_6dbc187e4e72793b7539c02387d04715" + }, + { + "submissionId": "sub_ik_8841d36f1e2e4ba9f39852be54d2e174", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_8841d36f1e2e4ba9f39852be54d2e174" + } + ], + "incarnation": "inc_01M1NQEXM24JHNYN40Q8RA5DH5" +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/latest-workpiece.md b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/latest-workpiece.md new file mode 100644 index 00000000000..be2a95f9fc4 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/latest-workpiece.md @@ -0,0 +1,40 @@ +# Final inspection and dispatch workpiece — Revised + +## Purpose and posture +Model the batch path from final inspection to dispatch readiness with explicit crew resource management. This revision adds the missing crew-consumption arc to enforce the resource constraint. + +## Operational account +- A batch that is ready enters final inspection. +- Starting final inspection requires both a ready batch AND the sole available dispatch crew. +- Starting final inspection consumes that crew token. +- Sign-off releases that crew and makes the batch ready for dispatch. + +## Quantity and resource policy +Exactly one dispatch crew is available. Starting final inspection consumes that one available crew; sign-off returns it. No transition fires without sufficient tokens in all input places. + +## Petrinaut correspondence +The net contains four places: +- `batch-ready`: batches awaiting final inspection +- `under-final-inspection`: batches currently in inspection +- `ready-for-dispatch`: batches cleared for dispatch +- `dispatch-crew-available`: crew availability (1 token when free) + +Transitions: +- `start-final-inspection`: requires 1 token from batch-ready AND 1 token from dispatch-crew-available; produces 1 token to under-final-inspection +- `sign-off`: requires 1 token from under-final-inspection; produces 1 token to ready-for-dispatch AND 1 token to dispatch-crew-available + +The missing standard weight-1 input arc from `dispatch-crew-available` to `start-final-inspection` has been **added and verified** in the live Petrinaut definition. + +## Explicit unknowns +- Inspection timing: duration, stochasticity, or determinism remain unresolved +- Sign-off timing: duration, stochasticity, or determinism remain unresolved +- Failure modes: whether inspection can fail, halt, or reject a batch +- Recovery behavior: how failures or rejections affect batch state or crew availability + +## Claim boundary +This workpiece and the corrected net establish only: +- The crew-consumption constraint at start of inspection +- The crew-release at sign-off completion +- Token flow from ready batch through inspection to dispatch readiness + +This is test-authored diagnostic material for the narrow final-inspection–to-dispatch path. It does not establish capture provenance, behavioral execution, failure handling, full process projection, or integration with upstream or downstream operations. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/prepared-workpiece.md b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/prepared-workpiece.md new file mode 100644 index 00000000000..fa01def8c11 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/prepared-workpiece.md @@ -0,0 +1,21 @@ +# Final inspection and dispatch workpiece + +## Purpose and posture +Maintain the narrow batch path from final inspection to dispatch readiness and test one evidence-backed correction against the live Petrinaut document. + +## Operational account +- A batch that is ready enters final inspection. +- Final inspection reserves the sole available dispatch crew. +- Sign-off releases that crew and makes the batch ready for dispatch. + +## Quantity and resource policy +Exactly one dispatch crew is available in this fixture. Starting final inspection consumes that one available crew; sign-off returns it. + +## Current Petrinaut correspondence +The prepared non-empty net contains the batch path and the crew return from sign-off. It deliberately lacks the standard weight-1 input arc from `Dispatch crew available` to `Start final inspection`. + +## Explicit unknowns +Inspection and sign-off timing, failure modes, and recovery behavior remain unresolved. + +## Claim boundary +This prepared revision is test-authored diagnostic material. It is not model-produced evidence and does not establish capture provenance, behavioral execution, or broad projection quality. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/route-evidence.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/route-evidence.json new file mode 100644 index 00000000000..da12d3d008a --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/route-evidence.json @@ -0,0 +1,7 @@ +{ + "origin": "http://127.0.0.1:4915", + "historyRoute": "/agents/chat/?view=history", + "status": 200, + "retainedAuthorizationHeaders": false, + "retainedProviderPayloads": false +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/screenshot-tab-a-after.png b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/screenshot-tab-a-after.png new file mode 100644 index 00000000000..0f42bfeaebf Binary files /dev/null and b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/screenshot-tab-a-after.png differ diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/screenshot-tab-a-before.png b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/screenshot-tab-a-before.png new file mode 100644 index 00000000000..142e160b12b Binary files /dev/null and b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/screenshot-tab-a-before.png differ diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/screenshot-tab-b-after.png b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/screenshot-tab-b-after.png new file mode 100644 index 00000000000..5527acbca57 Binary files /dev/null and b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/screenshot-tab-b-after.png differ diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/settled-manifest-after.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/settled-manifest-after.json new file mode 100644 index 00000000000..cd937a8620a --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/settled-manifest-after.json @@ -0,0 +1,25 @@ +{ + "version": 1, + "fixtureId": "crew-reservation-v1", + "revision": 1, + "settledAt": "2026-09-04T08:10:58.162Z", + "conversation": { + "logicalId": "mission-6-crew-reservation-conversation-v1", + "canonicalId": "conv_01M1NQEXM3CAPPTXM33ZE1YSRG", + "offset": "0000000000000000_0000000000000108" + }, + "latestWorkpiece": { + "authorship": "model-produced", + "contentSha256": "785135be03f8cbe9156b835f34d463bf7111fc109dd90dbe9db55955670c050e", + "sourceKind": "assistant", + "sourceMessageId": "entry_01M1NQGRAKWG69MWYMPYTCFXCZ", + "sourceMessageSha256": "5c5645d0f63c9792ece099228cbc021e117853108a1501c0cc230334eb2a6af8", + "sourceSubmissionId": "sub_ik_6dbc187e4e72793b7539c02387d04715" + }, + "document": { + "id": "mission-6-crew-reservation-document-v1", + "sha256": "3c47961d02296c00131644d1aea0dac16a017f470a66aea919fcf324a2bc9e37", + "targetArc": "present" + }, + "manifestId": "a00f05964afc87b1ef34b50c96711232ac44c5b60eb6e8ce60a540af3b5dab49" +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/settled-manifest-before.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/settled-manifest-before.json new file mode 100644 index 00000000000..48e8013a09f --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/settled-manifest-before.json @@ -0,0 +1,25 @@ +{ + "version": 1, + "fixtureId": "crew-reservation-v1", + "revision": 0, + "settledAt": "2026-09-04T08:10:01.220Z", + "conversation": { + "logicalId": "mission-6-crew-reservation-conversation-v1", + "canonicalId": "conv_01M1NQEXM3CAPPTXM33ZE1YSRG", + "offset": "0000000000000000_0000000000000043" + }, + "latestWorkpiece": { + "authorship": "test-authored", + "contentSha256": "1cc7a1b5d961f9f6327b458cf8292703ced5627fe26ee3f7b878f6375e51501a", + "sourceKind": "prepared-signal", + "sourceMessageId": "entry_direct_c3ViX2lrX2YyNDkzOWJlYmI4NDFmZmUxNDY5YTdmM2E0YTA2OTE1", + "sourceMessageSha256": "05003ea859f0658266d92b24eeaca0103aa75d2c4a3ec4eddaffe606b6775fc6", + "sourceSubmissionId": "sub_ik_f24939bebb841ffe1469a7f3a4a06915" + }, + "document": { + "id": "mission-6-crew-reservation-document-v1", + "sha256": "8dfa723b8dabadad790d2552de8e191e4227b07fe6c4d4e9d8e2d365e6ec4abd", + "targetArc": "absent" + }, + "manifestId": "fef5b371de498d5c2e6bb0456878c21aeb05a0f68957cde4a859f194b5122fab" +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/settled-manifest-tab-b.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/settled-manifest-tab-b.json new file mode 100644 index 00000000000..cd937a8620a --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/settled-manifest-tab-b.json @@ -0,0 +1,25 @@ +{ + "version": 1, + "fixtureId": "crew-reservation-v1", + "revision": 1, + "settledAt": "2026-09-04T08:10:58.162Z", + "conversation": { + "logicalId": "mission-6-crew-reservation-conversation-v1", + "canonicalId": "conv_01M1NQEXM3CAPPTXM33ZE1YSRG", + "offset": "0000000000000000_0000000000000108" + }, + "latestWorkpiece": { + "authorship": "model-produced", + "contentSha256": "785135be03f8cbe9156b835f34d463bf7111fc109dd90dbe9db55955670c050e", + "sourceKind": "assistant", + "sourceMessageId": "entry_01M1NQGRAKWG69MWYMPYTCFXCZ", + "sourceMessageSha256": "5c5645d0f63c9792ece099228cbc021e117853108a1501c0cc230334eb2a6af8", + "sourceSubmissionId": "sub_ik_6dbc187e4e72793b7539c02387d04715" + }, + "document": { + "id": "mission-6-crew-reservation-document-v1", + "sha256": "3c47961d02296c00131644d1aea0dac16a017f470a66aea919fcf324a2bc9e37", + "targetArc": "present" + }, + "manifestId": "a00f05964afc87b1ef34b50c96711232ac44c5b60eb6e8ce60a540af3b5dab49" +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/tab-b-correlation.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/tab-b-correlation.json new file mode 100644 index 00000000000..d5c02471672 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/tab-b-correlation.json @@ -0,0 +1,18 @@ +{ + "conversationId": "conv_01M1NQEXM3CAPPTXM33ZE1YSRG", + "offset": "0000000000000000_0000000000000123", + "manifestId": "a00f05964afc87b1ef34b50c96711232ac44c5b60eb6e8ce60a540af3b5dab49", + "documentSha256": "3c47961d02296c00131644d1aea0dac16a017f470a66aea919fcf324a2bc9e37", + "workpieceSha256": "785135be03f8cbe9156b835f34d463bf7111fc109dd90dbe9db55955670c050e", + "preparedSourceCount": 1, + "addArcCallCount": 1, + "followUp": { + "submissionId": "sub_ik_8841d36f1e2e4ba9f39852be54d2e174", + "responseMessageId": "entry_01M1NQJG7GRPC479PRF826T6F3", + "settlement": { + "submissionId": "sub_ik_8841d36f1e2e4ba9f39852be54d2e174", + "outcome": "completed", + "answeredBySubmissionId": "sub_ik_8841d36f1e2e4ba9f39852be54d2e174" + } + } +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/witness.md b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/witness.md new file mode 100644 index 00000000000..87c7d8d2fc5 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-outer-browser-witness-2026-09-04/witness.md @@ -0,0 +1,90 @@ +# FE-1575 outer browser witness — 2026-09-04 + +## Scope + +This is the retained outer mechanical witness for Mission 6 at commit +`ace2968`. It used a clean browser principal in one Playwright context, the +stable `crew-reservation-v1` fixture route, the local Brunch Flue mount, and a +real configured provider credential. Credentials, authorization headers, the +browser principal, the Flue instance route component, and provider request +payloads are not retained. + +The provider serialized the `addArc` weight as `"1"`. The witnessed build +normalized that finite numeric string at the Petrinaut tool boundary before +canonical validation and browser execution. The retained raw Flue snapshot +preserves the provider-supplied input; the resulting Petrinaut definition +preserves the canonical numeric weight `1`. + +## Protocol and result + +1. Started `yarn dev:brunch` after loading `.env.local` without printing it. +2. Cleared browser local storage, opened + `http://127.0.0.1:4915/?brunch-fixture=crew-reservation-v1`, and waited for + settled revision zero. +3. Retained the before Flue snapshot, canonical definition, runtime manifest, + and Tab A screenshot. +4. Submitted one confirmation/construction turn: + + > Confirmed: final inspection uses the single dispatch crew and sign-off + > releases it; timing, failure, and recovery remain unknown. Read the live + > Petrinaut definition, add the missing standard weight-1 input arc from + > Dispatch crew available to Start final inspection, verify it, and emit + > the full revised runbook-ir workpiece. + +5. Observed one `addArc` call and one correlated successful client-tool result: + `toolu_01KLHzRE7gbPbFfPaXe3RTry`. +6. Verified that the only semantic definition delta was one standard, + weight-1 input arc from `dispatch-crew-available` to + `start-final-inspection`. +7. Observed runtime manifest revision 1 selecting the model-produced workpiece + and changed document, with target arc `present`. +8. Opened Tab B in the same browser context. It selected the same manifest, + workpiece hash, document hash, and canonical conversation, with exactly one + prepared source and one `addArc` call. +9. Submitted a non-mutating follow-up in Tab B: + + > From the resumed workpiece, list the unresolved timing, failure, and + > recovery questions. Do not change the Petrinaut net. + +10. Observed completed submission + `sub_ik_8841d36f1e2e4ba9f39852be54d2e174` and correlated response message + `entry_01M1NQJG7GRPC479PRF826T6F3`. The document and settled manifest were + unchanged. + +## Retained identities and invariants + +- Canonical conversation: `conv_01M1NQEXM3CAPPTXM33ZE1YSRG` +- Settled manifest revision: `1` +- Settled manifest ID: + `a00f05964afc87b1ef34b50c96711232ac44c5b60eb6e8ce60a540af3b5dab49` +- Prepared source count after Tab B: `1` +- `addArc` call count after Tab B: `1` +- Tab B follow-up outcome: `completed` +- `definition-after.json` and `definition-tab-b.json` have the same SHA-256. +- `settled-manifest-after.json` and `settled-manifest-tab-b.json` have the same + SHA-256. + +## Artifacts + +- Before state: [Flue](flue-snapshot-before.json), + [definition](definition-before.json), + [manifest](settled-manifest-before.json), + [screenshot](screenshot-tab-a-before.png) +- Settled Tab A state: [Flue](flue-snapshot-after.json), + [definition](definition-after.json), + [manifest](settled-manifest-after.json), + [call/result correlation](call-result-correlation.json), + [screenshot](screenshot-tab-a-after.png) +- Tab B continuation: [Flue](flue-snapshot-tab-b.json), + [definition](definition-tab-b.json), + [manifest](settled-manifest-tab-b.json), + [correlation](tab-b-correlation.json), + [screenshot](screenshot-tab-b-after.png) +- Semantic inputs: [prepared workpiece](prepared-workpiece.md), + [latest workpiece](latest-workpiece.md) +- Redacted route observation: [route evidence](route-evidence.json) +- Integrity: [SHA256SUMS](SHA256SUMS) + +This witness proves the bounded browser protocol above. It does not establish +capture provenance, timing behavior, failure/recovery behavior, simulation +validity, or broad automatic projection quality. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-resumable-workpiece-petrinaut.md b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-resumable-workpiece-petrinaut.md new file mode 100644 index 00000000000..5ab166121f7 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/fe-1575-resumable-workpiece-petrinaut.md @@ -0,0 +1,47 @@ +# FE-1575 — resumable workpiece and Petrinaut document + +## Deterministic implementation evidence + +The prepared crew-reservation fixture uses distinct fixture, logical +conversation, canonical Flue conversation, workpiece-source, and Petrinaut +document identities. Revision zero is delivered through the public mounted +Flue route as one `prepared-fixture` system/dispatch signal with a deterministic +idempotency key. The browser transport derives stable keys for typed messages +and correlated client-tool-result signals. + +Focused tests cover: + +- exact prepared-signal retry and append-only workpiece selection; +- fixture-only `getLatestNetDefinition` and `addArc` advertisement; +- the built agent's read, mutation, original call-id result, and continuation; +- rejected and duplicate/no-op canonical browser mutations; +- exact prepared and revised document structure; +- history, workpiece, mutation-result, and document mismatch refusal; and +- content-addressed selection of the prior coherent document revision while a + partial mirrored value remains inspectable. + +The affected Brunch, transport, plugin, Petrinaut, and website builds, type +checks, and lint checks passed on 2026-09-04. The app-wide lint checks retain +pre-existing warning-only findings; no persona suite was run. + +## Live two-tab browser witness + +The corrected 2026-09-04 witness is retained in [fe-1575-outer-browser-witness-2026-09-04-r2](fe-1575-outer-browser-witness-2026-09-04-r2/witness.md). It used the production dev processes underlying `yarn dev:brunch`, one fresh Playwright browser context, the mounted `/agents/chat/:instanceId` route, a real configured provider credential, and the stable fixture URL: + +```text +http://127.0.0.1:4915/?brunch-fixture=crew-reservation-v1 +``` + +The clean run created canonical conversation `conv_01M1NV5WZETMYEGGMFXNYDSTRS` and exactly one tagged prepared source. Tab A advanced from settled revision zero with the target arc absent to revision 1 with a model-produced workpiece and the target arc present. It retained one `addArc` call and one unique correlated successful result, `toolu_01BQukCZTAhJ64VNE7oC1CWG`, materialized in two cumulative signal deliveries without applying a second arc. Mechanical comparison found exactly one semantic document change: a standard weight-1 input arc from `dispatch-crew-available` to `start-final-inspection`. + +Tab B reopened the same manifest, workpiece hash, document hash, and canonical conversation. It submitted a non-mutating follow-up and received completed correlated response `entry_01M1NV73Z110CY393GEB8T02SH` without another prepared source or `addArc` call. The post-Tab-A and Tab-B definitions and manifests have identical hashes. + +The provider serialized the arc weight as `"1"`. The corrected correlation artifact retains that raw input and the post-normalization parsed input with numeric weight `1`; no broader nested input normalization remains. The selected assistant workpiece explicitly labels revision 1 as model-produced from test-authored revision zero and preserves the fixture's non-claims. The earlier HTTP 401 remains historical authentication/environment evidence only, not a carrier/schema conclusion. + +The first [2026-09-04 witness](fe-1575-outer-browser-witness-2026-09-04/witness.md) remains immutable historical evidence but is superseded for acceptance: its model-produced workpiece incorrectly called itself test-authored and its correlation artifact omitted the parsed canonical input. + +## Human checks + +The cold reader accepted the fixture and revised workpiece on 2026-09-04; the complete adjudication is retained in [cold-reader-gate.md](fe-1575-outer-browser-witness-2026-09-04-r2/cold-reader-gate.md). + +The product manager accepted the visible two-tab conversation, workpiece, and document path on 2026-09-04 after a fresh run advanced from settled revision 0 to revision 1, displayed the exact crew-reservation arc, reopened coherently in Tab B, and answered a non-mutating follow-up. The durable correlation and the run's explicit limitation are retained in [product-manager-gate.md](fe-1575-outer-browser-witness-2026-09-04-r2/product-manager-gate.md): the fresh human run contained no Voice-origin or aborted assistant records, so those presentation clauses were not independently re-exercised by the product manager. The owner explicitly waived those checks, closed Mission 6, and carried them into `MISSION.next.md` for later scenario testing; the waiver is recorded as a closure exception rather than evidence of a pass. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/mission-5-direct-voice-flue/README.md b/libs/@hashintel/brunch-agent/docs/evidence/implementations/mission-5-direct-voice-flue/README.md new file mode 100644 index 00000000000..6f5dd2bc43c --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/mission-5-direct-voice-flue/README.md @@ -0,0 +1,87 @@ +# Mission 5 direct Voice over Flue evidence + +## Readiness status + +Automated contract evidence passed on 2026-09-03. A real human Voice witness was attempted on 2026-09-04. It passed typed and Voice admission, exact-once visible Voice input, spoken canonical output, barge-in, and explicit durable Stop, but failed faithful reopen. This record therefore does not claim Mission 5 product acceptance. + +The implementation under test is: + +- `bb4457c558` — browser Flue `ChatTransport`, stream projector, history projection, and ownership headers; +- `daf525e142` — typed Petrinaut panel wiring and same-origin Flue proxy; +- `969808e772` — removal of the Brunch `/api/chat` route; +- `0d5343b069` — Voice submission correlation, canonical response selection, observation-based reopen, and durable Stop; +- `2936a4b3f7` — review fixes for canonical history hydration, exact TTS text, content-free lifecycle latency telemetry, Clear behavior, API simplification, and documentation; +- `05b363649e` — React-compiler-safe tracker lifecycle and final live-authority corrections; +- `f1189523a8` — real Flue admission timing and production-path correlation evidence; +- `a4ec9f28ce` — client-tool-result ordering that keeps the Voice submission pending until its real Flue admission and cancels stale admission waits; +- `2a1bb35775` — durable Stop correlation and aligned live/history conversation projections; and +- `eecbe99e20` — reply correlation across every submission that wrote a resumed assistant message; and +- `2d4e81f3a4` — preservation of Petrinaut's Voice API handlers in the Brunch local preview. + +## Automated verification + +The focused repository command completed with 36 successful tasks out of 36: + +```sh +yarn exec turbo run lint:tsc lint:eslint test:unit build \ + --filter @apps/brunch-agent \ + --filter @apps/petrinaut-website \ + --filter @hashintel/petrinaut \ + --filter @hashintel/brunch-agent \ + --filter @hashintel/brunch-agent-plugin-sdcpn \ + --filter @hashintel/brunch-agent-transport-aisdk +``` + +The unit results included: + +| Workspace | Test files | Tests | +| ---------------------------------------------- | ---------: | ----: | +| `@apps/brunch-agent` | 16 | 79 | +| `@apps/petrinaut-website` | 31 | 212 | +| `@hashintel/petrinaut` | 53 | 478 | +| `@hashintel/brunch-agent` | 9 | 77 | +| `@hashintel/brunch-agent-plugin-sdcpn` | 2 | 8 | +| `@hashintel/brunch-agent-transport-aisdk` | 3 | 14 | + +`yarn install --immutable` passed with the repository's existing peer-dependency warnings. `yarn workspace @local/petrinaut-arch-docs lint:arch-docs` also passed with 62 layers, 297 edges, 613 files, 63 generated pages, and 31 authored pages. The focused ESLint run retained one non-blocking `set-state-in-effect` warning in `voice-interview-control.tsx`. + +The proof-leaf route scan over `apps/brunch-agent`, `packages/`, and the Petrinaut local-storage demo found no production path that sends a Brunch turn through `/api/chat`: its live hits are the stock Petrinaut fallback and negative tests asserting the removed Brunch route returns 404. Current integration and topology references now name `/agents/chat/:instanceId`; archived missions, prior implementation evidence, and historical decision records retain `/api/chat` as provenance for the superseded door. + +The Voice integration holds the finite Flue response stream open and asserts that `submission-admitted` arrives from the real `createFlueChatTransport().onAdmission` callback before composer submission completion. The Voice control tests also prove that a locally completed interactive-tool result remains pending until the subsequent client-tool-result admission and that cancellation releases the one-shot subscription. Bridge tests separately cover direct-message and client-tool-result matching, duplicate delivery, stale cancellation, mismatched ids, and submission-id-based canonical response selection. + +## Human witness still required + +Run `yarn dev:brunch` with `ANTHROPIC_API_KEY`, `PETRINAUT_OPENAI_VOICE_ENABLED=true`, and a dedicated `OPENAI_VOICE_API_KEY`, then perform this witness against source commit `2d4e81f3a4` or a descendant that changes evidence only: + +1. Open one saved net, submit one typed panel turn, and confirm the network ledger contains conversation traffic only under `/agents/chat/:instanceId`. +2. Start Voice mode, accept the disclosure if required, speak one finalized answer, and confirm exactly one corresponding visible user message. +3. Confirm the content-free lifecycle ledger records one ordered admission, first canonical text, settlement, first TTS request, and first TTS audio sequence for the same opaque correlation id. +4. Compare the ordered canonical Brunch text with the exact `response_text` string array queued for speech. Record only matching hashes, lengths, and the boolean result; do not retain the text. +5. Interrupt assistant playback by speaking and confirm canonical history is unchanged. +6. Start another unsettled turn, select **Stop**, and confirm Flue records either an aborted settlement or the documented already-settled race rather than only cancelling the browser stream. +7. Reload or reopen the same net and confirm canonical messages reappear without a duplicate submission, a replayed tool effect, or Voice audio replay. + +Retain these sanitized artifacts here: + +1. `witness.md` — date, adjudicator, source/build commit, and observed outcome; +2. `voice-events.jsonl` — content-free admission, first canonical text, first TTS/audio, interruption, Stop, and settlement timing; +3. `network-routes.json` — method and route summary proving conversation traffic used only `/agents/chat/:instanceId`; +4. `flue-snapshot.json` — sanitized canonical snapshot after reopen; +5. `settlements.json` — settled, aborted, and abort-lost-to-completion outcomes; +6. `manifest.sha256` — hashes for the retained witness artifacts. + +The witness must type one turn, speak one finalized answer, confirm exactly one visible user message, compare canonical text with the exact TTS request input, interrupt playback, durably stop one unsettled turn, and reopen without resubmission or audio replay. Do not retain transcript text, audio, credentials, SDP, prompts, tool payloads, or provider response bodies in ordinary telemetry. + +## Human witness attempt — 2026-09-04 + +The local `yarn dev:brunch` pair ran against source commit `2d4e81f3a4` with the required Voice configuration available. The human observed: + +- one typed turn completed through the Brunch panel; +- one finalized spoken answer produced exactly one visible user message; +- Brunch's visible response also played aloud, and speaking over it stopped playback without removing the visible response; +- the transcript was initially hidden behind a small **Show transcript** control; +- **Exit voice mode** stopped the audio session but did not durably stop an admitted Brunch submission; the partial spoken input was submitted and the response completed as text; +- using the chat composer's actual Stop control durably stopped the unsettled response and displayed **Response stopped** before reload; and +- after closing the panel, reloading, and reopening the same conversation, all message content returned, but typed/Voice provenance was absent and the stopped assistant entry appeared as ordinary truncated content. The global stopped status remained visible. + +The reopen gate failed because the transcript did not return exactly as left. Absence of duplicate submission and audio replay was not fully adjudicated after this failure, and the required content-free event, route, snapshot, settlement, and hash artifacts were not retained. The owner chose not to expand Mission 5 with immediate product remediation. Mission 6 owns preserving per-message typed/Voice provenance and stopped-turn presentation across its second-tab resume proof; its cut should also account for the observed discoverability gap between transcript reveal, local Voice exit, and durable conversation Stop. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/mission-5-voice-safety-parity/donor-behavior-matrix.md b/libs/@hashintel/brunch-agent/docs/evidence/implementations/mission-5-voice-safety-parity/donor-behavior-matrix.md new file mode 100644 index 00000000000..0afe5e39b2b --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/mission-5-voice-safety-parity/donor-behavior-matrix.md @@ -0,0 +1,113 @@ +# FE-1580 donor-behavior matrix + +## Decision frame + +This record pins the semantic disposition of the Voice donor branches for the live [FE-1580 mission](../../../../MISSION.md). The parent and donors are read-only source evidence at these exact heads: + +| Source | Pinned head | Role | +| --- | --- | --- | +| Parent PR [#9528](https://github.com/hashintel/hash/pull/9528) | `58f75840804766a84ce85b9daab5b5194f3875ec` | Unified Flue route and path-B departure base | +| Donor PR [#9496](https://github.com/hashintel/hash/pull/9496) | `c7fe8a2e68e8fdc37018b21ec2e9daf4e9ef7c82` | Canonical TTS queue and replay mechanics | +| Donor PR [#9500](https://github.com/hashintel/hash/pull/9500) | `935aa9f02a5ac635a50eb8bc130edb3e258af8e4` | Completed-transcript authority | +| Donor PR [#9507](https://github.com/hashintel/hash/pull/9507) | `252b9dbb0c77fae8cee45a506f09cac3e20c381c` | Temporary `brunch_ask` shim, excluded | +| Donor PR [#9512](https://github.com/hashintel/hash/pull/9512) | `d13535d1077b3a78d6a1411031b7d0a0a78e3144` | Half-duplex cancellation, replay UX, and provenance | + +No source is merged, cherry-picked, rebased, retargeted, rewritten, or closed by the implementation. Tests are transplanted first and adapted to the one Flue submission route; production behavior is reimplemented semantically. + +The owner selected half-duplex turn ownership on 2026-09-03: assistant output owns the audio turn until **Your turn** completes an acknowledged cancellation barrier. Automatic duplex is not an admissible fallback. + +## Behavior disposition + +| Source | Behavior | Disposition | Reason | Outstanding adaptation or proof | +| --- | --- | --- | --- | --- | +| #9528 | One `/agents/chat/:instanceId` product route, browser `ChatTransport`, one memoized client, path-B Voice submission through shared `useChat` | **Adopt** | This is the departure architecture and prevents a second admission authority. | Restack onto every new parent head; verify no successor code calls `send()` directly from Voice. | +| #9528 | Direct Voice `send()` as a fog-line fallback | **Reject** | It creates a second admission path and mutable coordination surface. The parent has already proved path B. | Mission authority now permits path B only. | +| #9528 | Claim that Flue 2.0.3 lacks caller idempotency | **Reject as factually false** | Installed typings expose `AgentPromptOptions.idempotencyKey`, `AgentSendResult.deduplicated`, and 409 `submission_conflict` with the existing `submissionId`. | Implemented with transport convergence/conflict tests and typed Voice admission outcomes. | +| #9528 | Canonical hydration guard, multi-submission response correlation, settlement-driven durable Stop, aligned live/snapshot projection, queued Voice-input cancellation, and client-tool continuation | **Adopt through restack** | These mechanisms remain parent-owned and must enter the successor through the stack rather than copied fixes. | Restacked onto `58f758408047`; hydration no longer blocks the real witness. Further defects in these mechanisms remain parent scope. | +| #9496 | Serialized canonical speech queue, retained exact source segments, response/output terminal gating | **Adopt mechanics** | Replay and ordinary TTS need one lifecycle-safe queue, and exact text preserves canonical authority. | Implemented without a preparation/simplifier dependency; exact-segment and queue tests pass. | +| #9496 | `canReadFullResponse`, `readFullResponse()`, exact full-response playback menu | **Adopt** | Exact full-response replay is supported by retained canonical segment identity. | Implemented with idle-state and matching response/output terminal gates. | +| #9496 | `canRepeatQuestion`, `repeatQuestion()`, and playback-menu action | **Adopt UX; reject final-segment inference** | The final segment may be ordinary prose and is not authority for question identity. The approved `brunch_mark_question` data marker now supplies deterministic identity without accepting an answer. | Implemented by replaying only exact marked text found in finalized prose from the same assistant message; a missing or unmatched marker leaves the action disabled. | +| #9496 | Realtime-generated concise response preparation or any fallback that rewrites canonical text | **Reject** | Response simplification is a non-goal and violates exact canonical speech. | Tests compare retained segment ids and exact queued strings; no preparation API remains on this path. | +| #9500 | No Realtime tools, `tool_choice: "none"`, semantic VAD `create_response: false` | **Adopt** | Realtime detects/transcribes and renders supplied TTS only; it must not generate user meaning. | Implemented in policy, session, and production-preview integration tests. | +| #9500 | Only `conversation.item.input_audio_transcription.completed` can submit; model function arguments ignored | **Adopt** | Shape validation cannot prove model-generated arguments match the audio. | Implemented with current-turn speech-boundary, stale, reordered, and late-output rejection tests. | +| #9500 | Transcript identity `(connectionEpoch, itemId, contentIndex)`, stable submission id, trim plus Unicode whitespace collapse, 32,000-code-point limit | **Adopt** | This gives one deterministic logical Voice delivery and one normalization boundary. | Implemented through path B; the panel preserves the bridge-normalized payload unchanged. | +| #9500 | Explicit duplicate, empty, failed, unavailable, and over-limit rejection; passive/recoverable not-heard UI; provisional display only | **Adopt** | Rejected audio must never become a turn, while ordinary silence/failure must not poison the session. | Implemented with reason-specific bridge/controller UI coverage. | +| #9500 | Silently settling ownership by discarding every playback-overlapping utterance without an explicit handoff | **Supersede** | It avoids echo but leaves users without a deliberate way to take the turn. | Use #9512 half-duplex `canTakeTurn`/`takeTurn()` and reject all speech captured before the completed handoff. | +| #9500 | `brunch_ask` answer/tool correlation and preparation code inherited from its base | **Reject** | Structured questions and response preparation are excluded. | Correlate the Voice delivery to its path-B submission and canonical response facts; exact question replay uses the non-interactive marker instead. | +| #9507 | Temporary `brunch_ask` registration, widget, correlated spoken ask answer, transcript formatting | **Reject entire shim** | The current transport only admits the supported follow-up set; a spoken ask can otherwise wait forever. Structured questions are a separate product decision. | Remove or gate dormant `brunchAskInteractiveTool` and `"brunch-ask"` canonical-speech recognition only if still present after restack. | +| #9512 | Half-duplex `canTakeTurn`, `takeTurn()`, `"cancelling"` output state, and **Your turn** control | **Adopt by owner decision** | It makes output/input ownership explicit and prevents assistant playback from becoming a false user turn. | Implemented through the public Voice store and production panel registration path. | +| #9512 | Promise-returning `cancelOutput()` that waits for input/output clears, matching acknowledgements, and response terminal events | **Adopt** | The microphone cannot safely reopen on a fire-and-forget cancel. | Implemented with acknowledgement/race tests, latest-mute behavior, and fresh post-handoff capture. | +| #9512 | Replay availability tied to exact retained source, terminal response, and output completion | **Adopt with #9496 mechanics** | This closes replay races without changing canonical content. | Implemented against parent segment/submission correlation for exact full-response and marked-question replay. | +| #9512 | Voice answer icon/provenance before interactive answers | **Partially adopt; blocked for direct user turns** | Live attribution is useful but one origin per assistant message is insufficient after coalesced or sibling Voice deliveries. Flue's client-tool result signal can durably carry those origins. Its direct-user delivery and snapshot types expose no caller metadata or idempotency key, so a direct spoken user message cannot be identified after reopen without a forbidden second store or text encoding. | Keep `voiceToolCallIds`, preserve successful siblings on partial failure, and reconstruct supported tool-result origins from Flue signals. Re-enter direct-user attribution only when Flue provides a supported durable correlation seam. | +| #9512 | App-local agent topology, temporary ask UI, response preparation, or donor-specific host composition | **Reject** | The parent owns the one Flue route and current host composition; these mechanisms are obsolete or non-goals. | Reuse only state-machine, cancellation, replay, and attribution behavior. | + +## Adopted-behavior replacement coverage + +| Adopted behavior | Replacement implementation | Regression test | Production integration proof | Status | +| --- | --- | --- | --- | --- | +| One path-B Flue admission route | `local-storage-demo-app.tsx`, `brunch-panel-transport.ts`, transport `src/index.ts` | `brunch-panel-transport.test.ts`, `chat-transport.test.ts` | `voice-preview.integration.test.ts` crosses completed transcript → panel submission → Flue transport → canonical speech | **Implemented**; parent defects remain downstack | +| Stable admission identity and typed outcomes | transport `src/index.ts`, `brunch-panel-transport.ts`, `submitVoiceInputWithAdmission`, `realtime-brunch-bridge.ts` | transport admission cases; bridge/controller cases for rejected, conflict, ambiguous, and local abort | production preview carries 409 conflict, 500 ambiguity, and local abort through transport → tracker → `submitVoiceInputWithAdmission` → bridge; each observes one `send()`, and local abort never invokes durable `FlueClient.abort()` | **Implemented** | +| Exact canonical TTS queue and full-response replay | `openai-realtime-session.ts`, `voice-turn-controller.ts`, Petrinaut playback menu | session queue/cancellation cases; controller exact-segment and terminal-gating cases; panel action tests | real host registration exposes `readFullResponse`; panel forwards it through `voiceSessionStore` | **Implemented** | +| Exact question replay | core `brunch_mark_question` tool/data contract; transport hidden-tool projection; `canonical-speech.ts`; bridge/controller; Voice host callback | core marker tests; live/snapshot transport projection tests; canonical selector malformed/unmatched/cross-message cases; controller final-segment negative and exact-marker replay cases | real Flue integration persists and reopens `data-brunch-question` while hiding the marker tool; controlled Voice preview carries the marker through response correlation and queues only the exact question; panel host forwards the action | **Implemented**; missing or unmatched markers fail closed | +| Disabled Realtime generation/tools | `openai-voice-policy.ts`, `openai-realtime-session.ts` | policy/session tests reject tools and function arguments | controlled production preview negotiates the server policy and emits only canonical speech | **Implemented** | +| Completed-transcript authority | `openai-realtime-session.ts`, `realtime-brunch-bridge.ts` | missing/stale/reordered boundary, keyed identity, normalization, duplicate/failure/limit, canonical-request-before-output, and late-output cases | controlled production preview proves a pre-request item cannot call Flue `send()` before output starts and only fresh post-handoff input submits through path B | **Implemented**; provider-valid boundaryless commits are intentionally rejected by mission policy | +| Half-duplex acknowledged handoff | `openai-realtime-session.ts`, `voice-turn-controller.ts`, Voice public store/dock | canonical-request invalidation, input/output clear acknowledgement, targeted response terminal, latest mute, stale/pre-handoff rejection | panel registration tests exercise **Your turn**; preview integration proves the microphone closes before `response.create` and fresh post-handoff capture submits once | **Implemented** | +| Durable Stop distinct from local cancellation | app `requestFlueStop`, panel `stopComposer`, session `cancelOutput` | panel durable-before-local Stop, controller/session local-cancel cases, app host Stop case | configured Brunch app invokes `FlueClient.abort()`, observes an aborted settlement, and does not invoke local playback cancellation | **Implemented**; parent-owned Stop races excluded | +| Multi-origin Voice client-tool provenance | panel `addMappedToolOutput`, transport client-tool-result signal/projection, `useFlueChatHistory` | sibling partial-failure, persisted-signal projection, hydration/reopen cases | configured app consumes the public Flue observation and restores every `voiceToolCallId` | **Implemented for client-tool results**; direct-user marker **blocked** | +| No live `brunch_ask` | Brunch app registers `interactiveTools: []`; canonical speech selector ignores the ask name | canonical-speech negative case and configured-app registration negative case | captured production Brunch `PetrinautAiAssistant` has no ask tool while retaining Flue Stop wiring | **Implemented exclusion** | + +## Outstanding acceptance ledger + +| Area | Required closing evidence | Current state | +| --- | --- | --- | +| Transcript authority | Transplanted-first session, bridge, controller, and integration regressions pass on path B. | Implemented. Matching current-turn `speech_started`, stale/reordered boundaries, canonical-speech-request and late-output invalidation, provisional UI clearing, exact bridge normalization, and unchanged panel payload are covered. | +| Admission idempotency | Typed and Voice logical replays converge on one `submissionId`; conflict metadata is narrowed safely; ambiguous outcome does not retry. | Implemented. Transport tests cover stable typed/Voice keys, deduplicated receipts, 409 conflicts, and non-retried ambiguity; production-path integration preserves the original conflict `submissionId` and keeps local admission abort distinct from durable abort. | +| Cancellation barrier | Buffer acknowledgements and targeted response terminals settle before capture; stale/pre-handoff audio cannot submit; latest mute choice wins. | Implemented. Session/controller races cover the barrier and mute preference; panel registration and configured-app Stop cases cover the production host seams. | +| Canonical replay | Exact segment queue and playback menu pass availability/race tests without a simplifier. | Full-response replay preserves every exact segment. **Repeat question** uses only a durable non-interactive Brunch marker that exactly matches finalized prose in the same assistant message; final-segment inference remains rejected. Both actions share terminal/output/input gating. | +| Durable provenance | Multiple origins and partial failure survive projection, hydration, and reopen without user-text encoding. | Partially implemented for assistant client-tool results through persisted Flue signals; multiple sibling origins survive projection and partial failure. Direct spoken user attribution is blocked because Flue 2.0.3 snapshots do not expose caller idempotency or user-message metadata. The rejected browser store would violate mission authority. | +| Dormant ask | No mounted Voice ask capability remains, or the parent commit that removed it is recorded. | Implemented exclusion. Canonical speech ignores `brunch_ask`, and a configured-app registration test proves the production Brunch assistant supplies no ask tool. Dormant source remains unmounted. | +| Real witness | Microphone, handoff, unsettled Stop, reload, canonical snapshot, settlement, and same-origin absolute-`streamUrl` artifacts are retained with hashes. | Parent hydration blocker resolved by restack; human browser/microphone run and retained artifacts remain outstanding. | +| Comparative latency | Ten pinned #9496 trials and ten final-candidate trials retain raw finalized-speech-to-first-audible-canonical-TTS samples and show no median regression with p95 regression below 20%. | Donor isolated worktree is prepared and its five focused Voice suites pass 108/108 after dependency build. Twenty comparable human audible trials and statistics remain outstanding. | +| Donor retirement | Replacement accepted and each donor owner explicitly approves closure. | Deferred; no donor or stakeholder issue may be closed now. | + +## Corrective verification + +Fresh local checks on 2026-09-07 cover the 72-file successor diff against the +verified #9528 head `58f75840804766a84ce85b9daab5b5194f3875ec`. +The 62-commit replay required semantic resolutions in the mission authority, +the already-equivalent launcher comment, and the Voice transcript panel. The +combined panel keeps the parent's editor-owned width together with the +successor's always-live transcript and complete-error behavior. The full gate +then caught one unused parent import left by that merge; removing it returned +the complete verification set to green. The verified code head before this +evidence-only update is `b66869f393`: + +| Command | Result | +| --- | --- | +| `NODE_OPTIONS=--no-experimental-webstorage mise exec -- yarn exec turbo run lint:tsc lint:eslint test:unit build --filter @apps/brunch-agent --filter @apps/petrinaut-website --filter @hashintel/petrinaut --filter @hashintel/brunch-agent --filter @hashintel/brunch-agent-binding-flue --filter @hashintel/brunch-agent-plugin-sdcpn --filter @hashintel/brunch-agent-transport-aisdk` | Exit 0; 39/39 tasks and 1,216/1,216 tests passed: 16/16 Brunch app files with 80/80 tests, 10/10 Brunch core files with 86/86 tests, 3/3 transport files with 32/32 tests, 5/5 binding files with 18/18 tests, 2/2 plugin files with 8/8 tests, 83/83 Petrinaut files with 673/673 tests, and 32/32 website files with 319/319 tests. | +| `mise exec -- yarn workspace @local/petrinaut-arch-docs lint:arch-docs` | Exit 0; 70 layers, 356 edges, 725 files, 71 generated pages, and 38 authored pages. | +| `mise exec -- yarn lint:format` | Exit 0; all 5,586 matched repository files use the correct format. | +| `git diff --check` | Exit 0. | + +### Earlier focused evidence + +These focused checks were established on the earlier 2026-09-04 candidate. +Their complete files were rerun inside the 2026-09-07 seven-workspace gate: + +| Command | Result | +| --- | --- | +| `mise exec -- yarn workspace @apps/petrinaut-website test:unit src/main/app/voice-interview/openai-realtime-session.test.ts src/main/app/voice-interview/realtime-brunch-bridge.test.ts src/main/app/voice-interview/voice-turn-controller.test.ts src/main/app/voice-interview/voice-preview.integration.test.ts -t 'invalidates accepted input before requesting canonical speech output\|rejects unfinished input as soon as canonical speech is requested\|clears capture when canonical speech is requested before output starts\|bridges one completed transcript through Brunch and back to canonical half-duplex audio'` | Exit 0; 4/4 selected tests passed and 92 unrelated tests were filtered across four files. This covers the request-before-output race at session, bridge, controller, and production integration layers. | +| `mise exec -- yarn workspace @apps/petrinaut-website test:unit src/main/app/voice-interview/voice-preview.integration.test.ts -t 'ambiguous Flue admission\|conflicting submission\|local admission abort'` | Exit 0; 3/3 selected tests passed and 2 unrelated tests were filtered. Conflict retains the original `submissionId`; local abort remains distinct from durable abort; every path calls `send()` once. | +| `mise exec -- yarn workspace @hashintel/brunch-agent test:unit test/question-marker.test.ts` | Exit 0; 9/9 exact question-marker tests passed. | +| `mise exec -- yarn workspace @hashintel/brunch-agent-transport-aisdk test:unit` | Exit 0; 32/32 transport tests passed, including live and snapshot marker projection plus bounded Flue-error serialization. | +| `mise exec -- yarn workspace @apps/brunch-agent test:unit test/petrinaut-chat.test.ts` | Exit 0; 1/1 real-Flue integration test passed, including exact marker persistence through fresh-process reopen while marker tools remain hidden. | +| `mise exec -- yarn workspace @hashintel/petrinaut test:unit --run src/ui/views/Editor/panels/ai-assistant-panel.test.tsx` | Exit 0; 46/46 production host-registration and panel tests passed. | +| `mise exec -- yarn workspace @apps/petrinaut-website test:unit src/main/app/voice-interview/canonical-speech.test.ts src/main/app/voice-interview/openai-realtime-session.test.ts src/main/app/voice-interview/voice-turn-controller.test.ts` | Exit 0; 79/79 exact replay, queue, terminal-gating, and turn-controller tests passed. | +| `mise exec -- yarn exec turbo run lint:tsc lint:eslint test:unit build --filter @hashintel/brunch-agent` | Exit 0; 5/5 tasks passed, including 10/10 test files and 86/86 tests; the four question-marker mock lint failures are resolved with production-interface signatures. | +| In isolated detached worktree `/Users/kostandin/Projects/hashdev/worktrees/fe-1580-latency-baseline-9496`: `mise exec -- yarn exec turbo run build --filter '@apps/petrinaut-website^...'`, then `mise exec -- yarn workspace @apps/petrinaut-website test:unit src/main/app/voice-interview/canonical-speech.test.ts src/main/app/voice-interview/openai-realtime-session.test.ts src/main/app/voice-interview/realtime-brunch-bridge.test.ts src/main/app/voice-interview/voice-turn-controller.test.ts src/main/app/voice-interview/voice-preview.integration.test.ts` | Exit 0; dependency build passed 14/14 tasks, then all 5/5 donor Voice files and 108/108 tests passed at pinned #9496 head. The isolated donor and candidate panels return HTTP 200 on ports 4916 and 4915 respectively; real audible samples remain uncollected. | + +No production Voice source under `apps/petrinaut-website/src/main/app/voice-interview` +calls `FlueClient.send()`; its only `.send()` is the OpenAI Realtime data +channel. Production Brunch registration supplies `interactiveTools: []`, and +canonical speech has no `brunch_ask` recognition. The dormant ask source remains +unmounted. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/mission-5-voice-safety-parity/provenance-blocker.md b/libs/@hashintel/brunch-agent/docs/evidence/implementations/mission-5-voice-safety-parity/provenance-blocker.md new file mode 100644 index 00000000000..b3e9e897b07 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/mission-5-voice-safety-parity/provenance-blocker.md @@ -0,0 +1,46 @@ +# FE-1580 direct-user Voice provenance blocker + +## Observed boundary + +Flue 2.0.3 can durably preserve Voice provenance for client-tool results: the +existing client-tool result signal carries each Voice-origin tool-call id, and +canonical snapshot projection can reconstruct every surviving sibling origin. +Regression coverage preserves successful siblings after a partial failure, +projects both origins from the persisted signal, and restores them through the +production observation hook after unmount and reopen. + +The corresponding direct-user seam does not exist in the installed public +contract: + +- `DeliveredMessage` user input accepts only `body` and image `attachments`; +- the caller's `idempotencyKey` is accepted for admission but is not projected + into `FlueConversationMessage` or `FlueConversationSettlement`; +- materialized user messages expose the generated `submissionId`, but no Voice + source metadata; and +- snapshot `metadata` is agent-authored response metadata, not caller-authored + user-message metadata. + +The discarded implementation persisted Voice `submissionId` values in browser +storage and correlated them after hydration. That would create a second durable +store, which the mission explicitly names as a stop condition. Encoding the +origin in visible user text is also prohibited. Replacing the canonical direct +user message with a hidden Flue signal would change the delivery semantics and +require a synthetic second transcript projection, so it is not a transparent +representation of the existing path-B turn. + +## Current disposition + +Direct spoken user turns still render with a Voice chip while their AI SDK +message metadata is live. Their canonical text and submission survive Flue +hydration, but the Voice chip cannot be reconstructed after reopen. This portion +of proof item 5 is blocked rather than reported as complete. + +Re-enter only when Flue projects caller metadata or the caller idempotency key +onto the canonical direct-user message, or when the product owner explicitly +authorizes a different durable representation. The oracle is a snapshot-only +test that reconstructs the Voice marker after a fresh process with no browser +correlation state. + +The restacked branch still installs `@flue/sdk` 2.0.3 with this same public +shape. No supported projection seam or owner-approved deferral has been +recorded, so direct-user reopen attribution remains blocked. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/mission-5-voice-safety-parity/witness-blocker.md b/libs/@hashintel/brunch-agent/docs/evidence/implementations/mission-5-voice-safety-parity/witness-blocker.md new file mode 100644 index 00000000000..420b908da58 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/mission-5-voice-safety-parity/witness-blocker.md @@ -0,0 +1,61 @@ +# FE-1580 human-evidence gate + +## Current disposition + +The real Voice witness has **not** been run and no witness bundle is claimed. +Completed-transcript authority, admission idempotency, half-duplex handoff, +acknowledged cancellation, exact full-response replay, durable Stop, dormant-ask +exclusion, exact Brunch-marked question replay, and the supported client-tool +portion of Voice provenance have focused automated coverage. Automated coverage +cannot replace the microphone, handoff, unsettled Stop, hard-reload, and +network-route witness required for mission acceptance. Direct-user Voice +attribution has a separate [Flue projection blocker](provenance-blocker.md). + +The successor is restacked onto [PR #9528](https://github.com/hashintel/hash/pull/9528) +head `58f75840804766a84ce85b9daab5b5194f3875ec`. That parent now guards its +once-per-conversation hydration from replacing a locally visible assistant +response with an older canonical snapshot, so hydration no longer blocks this +witness. The remaining gate is the required human browser and microphone run. + +An owner-directed PR #9531 side quest also removed a local launcher blocker +found at the real boundary on 2026-09-04. The Brunch-specific Vite config had +removed Petrinaut's entire `petrinaut-api-dev` plugin, so +`/api/voice/config` returned transformed module source instead of the handler's +JSON. The launcher now retains the website API plugin while continuing to +proxy only `/agents/chat/*` to Brunch. A config-level regression test loads the +real merged config, and an isolated `yarn dev:brunch` panel process with an +enabled non-secret test environment returned +`{"available":true,"connectionTimeoutMs":15000}`. This proves local Voice API +wiring only; it does not satisfy the human witness below. + +## Re-entry gate + +Using the final source/build commit: + +1. submit one typed turn; +2. run one real microphone turn and confirm exactly one matching user message; +3. confirm visible text and synthesized speech use the same canonical response; +4. use **Your turn** during output and retain cancellation acknowledgements; +5. confirm pre-handoff audio cannot submit and fresh post-handoff speech can; +6. durably stop an unsettled turn and retain its stopped settlement; +7. replay the exact full response and exact marked question; +8. hard-reload the settled conversation and confirm no resubmission or + automatic replay; +9. retain the canonical Flue snapshot and settlement index; +10. retain a network route summary proving the absolute Flue `streamUrl` + remains on the same-origin proxy; and +11. record the exact source/build and evidence commits plus hashes for every + retained artifact. + +The comparative latency proof also requires ten audible trials at pinned donor +#9496 head `c7fe8a2e68e8fdc37018b21ec2e9daf4e9ef7c82` and ten at the final +candidate. Both sets use the same machine, browser, microphone/input phrase, +model configuration, warm/cold-start policy, and finalized-speech-to-first- +audible-canonical-TTS boundary. Raw sanitized samples, the calculation method, +environment, commit identities, median, and p95 must be retained; the candidate +median may not regress and p95 regression must remain below 20%. + +Until then, `witness.md`, `voice-events.jsonl`, `network-routes.json`, +`flue-snapshot.json`, and `settlements.json` are intentionally absent rather +than populated with simulated evidence. Latency samples and statistics are also +intentionally absent until the comparable human trials run. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/import.md b/libs/@hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/import.md new file mode 100644 index 00000000000..d47fada46a6 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/import.md @@ -0,0 +1,30 @@ +# Mission 6b source import + +## Provenance and scope + +Lu authorized Mission 6b implementation and subsequent Mission 7 restack on 2026-09-07. No Linear writes or PR submission are authorized; the later replacement PR will reference FE-1580 without rewriting it. KA's original branch and PR #9531 remain untouched. + +- Source contribution: `58f75840804766a84ce85b9daab5b5194f3875ec..be56a18ff0244c5750a8702e9c7f45c0b607dc06`, authored by Kostandin Angjellari and retained with attribution in the import commit. +- Destination: Mission 6 `01649899eb65ab8d7a8fec9407dc3ea613128264` over Mission 5 `7538264feeb1487aa494e991831bed0338ae76df`. +- Authority-only cut: `ecee802ce3`. Original preparation: Mission 7 commit `86e3755` and its reconciliation draft. The old `eecbe99e20..b53b1006fb` analysis range is not the import source. +- Import method: three-way application of the exact source contribution, excluding only its root `libs/@hashintel/brunch-agent/MISSION.md`. Source evidence remains immutable history; the replacement authority supersedes source prohibitions on integrating Mission 6 only within the accepted combined-path scope. + +## Necessary join resolutions + +- Retain Mission 6's configurable browser-tool catalogue and input mapper alongside KA's hidden non-interactive question marker in transport and history. Default remains the docs reader; fixture-specific tools and their canonical input normalization remain available. The source deleted an imported default-catalogue constant, so preserve a stable default set locally rather than losing fixture configurability. +- Retain the established Mission 6 `ai-sdk:user:` / `ai-sdk:client-tools:` delivery namespaces and sorted tool-call key identity, adding KA's bounded-key validation, typed rejected/conflict/ambiguous/aborted outcomes and canonical completed-transcript Voice identities. Update source test expectations to that retained namespace; do not invent a new prefix to bypass previous admission receipts. +- Combine snapshot input normalization with KA's persisted per-tool origin records and hidden marker projection. Preserve parent continuation folding. The later reconciliation must test origins contributed by folded continuation messages; mechanically joining the two maps alone is not proof. +- Keep all independent tests added at the same insertion points: fixture transport/refusal and input mapping/pending-tool step tests from the parent; admission failure and rich stream error tests from KA. The Voice route test uses the keyed completed-transcript identity and a real request AbortSignal, not the old provider function-call identity. +- Preserve the parent's composite composer busy status and Stop-withheld follow-up behavior; no new Voice scheduler is introduced by the import. The automatic browser-tool output path still requires its own combined lifecycle/failure discriminator. +- KA's host test mocked Brunch permanently configured; the repaired parent's unconfigured-fixture test consequently failed. Make the mock explicitly configurable for that test rather than undoing the parent's fallback behavior. +- Extend the reviewed architecture inventory for the core question-marker export and its hermetic logger/tool-run test. It invokes the tool with mocked writer/logger and no runtime, key, socket or model. This is the source feature crossing the newer parent inventory, not permission to loosen the inventory check. + +## Import verification, not acceptance + +The first checks caught retained-key test expectations, the conflicting configured-host mock and the new architecture inventory entries. These were corrected at the join. The complete seven-workspace command then passed **39/39 tasks** (23 cached) before focused reconciliation: + +```sh +yarn exec turbo run build test:unit lint:tsc lint:eslint --filter @hashintel/brunch-agent --filter @hashintel/brunch-agent-binding-flue --filter @hashintel/brunch-agent-plugin-sdcpn --filter @hashintel/brunch-agent-transport-aisdk --filter @apps/brunch-agent --filter @hashintel/petrinaut --filter @apps/petrinaut-website --continue=always --output-logs errors-only +``` + +This establishes that the joined source builds and passes the existing package gates. It does not establish safe pending static-tool execution across Stop, deterministic reordered result payloads, combined Voice failure release, faithful stopped-entry reopen, a real microphone/browser witness or comparative audible latency. The active authority owns those remaining discriminators and owner-held gates. No paid provider call or human acceptance is claimed. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/main-restack.md b/libs/@hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/main-restack.md new file mode 100644 index 00000000000..da53d471f1d --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/main-restack.md @@ -0,0 +1,31 @@ +# Full-stack restack onto main + +Lu explicitly requested `gt restack --no-interactive` on 2026-09-07 after the review-only Mission 7 move. That operation restacked Missions 5, 6, 6b and 7 onto `main` at `b1d3ffcfd1077546276a8698f45cee8f7144c6dc`. No push, PR submission, Linear write, provider call or acceptance occurred. Mission 6b remains unaccepted and Mission 7's shared/paid foundation gate remains closed. + +## Resolution and pins + +Only `apps/brunch-agent/src/app.ts` and `apps/brunch-agent/src/http/routes.ts` conflicted, while replaying Mission 5's removal of the legacy chat route. Main's newly added liveness route is retained alongside the ownership-guarded Flue conversation route. `/api/chat`, its handler and its route constant remain removed. The rest of the stack replayed without source conflicts. + +| Role | Rebased pin | +| --- | --- | +| Mission 5 | `b1295ad454ba7548a927e7d9771c5bb211e04827` | +| Mission 6 | `976bb1c67cc6673c06356b855a667584b662f8c9` | +| Mission 6b code candidate | `8ed08e1eba50ea972a96481227540461e03bba39` | +| Mission 6b before this pointer refresh | `ccf93d5bb5b33c4cc54c5b349c469bc632df221b` | +| Mission 7 at the verification run | `11bfa2a18da1c782ae0ed191f12f44a68a11e2c2` | + +The runtime tree differs from the previous review candidate by main's container/liveness changes, not new Voice reconciliation behavior. The imported KA contribution remains pinned at `be56a18ff0244c5750a8702e9c7f45c0b607dc06`. KA's frozen branch was observed at the later `9415e1b0075d7cb8c5b7fe19e0512b8bc917c97f` and was left untouched; that newer contribution is not imported by this restack. Original source, witness and pre-restack evidence pins remain historical records, not rewritten results. + +## Verification + +The same seven-package command in [the reconciliation verification](verification.md#verification-run), with `--force`, passed **39/39 tasks with zero cached tasks**: builds, unit tests, TypeScript and ESLint. Scoped suites passed **1,318 tests in 167 files**. The increase from the earlier run is main's new health unit test. The architecture-doc check passed with 70 layers, 356 edges, 736 files, 71 generated pages and 38 authored pages. Whitespace and conflict-marker checks passed. + +A separate Node probe loaded the real built application through `loadBuiltBrunchApplication()`, with a fresh temporary `BRUNCH_DEV_DB_PATH` and `OTEL_SDK_DISABLED=true`. It used the production application's `fetch`, not a test-only Hono route, and shut it down afterward. Assertions verified: + +```json +{"health":{"status":200,"body":{"status":"pass"}},"legacy":404,"guardedFlue":401} +``` + +The health response also had `cache-control: no-store` and `application/health+json` content type. Requests were `/health`, `/api/chat` and `/agents/chat/missing-identity`; none admitted a conversation or contacted a model. This proves that the conflict resolution retained liveness and the single guarded conversation door in the emitted application. It is not a container-runtime, deployment, microphone, reload or latency witness. + +Subsequent commits refresh the live Mission 6b/7 dependency pointers only; they do not change this tested runtime tree or clear any acceptance gate. The existing [acceptance dispositions](verification.md#acceptance-disposition--still-open) remain open. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/owner-witness-2026-09-07/canonical-summary.json b/libs/@hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/owner-witness-2026-09-07/canonical-summary.json new file mode 100644 index 00000000000..c78a7b36f29 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/owner-witness-2026-09-07/canonical-summary.json @@ -0,0 +1,168 @@ +{ + "schemaVersion": 1, + "capturedAt": "2026-09-07", + "branch": "ln/fe-1580-reconcile-voice-resumable-workpiece", + "implementationHead": "48e2b66666df05034777f9410024c2e1228c86be", + "implementationCommits": ["1e238f498e", "48e2b66666"], + "canonicalConversationId": "conv_01M1Y4SPKHEKPVFVAMQG9QNH4Y", + "streamPath": "agents/brunch-chat-agent/7b484f39802178a2222836a7ee4c0c5e3ef123c457d507d75b3faf5ac98b3e32", + "submissions": [ + { + "sequence": 2, + "submissionId": "sub_ik_53770e9263c875a6a3ac812ed2ae291e", + "kind": "signal", + "status": "settled", + "outcome": "completed", + "fixtureId": "crew-reservation-v1" + }, + { + "sequence": 3, + "submissionId": "sub_ik_9942648a081a4a1d257dc20b41e0d9ea", + "kind": "user", + "status": "settled", + "outcome": "completed", + "body": "SDCPN" + }, + { + "sequence": 4, + "submissionId": "sub_ik_40c1b6c5489dc05c9bf9c49e243db5ed", + "kind": "signal", + "status": "settled", + "outcome": "completed", + "results": [ + { + "toolCallId": "toolu_01Ff2VXcErUd5pLxPiVFHPgc", + "toolName": "getLatestNetDefinition", + "applied": null + } + ] + }, + { + "sequence": 5, + "submissionId": "sub_ik_b15d9c3a910649fef2d5a559db61a6ee", + "kind": "user", + "status": "settled", + "outcome": "completed", + "body": "Starting final inspection reserves the single dispatch crew immediately. Sign-off releases it. The timing, failure, and recovery behavior are still unknown." + }, + { + "sequence": 6, + "submissionId": "sub_ik_f7f80b5cd8b6e3360d6a8d1bfca86f86", + "kind": "signal", + "status": "settled", + "outcome": "completed", + "results": [ + { + "toolCallId": "toolu_01XoXQED2JUy5Xk6MiH3axDs", + "toolName": "addArc", + "applied": true + } + ] + }, + { + "sequence": 7, + "submissionId": "sub_ik_785634ce1e717631217d8fc0484a660d", + "kind": "signal", + "status": "settled", + "outcome": "completed", + "results": [ + { + "toolCallId": "toolu_01MaeDyPhW4iuULiJvWkpKeE", + "toolName": "getLatestNetDefinition", + "applied": null + } + ] + }, + { + "sequence": 8, + "submissionId": "sub_ik_8eb1e09c5ebb8b651ef29965140ecd40", + "kind": "user", + "status": "settled", + "outcome": "completed", + "body": "What remains unresolved in this workpiece? Do not mutate the net." + }, + { + "sequence": 9, + "submissionId": "sub_ik_336c2a985788889d677697626db20ba1", + "kind": "user", + "status": "settled", + "outcome": "aborted", + "body": "Please give a detailed explanation of every unresolved timing, failure, and recovery question in this workpiece without changing the net.", + "abortRequested": true + }, + { + "sequence": 10, + "submissionId": "sub_ik_bcdfbccbd9856a83982a7aa2a49e1972", + "kind": "user", + "status": "settled", + "outcome": "completed", + "body": "Just give me a very brief overview of what is less than optimal in the current model." + }, + { + "sequence": 11, + "submissionId": "sub_ik_3926c3230c824a5a3c7a6a13089a6729", + "kind": "user", + "status": "settled", + "outcome": "completed", + "body": "For testing purposes only, ask me a question please." + } + ], + "toolCalls": [ + { + "sequence": 32, + "submissionId": "sub_ik_9942648a081a4a1d257dc20b41e0d9ea", + "messageId": "entry_01M1Y4T7VKYRMJPBQ87QNY9HHF", + "toolCallId": "toolu_01Ff2VXcErUd5pLxPiVFHPgc", + "toolName": "getLatestNetDefinition", + "arguments": {} + }, + { + "sequence": 115, + "submissionId": "sub_ik_b15d9c3a910649fef2d5a559db61a6ee", + "messageId": "entry_01M1Y511RH9XABSYGBYAJE430A", + "toolCallId": "toolu_01XoXQED2JUy5Xk6MiH3axDs", + "toolName": "addArc", + "arguments": { + "transitionId": "start-final-inspection", + "arcDirection": "input", + "placeId": "dispatch-crew-available", + "weight": "1", + "type": "standard" + } + }, + { + "sequence": 126, + "submissionId": "sub_ik_f7f80b5cd8b6e3360d6a8d1bfca86f86", + "messageId": "entry_01M1Y51F3JYQVJW5N5CKC9PWE6", + "toolCallId": "toolu_01MaeDyPhW4iuULiJvWkpKeE", + "toolName": "getLatestNetDefinition", + "arguments": {} + } + ], + "modelProducedWorkpieceMessages": [ + { + "messageId": "entry_01M1Y511RH9XABSYGBYAJE430A", + "submissionId": "sub_ik_b15d9c3a910649fef2d5a559db61a6ee", + "sequence": 98, + "runbookBlockCount": 1 + }, + { + "messageId": "entry_01M1Y51QS8WTR61G9Z1V1YNFY3", + "submissionId": "sub_ik_785634ce1e717631217d8fc0484a660d", + "sequence": 148, + "runbookBlockCount": 1 + } + ], + "assertions": { + "targetAddArcCallCount": 1, + "clientResultSignalsAreSingleStep": true, + "durableAbortCount": 1, + "directSpokenUserOriginPresentAfterHydration": false, + "browserObservedSettledRevision": 2, + "browserObservedTargetArc": "present", + "browserObservedAutoplayOnHydration": false, + "browserObservedResumedWorkAfterAbort": false, + "browserObservedStoppedLabel": true, + "browserObservedPlaybackControlsPassed": true + } +} diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/owner-witness-2026-09-07/failed-cumulative-results.png b/libs/@hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/owner-witness-2026-09-07/failed-cumulative-results.png new file mode 100644 index 00000000000..fc935e7a845 Binary files /dev/null and b/libs/@hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/owner-witness-2026-09-07/failed-cumulative-results.png differ diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/owner-witness-2026-09-07/passing-negative-control.png b/libs/@hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/owner-witness-2026-09-07/passing-negative-control.png new file mode 100644 index 00000000000..a3150ba3975 Binary files /dev/null and b/libs/@hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/owner-witness-2026-09-07/passing-negative-control.png differ diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/owner-witness-2026-09-07/witness.md b/libs/@hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/owner-witness-2026-09-07/witness.md new file mode 100644 index 00000000000..a753b931f24 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/owner-witness-2026-09-07/witness.md @@ -0,0 +1,74 @@ +# Mission 6b owner witness — 2026-09-07 + +## Verdict + +Lu Nelson accepted Mission 6b on 2026-09-07 with the explicit claim and limitations below. The accepted local product path is: completed Voice transcript → canonical Brunch conversation → explicit half-duplex handoff → one browser mutation and verification → coherent revision 2 → Tab-B continuation → durable active-submission Stop → Tab-C stopped-entry recovery without autoplay or resumed work. + +This witness does not establish comparative latency, direct spoken-user Voice attribution after hydration, or durable recovery of browser work withheld locally after its Flue tool-call step has already settled. Those claims were explicitly deferred rather than passed. + +## Environment and pins + +- Branch: `ln/fe-1580-reconcile-voice-resumable-workpiece`. +- Tested implementation head after the two witness repairs: `48e2b66666df05034777f9410024c2e1228c86be`. +- Causal client-result repair: `1e238f498e`. +- Explicit-evidence fixture repair: `48e2b66666`. +- Local entrypoint: `yarn dev:brunch`. +- Browser fixture: `http://127.0.0.1:4915/?brunch-fixture=crew-reservation-v1` in a fresh private browsing context after origin storage was cleared. +- Canonical conversation: `conv_01M1Y4SPKHEKPVFVAMQG9QNH4Y`. +- Model reported by the canonical stream: `claude-haiku-4-5`. +- Secrets, authorization headers, SDP, audio, provider payloads, and browser principal are not retained. + +## Discovery run and repairs + +The first attempted spoken confirmation was transcribed canonically as only `SDCPN`. The pre-repair agent nevertheless inferred the intended fixture correction from revision zero, issued two browser reads across separate model steps, applied `addArc`, and then received a cumulative client-result signal containing the new mutation result plus both stale reads. Tool results were sorted by call id rather than causal order, so the continuation misread the old definitions as post-mutation verification and reported an anomaly. The browser showed the arc while the coherent-bundle guard correctly refused settlement and retained revision zero. + +Database inspection established that the duplicate-looking reads were not duplicate execution of one canonical tool call: they were distinct calls from successive assistant steps, accumulated into later AI SDK message state. `completedClientToolResults` scanned the entire folded assistant message on every automatic continuation. The first repair added a red public-seam test at `createFlueChatTransport().sendMessages()` and changed collection to the most recent assistant step containing client-tool output. A second real attempt exposed a mixed server/browser batch: `activate_skill` continued on the server while `getLatestNetDefinition` completed in the browser, leaving a later server-only step after the pending browser result. The regression was extended to that exact topology before the collector was corrected. The passing negative and positive runs each admitted one client result per signal, with no stale cumulative results. + +Revision zero also contradicted the model-facing fixture instruction: it said to wait for confirmed true-user evidence while the prepared workpiece already stated crew reservation as fact and described the missing arc as an approved correction. A red fixture test preceded the repair. Revision zero now labels crew reservation as an unconfirmed hypothesis, and the plugin instruction says fragments, topic labels, inspect/explain requests, and unrelated messages cannot authorize mutation. + +The failed databases remain outside the repository at `/tmp/brunch-agent-failed-witness-20260907T134055Z` and `/tmp/brunch-agent-negative-control-error-20260907T143604Z` for the life of this machine session. They are diagnostic inputs, not accepted evidence. + +## Accepted run + +1. The prepared fixture settled at revision zero with the target arc absent and its Markdown workpiece available. +2. Voice connected and the microphone check responded. +3. Lu supplied the negative control `SDCPN`. Canonical submission `sub_ik_9942648a081a4a1d257dc20b41e0d9ea` completed. Brunch inspected the net once, did not call `addArc`, kept revision zero settled, and asked for explicit confirmation. The response was much more verbose than necessary; this is interaction strain, not a correctness failure. +4. Lu used **Your turn**, waited for fresh listening, and said: `Starting final inspection reserves the single dispatch crew immediately. Sign-off releases it. The timing, failure, and recovery behavior are still unknown.` Canonical submission `sub_ik_b15d9c3a910649fef2d5a559db61a6ee` completed. +5. The assistant emitted one model-produced workpiece before construction, then issued `addArc` call `toolu_01XoXQED2JUy5Xk6MiH3axDs`. Result submission `sub_ik_f7f80b5cd8b6e3360d6a8d1bfca86f86` contained only that result and reported `applied: true`. +6. A later, separate `getLatestNetDefinition` call `toolu_01MaeDyPhW4iuULiJvWkpKeE` verified the changed document. Its result submission contained only that read. The assistant emitted the final full workpiece in another message, so revision 2 correctly represents distinct pre-mutation and post-verification model-produced workpieces rather than two user turns. +7. The browser showed exactly one standard weight-1 input arc from `Dispatch crew available` to `Start final inspection`, a settled revision-2 bundle, one visible canonical reply, and one audible rendering. +8. Tab B reopened revision 2 with the target arc, conversation, and workpiece intact. No audio autoplayed and no work or mutation duplicated. The typed follow-up `What remains unresolved in this workpiece? Do not mutate the net.` completed without another `addArc`. +9. Lu started another Voice turn asking for a detailed account of unresolved timing, failure, and recovery, exited Voice mode, and pressed durable Stop while the response was active. Submission `sub_ik_336c2a985788889d677697626db20ba1` has `abort_requested_at` and canonical outcome `aborted` with `submission_aborted` error. +10. Tab C retained the streamed partial prose as formatted headings/list items with a message-level **Response stopped** label. The final phrase remained honestly truncated. Revision 2 and the target arc stayed coherent; no audio autoplayed and no tool work resumed. +11. **Read full response**, **Repeat question**, stopped-response gating, and compact/expanded Voice controls behaved as specified. Two additional non-mutating test turns used for those controls remain visible in `canonical-summary.json`. + +## Owner dispositions + +- **Direct spoken-user Voice attribution after hydration — deferred truthfully.** Live Voice chips were visible, but both disappeared after Tab-B snapshot hydration. Flue/AI SDK 2.0.3 does not retain caller Voice metadata. The accepted claim is that spoken text is canonical and durable and client-tool Voice origins survive; direct spoken-user origin is not shown after reopen until the upstream SDK exposes durable caller metadata. No local sidecar, text encoding, or Flue patch is authorized. +- **Post-settlement local withholding — deferred with a narrowed Stop claim.** Durable Stop is accepted for active Flue submissions, as witnessed. If Flue has already settled a tool-call step, browser work withheld locally in the current process has no canonical withholding record and may reappear as pending after reopen. Already-applied mutations are not rolled back. Re-enter when the platform provides a durable canonical withholding/cancellation operation or a product consumer requires this race to close. +- **Comparative audible latency — deferred with no latency claim.** The required 10 donor + 10 candidate campaign did not run. Re-enter if latency becomes a release criterion, measured complaint, or performance regression investigation. +- **Interaction strain — accepted, not erased.** The negative-control response recited excessive net detail before asking the necessary question. Durable Stop was poorly discoverable while Voice was active: Lu had to exit Voice mode before using the streaming Stop action. These are future UX inputs, not evidence that the accepted control path failed. +- **Evidence bundle limitation — accepted explicitly.** The run retains canonical submissions, settlements, tool ids, workpiece-message ids, owner observations, and two screenshots. It does not retain the pre-registered full `voice-events.jsonl`, browser network-route export, raw canonical snapshot, or audible latency samples. No missing artifact is inferred or manufactured. + +## Artifacts + +- [`canonical-summary.json`](canonical-summary.json) — sanitized SQLite-derived submissions, tool calls, workpiece sources, and owner-observed browser assertions. +- [`failed-cumulative-results.png`](failed-cumulative-results.png) — first-run UI showing the out-of-order reasoning/tool chain and eventual incoherent state before repair. +- [`passing-negative-control.png`](passing-negative-control.png) — repaired negative control showing one net read, no mutation, and an explicit confirmation question. + +## Automated verification + +The red/green transport command was `yarn workspace @hashintel/brunch-agent-transport-aisdk test:unit chat-transport.test.ts`. Before repair it dispatched `mutation-latest,read-before-1,read-before-2`; the mixed-batch refinement then reproduced `The client-tool follow-up has no completed result.` After repair it passes 19 tests. + +Final focused checks observed during the witness: + +- `yarn workspace @hashintel/brunch-agent-transport-aisdk test:unit` — 42 passed. +- `yarn workspace @hashintel/brunch-agent-transport-aisdk lint:tsc` — passed. +- `yarn workspace @hashintel/brunch-agent-transport-aisdk lint:eslint` — no errors; two pre-existing sequential retry-test warnings. +- `yarn workspace @hashintel/brunch-agent-plugin-sdcpn test:unit` — 11 passed. +- `yarn workspace @hashintel/brunch-agent-plugin-sdcpn lint:tsc` and `lint:eslint` — passed without warnings. +- Focused prepared fixture and settlement tests — 14 passed. +- `@hashintel/petrinaut` `ai-assistant-panel.test.tsx` — 56 passed; existing React Compiler warnings only. +- Focused website transport, Voice preview, browser-tool integration, and local-storage app tests — 32 passed. + +These focused checks and the owner witness establish the accepted local claim. They do not replace the repository-wide final check or create a remote deployment claim. diff --git a/libs/@hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/verification.md b/libs/@hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/verification.md new file mode 100644 index 00000000000..d1d033a268c --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/verification.md @@ -0,0 +1,83 @@ +# Mission 6b — Local reconciliation verification + +## State and pins + +Local implementation candidate, **not mission acceptance or a real microphone/browser witness**. Recorded on 2026-09-07. Implementation approval did not waive provenance, human acceptance, latency or newly observed cancellation/reopen limits. No paid calls, Linear writes, PR submission or changes to KA's original branch/PR were made. + +- Candidate code: `c649eec3ba5d31b27294f6a870a0a5d676b79fd8`. +- Authority: `ecee802ce3`; source import: `66ac62693f`; import test joins/provenance: `221f3e53a0`. +- Mission 6 parent: `01649899eb65ab8d7a8fec9407dc3ea613128264`; Mission 5: `7538264feeb1487aa494e991831bed0338ae76df`. +- KA source contribution: `58f75840804766a84ce85b9daab5b5194f3875ec..be56a18ff0244c5750a8702e9c7f45c0b607dc06`, still unchanged at inspection. See [import provenance](import.md). +- Mission 7 remains at `86e37556e363c06bdd5700b67ba58991363ba5a3` when this record is first written; it has not yet moved above this candidate. + +## Demonstrated repairs + +The repaired parent already holds ordinary SDK automatic follow-up busy. The additional code addresses observed defects at deferred browser execution and canonical history, not a replacement scheduler. + +| Discriminator | Before repair | Candidate evidence | +| --- | --- | --- | +| Reordered cumulative client-tool results | Same idempotency key, different serialized payload order | `transport-aisdk/test/chat-transport.test.ts`: identical payload bytes and key after reordering | +| Folded continuation origins | Voice call IDs on a continuation disappeared when it folded into the root message | `transport-aisdk/test/transcript.test.ts`: surviving origins are merged | +| Reopened aborted entry followed by a completed reply | No per-message stopped metadata | Canonical settlements identify only the aborted entry; transcript and contents tests retain its label without a global Stop banner | +| Stop before deferred browser execution | Follow-up withheld, but the deferred mutation still ran | Panel regression asserts the not-yet-started mutation does not run | +| Textless automatic-tool failure | Hosts saw `ready` and Voice could remain owned | Panel records matching `output-error`, retains visible detail, exposes terminal error; combined test releases Voice through the error path | +| Durable aborted history with pending tool input | Reopening executed the stopped tool | Panel skips runnable parts of canonically stopped messages | +| StrictMode setup/cleanup/setup | Cleanup cancelled the execution timer but retained its claim; recovered work stayed busy | Pending timer claims are released on cleanup; initially hydrated StrictMode test executes exactly one continuation | +| Stop in conversation A, then switch to B | A's terminated generation suppressed B's recovered work | Conversation changes invalidate the generation and reset local turn presentation; B executes once | +| Async command from A completes after switch to B | A's output scheduled an unsolicited continuation in populated B | Generation and conversation ownership are checked before insertion and continuation; deferred-layout test observes no send to B | +| Preamble commits after cancellation finishes | A later ready render spoke the previously withheld prose | Bridge retires stopped segments; combined preamble/Stop test observes no speech after a repeated update | + +A read-only independent review identified the last four discriminators (three findings, with two conversation-identity cases). They were reproduced before repair and pass afterward. An initial conversation test fixture incorrectly returned an endless empty finish and used the wrong composer-control prop; it was corrected before adjudicating the identity cases. The resulting red tests, not that harness failure, support the findings. + +## Combined production-component test + +`apps/petrinaut-website/src/main/app/voice-interview/voice-browser-tools.integration.test.tsx` mounts the published `Petrinaut` component, its actual panel and `useChat`, production `createBrunchPanelTransport`, admission tracker, `submitVoiceInputWithAdmission`, canonical speech selection and `RealtimeBrunchBridge`. + +Five cases cover browser continuation with and without preamble, textless invalid browser input, and local withholding with and without preamble. They assert busy ownership while the continuation is held, original tool-call identity in the delivered signal, exact canonical speech after continuation, visible terminal failure, and no speech or continuation after local Stop. The preamble Stop case repeats the final update to detect speech resurrection. + +Flue send/wait events, media input/output and cancellation acknowledgement are controlled by the test. The browser tool reads documentation; it does not prove the real fixture mutation, microphone/VAD timing, audible cancellation, network route or fresh-tab persistence. The panel mutation test separately checks Stop-before-execution. These distinctions prevent a component integration pass from being presented as the required product witness. + +## Verification run + +At the candidate code state, all **39/39** tasks passed, with **0 cached** tasks: + +```bash +yarn exec turbo run build test:unit lint:tsc lint:eslint --filter @hashintel/brunch-agent --filter @hashintel/brunch-agent-binding-flue --filter @hashintel/brunch-agent-plugin-sdcpn --filter @hashintel/brunch-agent-transport-aisdk --filter @apps/brunch-agent --filter @hashintel/petrinaut --filter @apps/petrinaut-website --force --continue=always --output-logs errors-only +``` + +The scoped unit suites passed **1,317 tests in 166 files**: + +| Package | Files | Tests | +| --- | ---: | ---: | +| Brunch core | 11 | 93 | +| Flue binding | 5 | 18 | +| SDCPN plugin | 2 | 11 | +| AI SDK transport | 4 | 41 | +| Brunch application | 19 | 109 | +| Petrinaut | 84 | 687 | +| Petrinaut website | 41 | 358 | + +Additional checks: `yarn workspace @local/petrinaut-arch-docs lint:arch-docs` passed (70 layers, 356 edges, 736 files, 71 generated pages, 38 authored pages); changed TypeScript formatting, the three changed publishable/user Markdown files and `git diff --check` passed. Commit hooks passed formatting and Markdown lint. Existing non-blocking React Compiler and Node configuration warnings are not repaired here. Brunch Markdown is explicitly excluded from the repository formatter and Markdown lint, so those tools are not claimed as checks of this record. Full Local CI/GitHub CI and live screenshot/audio evidence were not run; no push occurred. + +## Acceptance disposition — accepted with explicit limitations on 2026-09-07 + +Lu Nelson accepted the narrowed Mission 6b claim after the real owner witness in [`owner-witness-2026-09-07/witness.md`](owner-witness-2026-09-07/witness.md). That witness exposed and repaired cumulative cross-step client results and the fixture's non-causal prepared answer, then passed the negative control, explicit spoken mutation, Your turn, coherent revision-2 settlement, Tab-B continuation, active-submission durable Stop, Tab-C stopped-entry recovery, and playback controls. The full pre-registered telemetry bundle was not retained; the owner accepted that evidence limitation explicitly. + +| Obligation | Disposition | +| --- | --- | +| Source preservation, scoped catalogue, canonical normalization, deterministic admission and inherited automated contracts | Imported with provenance; scoped suites pass | +| Deferred execution, termination and history joins above | Discriminated and repaired locally; the owner witness additionally proved one result per causal step after the cross-step accumulation repair | +| Exact Stop timing during held output insertion and insertion rejection through the full combined host | Not separately demonstrated by the owner witness; source/component cases remain bounded automated evidence rather than a claim that every race was witnessed | +| Real fixture spoken mutation, Your turn, Stop, coherent bundle, Tab-B continuation and compact/expanded inspection | Passed by the owner witness, including one causal mutation, no duplicate/autoplay, canonical active-submission abort and stopped-entry recovery | +| Direct spoken-user Voice chip after snapshot-only reopen | Observed missing and explicitly deferred by Lu; canonical text survives, but no direct-user Voice-origin claim is made after hydration | +| Reload-safe cancellation of a locally withheld tool continuation | Explicitly deferred with the narrowed Stop claim below; no invented durable marker | +| Comparative audible latency | Explicitly deferred; Mission 6b makes no comparative latency or no-regression claim | +| Human acceptance and original PR retirement | Narrowed mission claim accepted by Lu; KA's PR remains untouched and requires separate retirement authorization | + +### Local withholding is not a durable stopped record + +When a Flue tool-call step has already completed, the parent Stop adapter can return `already-settled`. The panel can withhold pending browser execution and its follow-up, and Voice can release that logical turn without speaking its late prose. The bridge labels this outcome `withheld`, not a fabricated Flue abortion. Canonical history still records the original step as completed with pending tool input. + +A fresh process cannot infer the local withholding from that snapshot. Pending completed-step tools remain recoverable work, whereas genuinely aborted submissions now project `metadata.stopped` and are not executed. The successful aborted-entry tests do **not** solve this local-withholding/reopen case. User docs explicitly warn that reopening can recover the locally withheld tool as pending work. + +Resolving that distinction durably requires a supported recording/termination boundary. Do not add a browser sidecar, forge aborted settlements, admit an extra hidden turn, or silently disable ordinary pending-tool recovery. Lu accepted the narrower behavior on 2026-09-07: Stop is durable while the Flue submission is active; after a tool-call step settles, locally withheld browser work may reappear as pending after reopen, and already-applied mutations are not rolled back. Re-enter when the platform supplies a durable canonical withholding/cancellation operation or a product consumer makes this race load-bearing. diff --git a/libs/@hashintel/brunch-agent/docs/mission-archive/6-resumable-workpiece-petrinaut.md b/libs/@hashintel/brunch-agent/docs/mission-archive/6-resumable-workpiece-petrinaut.md new file mode 100644 index 00000000000..18f9c2b79b0 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/mission-archive/6-resumable-workpiece-petrinaut.md @@ -0,0 +1,162 @@ +# Mission 6 — resume one prepared workpiece and Petrinaut document + +## Status + +**Closed on `ln/fe-1575-resumable-workpiece-petrinaut` by owner decision on 2026-09-04.** [FE-1575](https://linear.app/hash/issue/FE-1575/resume-one-brunch-workpiece-and-petrinaut-document-across-tabs) delivered the implementation, outer mechanical witness, cold-reader adjudication, and the product manager's fresh two-tab conversation/workpiece/document demo; see the [retained implementation and witness evidence](../evidence/implementations/fe-1575-resumable-workpiece-petrinaut.md). The owner explicitly waived re-running the Voice-origin and aborted-assistant presentation clauses in the fresh product-manager conversation and closed the mission anyway: those records were absent from that run, their behavior is mechanically covered by the outer witness, and their future scenario obligations are carried in [`MISSION.next.md`](../../MISSION.next.md#voice-after-the-live-transport-cut). This is a closure exception, not evidence that the skipped human checks passed. Earlier on 2026-09-04 the owner amended only the Deferred section, to point at the recut future planning record and carry two admissions from this mission's evidence; the imperative, throughline, proof, constraints, fog-line, and stop conditions otherwise remain the historical execution contract. + +## Imperative + +Determine whether one canonical Brunch conversation can maintain a useful Markdown workpiece and drive a meaningful change to a real Petrinaut document through the browser without reviving a comprehensive typed domain IR. + +Mission 3 separately showed a recoverable Markdown workpiece and hermetic canonical Petrinaut callbacks, but its paid model could not carry a nested construction schema and no product path joined the two results. Mission 4 accepted the independent core `elicitation` capability and SDCPN job-skill composition but produced no full-run candidate. This mission must retire the join and resume uncertainty honestly with one deliberately prepared fixture rather than treating either historical result as an integrated product. + +### Visible product advance + +**Release note:** Brunch edits the Petrinaut net you are looking at from the conversation, and your work survives closing the tab. + +**Demo script (no engineer present):** with the local Brunch/Petrinaut development stack running, open the stable demo fixture selector for the labelled prepared crew-reservation case. Its canonical Brunch conversation, current Markdown workpiece, and non-empty Petrinaut net come back together. The fixture visibly states that it is test-authored and prepared, and what it does not claim. Tell Brunch the one new realistic fact the fixture is prepared for: final inspection uses the single dispatch crew, and sign-off releases it. Watch the workpiece update and a new arc appear in the live net from `Dispatch crew available` to `Start final inspection`. Wait until the fixture reports that the conversation, workpiece, and automatically mirrored document are settled. Open the same fixture in a second tab, confirm that messages retain their typed/Voice provenance and that an aborted assistant entry still presents as stopped rather than as an ordinary truncated answer, submit one follow-up message, and receive Brunch's response in the same conversation without duplicate submission or identity drift. + +**Previously impossible:** Brunch only produced off-canvas net JSON for manual load; nothing it did touched the live document or survived a reload. + +**Deployment posture:** the demo runs against the locally run Petrinaut website and Brunch agent (`yarn dev:brunch`). Mission 8 stopped before remote deployment, so no product-manager-noticeable claim here depends on remote infrastructure; remote durability stays with Mission 8. + +**Completion:** the mission is done when a product manager can run that demo script end to end for this fixture and every readiness-gate obligation in [Proof](#proof) is closed. The first green pass through the two-tab path is an internal milestone inside the mission, not its completion. + +## Throughline + +### Observed departure point and first unproved boundary + +The production browser already has most local pieces: + +- `apps/petrinaut-website`'s local-storage demo owns an editable `PetrinautDocHandle`, automatically writes handle changes to `petrinaut-sdcpn`, and maps each net to a persistent Brunch conversation id; +- Petrinaut's stock AI panel already validates and executes canonical read, mutation, and command tools against the active browser document and returns the original tool-call id; +- live Mission 5 is replacing the server-side `GET`/`POST /api/chat` adapter with one browser `FlueClient` plus host-supplied AI SDK `ChatTransport` over the mounted `/agents/chat/:instanceId` route; that route carries typed turns, `history()` hydration, and correlated client-tool-result signals, and Mission 6 must consume rather than duplicate or reverse that transport; and +- the SDCPN skill already emits a full recoverable `runbook-ir` block and requires construction to consume that workpiece rather than transcript archaeology. + +The first unproved boundary is ordinary Brunch conversation over Mission 5's browser Flue transport → mounted canonical document read / least mutation → browser execution → correlated Flue continuation. Today ordinary SDCPN conversations mount only the Petrinaut documentation reader as a browser tool; the validated construction subset is headless-only, and no stable fixture selector or coherent cross-tab witness joins the conversation, workpiece, and document lifecycles. Mission 6 may develop independent fixture/workpiece/document logic while Mission 5 proceeds, but it must consume Mission 5's landed browser transport before integrated or outer proof and must not add another conversation route in the interim. + +### Accepted fixture and boundary crossings + +Prepare the existing final-inspection / dispatch-crew case as an explicitly test-authored fixture. Its starting workpiece and non-empty net preserve this narrow account: one crew is reserved during final inspection, sign-off releases it, the batch then becomes dispatch-ready, and timing plus failure/recovery remain unresolved. Its prepared material must identify its authorship and must not be presented as a Mission 4 candidate or model-produced evidence. + +Deliver the prepared starting workpiece exactly once through Flue's public dispatch surface as a tagged structured signal. Its canonical record must remain `role: system`, `purpose: dispatch`, carry the fixture id, `test-authored` authorship, and non-claims as signal attributes, and preserve the exact Markdown body. This record is prepared revision zero. Later full `runbook-ir` blocks emitted in genuine assistant responses are model-produced revisions; the workpiece resolver selects the latest eligible revision without rewriting Flue's append-only history. This is analogous to last-one-wins selection of extension-contributed artifacts in a Pi raw session log, not permission to overwrite either log. + +The disposable production-route probe established the carrier facts: the tagged signal retained its exact body and attributes, an exact idempotent retry converged on the original submission without adding messages, and the snapshot survived process reopen unchanged. The current `ChatAgent` rejected fixture authorship supplied as `initialData` with `400` and created no history; `initialData` is not a substitute for the public workpiece source. A user delivery would impersonate the person, while faux-provider output, hand-authored assistant records, private canonical record types, direct database writes, and a second history store are not preparation routes. The probe's configured Anthropic credential was rejected with `401`, so its separately classified faux assistant response established no model-behavior claim. + +Prepare the net with `Batch ready`, `Under final inspection`, `Ready for dispatch`, and `Dispatch crew available` places plus `Start final inspection` and `Sign-off` transitions. Preserve the batch-flow arcs and the return of the crew from sign-off, but deliberately omit the standard input arc that reserves the sole crew when final inspection starts. Use one realistic confirming answer: final inspection consumes the sole available dispatch crew, sign-off returns it, and timing plus recovery remain unknown. The least candidate mutation is one canonical weight-1 standard input arc from `Dispatch crew available` to `Start final inspection`. The exact before/after edge makes the semantic oracle discriminating while avoiding Mission 3's deeply nested schema failure. If that shallow mutation still cannot cross Flue faithfully, stop with the carrier blocker rather than weakening the claim. + +```text +stable prepared-fixture selector +→ resolve distinct fixture, Petrinaut document, and Flue conversation identities +→ open the prepared non-empty browser document and use the browser Flue client to idempotently deliver or recover the tagged revision-zero signal +→ hydrate canonical Flue history through `history()` on the mounted route +→ recover prepared revision zero from the tagged dispatch record, or the latest eligible assistant revision, by source message id plus content hash +→ submit the realistic crew-reservation confirmation through Mission 5's production browser Flue transport +→ Brunch emits an inspectable full workpiece revision without erasing prior meaning or the remaining unknown +→ SDCPN construction reads that current workpiece and the live browser document +→ Brunch requests the least canonical meaningful mutation +→ Petrinaut validates and executes it against the bound document +→ the original tool-call id and result return as one correlated signal through the same browser Flue transport and resume the same conversation +→ inspect the canonical non-empty document and advance the runtime settled manifest only after conversation/workpiece/document state is observable +→ a second tab opens the same fixture selector, resolves the same identities and settled hashes, submits one follow-up, and receives Brunch's response +``` + +The settled fixture manifest is runtime local product state, not merely retained evaluation evidence: the stable selector uses it to choose the latest coherent observed bundle of distinct fixture, Flue conversation, workpiece source/hash, and Petrinaut document/hash or revision identities across reopen. It is a small viability pointer, not a new event log, independent workpiece store, or distributed transaction. A failed history load, workpiece recovery, rejected/no-op mutation, or missing result correlation must leave the prior settled bundle selected while partial state and failure remain visible for diagnosis. Retained witness artifacts copy and inspect this runtime state but do not select the product bundle. The existing automatic localStorage mirror is the only document-save mechanism unless a real failure proves it insufficient; this mission adds no explicit Save affordance. + +### Expected touched paths + +This manifest is provisional and may shrink or move when the first real probe exposes the deeper existing boundary: + +```text +libs/@hashintel/brunch-agent/ +├── MISSION.md ~ live authority and eventual close evidence +├── MISSION.next.md ~ future joins and carried flags only +├── packages/plugin-sdcpn/ ~ mount only the read/mutation capability earned by this tracer +└── docs/evidence/ + prepared fixture manifest and browser witness +apps/brunch-agent/ +├── src/agents/chat-agent/ and src/conversation/ ? only if fixture-scoped mounting or workpiece recovery belongs outside the landed browser transport +└── test/ + real Flue/client-tool fixture integration +apps/petrinaut-website/ +└── src/main/app/local-storage-demo/ ~ consume Mission 5 transport; fixture selection, prepared signal, runtime settled manifest, and cross-tab continuation +libs/@hashintel/brunch-agent/packages/transport-aisdk/ ? consume the landed Mission 5 public surface; do not duplicate its implementation here +libs/@hashintel/petrinaut-core/ or libs/@hashintel/petrinaut/ ? only for an observed canonical contract or browser-host defect +``` + +## Proof + +The visible advance is the demo script in the imperative, run by a product manager against the named local posture. The evidence that backs the claim is one stable local demo URL or fixture selector plus its labelled prepared manifest, exact before/after Flue snapshots, recovered Markdown workpiece revisions, canonical Petrinaut document states, and two-tab witness; those are oracles for the builder and adjudicator, not the advance itself. Together they establish single-fixture browser-backed viability. They do **not** establish automatic full-net projection, capture-backed or selected-pair provenance, behavioral execution, broad scenario coverage, remote replacement durability, concurrent editing, Mission 3/4 quality superiority, or a promoted reusable product seed. + +### Internal milestone: first green throughline + +The first internal milestone is one pass through the throughline for the prepared fixture: a cold reader can reconstruct the spine and distinguish supplied evidence, inference, and the explicit unknown in the workpiece; one realistic turn produces an inspectable workpiece revision without erasing the unknown; Brunch reads the live document and applies the one supported arc through the real browser client-tool boundary; the canonical net is non-empty and visibly corresponds to the confirmed meaning; and a second tab observes the same settled conversation, workpiece, and document revision and continues without duplicate submission or identity drift. Reaching this milestone authorizes the readiness work below; it does not close the mission. + +### Readiness gate: completion bar + +The mission completes only when the demo script works for this fixture and these obligations are closed: stale fixture/workpiece/document revision refusal, duplicate tool delivery, read/write failure visibility, unsupported meaning, no-op mutation honesty, partial-save behavior, second-tab rehydration, separate identity integrity, and one negative mutation case. Do not close every consequential-element provenance link, remote task replacement, broad scenario coverage, or repeated automatic projection here; those become Mission 7 or Mission 9 obligations only after this tracer exposes a finite peer set and load-bearing seams. + +Every final leaf has a discriminating oracle: + +1. **The prepared fixture is honest and sufficient for this narrow test.** The committed fixture manifest, raw Flue snapshot, and a cold-reader adjudication identify the prepared workpiece's tagged system/dispatch source, exact test-authored Markdown, process spine, constrained crew, release policy, quantity context, explicit unknown, prepared net meaning, and non-claims. The same inspection distinguishes every later assistant revision as model-produced and must not require transcript archaeology. +2. **One evidence turn maintains the Markdown workpiece.** A production-agent fixture integration mechanically recovers prepared revision zero from the tagged dispatch record, then selects the latest eligible assistant `runbook-ir` block after the confirming turn, retaining each source message id and SHA-256. Before/after adjudication must find the supplied contextual quantity, retained crew/release meaning, retained unsupported context, and no invented fact or hardened unknown. +3. **The real browser executes a correlated Petrinaut read and write.** Focused plugin/transport tests prove that `getLatestNetDefinition` and the selected `addArc` schema come mechanically from Petrinaut's canonical contracts, fixture mode advertises only the selected operations, duplicate result delivery does not apply the mutation twice, rejected input remains visible, and a mutation that would change nothing is reported as a no-op rather than as a change. The browser witness must retain tool name, call id, parsed input, execution output, resumed signal, and resulting canonical definition; a headless callback alone does not pass. +4. **The document change is meaningful rather than merely accepted.** A structural comparison proves there was no standard input arc from `Dispatch crew available` to `Start final inspection` before the turn and exactly one weight-1 arc afterward, while `Sign-off` still returns the crew and the prepared net remains non-empty. The changed workpiece retains the reservation/release meaning and unresolved timing/recovery. Parser/schema acceptance or a disconnected convenience element fails. +5. **The runtime settled manifest cannot bless partial state.** A focused failure test injects history/workpiece-recovery failure, rejected `addArc`, or missing/duplicate result correlation and shows that the prior coherent runtime bundle remains selected while the failure and any partial state are inspectable. A retained evidence manifest alone does not pass this leaf, and no localStorage failure interface is invented solely to satisfy it. +6. **A second tab resumes and continues the same fixture.** With `yarn dev:brunch` running, the recorded browser protocol opens the stable selector in Tab A, performs and settles the turn, then opens it in Tab B. The witness compares fixture id, document id and canonical definition hash, Flue conversation id and history, latest workpiece source/hash, runtime settled-manifest identity, per-message typed/Voice provenance, stopped-turn presentation, and absence of duplicate submission. An aborted entry rendered as ordinary truncated content fails this check even if a global latest-settlement banner still says stopped. Tab B must then submit one follow-up message and receive its correlated Brunch response in that same conversation. A read alone does not pass. Tab B opened against a stale or mismatched revision must refuse visibly rather than silently select older artifacts. +7. **The cut has not smuggled in the later architecture.** Public-schema and dependency inspection finds only fixture identity/revision links, Markdown recovery metadata, and canonical Petrinaut payloads—no closed process ontology, typed capture-to-workpiece reducer, graph database, second conversation log, or general projection engine. + +Verification proceeds inside-out but closure requires the outer boundary: + +- **Inner:** fixture parsing and prepared-label checks; identity separation; workpiece recovery/hash; canonical `addArc` schema and exact before/after edge assertion; idempotent client-tool result handling; runtime-manifest refusal. +- **Middle:** the built production `ChatAgent` and Mission 5 browser `FlueClient`/`ChatTransport` path at `/agents/chat/:instanceId` hydrate the prepared conversation, accept the evidence turn, recover the revised workpiece, and carry actual browser-tool calls/results. No `GET` or `POST /api/chat` evidence passes. Run the focused workspaces through root Turbo (`test:unit`, `lint:tsc`, `lint:eslint`, and `build` where changed). +- **Outer:** the two-tab `yarn dev:brunch` witness above, with retained before/after artifacts, one Voice-origin message, and one durably stopped assistant turn. A content-only transcript match does not establish faithful resume. +- **Semantic:** a cold human accepts fixture/workpiece honesty and the workpiece-to-document correspondence. The oracle may falsify those claims; it may not rewrite the interaction or architecture policy. +- **Product:** a product manager who did not watch the work runs the demo script from the imperative without an engineer and notices the advance. This is the last check before close, after the readiness gate; it is not a substitute for the oracles above. + +## Constraints + +- Keep fixture id, Flue conversation id, latest workpiece source/revision, and Petrinaut document id/revision distinct and explicitly linked. One id must not impersonate all lifecycles. +- Flue history remains the canonical conversation log. Browser message caches and fixture artifacts are projections or evidence, never a second authority. +- Consume Mission 5's browser `FlueClient` plus host-supplied AI SDK `ChatTransport`; typed turns, prepared signals, history hydration, and client-tool results all cross `/agents/chat/:instanceId`. Do not keep, restore, or add another product conversation route. +- The tagged prepared signal is the only test-authored workpiece source admitted by this fixture. It remains a diagnostic system/dispatch record; latest-revision selection may supersede it with a genuine assistant workpiece but may not mutate, relabel, or hide its authorship. +- Markdown remains the semantic workpiece. Recover its full latest version; do not introduce a comprehensive typed domain IR to make fixture lookup convenient. +- Projection consumes the current workpiece. The transcript may establish provenance and help recover that artifact but may not become the primary construction IR. +- Petrinaut owns canonical schemas, browser validation, mutations, and document state. Brunch imports or mechanically derives those contracts and does not hand-copy their field shapes. +- Client tools execute against the active bound browser document and return the original tool-call id. Stale, duplicate, cross-document, malformed, failed, and no-op outcomes fail visibly. +- Advance the runtime settled manifest only after the claimed Flue snapshot, workpiece revision, and document state can all be inspected. It selects the coherent local bundle but does not make the browser and Flue stores transactional. Automatic localStorage mirroring remains the only save behavior; do not invent an explicit Save affordance or cross-store transaction machinery without an observed recovery failure requiring it. +- Preserve the accepted Mission 4 `useBrunchAgent()` plus `useSdcpnPlugin()` architecture. The app composes; the plugin owns SDCPN operation semantics; the transport carries results; the UI executes them. +- Keep construction tools unavailable to unrelated ordinary conversations unless the real path proves the smallest safe selection can be scoped to this fixture/mode. Stock-assistant behavior must remain unchanged when Brunch is absent or unselected. +- The fixture is local and deliberately prepared. Make no remote durability, capture provenance, automatic projection, behavioral execution, or concurrent collaboration claim. +- No HASH Graph, Temporal, Redis, new database, observer, workflow engine, second agent, second event log, or closed workpiece schema. +- Update the affected Petrinaut user guide in the same change if the selector, save/resume behavior, or panel behavior becomes user-facing; add one Petrinaut changeset only if a published Petrinaut package changes. +- Repair typed/Voice provenance and stopped-turn presentation at the canonical history-to-Petrinaut projection boundary; do not add a second transcript store. Account for the observed discoverability strain around **Show transcript**, **Exit voice mode**, and the chat composer's durable **Stop** without conflating local Voice exit with Flue abort. + +## Fog-line + +- Whether the selected shallow `addArc` schema survives the provider-visible Flue carrier and results in exactly one browser mutation without reopening the broader nested-schema problem. +- The least safe way to expose canonical `getLatestNetDefinition` plus `addArc` in a fixture conversation while retaining the headless-only guard for broader construction. +- Whether the latest `runbook-ir` message id and hash are sufficient workpiece revision identity or the two-tab consumer exposes a need for a separate persisted workpiece artifact. +- Whether Mantine/localStorage synchronization plus the active `PetrinautDocHandle` is sufficient for the same-browser two-tab witness, and which document hash/revision signal best distinguishes settled from stale state. +- Whether the known provider-visible nested-schema failure is absent for the selected flat mutation. Do not generalize one success to nested construction classes. +- Which of history recovery, invalid `addArc`, or duplicate result delivery is the cheapest discriminating failure for the settled-witness rule after the first real path reveals the ordering. + +Resolve these at the named production/browser boundaries. Clarifying prose alone does not clear them. If a choice changes the accepted interaction policy, architectural ownership, or proof claim, return it to the owner and amend this authority before implementation continues. + +## Stop or reorient + +Stop and surface evidence if: + +- fixture preparation requires pretending a Mission 4 candidate exists, placing prepared text in a user or assistant record, accepting an untagged preparation signal, or otherwise hiding test-authored/model-authored boundaries; +- the path conflates fixture, conversation, workpiece, and document identities or creates a second canonical conversation history; +- typed traffic, prepared signals, history, or client-tool results cross a product route other than Mission 5's mounted browser Flue route; +- the agent rereads transcript prose as its primary projection input because the current Markdown workpiece cannot carry the needed meaning; +- parser/schema acceptance, document non-emptiness, or a disconnected convenience element is offered as semantic correspondence; +- client-tool results lose their original call id, can target the wrong document, or duplicate execution on retry/reload; +- a partial or failed write advances the runtime settled manifest, second-tab reopening silently selects stale/mismatched artifacts, or Tab B proves only a read without a real continuation; +- exposing one browser mutation requires mounting an unrestricted construction surface for every ordinary conversation; +- the selected provider/Flue schema cannot faithfully carry the least meaningful mutation—record the crisp blocker rather than hand-copying Petrinaut schemas or widening into Mission 9; +- the tracer needs a closed ontology, typed claim ledger, general projection engine, distributed transaction, or new durable service before a concrete failure demonstrates that need; or +- work widens into capture-backed why/provenance, automatic projection breadth, remote deployment durability, concurrent collaboration, or broad scenario readiness. + +## Deferred + +On 2026-09-04 the future planning record was recut around provenance by lineage with declared basis; see the [2026-09-04 migration disposition](../../MISSION.next.md#2026-09-04-provenance-replanning-migration-disposition). Mission 7 now owns construction and explanation of one real net region from a genuine conversation: settled workpiece revisions as `update_workpiece` tool calls, constructor-declared basis on each mutation, verifiable transition records, the why operation with its safety and utility gates, schema-carrier repair, scenario-selected tool admission, and retirement of the orphaned `ask` and `sweep` client handling. Mission 9 owns repeatable projection breadth: unchanged repeat, changed input, retirement, concurrent change, cross-conversation document access, and the schema classes an extended region adds. Two facts from this mission carry into that record and its close report: the prepared fixture's "Current Petrinaut correspondence" section was fixture-authored rather than produced by any skill directive, so this fixture is a viability proof and is not promoted into the provenance pair; and the fenced `runbook-ir` block plus message-id-and-hash selection is a Mission 6 contract that Mission 7 replaces for model-produced revisions, keeping the tagged prepared signal for test-authored material only. This mission's constraint that construction tools stay out of ordinary conversations is amended by the Mission 7 cut, not here. Remote replacement durability and release infrastructure remain in the historical Mission 8 handoff, and a Mission 8 successor must be scheduled before any remote claim. Multi-tab concurrent editing, a durable cross-store commit protocol, explicit localStorage failure injection and refusal of a concurrent write from a tab holding an older revision (distinct from the readiness-gate refusal to reopen onto stale or mismatched artifacts), and promotion of this prepared fixture into a reusable product seed re-enter only if the automatic mirror loses or overwrites state, a later consumer requires atomic bundle identity, or this mission otherwise exposes concrete strain; their current planning home and re-entry conditions remain in [`MISSION.next.md`](../../MISSION.next.md) and the linked Mission 7/9 drafts. diff --git a/libs/@hashintel/brunch-agent/docs/mission-drafts/10-bounded-reviewer-revision.md b/libs/@hashintel/brunch-agent/docs/mission-drafts/10-bounded-reviewer-revision.md index 7c20b04c3a3..058fc424168 100644 --- a/libs/@hashintel/brunch-agent/docs/mission-drafts/10-bounded-reviewer-revision.md +++ b/libs/@hashintel/brunch-agent/docs/mission-drafts/10-bounded-reviewer-revision.md @@ -8,16 +8,17 @@ A fresh builder must read these sources before cutting or implementing this cluster: -- [`MISSION.md`](../../MISSION.md) — closure pointer for Mission 4. Mission 4 produced no full-run workpiece candidate; consume only the source/workpiece pair explicitly selected and promoted by Mission 7 or a predecessor addendum. +- [`MISSION.md`](../../MISSION.md) — the current branch's live authority; it supplies no Mission 10 execution authority or workpiece candidate. Consume only the genuine conversation, settled workpiece revisions, and constructed region accepted by Missions 7 and 9. +- [`7-explainable-construction.md`](7-explainable-construction.md) and [`../evidence/design/provenance-by-lineage-mini-spec-2026-09-04.md`](../evidence/design/provenance-by-lineage-mini-spec-2026-09-04.md) — the 2026-09-04 recut: settled-revision protocol, declared basis, transition records, identity epochs, passage identity policy, document reconciliation, and recorded roles replace the former capture-envelope and derivation-fixture seam this draft once assumed. - [`MISSION.next.md`](../../MISSION.next.md) — compact shared frame, standing locks, and current mission joins. - [`README.md`](README.md) — durable draft authority, lifecycle, conversion, and oracle-gap rules. -- [`docs/mission-archive/2-mechanical-capture-sweep.md`](../mission-archive/2-mechanical-capture-sweep.md) — exact-evidence capture, idempotency, Flue-history authority, and model-free scheduling. +- [`docs/mission-archive/2-mechanical-capture-sweep.md`](../mission-archive/2-mechanical-capture-sweep.md) — exact-evidence capture, idempotency, Flue-history authority, and model-free scheduling. Historical: capture envelopes and sweep semantics are rejected for provenance since 2026-09-04; reviewer evidence is retained as canonical Flue history and cited through the revision-time evidence relation. - [`docs/mission-archive/3-structurally-typed-runbook-to-headless-pn.md`](../mission-archive/3-structurally-typed-runbook-to-headless-pn.md) — accepted workpiece leg and falsified provider-schema construction leg. - [`evaluations/oracles/ir-quality-ruler-v1.md`](../../evaluations/oracles/ir-quality-ruler-v1.md) and [`evaluations/protocols/ir-quality-ruler-v1/cold-ir-reviewer.md`](../../evaluations/protocols/ir-quality-ruler-v1/cold-ir-reviewer.md) — current conservation, grounding, conflict-collapse, and cold-reading criteria; neither is yet a successive-revision oracle. - [`docs/evidence/evaluations/vestera-prospective-baseline-v1/campaign-adjudication.md`](../evidence/evaluations/vestera-prospective-baseline-v1/campaign-adjudication.md) — healthy foreground-turn range, costly whole-workpiece synthesis, and observed correction handling. - [`packages/core/src/prompts/SYSTEM.md`](../../packages/core/src/prompts/SYSTEM.md), [`packages/plugin-sdcpn/src/skills/sdcpn-modelling/SKILL.md`](../../packages/plugin-sdcpn/src/skills/sdcpn-modelling/SKILL.md), and [`packages/plugin-sdcpn/src/skills/sdcpn-modelling/templates/workpiece.md`](../../packages/plugin-sdcpn/src/skills/sdcpn-modelling/templates/workpiece.md) — current foreground lifecycle and workpiece correction behavior. - [`apps/brunch-agent/test/petrinaut-chat.test.ts`](../../../../../apps/brunch-agent/test/petrinaut-chat.test.ts), [`apps/brunch-agent/test/headless-petrinaut-client.test.ts`](../../../../../apps/brunch-agent/test/headless-petrinaut-client.test.ts), and [`packages/plugin-sdcpn/src/tools/petrinaut-construction.ts`](../../packages/plugin-sdcpn/src/tools/petrinaut-construction.ts) — current real door, bounded mutation subset, and its limits. -- [`7-capture-backed-review.md`](7-capture-backed-review.md) and [`9-traceable-projection.md`](9-traceable-projection.md) — provisional inherited artifacts, provenance seam, projection contract, and stable-identity obligations. Re-resolve these joins against accepted close evidence at cut time rather than assuming draft hypotheses landed. +- [`9-traceable-projection.md`](9-traceable-projection.md) — repeat, changed-input, retirement, and impact-boundary semantics this draft inherits. Re-resolve these joins against accepted close evidence at cut time rather than assuming draft hypotheses landed. - Commit `157730cc5a214dd9c543e8d95c7193a219c48aef` on deployment branch `ln/fe-1569-brunch-agent-deployment`, especially `libs/@hashintel/brunch-agent/docs/evidence/implementations/mission-8-deployment-handoff.md` — local application contract and the still-open infrastructure proof that any deployed durability claim must consume. ## Visible product advance @@ -61,14 +62,13 @@ Stale-base revision and legitimate impact widening are cross-class failure/exten ```text scenario declares reviewer authority + selected region + base revisions → reviewer enters the deployed Petrinaut assistant panel -→ AI SDK /api/chat transport resumes the owning Flue conversation +→ host-supplied browser `ChatTransport` over `@flue/sdk` resumes the owning Flue conversation at the mounted route → foreground Brunch agent conducts 3–5 focused operational-language turns -→ Flue history retains the canonical conversation -→ harness-owned mechanical sweep durably captures the settled reviewer range +→ Flue history retains the canonical reviewer turns under the compaction posture Mission 7 established → one bounded foreground phase-boundary synthesis reads: - prior workpiece revision + current derivation/region + newly captured evidence + prior settled workpiece revision + current region lineage (basis, transition records, epochs) + the reviewer's message ids → synthesis classifies correction | qualification | coexistence | conflict | refusal -→ attributed next workpiece revision + semantic diff + impact declaration +→ `update_workpiece` settles the attributed next revision, citing reviewer message ids through the revision-time evidence relation, with semantic diff + impact declaration → authority, base-revision, evidence, and impact gates admit or refuse commit → SDCPN plugin applies the bounded patch through Petrinaut-owned canonical mutations → Petrinaut validates the current net and selected behavior @@ -82,11 +82,11 @@ The foreground phase-boundary synthesis is the default. It is one explicit seman One scenario-declared, consequential operational distinction must cross the real deployed path and produce: - 3–5 focused reviewer turns in operational vocabulary; -- mechanically retained, attributed reviewer evidence; +- reviewer evidence retained as canonical history and cited by message id in the next settled revision; - an inspectable prior/current workpiece pair and semantic diff; - the correct class disposition; -- a bounded patch or explicit refusal; -- updated element → derivation → workpiece revision → original and reviewer evidence provenance; and +- a bounded patch or explicit refusal, every mutation citing the new settled revision with declared basis; +- updated element → basis → settled revision → original and reviewer evidence, with the correction visible in change history and the original in origin; and - unchanged ids and behavior outside the declared impact, except where a visible, justified widening is accepted. The default tracer should be a correction because it proves canonical change. It must be selected so a mistaken overwrite, qualification, coexistence, and conflict treatment would be observably different. One successful correction is only throughline proof and the first internal milestone; it does not close the class stratum and it is not mission completion, which additionally requires the demo's visible refusal or qualification. @@ -97,10 +97,10 @@ The default tracer should be a correction because it proves canonical change. It This cluster may start only after the prior missions have supplied and accepted: -- Mission 7's honest prebuilt pair, durable exact-evidence provenance, broken-link behavior, and element/workpiece/evidence identity seam; -- Mission 9's meaningful automatically projected live region, derivation coverage, canonical provider-visible mutation path, repeated-projection identity behavior, and explicit partial/unsupported failure; -- the current workpiece revision and exact source Flue conversation selected at the prior handoff; -- a deployment boundary that actually persists every state this path consumes across the replacement behavior it claims. +- Mission 7's genuine conversation and constructed region with the settled-revision protocol, declared basis, independently verifiable transition records, identity epochs, passage identity policy, live-document reconciliation, recorded roles, compaction posture, fixture materialization route, and the safety and utility gates for why; +- Mission 9's repeat idempotence, changed-input identity, retirement, concurrent-change refusal, impact-boundary semantics, and explicit partial or unsupported failure; +- the current settled workpiece revision and the exact source Flue conversation selected at the prior handoff; +- a deployment posture named honestly: local unless a Mission 8 successor has landed, with every persisted state this path consumes surviving the replacement behaviour actually claimed. Draft links are not evidence. If Mission 7 or Mission 9 ships a different representation, Mission 10 must consume that actual contract or return here for re-cutting. @@ -126,7 +126,7 @@ Breadth beyond the named classes and accepted scenario portfolio remains unearne ## Candidate evidence and oracles -- `apps/brunch-agent/test/petrinaut-chat.test.ts`, test **“the committed /api/chat door streams a plain Flue agent through server and client tools”**, currently proves the production AI SDK/Flue door, client-tool correlation, history recovery, ownership refusal, exact capture excerpts, idempotent recapture, and absence of sweep/construction tools on the interviewer. It does not prove reviewer revision or deployed infrastructure. +- `apps/brunch-agent/test/petrinaut-chat.test.ts`, test **“the committed /api/chat door streams a plain Flue agent through server and client tools”** (re-expressed by recut Mission 5 through the browser Flue transport at the mounted route; cite its successor), currently proves the production AI SDK/Flue door, client-tool correlation, history recovery, ownership refusal, exact capture excerpts, idempotent recapture, and absence of sweep/construction tools on the interviewer. It does not prove reviewer revision or deployed infrastructure. - `apps/brunch-agent/test/headless-petrinaut-client.test.ts`, tests **“constructs a parser-accepted document through the bounded callbacks”** and **“refuses tools outside the side-quest subset”**, currently prove only the six-tool construct subset and parser acceptance. They are evidence for bounded capability/refusal, not a scoped update patch or semantic fidelity. - `evaluations/oracles/ir-quality-ruler-v1.md` supplies stable `CONFLICT-COLLAPSE`, `CONS-MISS`, `CONS-DISTORT`, `INVENT`, `HARDEN`, `SCOPE`, and `GAP-MISCLASS` judgments. Its own scope excludes successive revision and PN construction, so it may seed but cannot settle the revision claim. - `docs/evidence/evaluations/vestera-prospective-baseline-v1/campaign-adjudication.md` records one correction preserved in a workpiece and healthy ordinary-turn timing. It does not prove authorization, successive revision, or patch locality. @@ -134,19 +134,19 @@ Breadth beyond the named classes and accepted scenario portfolio remains unearne - **ORACLE GAP — successive semantic revision:** no current oracle compares prior workpiece + newly captured evidence against the next revision across all five classes. Before cut, freeze a reviewed fixture set and adjudication rubric that detects lost supported meaning, incorrect authority, unsupported strengthening, conflict collapse, and incorrect disposition. - **ORACLE GAP — patch locality and behavior:** no current oracle proves that a semantic revision changes the intended linked region while preserving unrelated ids and behavior. Before cut, define the selected region, explicit allowed impact set, before/after id inventory, semantic expectations, and—where discriminating—a Petrinaut simulation comparison. - **ORACLE GAP — outer path:** no current test or artifact witnesses the 3–5-turn scenario portfolio through a remotely deployed Petrinaut/Brunch path. Before claiming the visible advance, record a human witness against the accepted deployment, exact scenario/base revisions, transcript, workpiece diff, mutation trace, before/after net, and refusal output. -- **ORACLE GAP — durable capture join:** the deployment handoff explicitly leaves the JSON capture store inactive and non-durable. Before this path consumes capture remotely, Mission 7 or this cut must identify and test the durable implementation across the claimed task-replacement boundary. +- **ORACLE GAP — lineage retention across compaction and replacement:** reviewer evidence lives in canonical Flue history and is cited by message id. Before this path claims retained reviewer evidence, consume Mission 7's compaction-probe result (history read, disclosed uncompacted window, or hardened session-log archive lane) and test it across the replacement boundary actually claimed. ## Verification approach - **Inner mechanism:** deterministic tests for authority checks, base-revision refusal, exact evidence references, semantic-diff representation, class disposition, idempotent commit, impact calculation, and canonical mutation validation. Use the frozen class fixtures and revision oracle; parser success cannot substitute for semantic review. -- **Middle integration/contract:** drive the production `ChatAgent`/AI SDK path from the selected Mission 9 artifact, perform the mechanical settled-range capture and foreground synthesis, apply the patch through the actual browser client-tool callbacks, and compare persisted before/after workpiece, derivation, and net artifacts. Exercise a stale-base attempt and one explicit refusal. +- **Middle integration/contract:** drive the production `ChatAgent` through the Mission 5 browser transport on the accepted Mission 9 conversation, perform the foreground synthesis into a settled `update_workpiece` revision citing reviewer message ids, apply the patch through the actual browser client-tool callbacks with declared basis, and compare persisted before/after workpiece revisions, transition records, epochs, and net definitions. Exercise a stale-base attempt and one explicit refusal. - **Outer deployed/user-visible:** a named human witness performs each accepted peer class through the deployed panel, including the 3–5-turn correction tracer, and verifies visible attribution, semantic diff, changed region, stable unrelated ids/behavior, updated why answer, and comprehensible refusal/failure. The live mission owns this outer proof; it cannot be delegated to Mission 11. ## Inputs and joins -- Upstream source exit: the frozen workpiece, exact source Flue conversation, instrument manifest, and evaluation/adjudication explicitly selected by Mission 7 or a predecessor addendum; Mission 4 itself supplies no full-run candidate. -- Mission 7: prebuilt workpiece/net pair, current workpiece revision and references, capture evidence references, net-element ids, projection rationale, durability disposition, and the why interaction. -- Mission 9: selected meaningful region, canonical mutation surface, derivation records, repeat-projection identity evidence, and accepted unsupported/partial behavior. +- Upstream source exit: the genuine persona or human conversation, its settled workpiece revisions, and the adjudication accepted by Mission 7; Mission 4 itself supplies no full-run candidate and the Mission 6 prepared fixture is not promoted. +- Mission 7: the constructed region, settled revisions, declared basis, transition records, identity epochs, passage policy, reconciliation, recorded roles, and the why operation with its gates. +- Mission 9: the extended region, canonical mutation surface, repeat and changed-input identity evidence, retirement semantics, impact boundary, and accepted unsupported or partial behaviour. - Mission 8: consume the actual application contract—fail-closed Postgres Flue state, verified TLS, IAM/static-password paths, content-free OTel, restricted routes, liveness, singleton ownership policy—but do not imply it is deployed. The infrastructure handoff, real RDS/Anthropic/collector/replacement/rollback proof, and owner acceptance remain required before an outer deployed claim. - Mission 11: receives only an accepted final workpiece/net/evidence/derivation revision package and the six-beat real-path evidence; its consumer contract may not weaken Mission 10's revision-integrity closure. @@ -157,17 +157,17 @@ Breadth beyond the named classes and accepted scenario portfolio remains unearne - **ASSUMPTION:** Mission 9's stable ids and derivation neighborhood are sufficient to calculate a bounded impact. **Impact if false:** local revision can cause unrelated churn or require broader context. **Cheapest validation:** dry-run the selected semantic change against the frozen Mission 9 before/after artifact and enumerate the minimal connected impact. - **RISK:** semantic diff reports textual edits while hiding a changed operational claim. **Impact:** a reviewer cannot understand what changed. **Cheapest validation:** cold human comparison against the class fixture's expected preserved/changed meaning. - **RISK:** compaction removes the recoverable workpiece or evidence needed by synthesis. **Impact:** stale or transcript-dependent revision. **Cheapest validation:** if the real path crosses compaction, reconstruct the same current revision and evidence references after that boundary; otherwise label the limitation and keep it outside the shipped durability claim. -- **RISK:** the capture store remains task-local JSON while the service claims replacement durability. **Impact:** reviewer evidence may disappear after acceptance. **Cheapest validation:** inspect the consumed Mission 7/Mission 8 storage contract before cut and refuse remote revision until capture durability is observed. +- **RISK:** reviewer evidence in canonical history is folded by compaction or lost at replacement while the service claims retained evidence. **Impact:** reviewer evidence may disappear after acceptance. **Cheapest validation:** inspect Mission 7's compaction-probe outcome and the consumed storage contract before cut and refuse the retained-evidence claim until retention is observed at the boundary claimed. ## Accepted constraints and guarded invariants - **STOP-THE-LINE — bounded authority:** canonical state changes only under the scenario's declared reviewer authority. Guard: authority fixture plus allowed/refused outer witness. -- **STOP-THE-LINE — evidence retention:** original and reviewer evidence stay exact, attributed, immutable, and reachable; model prose is never presented as quotation. Guard: capture identity/excerpt assertions and provenance inspection. +- **STOP-THE-LINE — evidence retention:** original and reviewer evidence stay exact, attributed by recorded role, immutable, and reachable by message id; model prose is never presented as quotation. Guard: verbatim-quote verification against canonical history and provenance inspection through the reopened why operation. - **STOP-THE-LINE — no recency overwrite:** prior supported meaning survives unless explicitly corrected, qualified, context-split, or retired under authority. Guard: successive-revision oracle across every accepted class. - **STOP-THE-LINE — patch locality:** unrelated ids and behavior remain stable, and necessary expansion is declared before commit. Guard: before/after id inventory, accepted impact set, and semantic/simulation check where applicable. -- Flue history remains the canonical conversation log; the capture ledger is not a second transcript. -- Mechanical capture remains domain-opaque and harness-owned. The foreground Markdown workpiece owns semantic synthesis. -- The foreground model neither receives nor schedules a sweep tool. Ordinary turns do not block on extraction, fold, completion, or projection. +- Flue history remains the canonical conversation log; no second transcript, capture ledger, or derivation store is admitted. +- The foreground Markdown workpiece owns semantic synthesis; revisions settle only through `update_workpiece`. +- The foreground model receives no sweep or extraction tool. Ordinary turns do not block on fold, completion, or projection. - Petrinaut owns canonical SDCPN schemas and mutations. Brunch imports or mechanically consumes them and does not copy field shapes. - Brunch remains a second assistant; preserve stock-assistant operation and distinct histories. Keep the panel on AI SDK `useChat` / `onToolCall`. - No comprehensive ontology, closed claim kinds, typed completion algebra, generic assertion fold, generalized runtime, TUI, second agent, or second server is earned. @@ -196,7 +196,7 @@ libs/@hashintel/brunch-agent/ └── docs/evidence/evaluations/ + observed revision campaign/adjudication apps/brunch-agent/ ├── src/agents/chat-agent/ ~ compose only accepted capabilities -├── src/capture/ ~ settled-range durable join, not semantic fold +├── src/capture/ - retired unless the compaction probe hardened the session-log archive lane ├── src/conversation/ ? explicit phase-boundary operation if this is the earned home ├── src/http/ ? only if the existing real door needs generic transport support └── test/ ~ production-path revision, refusal, persistence, and locality coverage @@ -218,7 +218,7 @@ No path is permission to edit before the cluster is cut. Prefer existing generic - The smallest linked neighborhood sufficient for synthesis and impact analysis. - What counts as unchanged behavior outside the region and when simulation is a useful discriminator. - How legitimate impact widening is previewed, authorized, and either committed or refused. -- The exact durable storage/transaction boundary across captures, workpiece revision, derivation links, and net commit. +- The exact durable storage and reconciliation boundary across settled workpiece revisions, transition records, epochs, and net commit; Mission 7's operation protocol is the starting point, not a transaction. - Whether the short path crosses Flue compaction; if not, which limitation must remain visible in the handoff. - Whether the chat answer alone makes prior/current meaning and patch impact inspectable or a generic linked detail surface is required. - Exact latency and usage ceilings must come from the accepted scenario and deployment budget, not invention. @@ -242,7 +242,8 @@ No path is permission to edit before the cluster is cut. Prefer existing generic - **Observer/fold rejected by default:** no observer exists on the production path, and the current IR ruler has not tested successive observer revisions. The canonical promotion mechanics and extraction ladder live in [`MISSION.next.md`](../../MISSION.next.md#foreground-revision-and-observer-re-entry). Mission 10 is the decisive strain gate: re-entry is considered only after repeated consequential foreground blocking, loss of prior supported meaning, stale state, unrecoverability, or unavoidable unbounded-history dependence. An admitted observer still may not mutate the net, and its likely short-review barrier is a forced tail sweep/queue flush because the token threshold alone may never fire. - **Recency overwrite rejected:** newer testimony may correct, qualify, coexist with, or conflict with earlier testimony. Time order alone is not authority. - **Append-only journal rejected:** it preserves history but leaves excessive cold-reading and canonical-meaning burden; the observed workpiece intent is a maintained current account with retained revision history. -- **One artifact rejected:** immutable captures and editable semantic workpiece revisions have different lifecycles. +- **One artifact rejected:** immutable conversation evidence and editable semantic workpiece revisions have different lifecycles. +- **Capture envelopes and derivation fixtures rejected for provenance (2026-09-04):** reviewer evidence is canonical history cited by message id through the revision-time evidence relation; element provenance is constructor-declared basis plus recorded transitions. See the [decision log](../evidence/design/provenance-and-tooling-decision-log-2026-09-04.md) entries F5, G3, G7, and G20. - **Deterministic typed fold rejected:** Condition 5's typed mapping plus in-loop model judgment caused minute-scale ordinary turns. Re-entry requires evidence that foreground synthesis cannot reliably preserve or classify meaning and that the narrower mechanism fixes the observed failure. - **Full regeneration rejected as a visible patch claim:** an implementation may reconsider broader context internally only if the applied diff remains bounded and unrelated identities/behavior are proven stable; otherwise it must report widening or refuse. - Mission 3 evidence establishes an accepted, cold-usable workpiece leg and one observed correction, but its construction leg failed 0-for-9 on nested provider-visible shape and produced a vacuous empty net. Mission 9 must retire that risk before this cluster treats patching as available. diff --git a/libs/@hashintel/brunch-agent/docs/mission-drafts/11-optimisation-handoff.md b/libs/@hashintel/brunch-agent/docs/mission-drafts/11-optimisation-handoff.md index f94547cf6bc..62e432f3c19 100644 --- a/libs/@hashintel/brunch-agent/docs/mission-drafts/11-optimisation-handoff.md +++ b/libs/@hashintel/brunch-agent/docs/mission-drafts/11-optimisation-handoff.md @@ -8,7 +8,8 @@ A fresh builder must read these durable sources before deepening this cluster: -- [`../../MISSION.md`](../../MISSION.md) — current closure pointer. Mission 4 is closed; later accepted mission archives and an owner-authorized live cut become inherited authority before this draft can execute. +- [`../../MISSION.md`](../../MISSION.md) — the current branch's live authority. Mission 4 is closed; later accepted mission archives and an owner-authorized Mission 11 cut become inherited authority before this draft can execute. +- [`7-explainable-construction.md`](7-explainable-construction.md) and [`9-traceable-projection.md`](9-traceable-projection.md) — the 2026-09-04 recut predecessors. Mission 11 consumes their genuine conversation, settled revisions, declared basis, transition records, and the why operation; it does not inherit a capture store or derivation fixture, because neither exists. - [`../../MISSION.next.md`](../../MISSION.next.md) and [`README.md`](README.md) — shared frame, standing locks, draft authority, and lifecycle. - [`10-bounded-reviewer-revision.md`](10-bounded-reviewer-revision.md) and the eventual accepted Missions 7, 9, and 10 close evidence — inherited real-path artifacts and proof. Draft promises are not join evidence. - [`../mission-archive/3-structurally-typed-runbook-to-headless-pn.md`](../mission-archive/3-structurally-typed-runbook-to-headless-pn.md) — accepted workpiece leg, falsified real-model construction, and the parser-valid-empty warning. @@ -83,7 +84,7 @@ One selected complete SDCPN and the known semantic artifact floor: - carry the accepted scenario and parameters with honest assumptions, omissions, losses, and limits; and - let them begin the one agreed optimisation experiment at the accepted boundary. -This proves one accepted handoff and is also the completion bar, since the consumer's acceptance is the readiness decision. It does not prove a generic export package, optimizer integration, result model, repeated-experiment protocol, public release, or broad scenario portfolio. +This proves one working handoff throughline. It is not the completion bar. Mission 11 has three distinct gates, corrected on 2026-09-04 after the [follow-up review](../evidence/design/provenance-by-lineage-follow-up-review-2026-09-04.md) item 23: (1) consumer contract acceptance of the six decisions and one fixture, which is the precondition for cutting; (2) the working handoff throughline above, which is the first internal milestone; and (3) post-throughline readiness closure sufficient for Chris and Yannis to begin the agreed experiment without reconstruction, which is completion. Artifact receipt or consumer enthusiasm is not an executable witnessed experiment start. The floor does not prove a generic export package, optimizer integration, result model, repeated-experiment protocol, public release, or broad scenario portfolio. ## Readiness ratchet @@ -91,8 +92,8 @@ This proves one accepted handoff and is also the completion bar, since the consu Mission 11 consumes rather than repairs: -- Mission 7's durable capture-backed provenance and visible why behavior; -- Mission 9's meaningful automatic projection, stable identities/derivations, and closed projection stratum for the selected region; +- Mission 7's genuine constructed region with settled revisions, declared basis, verifiable transition records, identity epochs, and the why operation past its safety and utility gates; +- Mission 9's repeat, changed-input, and retirement behaviour and closed breadth stratum for the extended region; - Mission 10's accepted reviewer-authority classes, retained evidence, semantic revision, scoped patch/refusal, and stable unrelated behavior; and - an actual deployment threshold sufficient for the consumers to use the path, with each claimed identity, durability, telemetry, access, and recovery property observed rather than inferred from the local image. @@ -100,9 +101,9 @@ If inherited closure is missing, return the defect to its owning mission. Missio ### Readiness gate after the new throughline -The lateral obligations are intentionally not enumerated beyond the six consumer decisions. Once the first accepted handoff works, enumerate only the package, transfer, execution, result, credibility, repeatability, access, or retention obligations that the actual boundary exposes. Close those required to trust and begin the selected experiment. Carry broader obligations only with a named successor, re-entry gate, and oracle. +The lateral obligations are intentionally not enumerated beyond the six consumer decisions. Once the handoff throughline works, enumerate the package, transfer, execution, result, credibility, repeatability, access, and retention obligations that the actual boundary exposes, and close those required for the consumers to begin the selected experiment without reconstruction. That closure is gate three and the completion bar; the throughline alone is not. Carry broader obligations only with a named successor, re-entry gate, and oracle. -Until consumer acceptance, any more detailed readiness list would plan past the fog-line. +Until consumer acceptance, any more detailed readiness list would plan past the fog-line. Lightweight, non-binding consumer discovery is nevertheless owed earlier, per the 2026-09-04 dispositions (decision log F15): before Mission 9 selects its extended region, record with Chris and Yannis one candidate optimisation question, the minimum scenario and parameter semantics it needs, the expected execution boundary, required outputs, and minimum credibility checks, so the proving cases exercise semantics the consumers will actually need and so file-level provenance can be judged load-bearing or not before Mission 11. Discovery informs selection; it does not authorize implementation here. ## Candidate evidence and oracles @@ -121,8 +122,9 @@ Until consumer acceptance, any more detailed readiness list would plan past the ## Inputs and joins -- Selected upstream source: frozen workpiece, exact source Flue conversation, instrument manifest, and adjudication chosen by Mission 7 or a predecessor addendum; Mission 4 itself closed without a full-run candidate. -- Missions 7, 9, and 10: accepted bounded workpiece/net/evidence/derivation chain, revision and patch-locality evidence, and the witnessed real path Mission 11 must broaden. +- Selected upstream source: the genuine conversation, settled workpiece revisions, and adjudication accepted by Mission 7; Mission 4 itself closed without a full-run candidate and the Mission 6 prepared fixture is not promoted. +- Missions 7, 9, and 10: accepted conversation, settled revisions, declared basis, transition records, identity epochs, repeat and change behaviour, revision and patch-locality evidence, and the witnessed real path Mission 11 must broaden. +- Early consumer discovery: the non-binding record of one candidate question, minimum semantics, execution boundary, outputs, and credibility checks gathered before Mission 9's region selection. - Mission 8 actual contract: locally verified application artifact plus still-open infrastructure handoff; no remote deployment is assumed. - Chris/Yannis: written acceptance of the six consumer decisions and one fixture. - Petrinaut: current serialization, scenario, optimization, and host capabilities are inspected as existing terrain and used only where the consumer contract accepts them. diff --git a/libs/@hashintel/brunch-agent/docs/mission-drafts/5-direct-voice-flue-transport.md b/libs/@hashintel/brunch-agent/docs/mission-drafts/5-direct-voice-flue-transport.md deleted file mode 100644 index 35e5ba40d2c..00000000000 --- a/libs/@hashintel/brunch-agent/docs/mission-drafts/5-direct-voice-flue-transport.md +++ /dev/null @@ -1,129 +0,0 @@ -# Draft Mission 5 — Direct Voice over canonical Flue transport - -> Draft cluster only. Not execution authority. Do not implement until this cluster is re-evaluated and cut into `MISSION.md`. - -## Cold-start reads - -- [FE-1574](https://linear.app/hash/issue/FE-1574/let-voice-speak-through-canonical-brunch-conversations) — tracker projection for this future branch mission; the eventual branch `MISSION.md` remains execution authority. -- [`../../MISSION.md`](../../MISSION.md) — Mission 4 closure pointer; no live Brunch mission exists. -- [`../../MISSION.next.md`](../../MISSION.next.md) — shared contracts, parallel-track rules, and current sequencing. -- [`../evidence/implementations/mission-4-voice-integration-handoff.md`](../evidence/implementations/mission-4-voice-integration-handoff.md) — observed Voice stack, conflict surfaces, and the package-composition invariant. -- [`../../packages/core/src/flue.ts`](../../packages/core/src/flue.ts) and [`../../../../../apps/brunch-agent/src/app.ts`](../../../../../apps/brunch-agent/src/app.ts) — accepted `useBrunchAgent()` + `useSdcpnPlugin()` agent composition and mounted Flue route. -- [`../../../../../apps/brunch-agent/src/http/petrinaut-chat.ts`](../../../../../apps/brunch-agent/src/http/petrinaut-chat.ts), [`../../../../../apps/brunch-agent/src/conversation/ui-stream.ts`](../../../../../apps/brunch-agent/src/conversation/ui-stream.ts), and [`../../packages/transport-aisdk/src/index.ts`](../../packages/transport-aisdk/src/index.ts) — current AI SDK adapter and Flue-to-UI projection; these are terrain, not a required Voice path. -- Flue [`FlueClient`](https://flueframework.com/docs/sdk/flue-client/) and React client documentation — supported `send`, `read`, `observe`, `history`, `abort`, offsets, submission correlation, and conversation incarnation semantics. -- Voice PRs #9496, #9507, and #9512 at their current accepted tips; do not reconstruct their behavior from this draft. - -## Visible product advance - -A person speaks one finalized answer in the Voice surface and hears the canonical Brunch reply begin through TTS while the same answer and reply appear exactly once in the owning Flue conversation. Voice connects through Flue's supported conversation protocol rather than submitting through the Petrinaut AI SDK chat composer, and no secondary model rewrites Brunch's reply before speech. - -The existing Petrinaut AI assistant may remain temporarily present during integration, but it is not the conversation authority or required transport for this proof. Removal of obsolete assistant UI and deletion of `transport-aisdk` are consequences only after dependency inspection proves they have no surviving consumer. - -## Contract stratum - -Close the **one-turn direct Voice/Flue transport stratum** for finalized input, streamed canonical output, cancellation, and conversation resumption. - -The accepted objects are one stable logical conversation id, one admitted submission id, one finalized user message, one canonical assistant response, and one Voice playback lifecycle. `conversationId` is the durable logical reference; `submissionId` correlates one admitted turn and supports reattachment; stream offsets are opaque Flue cursors; `uid` identifies one current Flue incarnation and must not become the durable demo/session id. - -## Boundary crossings and current throughline hypothesis - -```text -microphone → provisional STT (ephemeral) -→ one finalized transcript -→ supported FlueClient send to the owning Brunch conversation -→ accepted useBrunchAgent() + useSdcpnPlugin() composition -→ canonical Flue response chunks and settlement -→ exact canonical text projected to Voice -→ ordinary TTS playback -→ history/observe rehydration of the same conversation after reopen -``` - -Authentication, principal ownership, CORS or a same-origin protocol-preserving proxy remain host obligations. “Direct Flue” means use of `@flue/sdk`/`@flue/react`, not handwritten SSE parsing or an unauthenticated public agent route. - -## Throughline proof floor - -From the real Voice surface, one finalized spoken answer produces exactly one visible user message in canonical Flue history; one canonical Brunch response streams to both visible text and TTS without a generative simplification pass; interruption stops local playback and the selected durable abort action has its documented effect; reopening the conversation reconstructs the same settled turn without duplicate submission or playback. - -The retained proof artifact is the canonical Flue snapshot plus the Voice event ledger for STT finalization, admission/submission id, text/TTS projection, cancellation, settlement, and reopen. This does not prove client-side Petrinaut mutations, workpiece viability, broad Voice UX, remote deployment, or that the AI SDK adapter is removable. - -## Readiness ratchet - -### Inherited stratum closure - -- Preserve Mission 4 package composition; never restore the deleted app-local stub `ChatAgent` to resolve Voice conflicts. -- Preserve canonical Flue history as the sole conversation authority and exact finalized-answer correlation from the Voice work. -- Preserve principal/ownership semantics even if the AI SDK adapter is bypassed. - -### Readiness gate after the new throughline - -Before this one-turn capability is accepted, close provisional-versus-final transcript deduplication, submission correlation, replay/reopen behavior, TTS cancellation, durable abort races, visible failed/aborted settlement, authentication/origin handling at the claimed host boundary, and exact canonical spoken/visible correspondence. Carry only broader speech ergonomics, multi-turn barge-in tuning, and obsolete-adapter/UI deletion, each after observed strain or dependency proof. - -## Candidate evidence and oracles - -| Claim leaf | Candidate oracle | -| --- | --- | -| Finalized speech enters one canonical conversation once | Snapshot inspection shows one user message with the expected text and one admission/submission id; provisional STT never appears in history. | -| Voice bypasses AI SDK UI-message transport | Network/source inspection shows the supported Flue conversation protocol and no Voice request to the AI SDK chat route. | -| Spoken output is canonical | Captured TTS input equals the canonical response text selected by the documented deterministic policy; no secondary generation call occurs. | -| Cancellation and abort remain distinct | Voice event ledger plus Flue settlement/history distinguish local playback cancellation, local observation cancellation, and durable conversation abort. | -| Reopen resumes rather than duplicates | A second surface rehydrates the same conversation and settled submission from `history()`/`observe()` without a new user message or automatic replay. | -| Accepted agent architecture survives reconciliation | Composition/dependency test and code inspection retain `useBrunchAgent()` + `useSdcpnPlugin()` and exclude the older stub agent. | - -## Verification approach - -- **Inner:** deterministic tests for finalized-transcript deduplication, canonical text selection, TTS cancellation, submission correlation, and rehydration. -- **Middle:** run the real Brunch agent behind Flue and drive one Voice turn through `send` plus `observe` or `read`, retaining canonical history and the Voice ledger. -- **Outer:** a human speaks, hears the response begin, interrupts once, reopens the same conversation, and confirms visible/spoken/history agreement. Browser-only mocks or a server-only Flue call do not establish the Voice advance. - -## Inputs and joins - -- This mission may cut from Mission 4 independently of the fixture/workpiece mission; neither mission is a prerequisite for the other's first tracer. -- The Voice branch supplies STT, TTS, playback, and answer-correlation behavior. Mission 4 supplies the current Brunch composition and canonical conversation runtime. -- A later integration mission may reuse this direct client to service Petrinaut client tools, but this mission does not need tool mutation to prove transport. - -## Risks and assumptions - -- If canonical Mission 4 replies remain too long for speech, first try deterministic question-focused presentation or Brunch-owned spoken-mode instruction; re-admit secondary generative preparation only after measured failure and with visible canonical/spoken distinction. -- If browser-to-Flue auth/CORS cannot be made safe directly, use the thinnest same-origin proxy that preserves Flue semantics rather than translating into AI SDK messages. -- If `transport-aisdk` or the existing assistant UI has another live consumer, retain it; this mission establishes that Voice does not require it, not that the repository does not. - -## Accepted constraints and guarded invariants - -- One canonical Flue history; no Voice-side transcript authority. -- One finalized answer submission; provisional speech remains ephemeral. -- No lossy generative simplification in the tracer. -- Voice owns audio interaction and playback; Brunch owns canonical response content. -- Use supported Flue client APIs; do not hand-roll offset, retry, or stream reduction. -- Preserve ownership/authentication and make failures visible. -- Do not restore the old app-local Brunch agent or splice Voice into the stock assistant's history. - -## Cross-cutting obligations - -Record latency to admission, first canonical text, first audio, and settlement; distinguish local cancellation from durable abort; keep content out of ordinary telemetry; and update Voice/Petrinaut user documentation if the visible interaction or assistant surface changes. - -## Expected touched paths - -```text -Voice-stack application paths ~ direct Flue client host, STT/TTS projection, cancellation -apps/brunch-agent/src/app.ts ? protocol/auth mounting only if the existing route is insufficient -apps/brunch-agent/src/agents/chat-agent/ ~ preserve current package composition during reconciliation -apps/brunch-agent/src/conversation/ ? only shared identity/tool-result mechanics actually reused -libs/@hashintel/brunch-agent/packages/transport-aisdk/ ? retain or remove only after consumer inspection -libs/@hashintel/petrinaut/src/ui/ ? remove/replace obsolete assistant surface only if separately admitted -``` - -## Fog-line - -- The exact Voice-stack source after its PRs settle and the selected integration order. -- Whether `FlueClient.read` or a maintained `observe({ live: "sse" })` store best fits the existing Voice state machine. -- The authenticated production URL/proxy and origin policy. -- The deterministic policy for which canonical text is spoken if a response contains multiple text blocks or interactive tool parts. -- Whether any non-Voice consumer still needs `transport-aisdk` or the current assistant UI. - -## Stop or reorient - -Stop if integration creates a second conversation authority, submits provisional STT, rewrites canonical output through another model without an observed need, restores the old stub agent, exposes an unauthenticated Flue route, hand-rolls stream recovery, or claims adapter/UI removal before consumer inspection. Stop at a crisp host/auth blocker rather than rebuilding the AI SDK adapter under a new name. - -## Carried evidence and rejected alternatives - -The existing AI SDK transport remains a valid adapter for an AI SDK chat consumer; it is rejected only as an inherent Voice dependency. The older Voice simplifier was a workaround for pre-Mission-4 response shape, not permanent authority. Direct Flue preserves durable submission correlation, history, observation, and abort semantics while avoiding a second projection protocol. diff --git a/libs/@hashintel/brunch-agent/docs/mission-drafts/6-resumable-workpiece-petrinaut-fixture.md b/libs/@hashintel/brunch-agent/docs/mission-drafts/6-resumable-workpiece-petrinaut-fixture.md deleted file mode 100644 index 26a3163fc76..00000000000 --- a/libs/@hashintel/brunch-agent/docs/mission-drafts/6-resumable-workpiece-petrinaut-fixture.md +++ /dev/null @@ -1,164 +0,0 @@ -# Draft Mission 6 — Resumable workpiece-to-Petrinaut fixture tracer - -> Draft cluster only. Not execution authority. Do not implement until this cluster is re-evaluated and cut into `MISSION.md`. - -## Cold-start reads - -- [FE-1575](https://linear.app/hash/issue/FE-1575/resume-one-brunch-workpiece-and-petrinaut-document-across-tabs) — tracker projection for this future branch mission; the eventual branch `MISSION.md` remains execution authority. -- [`../../MISSION.md`](../../MISSION.md) — Mission 4 closure pointer and explicit absence of a full-run candidate. -- [`../../MISSION.next.md`](../../MISSION.next.md) — shared workpiece, projection, evidence, and product constraints. -- [`../mission-archive/3-structurally-typed-runbook-to-headless-pn.md`](../mission-archive/3-structurally-typed-runbook-to-headless-pn.md) and [`../evidence/implementations/fe-1525-headless-runbook-pn.md`](../evidence/implementations/fe-1525-headless-runbook-pn.md) — accepted workpiece viability, hermetic callback route, and failed real-model nested-schema carrier. -- [`../mission-archive/4-core-plugin-elicitation-proof-of-life.md`](../mission-archive/4-core-plugin-elicitation-proof-of-life.md) — accepted core/plugin architecture and exact proof exclusions. -- [`../../packages/plugin-sdcpn/src/flue.ts`](../../packages/plugin-sdcpn/src/flue.ts), [`../../packages/plugin-sdcpn/src/tools/petrinaut-construction.ts`](../../packages/plugin-sdcpn/src/tools/petrinaut-construction.ts), and Petrinaut's canonical AI/action schemas — current read and bounded construction capabilities. -- [`../../../../../apps/brunch-agent/src/conversation/client-tools.ts`](../../../../../apps/brunch-agent/src/conversation/client-tools.ts), [`../../../../../apps/brunch-agent/src/conversation/ui-stream.ts`](../../../../../apps/brunch-agent/src/conversation/ui-stream.ts), and the current browser host — existing client-tool carriage and result correlation; reuse semantics without requiring the old chat UI. -- Flue `FlueClient` documentation for stable conversation history, observation, submission reattachment, and tool-part materialization. - -## Visible product advance - -**Release note:** Brunch edits the Petrinaut net you are looking at from the conversation, and your work survives closing the tab. - -**Demo script (no engineer present):** open the stable demo fixture; the canonical Brunch conversation, current Markdown workpiece, and associated Petrinaut document come back together. Tell Brunch one new realistic thing about the process. Watch the workpiece update and a meaningful change appear in the live net. Save. Open the same fixture in a second tab and continue the conversation from the saved state. - -**Previously impossible:** Brunch only produced off-canvas net JSON for manual load; nothing it did touched the live document or survived a reload. - -The fixture may be deliberately prepared. It need not be a complete persona-produced Mission 4 artifact, a promoted quality baseline, or proof of comprehensive provenance. Prepared status, authored material, limitations, and any model-produced updates remain explicit, and the demo script says so out loud. - -**Completion:** the mission is done when a product manager can run the demo script end to end at the readiness gate below, not when the first browser mutation lands. - -## Contract stratum - -Close the **single-fixture viability stratum** for these two transformations and their resumable product boundary: - -```text -canonical conversation evidence → maintained Markdown workpiece -maintained Markdown workpiece → meaningful Petrinaut read/write change -``` - -The fixture has separate stable identities for the demo case, conversation, current workpiece revision, and Petrinaut document revision. One id must not impersonate all four lifecycles. A small manifest records their relationships, exact prepared inputs, current coherent bundle revision, and hashes or revision tokens needed to detect stale state. - -The minimum fixture contains one process spine, one shared or constrained resource, one decision/policy, one contextual quantity, one explicit unknown, and enough meaning to change a small non-empty net region. It does not require a comprehensive typed domain IR, assertion-card ontology, graph database, or full provenance ledger. - -## Boundary crossings and current throughline hypothesis - -```text -stable demo fixture id -→ resolve conversation id + workpiece revision + Petrinaut document id/revision -→ hydrate canonical Flue history and current Markdown workpiece -→ one realistic evidence turn updates the workpiece at an explicit phase boundary -→ Brunch reads current Petrinaut state through a browser-owned client tool -→ SDCPN skill interprets the current workpiece, not the transcript as projection IR -→ Brunch requests the least canonical Petrinaut mutation(s) -→ browser validates and executes against the bound document -→ correlated client-tool result resumes the same Flue conversation -→ verify meaningful non-empty state -→ publish a new coherent fixture revision only after workpiece and document saves succeed -→ second tab resolves and resumes that revision -``` - -A partial save remains visible and does not advance the fixture's current coherent revision. The first tracer does not require simultaneous multi-tab collaboration or a distributed transaction service. - -## Throughline proof floor - -For one deliberately prepared fixture: - -1. a cold reader can reconstruct the selected operational spine and distinguish supplied evidence, agent inference/assumption, and the explicit unknown in the current Markdown workpiece; -2. one new realistic conversation turn produces an inspectable workpiece revision without erasing the unknown or unsupported meaning; -3. through the real browser client-tool boundary, Brunch reads the associated Petrinaut document and applies one meaningful supported change derived from the current workpiece; -4. canonical Petrinaut state is non-empty and visibly corresponds to the selected meaning; and -5. after save, a second tab opens the same fixture id, observes the same settled conversation/workpiece/document revision, and successfully continues or reads it without duplicate submission or identity drift. - -One pass through those five steps is the first internal milestone, not mission completion. The retained oracles are the stable demo URL or fixture selector plus the before/after fixture manifest, exact Flue snapshot, Markdown workpiece revisions, and canonical Petrinaut document revisions; they are evidence for the builder, not the visible advance. This proves viability, not automatic full-net projection, selected-pair provenance breadth, remote replacement durability, concurrent editing, or Mission 3/4 quality superiority. - -## Readiness ratchet - -### Inherited stratum closure - -- Consume Mission 4's accepted `useBrunchAgent()` + `useSdcpnPlugin()` architecture and no broader quality claim. -- Consume Petrinaut-owned schemas/mutations mechanically; parser acceptance alone remains vacuous. -- Treat Flue history as canonical and client-tool results as correlated execution evidence. -- Preserve the Mission 3 failure: provider-visible nested mutation shapes are unproved and may force a smaller first mutation or a crisp upstream blocker. - -### Readiness gate after the new throughline - -This gate is the mission's completion bar: the demo script above must work for the named fixture. Before accepting this single-fixture capability, close stale fixture/workpiece/document revision refusal, duplicate tool delivery, read/write failure visibility, unsupported meaning, no-op mutation honesty, partial-save behavior, second-tab rehydration, separate identity integrity, and one negative mutation case. Do not close every consequential-element provenance link, remote task replacement, broad scenario coverage, or repeated automatic projection here; those become Mission 7 or Mission 9 obligations only after this tracer exposes a finite peer set and load-bearing seams. - -## Candidate evidence and oracles - -| Claim leaf | Candidate oracle | -| --- | --- | -| Prepared fixture is honest and minimally sufficient | Frozen manifest plus cold-reader adjudication identifies the spine, resource, policy, quantity, unknown, authorship, and preparation route. | -| Conversation evidence can maintain Markdown | Before/after workpiece inspection against the exact Flue snapshot detects invention, hardening, lost prior meaning, and lost unknowns. | -| Browser executes real Petrinaut read/write tools | Production-boundary integration records tool call ids, canonical parsed inputs, execution outcomes, correlated result signals, and current document state. | -| Change is meaningful | Human comparison binds one workpiece meaning to a visible canonical type/parameter/place/transition/arc change appropriate to the fixture; non-empty/parser-valid alone fails. | -| Save is coherent | Injected workpiece-save or document-save failure leaves the prior current bundle revision selected and exposes the partial result for recovery. | -| Second tab resumes stable state | Open the same stable fixture selector after save and compare conversation id/history, workpiece revision/hash, document id/revision, and canonical definition before continuing. | -| No typed domain IR was smuggled in | Public-schema and dependency inspection finds only fixture identity/revision links and canonical Petrinaut payloads, not a closed process ontology or typed capture-to-workpiece model. | - -## Verification approach - -- **Inner:** fixture-manifest parse/version/stale checks, explicit identity separation, coherent-revision publication, idempotent client-tool result handling, and canonical Petrinaut mutation tests. -- **Middle:** drive the production Brunch agent through Flue, update the Markdown artifact, execute actual browser callbacks against the fixture-bound Petrinaut instance, and retain before/after artifacts plus one injected failure. -- **Outer:** from the real demo route or equivalent product selector, perform the update/save in Tab A and reopen/continue from the same fixture in Tab B. A headless callback alone does not establish this mission. -- **Semantic:** a cold human judges whether the workpiece remained honest and the changed net region corresponds to it. - -## Inputs and joins - -- This mission may cut directly from Mission 4 and run independently of the direct Voice mission. Typed text is sufficient for its first tracer; Voice can later become another input modality to the same canonical conversation. -- An owner selects one deliberately prepared fixture and records its non-claims. No full Mission 4 candidate or new persona campaign is prerequisite. -- Mission 7 inherits this fixture only if it needs to close capture-backed why/provenance breadth. Mission 9 inherits the browser mutation and semantic-projection seam only if the tracer proves them viable. -- Mission 8's local deployment artifact is terrain, not a prerequisite for a local two-tab viability proof and not evidence of remote durability. - -## Risks and assumptions - -- If a realistic prepared conversation/workpiece cannot support one meaningful mutation without richer typed structure, record the exact lookup, identity, or ambiguity strain before adding any schema. -- If existing per-action provider schemas cannot carry the required nested mutation, reduce to the smallest meaningful supported action only if semantic correspondence survives; otherwise stop with the crisp provider/Flue schema blocker. -- If coherent save cannot span existing workpiece/document stores, the least fixture-scoped commit marker may publish only after both writes; do not invent distributed transactions before a failure demonstrates the need. -- If direct browser tool servicing needs a transport abstraction, extract only tool-call/result correlation from the existing AI SDK adapter; do not require the chat UI or duplicate Flue observation. - -## Accepted constraints and guarded invariants - -- Separate demo, conversation, workpiece, and document identities with explicit links. -- One canonical Flue history; fixture log projections do not become another authority. -- Markdown is the semantic workpiece; no comprehensive typed domain IR. -- Projection consumes the current workpiece, not the transcript as primary IR. -- Petrinaut owns canonical schemas and mutation execution. -- Client tools execute in the browser against the bound document and return the original tool call id. -- Current coherent revision advances only after all required saves succeed. -- Prepared fixture status and unsupported meaning remain visible. -- No claim of remote replacement durability, automatic full projection, provenance breadth, or concurrent collaboration. - -## Cross-cutting obligations - -Preserve exact evidence attribution, visible failure, stable identity, workpiece sufficiency, semantic correspondence, stock-assistant isolation if it remains present, and same-change user documentation for the demo selector/save/resume behavior. - -## Expected touched paths - -```text -libs/@hashintel/brunch-agent/ -├── evaluations or docs/evidence fixture area + one prepared fixture and adjudication -├── packages/core/ ? only minimal workpiece/fixture contracts with a real second consumer -└── packages/plugin-sdcpn/ ~ least read/write capability and guidance needed by the tracer -apps/brunch-agent/ -├── src/agents/chat-agent/ ~ mount accepted fixture read/write path -├── src/conversation/ ~ client-tool correlation without UI-message authority -└── test/ + real Flue/browser-tool integration -libs/@hashintel/petrinaut-core/ ~ canonical contracts only if a source defect is found -libs/@hashintel/petrinaut/src/ ~ stable fixture resolution, save/resume, browser tool execution -``` - -## Fog-line - -- The exact prepared scenario and smallest meaningful document mutation. -- Where the fixture manifest and current coherent-revision marker belong. -- The current Petrinaut document persistence/revision API and whether the demo route already has a stable selector. -- Whether workpiece Markdown is a file, Flue data part, or product document for this tracer; choose the least real persistence boundary that supports two-tab reopen. -- The least browser host for direct Flue client-tool servicing after removal or bypass of the old assistant UI. -- The exact negative save/mutation case and acceptable local-only durability claim. - -## Stop or reorient - -Stop if the tracer requires pretending a Mission 4 candidate exists, makes a prepared fixture look model-produced, conflates all ids, treats parser validity as meaning, submits client-tool results without original correlation, advances the current bundle after a partial save, uses transcript text as the projection IR, or introduces a closed domain ontology before observed strain. Stop at provider-schema or host-persistence blockers rather than widening into Mission 7/9 readiness work. - -## Carried evidence and rejected alternatives - -Mission 3 showed that a Markdown workpiece can be useful and that a hermetic callback can build canonical non-empty state, while falsifying the exercised real-model nested-schema carrier. Mission 4 established capability composition but produced no full-run candidate. This mission intentionally joins those facts with a prepared fixture to test viability before requiring promoted-source quality, complete provenance, or a generalized semantic model. diff --git a/libs/@hashintel/brunch-agent/docs/mission-drafts/7-capture-backed-review.md b/libs/@hashintel/brunch-agent/docs/mission-drafts/7-capture-backed-review.md deleted file mode 100644 index 8d930f60581..00000000000 --- a/libs/@hashintel/brunch-agent/docs/mission-drafts/7-capture-backed-review.md +++ /dev/null @@ -1,294 +0,0 @@ -# Draft Mission 7 — Capture-backed review of an honest prebuilt pair - -> Draft cluster only. Not execution authority. Do not implement until this cluster is re-evaluated and cut into `MISSION.md`. - -## Cold-start reads - -- [FE-1573](https://linear.app/hash/issue/FE-1573/explain-one-prepared-petrinaut-net-from-exact-conversation-evidence) — tracker projection for this future branch mission; it advances stakeholder outcome [FE-1478](https://linear.app/hash/issue/FE-1478/provide-provenance-from-a-generated-net-back-to-the-requirements-graph) without rewriting that record. - -A fresh builder must resolve the current repository and the deployment handoff rather than treating this draft as a specification: - -- [`../../MISSION.md`](../../MISSION.md) — closure pointer; Mission 4 produced no full-run conversation/workpiece candidate and this draft must not imply otherwise. -- [`6-resumable-workpiece-petrinaut-fixture.md`](6-resumable-workpiece-petrinaut-fixture.md) — independent viability predecessor. If accepted, its deliberately prepared and honestly labelled fixture may become this mission's selected pair after a separate provenance-suitability decision; a complete persona workpiece is not intrinsically required. -- [`../../MISSION.next.md`](../../MISSION.next.md) — compact future spine, FE-1476 product frame, shared proof obligations, standing locks, and any later evidence admitted after this draft was written. -- [`../mission-archive/2-mechanical-capture-sweep.md`](../mission-archive/2-mechanical-capture-sweep.md) — accepted mechanical capture throughline, exact close evidence, empty-payload boundary, conversation identity, and carried flags. -- [`../mission-archive/3-structurally-typed-runbook-to-headless-pn.md`](../mission-archive/3-structurally-typed-runbook-to-headless-pn.md) and [`../evidence/implementations/fe-1525-headless-runbook-pn.md`](../evidence/implementations/fe-1525-headless-runbook-pn.md) — accepted runbook/workpiece leg, falsified real-model construction leg, and the distinction between a hermetic non-empty fixture and vacuous empty-net parser success. -- [`../evidence/evaluations/vestera-prospective-baseline-v1/campaign-adjudication.md`](../evidence/evaluations/vestera-prospective-baseline-v1/campaign-adjudication.md) — frozen Mission 3 control and cold-reader evidence; do not substitute current source for its instrument revision. -- [`apps/brunch-agent/test/petrinaut-chat.test.ts`](../../../../../apps/brunch-agent/test/petrinaut-chat.test.ts), [`apps/brunch-agent/test/petrinaut-chat.integration.ts`](../../../../../apps/brunch-agent/test/petrinaut-chat.integration.ts), and [`apps/brunch-agent/src/capture/apply-sweep.ts`](../../../../../apps/brunch-agent/src/capture/apply-sweep.ts) — current production chat door and explicit harness-owned sweep. -- [`../../packages/core/src/evidence/capture-store.ts`](../../packages/core/src/evidence/capture-store.ts), [`../../packages/core/test/capture-store.test.ts`](../../packages/core/test/capture-store.test.ts), [`../../packages/binding-flue/src/local-capture-store.ts`](../../packages/binding-flue/src/local-capture-store.ts), and [`../../packages/binding-flue/test/local-capture-store.test.ts`](../../packages/binding-flue/test/local-capture-store.test.ts) — capture envelope, archived evidence, ownership, atomicity, parse, and local durability contracts. Their richer historical types are not permission to expose a typed capture ontology in this mission. -- [`apps/brunch-agent/src/http/petrinaut-chat.ts`](../../../../../apps/brunch-agent/src/http/petrinaut-chat.ts), [`apps/brunch-agent/src/conversation/client-tools.ts`](../../../../../apps/brunch-agent/src/conversation/client-tools.ts), and [`../../../petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.tsx`](../../../petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.tsx) — AI SDK transport, Flue client-tool suspension/resume, and the existing `useChat` / `onToolCall` browser execution boundary. -- Commit `157730cc5a214dd9c543e8d95c7193a219c48aef` on deployment branch `ln/fe-1569-brunch-agent-deployment`, read with `git show`, especially `libs/@hashintel/brunch-agent/docs/evidence/implementations/mission-8-deployment-handoff.md`, plus its `MISSION.md`, `MISSION.next.md`, Mission 4 archive, and archive README. That commit proves a local application artifact and stops at the application-to-infrastructure handoff; it does not prove remote deployment. -- On that branch, inspect `apps/brunch-agent/src/db.ts`, `src/postgres.ts`, `src/database-config.ts`, `test/postgres.test.ts`, `test/database-config.test.ts`, and `test/container-smoke.integration.ts`. Mission 7 activates capture as product data and therefore must use a durable implementation at the claimed replacement boundary; task-local JSON is not an admissible deployed capture store. -- [`../../../petrinaut/docs/ai-assistant.md`](../../../petrinaut/docs/ai-assistant.md) and the other Petrinaut user-guide pages that mention the affected panel flow. Any user-visible change requires same-change documentation and a prompt to replace screenshots if they become stale. - -Mission 4 closed without admitting its full run and therefore retained no source conversation/workpiece handoff candidate. Mission 6 may establish an honestly prepared conversation/workpiece/document fixture without changing that fact. Mission 7 must select either that accepted prepared fixture, another explicitly eligible retained source, or a newly authorized run, then record why it is sufficient for the narrower capture-backed provenance claim. Selection is not retrospective persona acceptance or a general quality claim. - -## Visible product advance - -**Release note:** ask Brunch why any element in the demo net exists and get back what the expert actually said. - -**Demo script (no engineer present):** open the honestly prebuilt demo net in the Petrinaut Brunch panel, on the deployment posture named at cut time (a locally run panel is acceptable; remote durability stays in the readiness gate). Pick any consequential element and type its visible name or id. Read the current workpiece passage that supports it, the prebuilder's rationale including any assumption, default, omission, or loss, and the exact quoted excerpts from the source conversation. Pick the element the demo marks as unsupported and watch Brunch decline rather than improvise. - -**Previously impossible:** nothing connected a net element to the conversation evidence behind it; a reviewer had to trust the modeller. - -Each answer contains: - -1. the current selected Markdown workpiece passage that supports the modelled meaning; -2. the prebuilder's explicit projection rationale, including consequential assumption, uncertainty, omission, default, or representational loss; and -3. exact mechanically retained excerpts from the source Flue conversation. - -The response visibly identifies both the workpiece and SDCPN as prebuilt. It makes no claim that Brunch automatically projected the net, inferred a complete provenance graph, or observed and consolidated the conversation in the background. A deliberately broken provenance link returns a visible unsupported/unavailable result rather than a plausible reconstructed explanation. - -This is FE-1476 beats 1–3 over one honest pair. The six-beat story is the integrated floor, not the product or demo ceiling; the broader scenario portfolio remains unenumerated and must be named when this draft is cut. - -Typing a visible element name or id is the accepted first interaction. Click-to-chat and automatic canvas-selection context are deferred unless textual identification proves ambiguous or burdensome in observed review use. - -**Completion:** the mission is done when every consequential element in the demo net either resolves or visibly declines, at the readiness gate below. One resolving element is the throughline tracer inside the mission, not the mission. - -**Scope decision, 2026-09-03:** the earlier one-element cut was judged too small under the product-manager litmus. The owner expanded Mission 7 to the whole demo net rather than consolidating it. Folding it into Mission 6 was rejected because it would load the viability tracer with capture durability and delay it. Folding it into Mission 9 was rejected because it would tie explainability, a stakeholder outcome in its own right (FE-1478), to the unproved provider-schema projection route. Expansion is cheap: capture durability and the why route cost the same for one element or all of them, and the extra work is preparing provenance for the rest of the pair. Reverse toward consolidation with Mission 9 only if preparing whole-net provenance by hand proves to be the dominant cost with no mechanism strain, in which case the why route should ride on Mission 9's generated derivations instead. - -## Contract stratum - -Close the **capture-backed provenance stratum for the selected prebuilt workpiece/SDCPN pair**. - -The accepted objects and minimum seam are: - -- one current Markdown workpiece revision promoted from an explicitly named retained source only after eligibility inspection and owner selection; -- one exact source Flue conversation and explicit settled range; -- immutable mechanical capture envelopes containing exact evidence and source pointers; -- stable references from consequential workpiece passages to capture evidence; -- one honestly prebuilt non-empty SDCPN with stable element ids; -- a minimal derivation fixture from consequential net elements to current workpiece passages, projection rationale, and relevant uncertainty/assumption/loss; and -- one reviewer-facing resolution operation from a typed visible element name/id to that chain. - -This stratum is narrower than automatic projection and broader than one green lookup. Every consequential element in the selected pair must have either resolvable provenance or an explicit unsupported/unlinked disposition before the visible pair can be trusted as capture-backed. The contract also covers duplicate, ambiguous, and stale identity; missing evidence; replay/idempotency; capture durability; cross-owner refusal; visible failure; and recovery at the replacement boundary the deployed product claims. - -Capture remains domain-opaque evidence. The foreground Markdown workpiece owns semantic synthesis. The derivation fixture records what the human or explicitly identified prebuilder decided. No capture payload becomes the canonical workpiece, assertion card, SDCPN proposal, or semantic intermediate representation. - -## Boundary crossings and current throughline hypothesis - -```text -owner-selected eligible retained conversation/workpiece source - → harness explicitly names the settled source range - → Mission 2 mechanical sweep reads Flue history - → durable capture store archives exact user evidence and immutable envelopes - → prepared Markdown workpiece references the relevant capture ids/spans - → identified prebuilder creates a non-empty SDCPN and minimal derivation fixture - → durable product state preserves workpiece, derivation, captures, and owner binding - → deployed Petrinaut reviewer sees the selected prebuilt net - → reviewer types a visible element name or id in the existing AI panel - → AI SDK transport sends the turn to the Brunch Flue ChatAgent - → provenance capability resolves element → derivation → current workpiece → capture archive - → client/server response returns exact excerpts plus attributed rationale - → panel renders an evidence-grounded why answer or visible unsupported/unavailable refusal -``` - -Actor and authority crossings: - -- **Flue conversation → Brunch harness:** history is the canonical conversation log; an explicit harness fact, never the interviewer model, schedules the sweep. -- **Harness → capture store:** only mechanical capture projection and evidence archiving occur. The store validates ownership, source pointers, idempotency, atomicity, and durable format. -- **Capture store → workpiece preparation:** a person or explicit preparation step writes narrow references. There is no automatic capture-to-workpiece reducer. -- **Workpiece → prebuilder:** the prebuilder interprets the selected Markdown meaning and records its rationale. The net is not represented as model-generated. -- **Brunch server → Petrinaut browser:** the Flue agent emits a client-tool request or uses another application-level host extension; the existing `useChat` / `onToolCall` path executes it. Petrinaut library code must not gain Brunch-specific business logic. -- **Element id/name → evidence:** deterministic stored links select the derivation and evidence. The model may explain linked material but may not invent links or substitute a transcript reread. -- **Application → deployment substrate:** active Flue and capture/workpiece/derivation state cross the actual Mission 8 persistence boundary. The application artifact exists on the deployment branch; infrastructure deployment and replacement proof remain open. - -## Throughline proof floor - -At the real product boundary named at cut time: - -1. one consequential visible element in the honestly prebuilt SDCPN resolves from its stable id or unambiguous visible name to the current workpiece passage, prebuilder projection rationale, exact source excerpts, and at least one relevant uncertainty, assumption, omission, default, or loss; and -2. one deliberately broken or stale link visibly returns unsupported/unavailable without fabricated rationale or evidence. - -This floor is the first internal milestone: a real capture-backed why route for one element and its honest negative control. It is not mission completion, which is the readiness gate over every consequential element. It does not close the selected pair's whole provenance stratum, prove automatic projection, establish an observer, type capture semantics, or enumerate the broader scenario portfolio. - -## Readiness ratchet - -```text -Mission 2 mechanical-capture throughline -+ one retained source selected and promoted through an explicit eligibility and identity decision -+ Mission 8 landed application contract and still-open infrastructure handoff -→ inherited capture/workpiece/deployment closure required here -→ one deployed capture-backed why answer plus broken-link refusal -→ readiness gate -├─ close provenance breadth and durability for the selected prebuilt pair before Mission 7 ships -├─ admit the stable workpiece/derivation/element seam into Mission 9 automatic projection -└─ leave typed capture semantics, automatic observation, broad scenario coverage, and autonomous projection unearned -``` - -### Inherited stratum closure - -Mission 7 consumes, but must not overstate: - -- **Mission 2 throughline:** explicit settled Flue history ranges produce idempotent, source-linked envelopes with payload `{}` and no extraction model. Before use as product data, replay must preserve exact source evidence, owner refusal, format validity, and atomic all-or-nothing behavior. -- **Mission 3/4 evidence boundary:** Mission 4 accepted the core/plugin implementation on partial activation/restraint evidence but retained no full-run workpiece candidate. Before preparing the pair, this mission or its predecessor addendum must select a retained source, establish that its workpiece is cold-readable and sufficiently epistemically honest for the named review slice, freeze it with the exact source conversation and instrument, and record every accepted limitation. It may use only the topology-neutral rows made load-bearing by that slice and may not hide a known gap in the derivation. -- **Prebuilt-pair honesty:** all net content used by the visible path must have an identified preparation route, stable ids, and explicit projection rationale. Parser validity alone and the Mission 3 empty paid document are ineligible. -- **Deployment application contract:** the pinned Mission 8 handoff has locally verified fail-closed Postgres Flue storage, TLS, image, health, content-free telemetry, and container smoke, but no remote infrastructure proof. Because this mission activates capture, its durable storage and replacement behavior become application and infrastructure obligations. Its inactive local JSON capture store is not inherited closure. -- **Product door:** panel → AI SDK → Flue `ChatAgent` and client-tool resume already work. The panel remains the real entrypoint and the stock assistant remains independent. - -If any inherited item is unavailable at cut time, name it as open inherited closure with an owner and oracle; do not call the throughline a dependable base. - -### Readiness gate after the new throughline - -This gate is Mission 7's completion bar. Before Mission 7 can ship its selected-pair claim, assess every consequential element in the demo net and close: - -- resolvable current provenance or an explicit unsupported/unlinked disposition; -- duplicate ids/names, ambiguous name lookup, stale workpiece revision, stale derivation, deleted/renamed element, missing capture, and mismatched owner; -- exact-evidence replay, sweep idempotency, capture/workpiece/derivation durability, atomic update/refusal, format/version refusal, and replacement recovery; -- cross-owner read/write refusal and absence of evidence leakage in errors, telemetry, or rendered answers; -- visible negative states for unsupported, unavailable, ambiguous, stale, and temporarily failed resolution; -- deterministic context source: stored current workpiece and derivation, never transcript fallback disguised as provenance; -- stock-assistant coexistence and a Brunch selection/routing posture sufficient for the selected deployed path; -- representative latency, model/tool usage, timeout, and failure behavior without reintroducing minute-scale foreground extraction/fold work; and -- compaction/stale-state risk: either cross a real compaction boundary and preserve the resolution chain, or state and visibly guard the accepted non-compaction limit. - -Mission 9 may inherit the stable seam only after these leaves are enumerable and accepted: current workpiece revision identity, workpiece passage/reference identity, exact capture evidence references, stable net element ids, and projection rationale/derivation identity. **Owner:** Mission 9. **Re-entry gate:** its first automatic projection must write the same seam and Mission 7's why operation must resolve a generated element without fixture-only translation. **Oracle:** Mission 9's deployed generated-element why proof plus repeated/changed projection identity checks. - -Do not carry selected-pair provenance breadth, capture durability, owner refusal, or broken-link visibility into Mission 9: Mission 7's visible claim already depends on them. - -## Candidate evidence and oracles - -| Claim leaf | Existing evidence or candidate oracle | -| --- | --- | -| Explicit harness-owned sweep over real Flue history; no interviewer sweep tool; exact excerpt, `{}` payload, idempotent retry | Existing `apps/brunch-agent/test/petrinaut-chat.test.ts`, test `the committed /api/chat door streams a plain Flue agent through server and client tools`, driven by `apps/brunch-agent/test/petrinaut-chat.integration.ts`. Run `yarn workspace @apps/brunch-agent test:unit`. | -| Capture command closure, source evidence, all-or-nothing refusal, supersession/conflict guards, persisted parse | Existing `libs/@hashintel/brunch-agent/packages/core/test/capture-store.test.ts`, suite `capture-store contract`. Run `yarn workspace @hashintel/brunch-agent test:unit`. These tests are evidence for internal historical mechanics, not permission to expose typed payload semantics. | -| Owner refusal, tmp-and-rename persistence, serialization, invalid-format failure | Existing `libs/@hashintel/brunch-agent/packages/binding-flue/test/local-capture-store.test.ts`, suite `local capture store`. Run `yarn workspace @hashintel/brunch-agent-binding-flue test:unit`. This is local-file evidence only. | -| Panel executes client tools and resumes one turn through AI SDK | Existing `apps/brunch-agent/test/petrinaut-chat.test.ts` plus `libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.test.tsx`, test `adds one dynamic output and sends one automatic follow-up`. Run `yarn workspace @apps/brunch-agent test:unit` and `yarn workspace @hashintel/petrinaut test:unit --run`. | -| Mission 3 workpiece is recoverable and cold-readable; empty paid net is semantically false | Existing `docs/evidence/implementations/fe-1525-headless-runbook-pn.md` and `docs/evidence/evaluations/vestera-prospective-baseline-v1/campaign-adjudication.md`; artifact inspection is the oracle. | -| Mission 8 application contract is locally verified but remote replacement remains open | `157730cc5a214dd9c543e8d95c7193a219c48aef:libs/@hashintel/brunch-agent/docs/evidence/implementations/mission-8-deployment-handoff.md`: exact recorded commands include `yarn workspace @apps/brunch-agent lint:tsc`, `lint:eslint`, `test:unit`, `build`, `build:docker`, and `turbo run test:unit --filter='@hashintel/brunch-agent...'`, plus native arm64, explicit `linux/amd64`, and Docker/Postgres/collector smoke. The handoff explicitly is not remote proof. | -| One retained source is exact, and one workpiece is explicitly promoted as eligible for the selected pair | **ORACLE GAP:** Mission 4 supplied no full-run candidate. Resolve before this draft is cut by naming an eligible retained source or addendum-owned run, selecting the smallest workpiece-eligibility checks required by the visible review slice, recording identity/remapping rules, freezing the promoted input, and obtaining owner selection. Do not imply full topology-neutral or comparative acceptance. | -| Every consequential element in the selected prebuilt pair has a derivation or explicit unsupported disposition | **ORACLE GAP:** no selected pair or inventory exists. Resolve with a frozen element inventory mechanically compared with the derivation fixture and human inspection of every unsupported disposition. | -| One typed name/id yields an evidence-grounded answer and broken link yields visible refusal in deployed panel | **ORACLE GAP:** no existing test or deployed witness exercises this operation. At cut time bind it to the exact production-path test and a human panel witness; do not count a server-only fixture. | -| Capture/workpiece/derivation survive the actual claimed replacement boundary | **ORACLE GAP:** deployment branch stopped before remote task replacement and left capture inactive. Resolve with one immutable image, selected durable store, process restart and cross-host replacement inspection against the same ids. | -| Cross-owner provenance refusal | Existing local capture-store owner refusal is inner evidence only. **ORACLE GAP:** bind an outer deployed second-principal probe to the selected identity/access boundary. | -| Stock assistant works with Brunch unavailable | **ORACLE GAP:** current standing lock is not an observed Mission 7 witness. Resolve with the exact host-mode test and browser witness selected at cut time. | -| Latency, usage, transcript fallback, and stale-state behavior are visible | **ORACLE GAP:** define thresholds only from a representative deployed run and owner acceptance; instrument the selected operation without content export. | - -## Verification approach - -- **Inner mechanism evidence:** run the existing core capture-store, binding local-store, and app sweep tests; add only tests required by the chosen narrow reference and durable-store representation. Mechanism checks must pin exact evidence, immutable captures, stable references, owner refusal, stale/ambiguous resolution, atomic failure, and format refusal. They do not establish the product claim. -- **Middle integration/contract evidence:** drive the production built Brunch application through AI SDK and Flue with the frozen pair, execute the actual provenance capability/client-tool boundary, and verify element → derivation → current workpiece → captures for positive and deliberately broken links. Exercise process restart and the selected durable implementation. Compare every consequential element to the frozen disposition inventory. -- **Outer deployed/user-visible evidence:** a human reviewer opens the selected prebuilt net through the deployed Petrinaut/Brunch boundary, types the visible element name/id, sees the attributed answer and prebuilt label, then exercises a broken link and a cross-owner attempt. Repeat after the claimed task replacement. Explicitly witness that stock mode still works. The mission owns this outer evidence; it may not defer it to Mission 9. -- **Semantic adjudication:** a cold reader checks that each answer distinguishes exact expert excerpts, current workpiece synthesis, and prebuilder rationale/assumption/loss. Plausible prose, source-path display, or link presence without semantic correspondence fails. - -## Inputs and joins - -- **Upstream source join:** Mission 4 supplies activation/restraint evidence and an explicit record that no full-run candidate exists. Mission 7 may consume Mission 6's honestly prepared fixture, name another retained source, or produce one under new authority, but must freeze the exact conversation/workpiece/document inputs and pass the minimum provenance-suitability and identity/remapping contract. The join fails if prepared material is presented as persona/model evidence, a branch-tip workpiece is treated as previously accepted, or a Flue identity is presented as Petrinaut net/user identity. -- **Mission 2 join:** explicit `applyCaptureSweep`-style harness operation, evidence archive, capture idempotency, owner key, and no interviewer scheduling. Reuse mechanics only after inspecting current contracts; do not revive generalized typed elicitation. -- **Prebuilt fixture join:** identified preparer, stable net element ids, current workpiece references, capture evidence references, projection rationale, and explicit unsupported dispositions. The pair must be non-empty and semantically inspectable. -- **Mission 8 join:** consume the landed application contract and the open infrastructure handoff accurately. Mission 7 must add durable capture/product-state scope before claiming replacement durability, then join to actual ECS/RDS/collector/ingress identity supplied by infrastructure. -- **Petrinaut host join:** use the existing generic panel tool-execution surface and canonical net identity. Any new UI or user behavior updates Petrinaut docs in the same change. -- **Mission 9 output join:** hand off the accepted seam and why operation so automatic projection can generate derivations that resolve without a fixture-specific adapter. - -## Risks and assumptions - -| Risk or assumption | Impact if false | Cheapest discriminating validation | -| --- | --- | --- | -| A workpiece promoted from the selected retained source can host stable passage/reference identity without becoming assertion cards | If false, links churn or a second semantic artifact is needed | Prepare references for the consequential prebuilt pair and revise a non-semantic line; observe whether meaning-bearing references remain unambiguous. Stop before choosing a new ontology. | -| Visible element name is unique enough for reviewer input, with id as escape hatch | If false, a name-only why request can resolve the wrong element | Inventory duplicate/renamed names and exercise an ambiguous query that must request/disclose the id rather than guess. | -| A minimal companion derivation fixture is sufficient for why review | If false, rationale or loss cannot be recovered without transcript reread | Cold-read one consequential and one unsupported element using only workpiece, derivation, and captures. | -| Exact excerpts plus workpiece context are enough for a useful why answer | If false, the UI may expose provenance yet fail the review task | Human reviewer judges whether the answer explains the modelling choice and its uncertainty, not merely lists ids or quotes. | -| The Mission 8 Postgres application boundary can durably host or coordinate activated capture/workpiece/derivation state | If false, task replacement breaks provenance or requires a different durable owner | Implement the least candidate behind existing storage boundaries and run process/cross-host replacement; do not infer from Flue-table durability. | -| The selected short path need not cross Flue compaction | If false, workpiece/evidence recovery may fail during the visible review | Measure the selected conversation against compaction behavior; if crossed, make compaction recovery part of this mission. If not, guard and disclose the limit. | -| A model can explain deterministic linked material without inventing provenance | If false, free-form generation can launder unsupported claims | Negative controls remove or stale one link and compare the answer; require structured unavailable state before explanatory prose. | -| One selected prebuilt pair makes the peer set enumerable | If false, stratum closure cannot be distinguished from one tracer | Freeze the pair and inventory all consequential elements before broadening. | - -## Accepted constraints and guarded invariants - -- **One authority:** this file remains non-executable until converted into `MISSION.md`. Guard: exact warning and absence of live mission headings. -- **Flue history is canonical conversation log; capture is not a second transcript.** Guard: sweep reads named Flue entries and stores exact spans/excerpts only. -- **Harness owns sweep scheduling.** The foreground model receives no sweep tool and no scheduling instruction. Guard: existing app throughline test's tool-name assertions plus production manifest inspection. -- **Capture envelopes are immutable, exact-evidence, and domain-opaque.** Guard: capture-store parse/idempotency tests and schema inspection; stop if SDCPN fields enter capture payload contracts. -- **Foreground Markdown workpiece owns semantic synthesis.** Guard: cold-reader inspection and absence of an automatic capture reducer. -- **Prebuilt means prebuilt.** Guard: visible product label and frozen preparation manifest. Stop the line if the pair is described as automatically projected. -- **No observer.** No token threshold, `useAgentFinish` scheduler, asynchronous model fold, assertion consolidation queue, or automatic background update enters this mission. Guard: dependency/tool/state inventory. -- **No typed capture ontology or assertion-card default.** No closed kinds, slots, subject/predicate/value, per-capture SDCPN hints, or typed completion algebra. Guard: public-schema review. -- **No automatic projection.** The net and derivation are fixtures/prepared artifacts; no workpiece-to-mutation engine is mounted. Guard: tool manifest and preparation record. -- **No transcript fallback.** A missing stored link returns unsupported/unavailable. Guard: broken-link negative control. -- **Durability matches the claim.** Task-local JSON cannot support replacement durability. Guard: restart and cross-host replacement with the same ids and owner binding; startup refuses incompatible/missing durable configuration. -- **Ownership fails closed.** Guard: existing local owner refusal plus deployed second-principal probe. -- **Petrinaut remains contract owner and stock assistant remains independent.** Guard: no Brunch-specific logic in the published Petrinaut core, host coexistence test, and stock-mode browser witness. -- **No content-bearing telemetry by default.** Guard: trace/log inspection for excerpts, prompts, tool payloads, credentials, and owner material. - -## Cross-cutting obligations - -- Workpiece sufficiency: a cold reader can reconstruct the relevant objective/process meaning and distinguish evidence, inference, assumption, unknown, conflict, omission, and construction-opened loss. -- Evidence provenance: exact conversation evidence remains attributable; normalized workpiece or model prose is never presented as quotation. -- Projection fidelity for this prebuilt pair: every consequential prebuilt region names the workpiece material and preparer's rationale; no automatic generation claim is made. -- Failure visibility: ambiguity, missing/stale links, owner mismatch, durable-store refusal, and unavailable Brunch visibly stop/degrade the operation without advancing or fabricating state. -- Interaction quality: the why operation remains in reviewer language and does not expose construction schemas or block on semantic extraction/fold work. -- Security/privacy: consume Mission 8's restricted-boundary posture, trusted identity decision, durable state, and content-free operational visibility as actually accepted at cut time. -- Host continuity: preserve `useChat` / `onToolCall`, separate histories, and stock-assistant availability. -- User docs: update affected Petrinaut docs with what the reviewer types, what appears, and failure behavior; prompt for screenshot replacement if the UI changes. -- Architecture docs: if a new Petrinaut/Brunch folder forms a real architectural unit, add the required local declaration and run the Petrinaut architecture-doc lint. - -## Expected touched paths - -Tentative only; re-evaluate after the real boundary survey. - -```text -libs/@hashintel/brunch-agent/ -├── MISSION.md ~ cut-time authority only -├── docs/evidence/ + selected-pair/provenance adjudication -├── packages/core/src/evidence/ ~ only if narrow reference/durable contracts belong in core -├── packages/core/test/ ~ corresponding contract guards -├── packages/binding-flue/src/ ~ durable capture adapter only if this remains the honest binding -└── packages/binding-flue/test/ ~ ownership/recovery/refusal guards - -apps/brunch-agent/ -├── src/capture/ ~ explicit harness sweep and durable store composition -├── src/conversation/ ~ narrow provenance capability/client-tool signal if earned -├── src/agents/chat-agent/ ~ mount only the why capability, never automatic projection -├── src/http/ ~ selected deployed route/identity composition if required -└── test/ ~ production throughline and replacement integration - -libs/@hashintel/petrinaut-core/ ? generic host contract only if an existing neutral extension is insufficient -libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel/ ~ generic visible why/failure presentation if required -libs/@hashintel/petrinaut/docs/ ~ affected user-facing guidance -deployment/infrastructure source outside this checkout ? actual durable restricted service resources and remote proof -``` - -Do not create a capture ontology package, observer package, projection engine, graph database, generalized provenance platform, second server, or TUI. - -## Fog-line - -- Which retained source or addendum-owned run is eligible for promotion, which limitations are accepted for the selected review slice, and whether stable references can be embedded in Markdown without changing its semantics. -- The exact source conversation/range and capture replay needed for the pair. -- The smallest honest derivation representation and whether it travels with the workpiece, net, or as a companion manifest. -- The consequential-element inventory and what counts as consequential for the selected pair. -- Whether visible names are unique, ids are discoverable, or the existing panel needs a generic element-reference affordance. -- The exact durable owner for capture, workpiece, and derivation data at the Mission 8 replacement boundary. Flue Postgres durability does not automatically include these objects. -- The deployed host selection and trusted identity/access boundary; deployment branch evidence stops before these exist. -- Whether the selected review crosses Flue compaction and, if so, how current workpiece and evidence references survive it. -- Representative latency/usage and the smallest non-content operational signals needed to diagnose why-resolution failure. -- The accepted broader scenario portfolio. Do not infer it from Vestera or from the one prebuilt pair. - -## Stop or reorient - -Stop and surface the smallest blocker if: - -- no exact retained source or addendum-owned run is selected, or no owner-approved eligibility and identity/remapping decision promotes it for the selected pair; -- a selected pair cannot be prepared without inventing unsupported operational meaning or hiding material workpiece gaps; -- product language or UI implies the prebuilt net was automatically projected; -- why resolution depends on rereading the transcript, model-generated plausible links, or source-path proximity rather than stored references; -- a missing/stale/broken link produces an answer instead of unsupported/unavailable; -- task-local JSON is retained while the product claims survival across task replacement; -- capture payloads acquire SDCPN types, assertion-card semantics, closed kinds/slots, mapping hints, or completion state; -- the foreground model gains a sweep tool, schedules capture, or ordinary turns wait for extraction/fold work; -- an observer, automatic projector, graph database, or one-artifact capture/workpiece merger appears to tidy the route; -- one green element is treated as closure without inventorying every consequential element in the selected pair; -- the published Petrinaut library gains Brunch-specific product logic or the stock assistant becomes dependent on Brunch; -- remote deployment, trusted identity, owner refusal, telemetry, or replacement recovery cannot be observed at the boundary being claimed; or -- the scenario portfolio must be invented rather than named honestly at cut time. - -## Carried evidence and rejected alternatives - -- Mission 2 established the least capture pipe: explicit harness range, one exact envelope per user utterance, payload `{}`, stable ids on replay, no model extraction, no sweep tool. It did not establish typed semantics, a workpiece join, or durable remote product data. -- Mission 3 accepted one Flue runbook/workpiece path and falsified real-model construction on the exercised provider-visible schema bridge. The hermetic non-empty callback fixture proves packaging and canonical validation; the paid empty net is not a candidate prebuilt pair. -- Mission 4 supplied no full-run conversation/workpiece candidate. Mission 7 may select an accepted Mission 6 prepared fixture for the named review slice, but must preserve its prepared status and may not silently invent candidate status, claim the full topology-neutral portfolio, or redesign accepted upstream semantics while adding references. -- The pinned Mission 8 handoff supplies a locally verified application contract and explicit handoff: fail-closed Postgres Flue state, IAM/static-password paths, TLS, image, health, content-free OTel, and container smoke landed; ECS/RDS/collector/ingress credentials, real IAM/provider turn, replacement recovery, rollback, and acceptance did not. Capture remained inactive and local JSON. That distinction is load-bearing. -- The full capture/workpiece A–D alternatives, shadow-join probe, measurements, and re-entry conditions live in [`MISSION.next.md`](../../MISSION.next.md#captureworkpiece-seam-history-and-rejected-mechanisms). **Mission 7 selects support links only for the prepared pair:** immutable evidence stays separate from editable Markdown synthesis and joins through stable references plus derivation. Complete independence loses only as a sufficient FE-1476 delivery posture; capture-fold and one-artifact shapes remain rejected here. -- Versioned assertion cards remain a possible future response only if the selected Markdown reference seam fails under observed revision strain. They are not the Mission 7 default. -- Typed capture payloads, per-capture loss categories, closed kind/slot catalogs, precision ladders, completion algebra, `firesWhen`, plugin/repertoire runtime, graph storage, and a target-document ontology remain rejected until a real consumer and failure require them. -- An asynchronous inferential observer remains absent. It may re-enter only under later foreground revision strain with its own evidence for ordering, failure, flush, prior-meaning preservation, and latency. -- Automatic projection belongs to Mission 9. Mission 7's prepared net and derivation make the provenance contract testable without pretending the provider-schema and repeated-projection risks are solved. diff --git a/libs/@hashintel/brunch-agent/docs/mission-drafts/7-explainable-construction.md b/libs/@hashintel/brunch-agent/docs/mission-drafts/7-explainable-construction.md new file mode 100644 index 00000000000..4b788d0cdff --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/mission-drafts/7-explainable-construction.md @@ -0,0 +1,399 @@ +# Draft Mission 7 — Construct and explain one real net region from a genuine conversation + +> Draft cluster only. Not execution authority. Do not implement until this cluster is re-evaluated and cut into `MISSION.md`. + +This draft is written at cut-level detail so that conversion into a live `MISSION.md` is a re-evaluation rather than a rewrite; the [cut conversion map](#cut-conversion-map) at the end names which section becomes which live address and how the two-step authority is represented. It was recut on 2026-09-04 from the former "capture-backed review of an honest prebuilt pair" after two independent reviews of the provenance design, then tightened the same day after a readiness review of the recut; the reasoning is in the [decision log](../evidence/design/provenance-and-tooling-decision-log-2026-09-04.md) (sections C, F, G, H), the [mini spec](../evidence/design/provenance-by-lineage-mini-spec-2026-09-04.md), the [independent review](../evidence/design/provenance-by-lineage-independent-review-2026-09-04.md), and the [follow-up review](../evidence/design/provenance-by-lineage-follow-up-review-2026-09-04.md). Where this draft cites an entry such as G7, that entry is the surviving rationale. The owner's standing qualification on the readiness review is recorded as H0: it may make this mission more rigorous, never narrower. + +## Cold-start reads + +Tracker: [FE-1573](https://linear.app/hash/issue/FE-1573/explain-one-prepared-petrinaut-net-from-exact-conversation-evidence) is the tracker projection for this future branch mission and advances the stakeholder outcome [FE-1478](https://linear.app/hash/issue/FE-1478/provide-provenance-from-a-generated-net-back-to-the-requirements-graph) without rewriting that record. Its current title and description describe the superseded prepared-pair cut and must be re-titled with owner approval before this draft is cut; FE-1478's "requirements graph" and "captured assertions" wording remains the stakeholder's, satisfied here by declared basis over settled workpiece revisions rather than by a graph. + +A fresh builder must resolve these authorities and this terrain before implementing anything: + +- [`../../MISSION.md`](../../MISSION.md) — the current branch's live authority (Mission 6 at the time of writing). Mission 7 stacks on Mission 6's accepted archive and on Mission 5's landed browser Flue transport; create the Mission 7 branch from the final Mission 6 close commit, not from a pre-close head. Mission 6's constraint that construction tools stay out of ordinary conversations is amended by this cut, not silently. +- [`../../MISSION.next.md`](../../MISSION.next.md) — compact spine, FE-1476 product frame, cross-mission obligations, standing locks, the 2026-09-04 planning migration matrix, and later evidence admitted after this draft. +- [`README.md`](README.md) — draft authority, lifecycle, and conversion rules. +- The four design-evidence documents named above. Design evidence, not authority; every settled item becomes authority only when written into the cut `MISSION.md`. +- [`../mission-archive/2-mechanical-capture-sweep.md`](../mission-archive/2-mechanical-capture-sweep.md) — the accepted mechanical capture throughline. Historical: capture envelopes and sweep semantics are rejected for this mission's provenance (G20); the session-log archive lane in `binding-flue` is a separate existing capability. +- [`../mission-archive/3-structurally-typed-runbook-to-headless-pn.md`](../mission-archive/3-structurally-typed-runbook-to-headless-pn.md) and [`../evidence/implementations/fe-1525-headless-runbook-pn.md`](../evidence/implementations/fe-1525-headless-runbook-pn.md) — accepted workpiece leg, falsified provider-visible nested-schema construction (0 for 9 on `addType.elements`), and the vacuous empty-net warning. This mission retires that blocker. +- [`../mission-archive/4-core-plugin-elicitation-proof-of-life.md`](../mission-archive/4-core-plugin-elicitation-proof-of-life.md) — the accepted core/plugin/app split and interaction decisions this mission composes within. +- [`../evidence/implementations/fe-1575-resumable-workpiece-petrinaut.md`](../evidence/implementations/fe-1575-resumable-workpiece-petrinaut.md) and the r2 outer witness beside it — Mission 6's viability proof of transport, least mutation, settled manifest, and two-tab resume, and its honest admissions: the prepared fixture's "Current Petrinaut correspondence" section was fixture-authored (A3), and the fenced-block workpiece source is a Mission 6 contract this mission replaces (A4). The Mission 6 fixture is not promoted into this mission's pair. +- [`../evidence/implementations/mission-5-direct-voice-flue/README.md`](../evidence/implementations/mission-5-direct-voice-flue/README.md) — the browser Flue `ChatTransport` at `/agents/chat/:instanceId`, client-tool-result correlation, and admission timing this mission consumes. +- [`../../packages/core/src/workpiece.ts`](../../packages/core/src/workpiece.ts) and [`apps/brunch-agent/src/conversation/workpiece.ts`](../../../../../apps/brunch-agent/src/conversation/workpiece.ts) — the current resolver: core selects the tagged prepared signal or the latest fenced `runbook-ir` block by source message id; the app computes the SHA-256. Replaced for model-produced revisions by `update_workpiece`, which moves hashing into core; the tagged prepared route is retained. +- [`../../packages/core/src/flue.ts`](../../packages/core/src/flue.ts) and [`../../packages/core/src/client-tools.ts`](../../packages/core/src/client-tools.ts) — core owns no model-facing tool today and states the rule for adding one; the `ask` and `sweep` names here are orphans this mission retires. +- [`../../packages/plugin-sdcpn/src/flue.ts`](../../packages/plugin-sdcpn/src/flue.ts), [`../../packages/plugin-sdcpn/src/tools/petrinaut-construction.ts`](../../packages/plugin-sdcpn/src/tools/petrinaut-construction.ts), and [`../../packages/plugin-sdcpn/test/construction-tools.test.ts`](../../packages/plugin-sdcpn/test/construction-tools.test.ts) — the tool factory with the falsified carrier (`v.looseObject({})` plus `rawTransform` and the JSON Schema pasted into the description), the headless-only and fixture-only mounting modes, and the six-tool and two-tool subsets this mission retires as product surfaces. +- [`../../packages/plugin-sdcpn/src/skills/sdcpn-modelling/SKILL.md`](../../packages/plugin-sdcpn/src/skills/sdcpn-modelling/SKILL.md), [`templates/workpiece.md`](../../packages/plugin-sdcpn/src/skills/sdcpn-modelling/templates/workpiece.md), [`references/pn-construction.md`](../../packages/plugin-sdcpn/src/skills/sdcpn-modelling/references/pn-construction.md), and [`references/checks.md`](../../packages/plugin-sdcpn/src/skills/sdcpn-modelling/references/checks.md) — current teaching: concepts, the fenced-block emission rule, and Construction notes. This mission adds construction posture and the settled-revision and basis discipline. +- [`../../packages/binding-flue/src/history-reader.ts`](../../packages/binding-flue/src/history-reader.ts) and [`../../packages/transport-aisdk/src/client-tool-history.ts`](../../packages/transport-aisdk/src/client-tool-history.ts) — how history is acquired in-process with host-owned URL and transport, and how client-tool results are projected today (opaque correlated outputs, no effect semantics). +- [`apps/brunch-agent/src/agents/chat-agent/agent.ts`](../../../../../apps/brunch-agent/src/agents/chat-agent/agent.ts), [`src/conversation/identity.ts`](../../../../../apps/brunch-agent/src/conversation/identity.ts), [`src/http/ownership.ts`](../../../../../apps/brunch-agent/src/http/ownership.ts), and [`src/capture/apply-sweep.ts`](../../../../../apps/brunch-agent/src/capture/apply-sweep.ts) — composition, the principal key and conversation id that are the only identity the system carries, and the in-process fetch pattern the why lookups reuse. +- [`apps/brunch-agent/.pi/extensions/brunch-persona-testing/README.md`](../../../../../apps/brunch-agent/.pi/extensions/brunch-persona-testing/README.md) and [`src/evaluations/persona/brunch-turn.ts`](../../../../../apps/brunch-agent/src/evaluations/persona/brunch-turn.ts) — the persona harness: `--brunch-tool-host` (`none`, `mock`, `real-headless`), `--brunch-tool-mocks`, `--brunch-evidence-dir` retaining `snapshot.json` and projections per settled read, turn budget in the launch prompt only. +- [`../../evaluations/README.md`](../../evaluations/README.md), [`../../evaluations/cases/`](../../evaluations/cases/), and [`../../evaluations/oracles/`](../../evaluations/oracles/) — six persona cases with hidden truth ledgers, and the frozen protocols not to rerun. +- [`../../../petrinaut-core/src/ai.ts`](../../../petrinaut-core/src/ai.ts), [`action-schemas.ts`](../../../petrinaut-core/src/action-schemas.ts), [`command-schemas.ts`](../../../petrinaut-core/src/command-schemas.ts), [`schemas/entity-schemas.ts`](../../../petrinaut-core/src/schemas/entity-schemas.ts), [`schemas/metric-schema.ts`](../../../petrinaut-core/src/schemas/metric-schema.ts), and [`file-format/types.ts`](../../../petrinaut-core/src/file-format/types.ts) — canonical AI tool bundle, mutation and command schemas, strict entity objects with no metadata slot, and the file wrapper (`version`, document arrays, `title`, optional generator `meta`) with no provenance field. Authority; never copied. +- [`../../../petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.tsx`](../../../petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.tsx) and [`../../../petrinaut/docs/ai-assistant.md`](../../../petrinaut/docs/ai-assistant.md) — the host execution boundary and the user guide that must change with any user-visible behaviour. +- [`../specs/petrinaut-batched-construction-tools.md`](../specs/petrinaut-batched-construction-tools.md) — candidate `pn_read`/`pn_edit` input; observation O2 (the Mission 3 failure is a carrier failure, not a granularity failure) is load-bearing here; batching itself is Mission 9's decision unless this mission's scenario forces it. +- [`../reference/architecture/flue-routing.md`](../reference/architecture/flue-routing.md) — per-conversation versus cross-conversation state, `usePersistentState`, signals, and the upgrade pins. +- Installed Flue 2.0.3 documentation: `node_modules/@flue/runtime/docs/reference/agent-api.md` (tool `run` contract: a multi-tool batch ends the turn only when every result terminates; `ToolContext.toolCallId`), `node_modules/@flue/runtime/docs/reference/agent-hooks-api.md` ("Rendering and the rules of hooks": hooks only at render, setters only in callbacks), and `node_modules/@flue/runtime/docs/guide/models.md` (compaction folds older history into a summary, default 8000 recent tokens verbatim). These settle G1, G2, and F2 and motivate the compaction probe. +- Commit `157730cc5a214dd9c543e8d95c7193a219c48aef` on `ln/fe-1569-brunch-agent-deployment`, read with `git show 157730cc5a214dd9c543e8d95c7193a219c48aef:libs/@hashintel/brunch-agent/docs/evidence/implementations/mission-8-deployment-handoff.md` because the file does not exist in this checkout — locally verified application contract; no remote deployment. This mission names local posture. + +## Visible product advance + +**Release note:** talk to Brunch about a process and watch it build that part of the net; then ask why any element exists and see the workpiece passage the constructor declared as its basis, the conversation behind it, and which recorded step did what, or an explicit refusal. + +**Demo script (no engineer present):** with the local Brunch and Petrinaut stack running, open the demo conversation and its net in the Petrinaut Brunch panel. The workpiece pane shows the current revision, the revision list, and a diff between any two. Scroll the conversation: a real interview, labelled with its source (synthetic persona, internal human, or customer-derived), in which Brunch elicited the process, revised the workpiece as it went, and then built the region you see. Pick any element in the net and type its name or id. Read the passage Brunch declared as that element's basis, the revision it came from, the conversation lines or turns behind that passage, and the recorded steps: which assistant tool call requested it, which browser step applied it. Pick the element the demo marks as changed by hand and watch Brunch say it cannot attribute the current state. Pick the element marked as built without a declared basis and watch Brunch say so rather than improvise. + +**Previously impossible:** Brunch had never built a net region inside a real conversation, only from a prepared fixture or a headless harness, and nothing connected any element to what was said. + +**Completion:** the mission is done when a product manager can run that script for the proving scenario and every readiness-gate obligation below is closed, including the safety and utility gates for the why operation. The first green pass through the adversarial tracer and the first real constructed region are internal milestones. + +**Scope history.** On 2026-09-03 the one-element explainability cut was judged too small under the product-manager litmus and expanded to a whole prepared net. On 2026-09-04 the prepared pair and its hand-authored derivation fixture were rejected as fixture-rigging and useless respectively (A3, B4), and the owner consolidated construction and explanation into this mission rather than splitting a thin visible-workpiece mission first, to resist the regression to thin tracers and to build fully connected parts with real test beds (F12). The follow-up review then established that this mission must close the readiness of its own claim and may move only breadth to Mission 9 (G16). Reversal condition: if the adversarial tracer shows the model cannot construct with a usable declared basis under any revised interaction, the explainability release is withheld and construction stands on its own gates (decision table below). + +## Contract stratum + +Close the **construction-and-explanation stratum for one genuine conversation, one proving scenario, and one document incarnation**. Its objects and minimum seams: + +- **Settled workpiece revisions**: `update_workpiece` tool calls whose `revisionId` is the call's `ToolContext.toolCallId`, whose `sha256` is the content identity, and whose ordinal `revision` is display metadata only, with the Markdown persisted in per-conversation state (H6); the fenced-block route retired for model-produced revisions; the tagged prepared signal retained only for test-authored material. +- **Declared basis** on every mutation request: `declared { revisionId, sha256, locators, rationale, scope }` or `absent { reason }`, operation-level unless an intended-effect mapping names elements (G7). +- **Optional revision-time evidence relation** on `update_workpiece`: `evidence: [{ locator, messageIds, kind }]`, kind in elicited, inference, default, formalism-constraint, external, correction; carried forward unchanged passages inherit their relation (G3). An `elicited` relation is refused unless every referenced id resolves to an authorized true-user message in the bound conversation, reusing the session-log resolver's non-user-evidence refusal as the model (H8). +- **Mutation transition records**: requested base hash, observed pre-apply hash, post hash when a post-apply observation exists, outcome, disjoint derived effects, diff accounting; the first well-formed outcome is authoritative unless a later delivery conflicts, in which case the outcome becomes `unknown` and both deliveries remain as attempt history (G9, H7). +- **Identity epochs**: ids never reused; delete and recreate opens a new epoch; origin, current state, change history, attempt history are distinct query semantics (G8). +- **Passage identity policy** and its probe (G11). +- **Document reconciliation**: one conversation bound to one document incarnation; every why answer reconciles against the live hash or labels its staleness; external import records without laundering (G4, G5, G10). +- **Recorded roles**: assistant tool call, local browser executor, user under principal key, test-authored fixture author; human identity unknown; time is stream order (G6). +- **Scenario-selected tool admission with canonically derived schemas** over a repaired carrier (G15). +- **Consequential inventory** with one disposition per item and published numerator, denominator, and exclusions (G13). +- **Safety and utility gates** for the why operation (G14). +- **Runtime migration matrix** with a removal gate for any dual-read bridge (F15). + +Outside this stratum and owned by Mission 9 with re-entry gates: unchanged repeat, changed input, deletion and retirement beyond the single negative case exercised here, concurrent user change beyond the single hand edit, cross-conversation document access and a document-scoped lineage owner, schema classes beyond the proving scenario, and the per-action versus batch decision. + +## Boundary crossings and current throughline hypothesis + +```text +persona or human conversation in the Petrinaut Brunch panel (or the persona harness against the production agent) + → Mission 5 browser Flue ChatTransport → /agents/chat/:instanceId → ChatAgent + → agent revises the workpiece: update_workpiece { markdown, evidence? } settles; state holds { revisionId, sha256, revision, markdown } + → workpiece pane shows the revision; chat shows a one-line marker + → next render exposes the settled revision; agent reads the live definition via getLatestNetDefinition + → agent requests one mutation at a time citing { revisionId, sha256 } with declared basis; the turn terminates on the browser tool + → Petrinaut panel: observes pre-apply hash, validates canonical input, applies, derives effects, returns one transition record + → client-tool-result signal resumes the conversation; the agent reconciles effects against intent; unanticipated effects are basis-absent + → agent calls getNetCompilationErrors, repairs within budget, and records decisions in Construction notes and a closing update_workpiece + → reviewer types an element name or id; the why operation: locate element → epochs and transition records → basis → span in the cited revision → evidence relation or temporal context → recorded roles → live hash reconciliation + → panel renders the answer in the workpiece pane, or a structured refusal: unsupported, not attributable, external, stale, ambiguous +``` + +Actor and authority crossings: + +- **Flue log as substrate.** Revisions and mutations are tool-call records; correlation is by call id and submission order, never a shared turn id (F1). `update_workpiece` is never batched with a terminating construction tool (G1). +- **Agent to state.** `usePersistentState` at render, setter in the tool closure, called from `run` (F2). State holds the Markdown so the current revision survives compaction of the model's context (F10). +- **Agent to Petrinaut.** The plugin strips `basis` before forwarding canonical input; Petrinaut's contract is unchanged; schemas are derived mechanically (3.6 in the spec). Petrinaut library code gains no Brunch logic. +- **Browser to record.** The transition record is the only admissible statement of effect; a plan or self-report that fails diff accounting advances nothing (G9). +- **Core, plugin, binding, app.** Core owns revision and query semantics and `update_workpiece`; plugin owns mutation names, inputs, effects, template conformance, and the element locator; binding and app own authorized history acquisition and compose the why operation (F9). +- **Authorization.** Single principal, local, one conversation per document incarnation; retrieved history is untrusted evidence returned in the smallest range (F11, G5). + +## Throughline proof floor + +The floor has two steps, each under this mission's authority, separated by an owner gate (G18). + +### Step A — adversarial tracer and probes under the initial narrow authority + +One genuine conversation on the proving scenario, run through the production agent with the persona harness in `real-headless` mode or the panel, containing at least: two distinguishable workpiece passages, two mutations with declared basis, one no-op or failed mutation, one correction that changes a passage and its element, one hand edit made outside the conversation, one carried-forward passage, one passage with non-adjacent evidence, and one multi-source synthesis. The why operation must return deterministic answers or explicit refusals for every element, with no false attribution. + +The four probes run alongside, each with its decision table: + +| Probe | Pass | Partial | Fail | Re-entry | +| --- | --- | --- | --- | --- | +| **Compaction.** Set `keepRecentTokens` low, run past threshold, read `history()`. Do folded `update_workpiece` inputs, mutation parts, and user lines survive? | Lineage reads from `history()` | Current revision from state; history claims limited to the uncompacted window and disclosed in every answer | Harden the existing session-log archive lane into an immutable lineage projection before any exact-line claim; no new log, no capture envelopes (G20) | Flue exposes a supported pre-compaction read | +| **Fixture materialization.** Export or retain, relocate, reopen, authorize, and query the tracer conversation | Retained live store or supported relocation is the demo fixture route | Relocation works but identities must be re-bound; record the binding rule | The demo runs on the retained live store where the genuine conversation was produced; relocation is filed as an upstream requirement; the prepared-projection route is not used for the why claim (H5) | Flue adds a supported export or import surface | +| **Passage identity** under the G11 policy, on the tracer workpiece, across rename, move, paraphrase, split, merge, deletion, reintroduction, duplicate headings | Locator scheme selected | Some edit classes refuse continuity; the refusals become part of the claim | Revision-local text only; no cross-revision "introduced by" | A cheaper anchor lifecycle appears in the template | +| **Carrier repair** for one real nested mutation from the proving scenario's classes | Admit the scenario's classes | Flat classes only; nested classes refused with a named blocker | Crisp upstream Flue requirement (Standard Schema or supplied JSON Schema); no local schema copy | Flue accepts Standard Schema | + +Two further measurements are taken in the tracer and gate the release, not the cut: + +| Measurement | Pass | Partial | Fail | +| --- | --- | --- | --- | +| **Revision cadence and basis quality.** How often `update_workpiece` is called unprompted; how often basis is declared, relevant, and non-contradictory | Blame and basis have grain | Coarser ranges disclosed; skill wording and pane interaction adjusted before breadth | Explainability release withheld; construction stands on its own gates | +| **Reviewer utility** under the blinded rubric | Utility gate passes | Coverage below threshold on named classes; claim scoped to passing classes | Explainability release withheld | + +Completion of Step A is not a pass. Every probe and measurement outcome is classified into exactly one of three eligibility classes, and the owner gate chooses only among the branches those classes allow (H5). Under the owner's standing qualification (H0), rework branches keep the consolidated construction-and-explanation shape; a terminal stop is reserved for outcomes that contradict that shape. + +| Outcome | Class | Allowed branch | +| --- | --- | --- | +| Tracer: deterministic answers or refusals, no false attribution; all probes Pass | Eligible for Step B amendment | Amend into Step B as drafted | +| Compaction Partial or Fail | Eligible after named rework | Current revision from state; history claims disclosed to the uncompacted window, or the existing archive lane hardened; Step B proceeds with the disclosure | +| Materialization Partial | Eligible after named rework | Record the identity re-binding rule; Step B proceeds | +| Materialization Fail | Eligible after named rework | Demo runs on a retained live store; relocation pursued as an upstream requirement; the prepared-projection route is not used for the why claim | +| Passage identity Partial or Fail | Eligible after named rework | Refusals for unsupported edit classes become part of the claim, or revision-local text with refused cross-revision claims; Step B proceeds | +| Carrier Partial | Eligible after named rework | Construction proceeds on carried classes; nested classes refused with a named blocker and an upstream Flue requirement filed | +| Carrier Fail | Eligible after named rework | Upstream Flue requirement filed; construction proceeds on flat classes while it is pursued; no local schema copy | +| Cadence or basis Partial | Eligible after named rework | Skill wording and pane interaction revised once; tracer rerun; measured again | +| Utility Partial | Eligible after named rework | Coverage threshold per class re-examined by the owner against the rubric; Step B proceeds on passing classes with the gap named | +| Tracer produces any false attribution that the record cannot prevent | Terminal stop for this mission shape | Return to design; do not amend | +| No route to a genuine reopened conversation at all | Terminal stop | Return to design | +| Effects cannot be mechanically derived from pre and post state | Terminal stop | Return to design | +| Basis remains circular or absent after the rework round | Terminal stop for the explainability half | Construction stands on its own gates; explainability returns to design | + +### Step B — the visible advance on the proving scenario + +One or more genuine persona conversations on the proving scenario, run to construction with the tool set the carrier probe admitted, each retained through the harness's evidence directory and reopened through the fixture route the probe selected. The demo script runs on one of them. Every consequential element in its net resolves or refuses through the reopened authorized why operation, the safety gate passes, and the utility gate passes at the predeclared coverage. + +## Readiness ratchet + +```text +Mission 5 browser Flue transport + Mission 6 viability (transport, least mutation, settled manifest, resume) +→ inherited: core/plugin/app split; canonical Petrinaut contracts; persona harness; Flue 2.0.3 contracts as pinned +→ Step A: adversarial tracer + four probes with decision tables → owner gate +→ Step B: real conversations to construction; why over them +→ readiness gate: close identity, failure, durability, basis quality, current state, oracle obligations for this claim +├─ hand Mission 9 the seam: settled revisions, basis, transition records, epochs, passage policy, reconciliation, tool set, compaction posture, fixture route, gates +├─ hand Mission 10 basis, transition records, epochs, evidence relation for reviewer citation +└─ leave repeat, changed input, retirement breadth, concurrent change, cross-conversation access, schema breadth, batching, observer, remote durability unearned +``` + +### Inherited stratum closure + +Mission 7 consumes, and must not overstate: + +- **Mission 5.** The browser `ChatTransport`, the mounted route, client-tool-result correlation, and admission timing are landed and tested; the human Voice witness is Mission 5's own gate and not consumed here. +- **Mission 6.** Transport-carried least mutation, runtime settled manifest, and two-tab resume are viability facts. The prepared fixture's correspondence section was fixture-authored and the fixture is not promoted. The fenced-block resolver is a Mission 6 contract replaced here; Mission 6's close report names the carried change (A3, A4). +- **Mission 3 and 4.** Accepted workpiece leg and core/plugin architecture; falsified nested carrier; no full-run candidate. The tracer conversation is the first genuine full run and is labelled synthetic-persona if produced by the harness. +- **Mission 2.** Capture envelopes and sweep semantics are not consumed. The session-log archive lane exists and may be hardened only under the compaction probe's fail branch. +- **Mission 8.** Local application contract only. This mission names local posture; remote durability stays with a scheduled Mission 8 successor or a pre-handoff release gate. +- **Flue 2.0.3.** The tool `run` termination contract, the rules of hooks, `ToolContext.toolCallId`, `usePersistentState` semantics, and compaction defaults are documented and pinned; the upgrade row in the routing guidance applies. + +### Readiness gate after the new throughline + +This gate is the completion bar. For the proving scenario's net, close: + +- **Inventory.** Consequential rule frozen before the run; inventory generated mechanically from the final canonical document; every identity-bearing or behaviour-affecting entity or field included; exactly one disposition per item (supported, partially supported, basis-absent, external, retired, refused); numerator, denominator, and exclusions published (G13). +- **Safety.** No false attribution; every required refusal correct: unsupported, not attributable, external, stale, ambiguous name, unknown outcome. +- **Utility.** Predeclared nonzero coverage of consequential elements with usable current-state answers, minimum coverage per admitted entity class, blinded reviewer task with the fixed rubric: identify the governing passage, distinguish elicited evidence from constructor inference, understand the current definition and latest correction, decide whether the answer changes the review judgement (G14). +- **Revision protocol.** No mixed batch; every mutation cites a settled revision; citation of an unknown or superseded revision refuses unless supersession is marked intended (G1, G2). +- **Basis quality.** Declared or absent-with-reason on every request; graded for relevance, contradiction, granularity, omitted dependencies; Construction notes never substitute (G7). +- **Transition records.** Independently verifiable on every call; duplicate delivery does not apply twice; conflicting duplicates resolve to unknown; failed, no-op, stale, unknown contribute only attempt history (G9). +- **Identity epochs.** One delete-and-recreate exercised; id not reused; origin and change history queryable (G8). +- **Reconciliation.** One hand edit exercised; the why answer refuses attribution for the affected state or discloses staleness; one external import exercised with dispositions retained (G4, G10). +- **Binding.** One-conversation-one-incarnation recorded and enforced; a second conversation targeting the document refuses (G5). +- **Roles and time.** Answers name recorded roles and stream order only (G6). +- **Passage policy.** Selected locator scheme or the revision-local fallback, with refusals as part of the claim (G11). +- **Compaction posture and fixture route.** Whichever branch the probes selected, disclosed in the product and the close report. +- **Carrier and tools.** Scenario-selected classes admitted over the repaired carrier; each class cites the case requirement it discharges; provider-schema rejection distinct from canonical rejection; repair budget enforced and visibly exhausted (G15). +- **Teaching.** Skill construction posture in place; measured cadence and basis quality recorded. +- **Visible workpiece.** Pane with current revision, list, diff; chat marker; projection in app or transport, not the Petrinaut library. +- **Subtraction, by inventory (H10).** Keep: `ping`, `activate_skill`, `readPetrinautDoc`. Remove: the website's `brunch-ask-interactive-tool.tsx` and test, `brunch-ask-mapping.ts`, the ask entries in `brunch-client-tools.ts`, the sweep filter in `brunch-panel-transport.ts`, `brunch-sweep-output.ts`, and the ask and sweep references in `voice-interview/canonical-speech.ts` and `interview-coverage.ts` with their tests; the `ASK_TOOL_NAME` and `SWEEP_TOOL_NAME` exports and the suspended ask contract in core `client-tools.ts`. Decide by the compaction probe's branch: `apps/brunch-agent/src/capture/apply-sweep.ts` and the sweep types consumed by `binding-flue/src/history-reader.ts`, `binding-flue/src/index.ts`, `core/src/evidence/capture-store.ts`, and `core/src/index.ts`, which are removed if the archive lane is not hardened and retained as the archive lane otherwise. Archive: nothing further; the Mission 2 and 4 records already hold the designs. Six-tool and two-tool subsets retired as product surfaces once Mission 6 archives. +- **Runtime migration matrix.** Old history with new code; new history with rolled-back code; conversations mixing fenced and tool revisions; mixed browser and server versions; Mission 6 fixture mode; retained evidence restoration; tool-manifest rollback; any dual-read bridge with an explicit removal gate (F15). +- **Behavioural discriminator.** One executable check derived from the workpiece (resource reservation and release, reachability, token conservation, or one scenario outcome) passes on the constructed region and is carried unchanged to Missions 9 and 10 (F15). +- **Stock coexistence, docs, telemetry.** Stock assistant unchanged when Brunch is absent or unselected; Petrinaut user guide updated for the pane and the why interaction with a screenshot prompt; no content-bearing telemetry. + +Mission 9 inherits the seam listed in the ratchet. **Owner:** Mission 9. **Re-entry gate:** an unchanged repeat request on the accepted conversation produces attempt history only, and one changed input produces a frozen expected impact set. **Oracle:** Mission 9's repeat, change, retirement, and current-state why witnesses. Mission 10 inherits basis, transition records, epochs, and the evidence relation for reviewer citation. **Re-entry gate:** an authorized reviewer's 3–5 turns produce a settled revision citing reviewer message ids and a bounded patch. Do not carry into Mission 9 anything this mission's visible claim already depends on. + +## Candidate evidence and oracles + +| Claim leaf | Existing evidence or candidate oracle | +| --- | --- | +| Browser Flue transport carries typed turns, history hydration, and correlated client-tool results | Existing Mission 5 evidence README and its 36-task Turbo run; Mission 6 focused tests for read, mutation, original call-id result, and continuation. Run `yarn exec turbo run test:unit --filter @apps/brunch-agent --filter @apps/petrinaut-website`. | +| Prepared signal retry and append-only selection; fixture-only advertisement; mismatch refusal; manifest retention | Existing Mission 6 tests named in `fe-1575-resumable-workpiece-petrinaut.md`. These remain guards for the prepared route only. | +| Construction tools currently expose the six-tool subset over the falsified carrier | Existing `plugin-sdcpn/test/construction-tools.test.ts`; `headless-petrinaut-client.test.ts`. Baseline to change, not success. | +| Multi-tool batch termination and hook rules | Prospective: `packages/core/test/update-workpiece.test.ts`, tests "declares a non-terminating result" and "captures the persistent-state setter at render and writes from run"; `packages/plugin-sdcpn/test/construction-tools.test.ts`, test "never mounts update_workpiece in a batch with a terminating construction tool". Command: `yarn workspace @hashintel/brunch-agent test:unit`, `yarn workspace @hashintel/brunch-agent-plugin-sdcpn test:unit`. | +| `update_workpiece` settles, hashes, persists state, refuses empty or oversize input | Prospective: `packages/core/test/update-workpiece.test.ts`, tests "returns revisionId equal to toolCallId and sha256 of the Markdown", "persists Markdown with the pointer", "refuses empty Markdown", "refuses Markdown over the size ceiling"; `apps/brunch-agent/test/workpiece-revisions.integration.ts`, test "the built agent settles a revision over the mounted route". | +| Mutation cites a settled revision; unknown or superseded citation refuses | Prospective: `packages/plugin-sdcpn/test/declared-basis.test.ts`, tests "accepts a basis citing the settled revision", "refuses a citation of an unknown revisionId", "refuses a superseded revision unless supersession is intended"; tracer artifact `docs/evidence/implementations/fe-1573-step-a//basis-citations.json`. | +| Transition record is independently verifiable; duplicates resolve to unknown | Prospective: `apps/petrinaut-website/src/main/app/local-storage-demo/transition-record.test.ts`, tests "observes the pre-apply hash independently of the request", "derives disjoint created, updated, deleted, derived sets from pre and post definitions", "refuses a record whose effects do not account for the diff", "marks conflicting duplicate browser outcomes unknown and retains both deliveries"; `apps/brunch-agent/test/transition-records.integration.ts`. | +| Identity epochs; no id reuse | Prospective: `packages/core/test/identity-epochs.test.ts`, tests "opens a new epoch on delete and recreate" and "refuses reuse of a retired id"; tracer artifact `/epochs.json`. | +| Hand edit and external import are detected and disposed honestly | Prospective: `apps/brunch-agent/test/reconciliation.test.ts`, tests "reports not attributable when the live hash has no recorded transition", "labels an answer as of the last reconciled state when the live hash is unavailable", "retains external dispositions after import until a recorded transition replaces them"; tracer artifact `/hand-edit-result.md`. | +| Passage policy holds under semantic edits | Prospective: `packages/core/test/passage-identity.test.ts`, one test per policy invariant (no reuse after deletion, split and merge lineage, paraphrase refusal, reintroduction as new identity, immutable revision-local span, duplicate headings and quotations, overbroad span fails); probe artifact `/passage-identity-result.md` recording the branch. | +| Compaction posture | Probe artifact `/compaction-result.md`: `keepRecentTokens` used, messages folded, whether `history()` retained the folded `update_workpiece` inputs, mutation parts, and user lines, and the selected branch. | +| Fixture route | Probe artifact `/materialization-result.md`: export or retention method, relocation steps, reopened conversation and document identities, authorization check, and the why query run through the product operation; acceptance assertions in `apps/brunch-agent/test/reopened-why.integration.ts`. | +| Carrier carries one real nested mutation | Probe artifact `/carrier-result.md`: provider and model, generated schema, raw arguments, runtime result, repair count, latency, cost; `packages/plugin-sdcpn/test/schema-carrier.test.ts`, test "derives a Valibot schema structurally equal to the canonical JSON Schema for each admitted class". | +| Why answers are safe and useful | Frozen inventory `/inventory.json` with expected disposition per element; safety assertions in `apps/brunch-agent/test/why-safety.integration.ts`, one test per disposition class through the reopened operation; blinded utility adjudication recorded in `/utility-adjudication.md` against the fixed rubric by a named reviewer. | +| Constructed region is meaningful | Human semantic adjudication `/semantic-adjudication.md` against the workpiece; behavioural discriminator test named at cut time under `evaluations/oracles//`. | +| Stock assistant unchanged | Existing host-mode test and browser witness pattern from Mission 6; rerun at close. | +| Product | A product manager runs the demo script on the proving scenario without an engineer. | + +## Verification approach + +- **Inner.** Core: `update_workpiece` validation, hashing, state write, revision numbering; query semantics for origin, current state, change history, attempt history. Plugin: basis parsing and refusal, locator resolution, effect interpretation, template conformance, class admission by scenario rule with schemas structurally compared to canonical Zod. Website: pre-hash observation, effect derivation, diff accounting, duplicate resolution, external import. Binding and app: history acquisition, authorization, why composition. Passage policy invariants as unit tests. +- **Middle.** The built production `ChatAgent` over the Mission 5 transport at `/agents/chat/:instanceId`: revise, cite, mutate, receive a transition record, resume, reconcile, and answer why, with duplicate delivery, stale base, unknown outcome, and hand edit injected. Run through root Turbo: `test:unit`, `lint:tsc`, `lint:eslint`, and `build` for `@apps/brunch-agent`, `@apps/petrinaut-website`, `@hashintel/petrinaut`, `@hashintel/brunch-agent`, `@hashintel/brunch-agent-plugin-sdcpn`, `@hashintel/brunch-agent-transport-aisdk`, and `@hashintel/brunch-agent-binding-flue`. +- **Outer.** The adversarial tracer and the Step B conversations retained through `--brunch-evidence-dir`, reopened through the selected fixture route, and queried through the product why operation in the panel with `yarn dev:brunch` running and a real provider credential. Snapshots and projections are diagnostics only (G12). +- **Semantic and behavioural.** Human adjudication of the constructed region against the workpiece; the behavioural discriminator; the blinded utility rubric. +- **Product.** The demo script, last, after the readiness gate. + +Paid provider evidence requires cut-time authorization with model, maximum calls, and spend ceiling recorded before execution. + +## Inputs and joins + +- **Mission 5 join.** The browser transport and correlation contract as landed; no second route. +- **Mission 6 join.** Viability facts and the two admissions; the prepared-signal route retained for test-authored material only; the fixture not promoted; Mission 6's construction-tool constraint amended here. +- **Persona harness join.** `real-headless` host for construction calls; evidence directory retention; turn budget in the launch prompt; a completion signal from Brunch's delivery status; ledger coverage as post-hoc grade (D4). Workpiece recovery in the harness must read `update_workpiece` tool parts. +- **Petrinaut canonical-contract join.** `petrinautAiTools`, `mutationActionInputSchemas`, `aiCommandActionInputSchemas`, entity schemas, writable callbacks, by import or mechanical derivation; mismatches route upstream; no schema change for provenance. +- **Flue join.** Documented tool, hook, state, signal, and history contracts; upstream requirement if the carrier cannot be repaired locally. +- **Scenario join.** The owner selects the proving scenario from the six cases, its admitted classes with cited requirements, its consequential rule, its behavioural discriminator, and the utility coverage threshold before the run. +- **Consumer discovery join.** Lightweight, non-binding discovery with Chris and Yannis before the proving scenario is fixed, so the region exercises semantics they will need (F15; Mission 11 draft). +- **Mission 9 and 10 output joins.** As listed in the ratchet. + +## Risks and assumptions + +| Risk or assumption | Impact if false | Cheapest discriminating validation | +| --- | --- | --- | +| The model calls `update_workpiece` often enough for revisions to have grain | Blame collapses to "the workpiece came from the conversation"; explainability release withheld | Count calls per turn in the tracer before Step B; adjust skill wording and pane interaction once | +| The model declares a usable basis unprompted | Basis is absent or circular; answers degrade to temporal context | Grade basis in the tracer for relevance, contradiction, granularity, omitted dependencies | +| `history()` keeps folded records | Exact lines and revision history vanish past 8000 tokens | Compaction probe | +| A genuine conversation can be relocated and reopened with identities intact | Persona runs cannot power the demo | Materialization probe on the tracer before any paid breadth | +| A locator scheme survives semantic edits under the policy | No cross-revision claim | Passage probe | +| The JSON Schema to Valibot interpreter preserves the scenario's nested classes | Nested classes blocked upstream | One real nested call | +| Effects can be derived mechanically from pre and post definitions and account for the diff | Self-report is unverifiable | Website unit tests with injected extra effects and hand edits | +| One-conversation-one-incarnation is enough for the proving scenario | A second conversation or principal needs the document | Decide at cut time; refuse otherwise | +| Visible names are unique enough for reviewer input, with id as escape hatch | A name-only query resolves the wrong element | Inventory duplicates; an ambiguous query must ask for the id | +| Exact lines plus declared basis are enough for a useful answer | Provenance exposed but review not helped | Blinded rubric | +| A synthetic persona yields a representative conversation | Provenance trivial on unique wording; fails on human messiness | Label sources; include the adversarial fixture with duplicate wording and rejected quotations (G12) | +| The proving scenario's consequential rule can be frozen before the run | Inventory gamed after generation | Freeze the rule and generate the inventory mechanically (G13) | +| Full-document emission per revision is affordable on the proving scenario's length | Cost forces coarser cadence | Measure tokens per revision in the tracer; structured patch is the later absorber | +| The interpreter, pane, tools, and probes fit one mission without unrelated fronts invalidating each other | Large implementation lands before a probe fails it | Step A gate before Step B (G18) | + +## Accepted constraints and guarded invariants + +- **STOP-THE-LINE — no false attribution.** A why answer never presents temporal context as evidence, a plan as effect, or absence as basis. Guard: safety assertions over the frozen inventory; negative controls. +- **STOP-THE-LINE — settled revision before mutation.** No mixed batch; explicit citation. Guard: co-batch and citation tests; tracer. +- **STOP-THE-LINE — transition record is the only statement of effect.** Guard: diff accounting and duplicate resolution tests. +- **STOP-THE-LINE — ids are never reused across epochs.** Guard: epoch ledger. +- **STOP-THE-LINE — external state is never laundered.** Guard: import dispositions retained until replaced. +- Flue history remains the canonical conversation log; no second log, capture ledger, or derivation store. Guard: dependency and state inventory. +- Markdown remains the semantic workpiece; revisions settle only through `update_workpiece`; the prepared signal remains tagged test-authored. Guard: resolver tests and public-schema inspection. +- Petrinaut owns canonical schemas, validation, mutations, document state; Brunch derives, never copies. Guard: structural alignment tests; stop on hand-copied fields. +- Core owns revision and query semantics; plugin owns operation semantics and locators; binding and app own acquisition and composition; the Petrinaut library gains no Brunch logic. Guard: topology tests. +- Stock assistant unchanged when Brunch is absent or unselected. Guard: host-mode test and witness. +- Single-principal local authorization named as a limit; retrieved history is untrusted evidence in the smallest range. Guard: ownership tests; answer inspection. +- No observer, automatic evidence fold, closed ontology, typed completion, assertion-card default, graph database, second agent or server, workflow engine, or general projection engine. Guard: dependency, tool, and state inventory. +- No content-bearing telemetry by default. Guard: trace inspection. +- Local posture only; "locally run," "locally verified image," and "remote replacement-safe" stay distinct claims. +- Paid provider evidence only under recorded budget. + +## Cross-cutting obligations + +- Workpiece sufficiency, projection fidelity, evidence provenance, revision integrity, Petrinaut semantic acceptance, deployed interaction quality, and visible failure, as stated in the spine's cross-mission obligations, hold over the constructed region and its why answers. +- Runtime migration matrix with removal gate (F15). +- Petrinaut user guide updated for the workpiece pane and why interaction; screenshot replacement prompted. +- Architecture docs: if a new folder forms a real architectural unit, add the local declaration and run the Petrinaut architecture-doc lint. +- Close report: each proof leaf's outcome, each probe's branch, the measured cadence and basis quality, the inventory numbers, the gates, and the flags carried to Missions 9 and 10. + +## Expected touched paths + +Tentative; Step A may shrink or redirect this manifest. + +```text +libs/@hashintel/brunch-agent/ +├── MISSION.md ~ cut-time authority; amended after the Step A gate +├── MISSION.next.md ~ carried flags only +├── docs/evidence/ + probe outcomes, tracer, Step B witnesses, adjudications, gates +├── packages/core/src/ + update_workpiece; revision and query semantics; passage policy +├── packages/core/src/client-tools.ts, _suspended/ - ask and sweep names and contract +├── packages/plugin-sdcpn/src/tools/ ~ carrier interpreter; scenario-selected admission; basis handling; locators +├── packages/plugin-sdcpn/src/flue.ts ~ mount by scenario; retire subsets after Mission 6 archives +├── packages/plugin-sdcpn/src/skills/sdcpn-modelling/ ~ construction posture; settled-revision and basis discipline +├── packages/binding-flue/src/ ~ history acquisition for why; archive lane only under the compaction fail branch +├── packages/transport-aisdk/src/ ~ transition-record projection; deduplication by call id; pane projection +└── evaluations/ + proving-scenario consequential rule, discriminator, rubric + +apps/brunch-agent/ +├── src/agents/chat-agent/ ~ compose update_workpiece and the why operation +├── src/capture/apply-sweep.ts - retired unless the compaction fail branch keeps the archive lane +├── src/evaluations/persona/ ~ workpiece recovery from tool parts; cadence and basis measurement +└── test/ + protocol, record, epoch, reconciliation, why integration + +apps/petrinaut-website/src/main/app/ +├── local-storage-demo/ ~ transition records; binding; pane; why rendering; remove ask/sweep handling +└── voice-interview/ - ask and sweep references + +libs/@hashintel/petrinaut/ +├── src/ui/views/Editor/panels/ai-assistant-panel* ? generic host surface only if the app cannot host the pane +└── docs/ ~ pane and why guidance + +libs/@hashintel/petrinaut-core/ ? only for an observed canonical contract defect; no provenance slot +``` + +## Fog-line + +- Compaction survival of `history()` records; the probe decides the branch. +- Fixture materialization route; the probe decides. +- Locator scheme under the passage policy; the probe decides. +- Carrier repair route: local interpreter or upstream Flue; the probe decides. +- Revision cadence and basis quality in a real conversation; measured in the tracer. +- Whether the optional evidence relation on `update_workpiece` is used by the model unprompted, and whether it drifts toward assertion cards under use. +- Whether one or two model-facing why tools serve the reviewer better. +- Token cost of full-document emission on the proving scenario, and when a structured patch earns its place. +- Which admitted classes misbehave at the provider boundary once the carrier carries fields. +- Whether the proving scenario needs cross-conversation document access. +- The proving scenario itself, its consequential rule, discriminator, and utility threshold: owner decisions at cut time, informed by consumer discovery. + +Resolve these at the real boundaries. If a choice changes accepted interaction policy, architectural ownership, or the claim, return it to the owner and amend the authority before continuing. + +## Stop or reorient + +Stop and surface evidence if: + +- the tracer cannot produce deterministic answers or explicit refusals without guessing, after one round of interaction adjustment; +- `update_workpiece` and a construction tool must share a batch to make the interaction work; +- a mutation cannot cite a settled revision because the model cannot reliably use the returned ids; +- the compaction probe fails and the only remedy is a new log rather than hardening the existing archive lane; +- the materialization probe fails and the prepared-projection route would make the why claim fixture-only; +- the carrier cannot be repaired locally without copying Petrinaut fields; record the upstream blocker; +- effects cannot be derived mechanically and the browser must self-report; +- a hand edit or external state is presented as attributed provenance; +- an id is reused across epochs; +- the constructor's basis is systematically circular or absent and no interaction change helps; withhold the explainability release; +- the utility gate cannot be met on any admitted class; withhold the explainability release; +- the pane or why operation requires Brunch logic in the Petrinaut library; +- a second conversation or principal must reach the document; that is Mission 9's owner and gate; +- the mission widens into repeat, changed input, retirement breadth, observer, remote durability, or reviewer authority; or +- the inventory rule is defined after the artifact is inspected. + +## Carried evidence and rejected alternatives + +- Mission 2 established the least capture pipe: explicit harness range, one exact envelope per user utterance, payload `{}`, stable ids on replay, no model extraction, no sweep tool. It did not establish typed semantics, a workpiece join, or durable product data. **Rejected for this mission's provenance (C8, G20):** Flue history already carries message ids and exact text; the store duplicated it under a second identity scheme. Its session-log archive lane survives as a separate capability with one named re-entry. +- Mission 3 accepted one Flue workpiece path and falsified real-model construction on the provider-visible carrier; the hermetic fixture proved packaging and canonical validation; the paid empty net is not a pair. **Consumed:** this mission repairs the carrier (B9, C11). +- Mission 4 supplied no full-run candidate. **Consumed:** the tracer is the first genuine full run, labelled by source. +- Mission 6 proved transport, least mutation, settled manifest, and resume. **Two admissions carried:** fixture-rigging (A3) and the fenced-block-to-tool change (A4). +- **Rejected: the honest prebuilt pair with a hand-authored derivation fixture** (B4, C1). Provenance now comes from constructor-declared basis and recorded transitions on a genuine conversation. +- **Rejected: temporal adjacency as causation** (F5, G3). "Latest revision before the mutation" is context, not basis; passage-to-turn ranges are context, not evidence, unless a revision-time relation is declared. +- **Rejected: a hash-only join between net and workpiece revisions** (F7, G9). Replaced by the transition record. +- **Rejected: storing provenance pointers in the Petrinaut document** (C6, B7). No slot exists; a file-level pointer waits for a Mission 11 consumer. +- **Rejected: the six-tool subset as a product surface** (C10) and **full-bundle admission by default** (F13, G15). Replaced by scenario-selected operations with canonically derived schemas. +- **Rejected: capture-fold, one-artifact merger, versioned assertion cards as default, closed kinds and slots, typed completion, per-capture losses, observer, graph database, general projection engine.** Their re-entry conditions live in the spine's backlog and standing locks. +- **Rejected: a side quest under Mission 6 or a separate probe mission for the probes** (G18). The two-step authority within this mission was chosen. +- Versioned assertion cards remain a possible future response only if the optional evidence relation on `update_workpiece` proves insufficient under observed revision strain; they are not the default. +- Typing a visible element name or id remains the accepted first interaction; click-to-chat and canvas-selection context are deferred unless textual identification proves ambiguous or burdensome (carried from the 2026-09-03 draft). +- The FE-1476 six-beat story remains the integrated floor, not the ceiling; the broader scenario portfolio remains unenumerated and must be named at cut time. + +## Cut conversion map + +The authority is cut in two steps, and the document shape must make it impossible to read Step B as authorized before the owner gate (H3). At the first cut, this draft is split rather than consumed whole: + +- **Step A → live `MISSION.md`.** The initial authority contains only Step A: the adversarial tracer, the four probes, the two measurements, the outcome classification table, and the exact oracles for those leaves. Its Deferred section points at the Step B packet without restating it. +- **Step B → this file, retitled "Draft Mission 7 — Step B amendment packet".** The Step B proof floor, the readiness gate, the Step B rows of the evidence table, and the construction body remain here under the non-authority warning, with a note that Step A's content has been consumed and lives only in `MISSION.md`. The spine's migration ledger records the split with a no-loss comparison. +- **After the owner gate**, the amendment converts the packet into the live contract in its own commit, and this file is removed under the lifecycle rules. + +| Live `MISSION.md` address at the first cut | Source in this draft | +| --- | --- | +| Status | New at cut: branch from the final Mission 6 close commit, FE-1573 re-title, two-step authority note, Mission 6 constraint amendment, paid-evidence budget | +| Imperative | Visible product advance, with the release note, demo script, previously impossible, deployment posture (local), and completion, stated as the mission's goal while the authority covers Step A only | +| Throughline | Boundary crossings and current throughline hypothesis, plus the Step A rows of Expected touched paths | +| Proof | Throughline proof floor Step A with its decision tables and outcome classification; the Step A rows of Candidate evidence and oracles; Verification approach for those leaves | +| Constraints | Accepted constraints and guarded invariants, Cross-cutting obligations, Inputs and joins | +| Fog-line | Fog-line, plus the open rows of the decision tables | +| Stop or reorient | Stop or reorient, plus the terminal-stop rows of the outcome classification | +| Deferred | A pointer to the Step B packet; the Mission 9 and 10 handoffs; the rejected alternatives with their re-entry conditions | + +### Pre-cut checklist (owner decisions, H2) + +Each item is recorded in the cut `MISSION.md` Status or Constraints before Step A runs: + +1. Mission 6 accepted, archived, and its close commit identified as the branch base (H1). +2. Proving scenario selected from the six cases. +3. Scenario-required Petrinaut operation classes, each citing the case requirement it discharges (3.8 of the spec is the candidate table). +4. Consequential-element rule, frozen before any run. +5. Behavioural discriminator derived from the workpiece. +6. Utility coverage threshold, with per-class expectations. +7. Acceptance of the one-conversation-one-document-incarnation binding for Mission 7. +8. Provider model, maximum calls, and spend ceiling. +9. FE-1573 title and description (re-titled 2026-09-04) confirmed against the cut. +10. Chris and Yannis discovery performed, or explicitly dispositioned by the owner as not a pre-cut dependency. + +Before cutting, also re-read the four design-evidence documents and the three reviews' evidence lists, and inspect the real boundary for each cold-start read. diff --git a/libs/@hashintel/brunch-agent/docs/mission-drafts/9-traceable-projection.md b/libs/@hashintel/brunch-agent/docs/mission-drafts/9-traceable-projection.md index 879211b56d3..90a2ef9e7f2 100644 --- a/libs/@hashintel/brunch-agent/docs/mission-drafts/9-traceable-projection.md +++ b/libs/@hashintel/brunch-agent/docs/mission-drafts/9-traceable-projection.md @@ -1,341 +1,283 @@ -# Draft Mission 9 — Automatic traceable projection of one meaningful region +# Draft Mission 9 — Repeatable projection breadth over the accepted lineage seam > Draft cluster only. Not execution authority. Do not implement until this cluster is re-evaluated and cut into `MISSION.md`. +Recut on 2026-09-04. The construction half of the former Mission 9 (schema-carrier repair, the first real nested mutation, one meaningful region built by the model, stable ids, and the positive why over a generated element) moved into the consolidated [Mission 7](7-explainable-construction.md), because the owner chose fully connected parts over thin tracers and because the provenance design showed that lineage only exists when the model actually constructs. This draft keeps what "repeatable" first makes load-bearing: unchanged repeat, changed input, deletion and retirement, concurrent user change, cross-conversation document access, broader schema classes, and the per-action versus batch decision if Mission 7 has not settled it. The reasoning is recorded in the [decision log](../evidence/design/provenance-and-tooling-decision-log-2026-09-04.md) entries F12 and G16 and the [follow-up review](../evidence/design/provenance-by-lineage-follow-up-review-2026-09-04.md) items 16 and 18. + ## Cold-start reads -- [FE-1438](https://linear.app/hash/issue/FE-1438/project-an-evidence-backed-workpiece-into-a-traceable-live-sdcpn) — tracker projection for this future branch mission; the eventual branch `MISSION.md` remains execution authority. +- [FE-1438](https://linear.app/hash/issue/FE-1438/project-an-evidence-backed-workpiece-into-a-traceable-live-sdcpn) — tracker projection for this future branch mission; the eventual branch `MISSION.md` remains execution authority. Its description predates the 2026-09-04 recut and must be re-titled to breadth and repeat behaviour with owner approval before the cut. A fresh builder must resolve these authorities and evidence before choosing a mechanism: -- [`../../MISSION.md`](../../MISSION.md) — current closure pointer. Mission 9 may be cut only after Mission 7 validly closes its accepted join and a new owner-authorized mission replaces that pointer as sole execution authority. -- [`../../MISSION.next.md`](../../MISSION.next.md) — compact future spine, FE-1476 floor, cross-mission obligations, standing locks, and current Mission 10 handoff. -- [`6-resumable-workpiece-petrinaut-fixture.md`](6-resumable-workpiece-petrinaut-fixture.md) and [`7-capture-backed-review.md`](7-capture-backed-review.md) — provisional viability and provenance predecessors. At cut time replace assumptions with their accepted evidence, exact current workpiece/derivation seam, and real browser mutation behavior. -- [`../mission-archive/3-structurally-typed-runbook-to-headless-pn.md`](../mission-archive/3-structurally-typed-runbook-to-headless-pn.md) and [`../evidence/implementations/fe-1525-headless-runbook-pn.md`](../evidence/implementations/fe-1525-headless-runbook-pn.md) — accepted workpiece leg, canonical callback fixture, provider-visible nested-schema failure, vacuous empty-net result, and explicit next-boundary decision. -- [`../specs/petrinaut-batched-construction-tools.md`](../specs/petrinaut-batched-construction-tools.md) — candidate `pn_read`/`pn_edit` design input and its corrected transaction, outcome, identity, carrier, and ownership constraints. It does not select batching; this mission repairs the known single-action carrier first and admits a batch only if subsequent probes establish it as the least sufficient mechanism. -- [`apps/brunch-agent/src/evaluations/runbook/headless-petrinaut-client.ts`](../../../../../apps/brunch-agent/src/evaluations/runbook/headless-petrinaut-client.ts), [`apps/brunch-agent/test/headless-petrinaut-client.test.ts`](../../../../../apps/brunch-agent/test/headless-petrinaut-client.test.ts), and [`../../packages/plugin-sdcpn/test/construction-tools.test.ts`](../../packages/plugin-sdcpn/test/construction-tools.test.ts) — current bounded six-tool callback route and its limits. -- [`../../packages/plugin-sdcpn/src/tools/petrinaut-construction.ts`](../../packages/plugin-sdcpn/src/tools/petrinaut-construction.ts) and [`../../packages/plugin-sdcpn/src/flue.ts`](../../packages/plugin-sdcpn/src/flue.ts) — the failed Valibot `looseObject({})` + `rawTransform` provider bridge, canonical runtime delegation, conditional construct-only mounting, and exact current tool subset. +- [`../../MISSION.md`](../../MISSION.md) — the current branch's live authority. Mission 9 may be cut only after Mission 7 validly closes its construction-and-explanation stratum and a new owner-authorized mission replaces the then-current branch authority. +- [`../../MISSION.next.md`](../../MISSION.next.md) — compact future spine, FE-1476 floor, cross-mission obligations, standing locks, the 2026-09-04 planning migration matrix, and the current Mission 10 handoff. +- [`7-explainable-construction.md`](7-explainable-construction.md) — the consolidated predecessor at cut-level detail: settled-revision protocol, declared basis, transition record, identity epochs, passage policy, document reconciliation, recorded roles, scenario-selected tool admission, and its readiness gate. At cut time replace this draft pointer with Mission 7's accepted archive and close evidence, and consume the actual seam it shipped. +- [`../evidence/design/provenance-by-lineage-mini-spec-2026-09-04.md`](../evidence/design/provenance-by-lineage-mini-spec-2026-09-04.md) and the two reviews beside it — the design rationale, the four contracts, the probe decision tables, and the rejected alternatives. Design evidence, not authority. +- [`../mission-archive/3-structurally-typed-runbook-to-headless-pn.md`](../mission-archive/3-structurally-typed-runbook-to-headless-pn.md) and [`../evidence/implementations/fe-1525-headless-runbook-pn.md`](../evidence/implementations/fe-1525-headless-runbook-pn.md) — accepted workpiece leg, canonical callback fixture, the provider-visible nested-schema failure that Mission 7 now retires, and the vacuous empty-net warning. +- [`../specs/petrinaut-batched-construction-tools.md`](../specs/petrinaut-batched-construction-tools.md) — candidate `pn_read`/`pn_edit` design input and its corrected transaction, outcome, identity, carrier, and ownership constraints. It does not select batching. Mission 7 repairs the single-action carrier; this mission admits a batch only if the probes below establish it as the least sufficient mechanism for repeat and changed-input projection. +- [`../../packages/plugin-sdcpn/src/tools/petrinaut-construction.ts`](../../packages/plugin-sdcpn/src/tools/petrinaut-construction.ts), [`../../packages/plugin-sdcpn/src/flue.ts`](../../packages/plugin-sdcpn/src/flue.ts), and [`../../packages/plugin-sdcpn/test/construction-tools.test.ts`](../../packages/plugin-sdcpn/test/construction-tools.test.ts) — the tool factory, mounting seams, and alignment guards as Mission 7 leaves them. - [`../../../petrinaut-core/src/ai.ts`](../../../petrinaut-core/src/ai.ts), [`../../../petrinaut-core/src/action-schemas.ts`](../../../petrinaut-core/src/action-schemas.ts), [`../../../petrinaut-core/src/schemas/entity-schemas.ts`](../../../petrinaut-core/src/schemas/entity-schemas.ts), and [`../../../petrinaut-core/src/ai.test.ts`](../../../petrinaut-core/src/ai.test.ts) — canonical Petrinaut AI schemas, mutation callbacks, ids, nested types, and JSON Schema evidence. These are the authority; Brunch prose or copied field catalogs are not. -- [`../../../petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.tsx`](../../../petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.tsx) and [`../../../petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.test.tsx`](../../../petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.test.tsx) — current `useChat` / `onToolCall`, canonical input parsing, mutation execution, diagnostics sequencing, dynamic interactive tools, and visible failure surface. -- [`apps/brunch-agent/src/http/petrinaut-chat.ts`](../../../../../apps/brunch-agent/src/http/petrinaut-chat.ts), [`apps/brunch-agent/src/conversation/client-tools.ts`](../../../../../apps/brunch-agent/src/conversation/client-tools.ts), and [`apps/brunch-agent/test/petrinaut-chat.test.ts`](../../../../../apps/brunch-agent/test/petrinaut-chat.test.ts) — real panel-to-Flue transport and browser callback resume. -- [`../../packages/plugin-sdcpn/src/skills/sdcpn-modelling/SKILL.md`](../../packages/plugin-sdcpn/src/skills/sdcpn-modelling/SKILL.md), [`../../packages/plugin-sdcpn/src/skills/sdcpn-modelling/templates/workpiece.md`](../../packages/plugin-sdcpn/src/skills/sdcpn-modelling/templates/workpiece.md), the skill's construction/check references, and the exact source/workpiece versions eventually selected by Mission 7 or a predecessor addendum — target-formalism guidance and current workpiece contract. Mission 4 produced no full-run candidate; do not treat branch-tip resources or probe evidence as one. -- Commit `157730cc5a214dd9c543e8d95c7193a219c48aef` on deployment branch `ln/fe-1569-brunch-agent-deployment`, read with `git show`, especially `libs/@hashintel/brunch-agent/docs/evidence/implementations/mission-8-deployment-handoff.md`, plus its `MISSION.md`, application persistence/telemetry files, and open infrastructure gates. Mission 9 consumes the actual deployed contract inherited through Mission 7; it must not imply the branch achieved remote deployment. -- [`../../../petrinaut/docs/ai-assistant.md`](../../../petrinaut/docs/ai-assistant.md), [`../../../petrinaut/docs/drawing-a-net.md`](../../../petrinaut/docs/drawing-a-net.md), and affected simulation/formalism guidance. User-visible projection behavior must update the user guide and prompt screenshot replacement where applicable. +- [`../../../petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.tsx`](../../../petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.tsx) and its test — current `useChat` / `onToolCall`, canonical input parsing, mutation execution, and visible failure surface. +- [`../../packages/transport-aisdk/src/client-tool-history.ts`](../../packages/transport-aisdk/src/client-tool-history.ts) and the Mission 7 transition-record contract — how browser results are correlated and deduplicated by call id. +- [`../../packages/plugin-sdcpn/src/skills/sdcpn-modelling/SKILL.md`](../../packages/plugin-sdcpn/src/skills/sdcpn-modelling/SKILL.md), [`templates/workpiece.md`](../../packages/plugin-sdcpn/src/skills/sdcpn-modelling/templates/workpiece.md), and [`references/pn-construction.md`](../../packages/plugin-sdcpn/src/skills/sdcpn-modelling/references/pn-construction.md) — construction posture as Mission 7 leaves it. +- [`../reference/architecture/flue-routing.md`](../reference/architecture/flue-routing.md) — the per-conversation versus cross-conversation state distinction that governs the document-scoped owner this mission may need. +- Commit `157730cc5a214dd9c543e8d95c7193a219c48aef` on `ln/fe-1569-brunch-agent-deployment`, especially `libs/@hashintel/brunch-agent/docs/evidence/implementations/mission-8-deployment-handoff.md` — the locally verified application contract and the still-open infrastructure handoff. Mission 9 names local posture unless a Mission 8 successor has landed. +- [`../../../petrinaut/docs/ai-assistant.md`](../../../petrinaut/docs/ai-assistant.md) and [`drawing-a-net.md`](../../../petrinaut/docs/drawing-a-net.md) — user-visible projection behaviour must update the user guide and prompt screenshot replacement. -The accepted bounded workpiece region, Mission 7 pair, derivation representation, generated-region semantics, and Mission 10 correction are not yet canonical paths. They must be named from accepted predecessor evidence when this draft is cut. +The accepted Mission 7 region, proving scenario, transition-record shape, and passage policy are not yet canonical paths. Name them from accepted predecessor evidence when this draft is cut. ## Visible product advance -**Release note:** Brunch builds a recognisable part of the net itself from the conversation, and can still explain every piece it built. - -**Demo script (no engineer present):** open the demo workpiece in the Petrinaut Brunch panel, on the deployment posture named at cut time. Ask Brunch to model the named region. Watch a non-empty region appear in the live net that a person who knows the process recognises as the thing that was discussed. Ask why about one of the generated elements and get the workpiece meaning and quoted conversation evidence back, exactly as for the prebuilt net in Mission 7. - -**Previously impossible:** every net in the demo was prebuilt by a person; Brunch's only real-model construction attempt produced a parser-valid but empty net. +**Release note:** ask Brunch to model the next part of the process and the net grows without disturbing what was already built; ask again and nothing duplicates. -Consequential generated elements carry stable caller-supplied ids and derivations that make Mission 7's why operation resolve back to the current workpiece and its exact retained evidence. +**Demo script (no engineer present):** open the Mission 7 demo conversation and its net in the Petrinaut Brunch panel, on the deployment posture named at cut time. Ask Brunch to model the part of the process the workpiece already describes but the net does not yet contain. Watch a non-empty region appear that a person who knows the process recognises. Ask the same thing again and confirm nothing duplicated or moved. Change one fact in the workpiece through the conversation, ask Brunch to bring the net up to date, and confirm only the affected elements changed while every other id and shape stayed put. Ask why about one generated element after the change and get the current-state answer, not the original one. -The region must be visually inspectable and operationally meaningful: it must exercise the canonical coloured type, parameter, place, transition, and arc contracts required by the selected process meaning. A toy place/transition pair, empty net, parser-only artifact, headless-only result, or one successful nested tool call is not the visible advance. Repeat, changed-input, and failure-class obligations harden this line at the readiness gate; they do not define whether the first line exists. +**Previously impossible:** Mission 7 proves Brunch can build and explain one region once. Nothing yet shows that doing it again is safe, that a changed workpiece yields a bounded change, or that removed meaning retires elements honestly. -Provider-schema repair, the transaction probe, and the per-action versus batch decision are internal sequencing for this mission and are recorded under the throughline hypothesis below. They are not the advance and must not be presented as progress to a product manager. +Repeat, changed-input, and retirement behaviour are the visible advance. Provider-schema classes beyond Mission 7's proving scenario, the per-action versus batch decision, and the document-scoped lineage owner are internal sequencing recorded under the throughline hypothesis; they are not the advance. -**Completion:** the mission is done when a product manager can run the demo script at the readiness gate below, not when the first nested tool call succeeds. +**Completion:** the mission is done when a product manager can run the demo script at the readiness gate below, not when the first unchanged repeat is idempotent. ## Contract stratum -Close the **automatic projection stratum for one named meaningful workpiece region and the canonical Petrinaut mutation classes it uses**. +Close the **repeatable projection stratum over the accepted Mission 7 lineage seam for the same document incarnation**: unchanged repeat, changed input, deletion and retirement, concurrent user change, and the schema classes the extended region requires. The bounded stratum includes: -- current workpiece-region identity and revision; -- canonical Petrinaut coloured types and nested elements used by the region; -- canonical net-level parameters used by the region; -- places, transitions, input/output arcs, and any executable fields required by the selected semantics; -- stable caller-supplied ids and explicit treatment of additions, changes, unchanged elements, and removals if the selected changed-input case requires them; -- derivations from every consequential generated element to current workpiece material, evidence references, projection rationale, assumptions/defaults/omissions/losses, and projector identity/version; -- rejection, bounded repair, unsupported/default behavior, and visible partial failure; -- repeated projection and changed-input projection against current net state; -- semantic correspondence and visual inspectability in the real panel; and -- the exact predecessor provenance operation and durable state boundary. +- unchanged repeat against current net state: no duplicate elements, no id churn, no unrelated mutation, attempt history only; +- changed input: identity-preserving change for touched elements, stable ids and definitions for untouched ones, an explicit impact boundary, and a visible reason where widening is legitimate; +- deletion and retirement: identity epochs closed rather than ids reused; retired elements keep origin and change history and answer why with a retired disposition; +- concurrent or hand change during projection: stale-base refusal per the Mission 7 transition record, external-import semantics, and never a silent overwrite; +- cross-conversation document access, if the proving scenario needs it: a document-scoped durable owner for shared current-workpiece and lineage indexes, replacing Mission 7's one-conversation-one-incarnation binding with its own identity and authorization rule; +- every canonical schema and mutation class the extended region uses, admitted per the scenario-selected rule with canonically derived schemas; +- the per-action versus bounded-batch decision, only if Mission 7 left it open and repeat or changed-input projection exposes a measurable need; +- basis and transition records for every generated, changed, and retired element, and the current-state why answer over them. -Stratum closure is over the named region, accepted scenario/peer set, and mutation classes actually used—not all Petrinaut tools, all SDCPN semantics, or the full optimisation handoff. Mission 11 owns broadening to its accepted full handoff scenario after Mission 10 proves bounded reviewer revision. - -Petrinaut owns canonical schemas and mutations. The projector may select and sequence them, but no Brunch schema copy becomes a parallel authority. The current Markdown workpiece is the semantic input. Captures remain evidence referenced by the workpiece; neither captures nor the full transcript are semantic projection IR. +Stratum closure is over the named extended region, accepted peer set, and mutation classes actually used, not all Petrinaut tools or the full optimisation handoff. Mission 10 owns reviewer authority; Mission 11 owns broadening to its accepted handoff scenario. ## Boundary crossings and current throughline hypothesis ```text -accepted Mission 7 workpiece/prebuilt pair/provenance seam - → select one bounded current workpiece region and its expected operational meaning - → person requests projection in the deployed Petrinaut Brunch panel - → AI SDK transport dispatches to the Flue ChatAgent - → projector reads the current workpiece region, current net, and accepted derivation state - → Brunch/Flue exposes mechanically preserved provider-visible schemas from canonical Petrinaut Zod contracts - → real model emits canonical caller-supplied ids and nested mutation inputs through the selected per-action or bounded-batch surface - → Flue suspends on client tools - → Petrinaut panel parses inputs with canonical schemas and executes canonical mutations through the selected, proved transaction boundary - → client-tool results resume the same Flue turn - → panel visibly shows the meaningful generated region - → Mission 7 why operation resolves generated element → derivation → workpiece → captures +accepted Mission 7 conversation, settled workpiece revisions, transition records, identity epochs + → person asks, in the Petrinaut Brunch panel, to model the next region or bring the net up to date + → Mission 5 browser Flue transport dispatches to the ChatAgent + → agent reads the current workpiece revision from state, the live document through getLatestNetDefinition, and its own lineage through the why lookups + → agent emits a projection plan: intended effects per element with basis locators, stable caller-supplied ids, and expected base hash + → each mutation request cites the settled revision and carries declared basis; the turn terminates on browser tools + → Petrinaut panel validates against the observed pre-apply hash, executes canonical mutations, returns transition records + → agent reconciles effects against the plan; unanticipated effects become basis-absent; stale outcomes refuse + → repeat: the plan finds every intended effect already present and records attempt history only + → changed input: the plan names touched elements, untouched elements, retirements, and any widening, and applies only that + → why over a generated, changed, or retired element resolves through current-state semantics ``` -Authority and actor crossings: +Actor and authority crossings: -- **Workpiece → projector:** semantic interpretation occurs here and is recorded as rationale. The transcript is not primary input and captures are not folded into a semantic model. -- **Petrinaut Zod → provider schema:** schema exposure must preserve arrays, nested objects, refinements that can be represented, descriptions, and required/optional structure mechanically. Provider limitations and any lossy conversion are explicit. -- **Provider → Flue runtime:** provider arguments cross Flue's supported tool-schema interface. Runtime canonical validation remains decisive even when provider schema accepts an approximation. -- **Flue server → Petrinaut browser:** client-tool suspension/resume carries mutation requests/results through the existing AI SDK panel contract. -- **Petrinaut schema → mutation operation → live document:** canonical input parsing precedes canonical mutation. Provider-envelope rejection and canonical per-step rejection are distinct. A non-throwing action may still be a no-op, so operation success requires an explicit outcome or verified postcondition; callback success is not semantic success. -- **Generated element → Mission 7 provenance:** the predecessor why operation consumes the same stable seam. A fixture-specific translation fails the join. -- **Application → deployed substrate:** workpiece, derivation, Flue conversation, and current net identity must survive the accepted Mission 7/Mission 8 replacement boundary. +- **Workpiece to projector:** semantic interpretation occurs here and is recorded as declared basis; the transcript is not primary input. +- **Projector to identity:** stable caller-supplied ids and identity epochs are load-bearing; a retired id is never reused. +- **Petrinaut Zod to provider schema:** Mission 7's repaired carrier; this mission adds classes, never a copy. +- **Browser to record:** the transition record is the only admissible statement of what happened; the plan is not. +- **Conversation to document:** if a second conversation or principal reaches the same document, the document-scoped owner arbitrates; otherwise Mission 7's binding stands and cross-conversation access refuses. -Internal sequencing hypothesis: the first in-mission tracer is narrower than the visible advance. Repair the provider-visible nested schema path enough for one real model call to emit and apply a single canonical nested input such as `addType.elements`. That tracer retires the Mission 3 blocker; it does not complete Mission 9 or select batching. Next, a bounded core transaction probe must establish rollback, readonly/extensions parity, indexed failure, and honest no-op outcomes before a five-action batch is tried through Flue and the production client path. Mission 9 selects the batch only if that comparison shows a material advantage over per-action tools without weakening feedback, identity, or failure visibility. +Internal sequencing hypothesis: first the unchanged repeat against the Mission 7 net, because it is the cheapest discriminator of duplicate and churn behaviour; then one changed input with an expected impact set frozen in advance; then one retirement; then, only if the extended region needs it, additional schema classes and the batch comparison from the batched-tools spec (bounded core transaction probe, then five-action production-path comparison against per-action tools). ## Throughline proof floor -The smallest deployed end-to-end proof must observe all of the following: +The smallest deployed end-to-end proof must observe all of the following on the accepted Mission 7 conversation and document: -1. A person requests projection of one named bounded workpiece region through the real Petrinaut Brunch panel. -2. The resulting automatically projected live region is non-empty, visually inspectable, and semantically corresponds to the selected operational meaning through the required type, parameter, places, transitions, and arcs. -3. Every consequential generated element has a stable caller-supplied id and derivation to the current workpiece, evidence references, and projection rationale, including any assumption or loss. -4. Mission 7's why operation resolves at least one generated element through that derivation. +1. An unchanged repeat request produces no canonical change, no duplicate element, no id churn, and one attempt-history record per intended effect. +2. One changed input produces a bounded canonical change whose applied effects equal the frozen expected impact set, with every untouched id and definition unchanged. +3. One retirement closes an identity epoch, leaves origin and change history queryable, and returns a retired disposition on why. +4. Why over one generated, one changed, and one retired element resolves through current-state semantics without fixture translation. -This floor is the first internal milestone, not mission completion: one automatic traceable meaningful region and the positive generated-element provenance link. It does not close repeat/change behavior, schema-class breadth, stale or partial states, repair exhaustion, derivation atomicity, visible failure, full-net generation, arbitrary revision, Mission 10 reviewer authority, an observer, simulation fidelity, or the Mission 11 optimisation package. Those first seven obligations belong to this mission's readiness gate and stratum closure, not to acknowledgment that the working line exists. +This floor is the first internal milestone, not completion. It does not close concurrent change, cross-conversation access, broader schema classes, the batch decision, or the accepted peer set. ## Readiness ratchet ```text -Mission 7 deployed capture-backed why over a closed prebuilt-pair provenance stratum -→ inherited provenance/durability closure required by automatic generation -→ single-action provider-visible nested-schema risk tracer -→ bounded transaction/outcome probe → per-action versus batch mechanism decision -→ meaningful live bounded region with stable ids, derivations, and positive why +Mission 7 construction-and-explanation stratum closed on one conversation and document +→ inherited: settled-revision protocol, declared basis, transition record, identity epochs, passage policy, reconciliation, recorded roles +→ unchanged repeat → changed input → retirement → current-state why → readiness gate -├─ close repeat/change, schema/mutation breadth, stale/partial state, repair, derivation, and failure obligations -├─ admit a stable current-region projection seam and selected correction into Mission 10 -└─ leave full handoff breadth, broad regeneration, observer consolidation, and optimisation unearned +├─ close concurrent change, cross-conversation access, schema-class breadth, batch decision, peer set +├─ admit a stable region identity, impact-boundary semantics, and one selected correction into Mission 10 +└─ leave reviewer authority, observer consolidation, full handoff breadth, and optimisation unearned ``` ### Inherited stratum closure -Mission 9 requires accepted evidence, not draft promises, for: - -- one current Mission 7 workpiece revision and stable region/passage references; -- exact evidence references and a durable, owner-bound capture/workpiece/derivation boundary; -- a why operation that resolves prebuilt element → derivation → workpiece → captures and visibly refuses stale/broken/cross-owner paths; -- a selected non-empty prebuilt pair whose consequential elements have closed provenance dispositions; -- the real deployed panel/AI SDK/Flue/client-tool path and stock-assistant coexistence; -- the actual Mission 8/Mission 7 persistence, identity, telemetry, and replacement contract. - -If the predecessor seam cannot accept a generated derivation without fixture translation, or Mission 7 did not close durability and negative provenance behavior, Mission 9 must stop at inherited closure. Automatic projection cannot turn a provisional provenance route into a dependable base by using it. +Mission 9 requires accepted evidence, not draft promises, for everything Mission 7 closed: the settled-revision protocol; declared operation-level basis with intended-effect mapping; the independently verifiable transition record; identity epochs; passage identity policy; live-document reconciliation; recorded roles; the one-conversation-one-incarnation binding; the scenario-selected tool set with a repaired carrier; the compaction posture and fixture materialization route; the safety and utility gates. If Mission 7 shipped a different representation, consume that actual contract or return here for re-cutting. Automatic repetition cannot turn a provisional line into a dependable base by using it. ### Readiness gate after the new throughline -For the named region, enumerate and close: +For the extended region, enumerate and close: -- every canonical schema and mutation class used, including nested arrays/objects, optional/null fields, ids, descriptions, runtime-only refinements, error messages, and actions that can no-op without throwing; -- provider-schema rejection versus canonical per-step rejection, repair budget, duplicate tool delivery, client-tool resume, timeout, abort, and partial sequence failure; -- if batching is selected, its supported handle scope, rollback contract, effective readonly and disabled-extension parity, per-step applied/no-op/failure outcomes, and state postconditions; +- unchanged repeat under duplicate delivery, retry, and reload; +- changed input for each accepted change class: added meaning, changed meaning, removed meaning, and legitimate widening; +- retirement semantics, including elements referenced by executable code, scenarios, or metrics; +- concurrent user mutation and hand edit during projection: stale-base refusal, external import, and no silent overwrite; +- cross-conversation and second-principal access to the same document, or an explicit refusal and its owner; +- every canonical schema and mutation class used by the extended region, including nested arrays and objects, optional and null fields, runtime-only refinements, and actions that can no-op without throwing; +- provider-schema rejection versus canonical per-step rejection, repair budget, timeout, abort, and partial sequence failure; +- if batching is selected: supported handle scope, rollback contract, readonly and disabled-extension parity, per-step outcomes, and state postconditions; - unsupported consequential defaults and every assumption, inference, omission, or construction-opened loss; -- semantic correspondence of type elements, parameters, places, transitions, arc direction/type/weight, executable code where used, and canvas-visible structure; -- unchanged repeat, changed input, stale workpiece revision, stale current net, partial prior projection, and concurrent/user change behavior; -- stable ids for unchanged elements, deliberate ids for new elements, deletion/retirement behavior where exercised, and absence of unrelated churn; -- derivation completeness, atomicity relative to applied state, lineage/change account, stale-link refusal, and no successful derivation for rejected mutation; -- visible partial failure and recovery/retry without duplicate state; -- path isolation from the stock assistant and from unrelated net regions; -- latency, usage, transcript fallback, compaction/recovery, and deployed replacement behavior where the real path crosses them. - -Mission 10 may inherit: +- semantic correspondence of the extended region, with the behavioural discriminator carried from Mission 7 rerun after each change; +- visible partial failure and recovery without duplicate state; +- path isolation from the stock assistant and unrelated regions; +- latency, usage, compaction, and replacement behaviour where the real path crosses them. -- one accepted bounded workpiece-region identity and current revision; -- one generated live net neighborhood with stable unrelated ids; -- one traceable projection operation and explicit impact boundary; -- one selected operational distinction whose correction has observable but bounded consequences; -- derivation lineage/change-account semantics that can represent retained, changed, added, retired, unsupported, and widened-impact dispositions. +Mission 10 may inherit: one accepted region identity and current revision; one generated neighbourhood with stable unrelated ids; the impact-boundary semantics; one selected operational distinction whose correction has observable but bounded consequences; and change-account semantics able to represent retained, changed, added, retired, unsupported, external, and widened dispositions. **Owner:** Mission 10. **Re-entry gate:** an explicitly authorized reviewer supplies new evidence in 3–5 focused turns, a foreground phase-boundary synthesis creates an inspectable revision citing reviewer message ids, and the same projector applies a scoped patch or explicit refusal without unrelated churn. **Oracle:** Mission 10's deployed correction, qualification, coexistence, conflict matrix and stable-unrelated-id check. -**Owner:** Mission 10. **Re-entry gate:** an explicitly authorized reviewer supplies new evidence in 3–5 focused turns, a foreground phase-boundary synthesis creates an inspectable revision, and the same projector applies a scoped patch or explicit refusal without unrelated churn. **Oracle:** Mission 10's deployed correction/qualification/contextual-coexistence/conflict matrix and stable-unrelated-id check. - -Do not defer provider-schema fidelity, repeated projection, changed-input identity, derivation atomicity, semantic correspondence, or visible partial failure to Mission 10: Mission 9's automatic projection claim already depends on them. +Do not defer repeat idempotence, changed-input identity, retirement, or concurrent-change refusal to Mission 10: Mission 9's repeatable claim already depends on them. ## Candidate evidence and oracles | Claim leaf | Existing evidence or candidate oracle | | --- | --- | -| Canonical callback path can build a non-empty parser-accepted type/parameter/place/transition/arc fixture | Existing `apps/brunch-agent/test/headless-petrinaut-client.test.ts`, test `constructs a parser-accepted document through the bounded callbacks`. Run `yarn workspace @apps/brunch-agent test:unit`. This is inner headless evidence only. | -| Current plugin exposes exactly the bounded six-tool subset and delegates runtime acceptance/rejection to canonical Zod | Existing `libs/@hashintel/brunch-agent/packages/plugin-sdcpn/test/construction-tools.test.ts`, tests `exposes exactly the bounded canonical subset`, `mechanically carries the canonical input contract`, and `delegates accepted and rejected inputs to Petrinaut's Zod schemas`. Run `yarn workspace @hashintel/brunch-agent-plugin-sdcpn test:unit`. | -| Petrinaut tool metadata aligns with canonical schemas; JSON Schema for representative tools is AI-friendly; callbacks validate before applying | Existing `libs/@hashintel/petrinaut-core/src/ai.test.ts`, suite `Petrinaut AI core exports`, including `tool metadata stays aligned with input schemas and has no execute`, `addArc exposes an AI-friendly object input schema`, and callback tests. Run `yarn workspace @hashintel/petrinaut-core test:unit --run`. | -| Real panel parses canonical mutation input and executes callbacks through `onToolCall` | Existing source in `libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.tsx`; current test covers dynamic follow-up, not automatic construction. **ORACLE GAP:** bind a panel integration test to the actual selected mutation sequence. | -| Real server/client suspension and resume work | Existing `apps/brunch-agent/test/petrinaut-chat.test.ts`, production-door test driven by `petrinaut-chat.integration.ts`. It currently mounts no construction tools on ordinary panel conversations; that negative assertion is a guard, not Mission 9 success. | -| Mission 3 provider-visible bridge failed specifically on nested `addType.elements`, 0-for-9, and empty parser success was vacuous | Existing `docs/evidence/implementations/fe-1525-headless-runbook-pn.md`; inspect the paid-run artifact named there. | -| Live provider accepts the mechanically preserved nested canonical schema | **ORACLE GAP:** no existing real-model call proves this. Resolve first with one budgeted single-action `addType.elements` tracer using the exact provider/model/schema artifact and retain raw tool call/rejection evidence. A successful call does not select batching or complete the mission. | -| A bounded batch can preserve canonical semantics and improve the selected path | **ORACLE GAP:** follow the three probes in `docs/specs/petrinaut-batched-construction-tools.md`: single-action carrier; first-class core transaction/outcome contract; then five-action production-path comparison against per-action tools. Batch selection requires rollback, readonly/extensions parity, indexed failure, no-op honesty, supported-handle scope, production client routing, and material measured benefit. | -| Selected meaningful region exercises required type/parameter/place/transition/arc semantics | **ORACLE GAP:** region and scenario portfolio are not selected. Resolve with a frozen workpiece-region fixture, expected semantic account, canonical resulting definition, and human visual inspection. | -| Mission 7 why resolves generated elements through the same derivation seam | **ORACLE GAP:** Mission 7 is provisional and no generated derivation exists. Resolve through the real deployed why operation without fixture-specific conversion. | -| Unchanged repeat is idempotent and changed input yields bounded identity-preserving change | **ORACLE GAP:** no projection operation exists. Bind to exact current-net before/after definitions, mutation log, derivation diff, and stable-id assertions when implemented. | -| Rejection/repair and partial failure do not advance canonical or derivation state incorrectly | Canonical mutation rejection is locally evidenced by `headless-petrinaut-client.test.ts` and plugin schema tests. **ORACLE GAP:** sequence-level atomicity/partial-state policy and visible deployed recovery are unresolved. | -| Semantic correspondence exceeds parser acceptance | **ORACLE GAP:** establish a workpiece-specific human adjudication; optionally admit a simulation-backed check only if it discriminates the selected meaning cheaply. Parser `ok: true` is explicitly insufficient. | -| Mission 10-ready selected correction has bounded observable consequences | **ORACLE GAP:** choose the correction with the owner only after the generated region exists; record expected retained/changed ids and behavior before Mission 10 is cut. | -| Deployment durability/identity/telemetry survive projection | **ORACLE GAP:** consume Mission 7 accepted remote evidence. The Mission 8 branch handoff alone stopped before infrastructure/replacement proof. | +| Canonical callbacks build a non-empty parser-accepted fixture | Existing `apps/brunch-agent/test/headless-petrinaut-client.test.ts`, test `constructs a parser-accepted document through the bounded callbacks`. Inner headless evidence only. | +| Petrinaut tool metadata aligns with canonical schemas; callbacks validate before applying | Existing `libs/@hashintel/petrinaut-core/src/ai.test.ts`, suite `Petrinaut AI core exports`. | +| Repaired carrier admits nested inputs; scenario-selected classes are mounted | Mission 7 close evidence; cite its exact tests at cut time. | +| Transition records are independently verifiable; duplicates resolve to unknown | Mission 7 close evidence; cite at cut time. | +| Unchanged repeat is idempotent | **ORACLE GAP:** bind to exact before/after canonical definitions, the transition-record log showing attempt history only, and a stable-id assertion when implemented. | +| Changed input yields bounded identity-preserving change | **ORACLE GAP:** freeze the expected impact set before the run; compare applied effects, untouched ids, and definitions. | +| Retirement closes an epoch and answers why | **ORACLE GAP:** bind to an epoch ledger assertion and a why answer with retired disposition. | +| Concurrent or hand change refuses rather than overwrites | **ORACLE GAP:** inject a hand edit between plan and apply and assert stale refusal plus external-import disposition. | +| Cross-conversation access is arbitrated or refused | **ORACLE GAP:** decide at cut time whether the proving scenario needs it; if so, bind a second-conversation probe to the document-scoped owner. | +| A bounded batch improves repeat or changed-input projection | **ORACLE GAP:** follow the three probes in `docs/specs/petrinaut-batched-construction-tools.md`; batch selection requires rollback, readonly and extension parity, indexed failure, no-op honesty, supported-handle scope, production client routing, and material measured benefit. | +| Semantic correspondence of the extended region | **ORACLE GAP:** workpiece-specific human adjudication plus the Mission 7 behavioural discriminator rerun after each change. | +| Mission 10-ready correction | **ORACLE GAP:** choose with the owner after the extended region exists; record expected retained and changed ids and behaviour before Mission 10 is cut. | ## Verification approach -- **Inner mechanism evidence:** verify mechanical schema derivation from canonical Petrinaut sources, provider-visible nested shape, canonical runtime rejection, stable id planning, deterministic derivation construction, and no derivation commit for rejected or no-op calls. Keep conversion tests structural and compare against canonical source schemas; do not bless copied snapshots as a second authority. If batching is selected, prove its transaction semantics through a first-class core operation rather than direct handle access. -- **First tracer:** make one real provider call against the single canonical nested schema that failed in Mission 3. Record provider/model, generated schema, raw arguments, runtime result, repair count, latency, and cost. Stop on a crisp upstream blocker. Passing retires only the provider-schema risk. -- **Mechanism decision:** after the carrier tracer, run the core transaction probe and then compare the bounded batch with the repaired per-action surface through the production client path. Record schema size, calls, latency, correction behavior, state outcome, and failure visibility. Keep per-action tools if batching does not earn its added core and host contracts. -- **Middle integration/contract evidence:** drive the built Brunch application through Flue client-tool suspension/resume into a real Petrinaut instance. Apply the complete meaningful region, inspect canonical state and derivations, run unchanged repeat, then changed-input projection and an invalid/unsupported case. Include stale revision/current-net and duplicate-delivery probes where the selected protocol permits them. -- **Outer deployed/user-visible evidence:** a human requests the bounded projection in the deployed panel, watches the meaningful region appear, inspects the region, asks why a generated element, repeats unchanged projection, changes the selected workpiece input, and observes bounded visible change or explicit refusal. Witness stock mode remains independent. Mission 9 owns this evidence. -- **Semantic adjudication:** compare current workpiece meaning and explicit expected consequences against the resulting SDCPN, not merely tool logs. Record assumptions/defaults/losses and any mismatch. A simulation-backed check may supplement but not replace this adjudication unless its discriminating contract is accepted. -- **Failure verification:** provider-schema error, canonical rejection, client callback failure, stale state, repair exhaustion, and partial sequence failure must be visible and must not produce false successful derivations. +- **Inner mechanism:** projection-plan construction from workpiece revision and live definition; intended-effect to basis mapping; stable id planning; epoch ledger; reconciliation of transition records against the plan; no basis for unanticipated effects; no state advance on rejected or no-op calls. +- **Middle integration:** drive the built Brunch application through the Mission 5 transport into a real Petrinaut instance on the Mission 7 conversation. Run unchanged repeat, one changed input, one retirement, a duplicate delivery, a stale-base attempt, and a hand edit between plan and apply. Inspect canonical state, transition records, epochs, and why answers. +- **Outer deployed and user-visible:** a human runs the demo script in the panel and witnesses no duplication, a bounded change, an honest retirement, and a current-state why. Stock mode remains independent. Mission 9 owns this evidence. +- **Semantic and behavioural:** compare the extended region with the workpiece meaning, and rerun the Mission 7 behavioural discriminator after each change. +- **Failure:** provider-schema error, canonical rejection, client callback failure, stale state, repair exhaustion, and partial sequence failure remain visible and never produce false success. +- **Mechanism decision:** only after repeat and changed input work per action, compare the bounded batch through the production client path and keep per-action tools unless the batch earns its core and host contracts. ## Inputs and joins -- **Mission 7 join:** accepted current workpiece, durable exact evidence references, stable workpiece/derivation/element seam, deployed why operation, selected prebuilt pair, negative provenance behavior, and owner/replacement guarantees. -- **Mission 3 failure join:** exact paid-run evidence for the failed Valibot open-object bridge and the canonical six-tool hermetic fixture. Repair only the provider-visible loss first; do not reinterpret empty parser success as partial semantic success. -- **Petrinaut canonical-contract join:** consume `petrinautAiTools`, `mutationActionInputSchemas`, entity schemas, and writable callbacks by import or mechanical generation. Mismatches between file-format and action schemas route upstream to Petrinaut. The batched-tools design is candidate input: Petrinaut core may own a generic subset-derived schema and first-class transaction/outcome operation, while Brunch retains subset selection, Flue carriage, client routing, and projection identity. -- **Flue join:** use a documented supported schema/tool path. If Flue cannot preserve the canonical nested schema, produce a crisp upstream requirement instead of deepening an opaque carrier. -- **Host join:** preserve AI SDK `useChat` / `onToolCall` and client-tool result resumption. Mutation execution remains browser/Petrinaut-owned. -- **Scenario join:** owner selects one meaningful workpiece region, operational expected account, accepted peer cases, and one Mission 10 correction. A toy fixture cannot supply this join. -- **Mission 10 output join:** stable region identity/current revision, impact boundary, repeat/change semantics, derivation lineage, and selected correction with expected consequences. -- **Mission 11 horizon:** record omissions needed to broaden from this region to the later accepted optimisation handoff; do not implement that breadth here. +- **Mission 7 join:** the accepted conversation, settled revisions, transition records, epochs, passage policy, tool set, compaction posture, fixture route, and gates. Draft promises are not join evidence. +- **Petrinaut canonical-contract join:** consume `petrinautAiTools`, `mutationActionInputSchemas`, entity schemas, and writable callbacks by import or mechanical generation. Mismatches route upstream. The batched-tools design is candidate input: Petrinaut core may own a generic subset-derived schema and first-class transaction operation; Brunch retains selection, Flue carriage, client routing, and identity. +- **Flue join:** the repaired carrier from Mission 7; a new upstream requirement if a class cannot be carried. +- **Host join:** preserve `useChat` / `onToolCall` and client-tool result resumption; mutation execution remains browser and Petrinaut owned. +- **Scenario join:** the owner selects the extended region, expected impact sets, accepted change classes, and one Mission 10 correction. +- **Mission 10 output join:** region identity, impact boundary, change-account semantics, and the selected correction with expected consequences. +- **Mission 11 horizon:** record the omissions needed to broaden from this region to the accepted handoff; do not implement that breadth here. ## Risks and assumptions | Risk or assumption | Impact if false | Cheapest discriminating validation | | --- | --- | --- | -| Flue can expose a mechanically preserved Petrinaut nested schema to the provider | If false, automatic projection is blocked upstream or requires a different supported schema bridge | First real `addType.elements` tracer using Standard Schema/supplied JSON Schema or the least mechanical shape-preserving path. | -| A Zod-to-provider conversion can preserve the load-bearing contract without copying fields | If false, provider acceptance and runtime semantics diverge | Compare generated nested JSON Schema and positive/negative samples directly against canonical Zod for every used tool class. | -| One bounded region can be both meaningful and small enough to close | If false, the mission either proves a toy or expands toward a full net | Select the region and expected operational account before implementation; reject candidates lacking type, parameter, flow, and an observable change. | -| Stable caller-supplied ids plus projection-level operation/base identity are enough for repeat/change locality | If false, generated ids churn, duplicate delivery mutates twice, or stale edits land | Run unchanged repeat, duplicate delivery, stale-base submission, and one changed input against a frozen current net; inspect all ids and unrelated definitions. | -| A first-class bounded batch can improve construction without weakening canonical mutation behavior | If false, atomicity is handle-specific, no-ops appear successful, or coarse feedback increases retries | Compare equivalent sequential and batch results under readonly and disabled extensions, inject duplicate/missing IDs and an invalid late step, then run the selected case through the production client path. | -| The projector can consume bounded context rather than the full workpiece/transcript | If false, locality and later revision become unreliable | Project from the selected region plus explicitly named dependencies; withhold unrelated transcript and observe whether the result remains sufficient. | -| A desired-region recomputation followed by bounded mutations satisfies locality | If false, internal global reasoning may cause hidden dependence/churn | Compare accessed inputs, proposed diff, and applied mutations; owner decides whether applied locality is sufficient for the delivery contract. | -| Mission 7's derivation representation can describe generated and changed elements | If false, automatic generation needs a seam revision before implementation continues | Emit one add, retain, change, and unsupported disposition on paper/fixture and run Mission 7 why resolution. | -| Bounded repair can recover provider mistakes without loops or silent defaulting | If false, projection latency/failure becomes unsafe | Inject one recoverable and one unrecoverable canonical rejection; enforce and visibly exhaust the accepted budget. | -| The selected changed-input case prepares Mission 10 without pre-solving reviewer authority | If false, Mission 10 inherits an irrelevant region or this mission expands into revision | Choose only expected operational consequence here; leave who may revise and how foreground synthesis authorizes it to Mission 10. | -| Parser plus visual inspection is enough for this region | If false, semantically wrong dynamics may look plausible | Try the cheapest workpiece-specific simulation expectation; promote only if it catches a plausible wrong projection. | +| A projection plan can find already-present intended effects without re-mutating | Repeat duplicates or churns | Run unchanged repeat against the Mission 7 net and inspect the transition log for attempt history only. | +| Stable caller-supplied ids plus epochs are enough for changed-input locality | Ids churn, stale edits land, or retired ids are reused | Frozen expected impact set; before/after id inventory; retire one element and attempt to reuse its id. | +| Mission 7's one-conversation-one-incarnation binding is sufficient for the proving scenario | A second conversation or principal reaches the document with no arbiter | Decide at cut time; if needed, place a document-scoped owner behind the existing storage boundary and probe two conversations. | +| A first-class bounded batch improves repeat or change without weakening canonical behaviour | Atomicity is handle-specific, no-ops look successful, coarse feedback increases retries | Compare sequential and batch results under readonly and disabled extensions with injected duplicate, missing, and invalid late steps, then the production client path. | +| The projector can consume the region plus named dependencies rather than the full workpiece | Locality and later revision become unreliable | Withhold unrelated workpiece sections and observe whether the plan remains sufficient. | +| Desired-region recomputation with bounded applied diff satisfies locality | Hidden global dependence causes churn | Compare accessed inputs, proposed diff, and applied mutations; the owner decides whether applied locality suffices. | +| Retirement can be represented without breaking executable references | Removing meaning breaks scenarios, metrics, or code | Retire an element referenced by a scenario and observe the canonical outcome and why answer. | +| Parser plus visual inspection plus the discriminator are enough for the extended region | Semantically wrong dynamics look plausible | Rerun the Mission 7 discriminator after each change; promote a second discriminator only if it catches a plausible wrong projection. | ## Accepted constraints and guarded invariants -- **Petrinaut owns canonical schemas and mutations.** Guard: imports/mechanical generation and structural alignment tests. A generic batch, if earned, is a first-class Petrinaut operation with explicit supported-handle, readonly, extension, rollback, and outcome semantics; Brunch does not reach through an instance to `handle.change`. Stop if field shapes are hand-copied into Brunch prose, Valibot, fixtures presented as authority, or a parallel schema package. -- **Provider repair is only the first risk tracer.** Guard: acknowledge the working line only after the meaningful-region and positive-why floor; mission acceptance then requires readiness closure for repeat, change, and failure classes. -- **Workpiece is semantic input.** Guard: projector input manifest names current workpiece revision/region; transcript and captures are excluded as primary semantic input. -- **Captures remain evidence, not projection IR.** Guard: derivations reference evidence through the workpiece; projector has no capture-to-model reducer. -- **Stable caller-supplied ids are load-bearing.** Guard: unchanged-repeat and changed-input before/after assertions. -- **Applied state and derivation agree.** Guard: derivations commit only after canonical mutation result/current-state confirmation; rejected calls cannot appear successful. -- **No unsupported consequential defaults.** Guard: expected semantic account and assumption/default/loss inspection; unsupported cases visibly stop or remain explicit. -- **Non-empty and semantically meaningful.** Guard: required canonical type/parameter/place/transition/arc inventory, panel witness, and workpiece-specific adjudication. Parser acceptance alone fails. -- **Bounded repair and bounded region.** Guard: named repair budget, selected region/dependencies, mutation/impact log, and stop on widening beyond the accepted boundary. -- **No unrelated churn.** Guard: stable unrelated-id and definition comparison for repeat/change. -- **No observer or automatic workpiece revision.** Mission 9 projects the current accepted workpiece; it does not consolidate conversation evidence or decide reviewer authority. Guard: no scheduler/fold queue and no canonical workpiece writes. -- **One agent, one mounted job skill, existing panel door.** Guard: composition/dependency inventory; no second server, TUI, workflow engine, or subagent topology. +- **Petrinaut owns canonical schemas and mutations.** Guard: imports or mechanical generation and structural alignment tests. A generic batch, if earned, is a first-class Petrinaut operation with explicit supported-handle, readonly, extension, rollback, and outcome semantics; Brunch does not reach through an instance to `handle.change`. +- **The transition record is the only statement of effect.** Guard: no basis, epoch, or why state advances from a plan or a self-reported effect set that fails diff accounting. +- **Identity epochs are never reused.** Guard: epoch ledger assertion on retire and recreate. +- **Repeat is idempotent; change is bounded; widening is declared.** Guard: attempt-history-only repeat log; frozen impact set; visible widening reason. +- **Workpiece is semantic input; captures and transcript are not.** Guard: projector input manifest names the settled revision; declared basis on every request. +- **No unsupported consequential defaults.** Guard: expected semantic account and assumption, default, loss inspection. +- **No observer or automatic workpiece revision.** Mission 9 projects the current accepted revision; it does not consolidate evidence or decide reviewer authority. Guard: no scheduler, fold queue, or canonical workpiece writes outside `update_workpiece` called by the foreground agent. +- **One agent, one mounted job skill, existing panel door.** Guard: composition and dependency inventory. - **Stock assistant remains independent.** Guard: path isolation and host witness. -- **Deployment claims match observed evidence.** Guard: consume accepted Mission 7 replacement proof; do not cite Mission 8's local image as remote deployment. -- **Visible failures do not advance canonical state silently.** Guard: injected rejection, stale state, partial sequence, and timeout/abort tests. -- **Paid provider evidence requires cut-time authorization and a stated budget.** Guard: no real-provider tracer runs from this draft; the eventual live mission records model, maximum calls, and spend ceiling before execution. +- **Deployment claims match observed evidence.** Guard: name local posture unless a Mission 8 successor has landed. +- **Paid provider evidence requires cut-time authorization and a stated budget.** Guard: the live mission records model, maximum calls, and spend ceiling before execution. ## Cross-cutting obligations -- Projection fidelity: the generated region comes from the current workpiece and every consequential decision has an attributable rationale. -- Evidence provenance: Mission 7 why reaches exact evidence without laundering model prose into quotation. -- Workpiece sufficiency: construction names a smallest gap instead of silently filling missing objective/process meaning. -- Petrinaut acceptance: canonical schema/mutation validity, non-empty state, diagnostics where executable code is used, visual inspection, and semantic correspondence are distinct leaves. -- Identity and derivation integrity: repeat/change preserve unrelated identities and explain all necessary impact widening. -- Failure visibility: provider schema, canonical rejection, unsupported meaning, stale state, client callback, and partial failure visibly stop/degrade. -- Interaction quality: projection and why occur through the real panel in operational language; construction schema vocabulary does not take over reviewer interaction. -- Deployment/privacy: stable owner-bound product state and content-free observability survive the accepted replacement boundary. -- User docs: document request, visible generated result, why flow, repeat/change behavior, and failure states; prompt replacement of stale screenshots. -- Mission 10 readiness: leave one meaningful selected correction and a trustworthy bounded projection seam, not a generic revision platform. -- Mission 11 horizon: retain omissions and breadth gaps needed for the eventual optimisation handoff. +- Projection fidelity, evidence provenance, and workpiece sufficiency as stated in the spine's cross-mission obligations, over generated, changed, and retired elements. +- Identity and change-account integrity: repeat and change preserve unrelated identities and explain all necessary widening. +- Failure visibility across provider schema, canonical rejection, unsupported meaning, stale state, hand edit, client callback, and partial failure. +- Interaction quality: projection and why in operational language; construction vocabulary does not take over reviewer interaction. +- Runtime migration matrix continued from Mission 7 for any representation this mission changes, with a removal gate. +- User docs: request, visible generated result, repeat and change behaviour, retirement, failure states; prompt replacement of stale screenshots. +- Mission 10 readiness: one selected correction and trustworthy impact-boundary semantics, not a generic revision platform. +- Mission 11 horizon: retained omissions and breadth gaps. ## Expected touched paths -Tentative only; the first real schema tracer may expose an upstream boundary and shrink or redirect this manifest. +Tentative only; Mission 7's accepted seam may shrink or redirect this manifest. ```text libs/@hashintel/brunch-agent/ ├── MISSION.md ~ cut-time authority only -├── docs/evidence/ + provider tracer, semantic adjudication, deployed projection -├── packages/plugin-sdcpn/src/tools/petrinaut-construction.ts ~ provider-visible canonical schema path and bounded tools -├── packages/plugin-sdcpn/src/flue.ts ~ mount projection capability only on the accepted product route -├── packages/plugin-sdcpn/src/skills/sdcpn-modelling/ ~ construction/projection guidance only where observed strain requires -├── packages/plugin-sdcpn/test/construction-tools.test.ts ~ canonical alignment/provider shape guards -├── packages/core/ ? minimal derivation mechanics only if Mission 7 places them here -└── packages/binding-flue/ ? no change unless supported Flue schema translation belongs at this boundary +├── docs/evidence/ + repeat/change/retirement witnesses and adjudication +├── packages/plugin-sdcpn/src/tools/ ~ additional scenario-selected classes; projection plan if plugin-owned +├── packages/plugin-sdcpn/src/skills/sdcpn-modelling/ ~ repeat/change/retirement posture +├── packages/plugin-sdcpn/test/ ~ alignment and plan guards +├── packages/core/ ~ epoch and change-account semantics if core-owned +└── packages/binding-flue/ ? document-scoped owner only if cross-conversation access is admitted apps/brunch-agent/ -├── src/agents/chat-agent/ ~ compose bounded projection capability -├── src/conversation/client-tools.ts ~ client-tool names/results as required -├── src/http/petrinaut-chat.ts ~ preserve production dispatch/resume -├── src/evaluations/runbook/headless-petrinaut-client.ts ~ evidence harness only, not product substitute -└── test/ ~ real provider tracer and production throughline +├── src/agents/chat-agent/ ~ compose the projection capability +└── test/ ~ repeat, change, retirement, stale, hand-edit integration libs/@hashintel/petrinaut-core/ -├── src/ai.ts ~ canonical schema export/generation; subset batch schema only if selected -├── src/instance.ts ~ first-class transaction/outcome operation only if the batch probe earns it -├── src/handle/ ? explicit transaction capability only if existing contracts cannot support the claim -├── src/action-schemas.ts ~ only canonical contract correction discovered at source -└── src/*.test.ts ~ canonical, transaction, readonly/extensions, no-op, and mutation guards +├── src/ai.ts, src/instance.ts, src/handle/ ? subset batch schema and first-class transaction only if the batch probe earns it +└── src/*.test.ts ~ canonical, transaction, readonly/extensions, no-op guards libs/@hashintel/petrinaut/ -├── src/ui/views/Editor/panels/ai-assistant-panel.tsx ~ generic host execution/visible failure only if needed -├── src/ui/views/Editor/panels/ai-assistant-panel.test.tsx ~ real host integration +├── src/ui/views/Editor/panels/ai-assistant-panel* ~ generic host execution and visible failure only if needed └── docs/ ~ affected user-facing guidance - -deployment/infrastructure source outside this checkout ? only if accepted product route exposes a missing deployed contract ``` -Do not add a hand-copied Brunch schema catalog, graph database, generalized projection framework, automatic observer, capture fold, workflow engine, second agent/server, or full 46-tool stock-modeller surface. +Do not add a hand-copied Brunch schema catalog, graph database, generalized projection framework, automatic observer, capture fold, workflow engine, second agent or server, or full stock-modeller parity. ## Fog-line -- Which Flue-supported schema interface can preserve canonical Zod nested shape: Standard Schema, supplied JSON Schema, a mechanical shape-preserving conversion, or an upstream Flue change. -- Which canonical refinements are provider-expressible and how runtime-only constraints are described without pretending the provider enforces them. -- The smallest operationally meaningful region and accepted peer cases; the broader demo portfolio remains unenumerated. -- Exact type elements, parameter, places, transitions, arcs, executable code, and extension requirements for that region. -- Whether the current Mission 7 Markdown reference seam supplies stable bounded region identity or needs the least additional revision marker. -- The smallest projector implementation and where its projection plan/derivation state belongs. -- Whether recomputing a desired bounded region internally while applying a local diff satisfies the owner, or genuinely local computation is required. -- How deletions/retirements are represented if the selected changed-input case removes meaning. -- Whether repaired per-action tools or a bounded batch are the least sufficient surface after measured schema cost, calls, latency, correction behavior, and failure visibility. -- If batching is selected, which handles explicitly support rollback, how silent canonical no-ops are reported, and whether one history checkpoint is acceptable in the stock editor. -- Repair budget, provider-envelope versus canonical per-step feedback, timeout, and partial-sequence policy. -- Concurrent user mutation, duplicate delivery, operation identity, base revision, and stale-current-net behavior during projection. -- The exact semantic oracle beyond workpiece-specific human adjudication; simulation remains optional until discriminating. +- The extended region, its accepted change classes, and the peer set; the broader demo portfolio remains unenumerated. +- Whether the proving scenario needs cross-conversation document access and therefore a document-scoped owner. +- How retirement interacts with executable references in scenarios, metrics, and code. +- Whether repaired per-action tools or a bounded batch are the least sufficient surface after measured schema cost, calls, latency, correction behaviour, and failure visibility. +- If batching is selected, which handles support rollback, how silent canonical no-ops are reported, and whether one history checkpoint is acceptable in the stock editor. +- Repair budget, provider-envelope versus canonical per-step feedback, timeout, and partial-sequence policy for multi-element plans. +- Whether desired-region recomputation with a bounded applied diff satisfies the owner or genuinely local computation is required. - The selected Mission 10 correction and what counts as a sufficiently local patch when connected semantics legitimately widen impact. -- Representative deployed latency/usage, compaction/recovery behavior, and any host selection needed for this path. +- Representative deployed latency, usage, and compaction behaviour for longer conversations. ## Stop or reorient Stop and surface evidence if: -- Mission 7's accepted workpiece/provenance/durability seam is unavailable or generated derivations require a fixture-specific translation; +- Mission 7's accepted seam is unavailable or repeat and change require a fixture-specific translation; - canonical Petrinaut field shapes are manually copied into Brunch; -- Flue/provider cannot receive the required nested shape through a supported mechanical path; record the crisp upstream blocker rather than extending the opaque open-object carrier; -- batching is implemented before the single-action carrier is proved, or selected without explicit transaction scope, readonly/extensions parity, honest no-op outcomes, production client routing, and measured advantage over per-action tools; -- one successful `addType.elements` call, empty net, toy pair, parser result, or hermetic fixture is presented as mission completion; -- the projector reads the full transcript as primary model or treats captures as semantic IR; -- construction silently invents an objective, process spine, resource fate, contention rule, timing/tail behavior, or consequential default absent from the workpiece; +- a class cannot be carried through the repaired carrier; record the upstream blocker rather than extending an opaque carrier; +- batching is implemented before per-action repeat and change are proved, or selected without transaction scope, parity, honest no-ops, production routing, and measured advantage; - repeated unchanged projection duplicates elements, churns ids, or mutates unrelated state; -- changed input triggers unrelated regeneration without a visible impact boundary and explanation; -- rejected/failed tool calls acquire successful derivations or partial state is represented as complete; +- changed input triggers unrelated regeneration without a visible impact boundary and reason; +- a retired id is reused or a retired element loses its history; +- a hand edit or concurrent change is overwritten rather than refused and imported; +- rejected or failed calls acquire basis or advance epochs, or partial state is represented as complete; - semantic correspondence cannot be distinguished from attractive canvas output; -- the bounded region expands toward a complete net or all Petrinaut tools without an accepted consumer; +- the region expands toward a complete net or all Petrinaut tools without an accepted consumer; - an observer, automatic evidence fold, reviewer-authority mechanism, or generic revision platform enters to prepare Mission 10; -- Brunch-specific logic enters Petrinaut's published library instead of a generic host/canonical contract; -- stock assistant behavior or separate history becomes dependent on Brunch; or -- deployment, owner binding, visible failure, or replacement durability is claimed without real-boundary evidence. +- Brunch-specific logic enters Petrinaut's published library; +- stock assistant behaviour or separate history becomes dependent on Brunch; or +- deployment, owner binding, or replacement durability is claimed without real-boundary evidence. ## Carried evidence and rejected alternatives -- Mission 3 proved canonical Petrinaut callbacks can construct a non-empty fixture through `getLatestNetDefinition`, `addType`, `addParameter`, `addPlace`, `addTransition`, and `addArc`. It also proved runtime rejection of a zero-weight arc and correction in the faux path. -- The paid Mission 3 model run falsified the provider-visible Valibot `looseObject({})` + `rawTransform` carrier: nine `addType.elements` arrays arrived as strings, all were correctly rejected, and the parser accepted only an empty legacy document. Preserve the 0-for-9 result; do not describe it as partial construction success. -- The next accepted move from that evidence was Flue support for Standard Schema/supplied JSON Schema or a mechanical shape-preserving conversion. Extending the open-object carrier or copying Petrinaut fields into Valibot remains rejected. -- Petrinaut's canonical Zod schemas, action schemas, AI tool bundle, and mutation callbacks are current authority. The file-format and action-schema families are aligned by source code and tests, not guaranteed by Brunch; discovered mismatch routes upstream. -- Mission 7 deliberately proves why over an honest prebuilt pair first. Mission 9 must replace the prebuilt projection step with bounded automatic generation while preserving the same provenance contract. -- A comprehensive requirements graph, process-domain ontology, universal subject/predicate/value model, closed kinds/slots, typed completion algebra, deterministic capture-to-model fold, and full regeneration engine remain rejected. They re-enter only under repeated observed inability of workpiece prose plus explicit derivations to support projection or readiness. -- Optional SDCPN mapping hints remain advisory and absent by default. They may re-enter only if projection repeatedly misses consequential structures and a hint demonstrably helps without biasing workpiece meaning; they never copy Petrinaut payload fields. -- Stable caller-supplied ids remain the current least identity hypothesis. A stronger identity ledger re-enters only if repeat/change projection demonstrates unavoidable churn or ambiguity. -- Full desired-net recomputation with bounded applied diff remains fog, not accepted architecture. Unrelated churn or hidden global dependence rejects it. -- Broad 46-tool parity with the stock modeller is rejected; close only the canonical mutation classes the meaningful region actually uses. -- `pn_read`/`pn_edit` are candidate model-facing names, not accepted architecture. Reuse `getLatestNetDefinition` unless an alias earns its production routing cost; retain repaired per-action tools if a bounded batch does not earn its transaction and host surface. -- An inferential observer remains absent. Mission 10's default revision mechanism is foreground phase-boundary synthesis; observer promotion requires separate evidence for ordering, flush, failure, prior-meaning preservation, and foreground latency. -- Mission 11 owns broadening to the accepted full optimisation handoff scenario. Mission 9 must not stop automatically after one tracer, but neither may it expand without the named region, peer set, and oracle. +- Mission 3 proved canonical Petrinaut callbacks can construct a non-empty fixture through `getLatestNetDefinition`, `addType`, `addParameter`, `addPlace`, `addTransition`, and `addArc`, and proved runtime rejection of a zero-weight arc with correction in the faux path. +- The paid Mission 3 model run falsified the provider-visible Valibot `looseObject({})` + `rawTransform` carrier: nine `addType.elements` arrays arrived as strings, all correctly rejected, and the parser accepted only an empty legacy document. Preserve the 0-for-9 result. Mission 7 now owns the repair; this mission consumes it. +- The next accepted move from that evidence was Flue support for Standard Schema or supplied JSON Schema, or a mechanical shape-preserving conversion. Extending the open-object carrier or copying Petrinaut fields into Valibot remains rejected. +- Petrinaut's canonical Zod schemas, action schemas, AI tool bundle, and mutation callbacks are current authority; file-format and action-schema families are aligned by source and tests, not guaranteed by Brunch. +- The former Mission 7 "honest prebuilt pair" with a hand-authored derivation fixture was rejected on 2026-09-04 as useless; provenance now comes from constructor-declared basis and recorded transitions on a genuine conversation, so this mission's why join is to Mission 7's real seam, not to a prepared translation. +- A comprehensive requirements graph, process-domain ontology, universal subject/predicate/value model, closed kinds and slots, typed completion algebra, deterministic capture-to-model fold, and full regeneration engine remain rejected; they re-enter only under repeated observed inability of workpiece prose plus declared basis to support projection or readiness. +- Optional SDCPN mapping hints remain advisory and absent by default; they may re-enter only if projection repeatedly misses consequential structures and a hint demonstrably helps without biasing meaning, and they never copy Petrinaut payload fields. +- Stable caller-supplied ids plus identity epochs remain the least identity hypothesis; a stronger identity ledger re-enters only if repeat or change demonstrates unavoidable churn or ambiguity. +- Full desired-net recomputation with bounded applied diff remains fog, not accepted architecture; unrelated churn or hidden global dependence rejects it. +- Broad stock-modeller tool parity is rejected; admission is scenario-selected with canonically derived schemas and expands on observed need. +- `pn_read` / `pn_edit` are candidate model-facing names, not accepted architecture; reuse `getLatestNetDefinition` unless an alias earns its routing cost; retain per-action tools unless a bounded batch earns its transaction and host surface. +- An inferential observer remains absent; Mission 10's default revision mechanism is foreground phase-boundary synthesis. +- Mission 11 owns broadening to the accepted full optimisation handoff scenario; Mission 9 must not stop automatically after one repeat, but neither may it expand without the named region, peer set, and oracle. diff --git a/libs/@hashintel/brunch-agent/docs/mission-drafts/README.md b/libs/@hashintel/brunch-agent/docs/mission-drafts/README.md index 1c66541f0f3..3b31268ca18 100644 --- a/libs/@hashintel/brunch-agent/docs/mission-drafts/README.md +++ b/libs/@hashintel/brunch-agent/docs/mission-drafts/README.md @@ -1,6 +1,6 @@ # Provisional mission drafts -Files in this directory are detailed context repositories for possible future missions. They are not execution authority, do not create live missions, and must not be implemented. [`MISSION.md`](../../MISSION.md) is currently a closure pointer and [`MISSION.next.md`](../../MISSION.next.md) is the compact future spine. A draft must be re-evaluated and converted into a new root `MISSION.md` as the sole execution authority on its own issue, branch, and PR before implementation. +Files in this directory are detailed context repositories for possible future missions. They are not execution authority, do not create live missions, and must not be implemented. [`MISSION.md`](../../MISSION.md) is the current branch's sole live mission authority and [`MISSION.next.md`](../../MISSION.next.md) is the compact future spine. A draft must be re-evaluated and converted into a new root `MISSION.md` as the sole execution authority on its own issue, branch, and PR before implementation. Each planning item has one authoritative planning home across `MISSION.next.md` and these linked drafts. A spine summary is only a pointer. Keep accepted decisions, rejected alternatives and reasons, re-entry conditions, scenario classes, evidence, constraints, fog, stop conditions, risks, assumptions, and named mechanisms in one discoverable home at the precision needed by a cold-start builder. diff --git a/libs/@hashintel/brunch-agent/docs/mission-drafts/voice-runtime-ownership-conversion.md b/libs/@hashintel/brunch-agent/docs/mission-drafts/voice-runtime-ownership-conversion.md new file mode 100644 index 00000000000..af0f0337547 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/mission-drafts/voice-runtime-ownership-conversion.md @@ -0,0 +1,164 @@ +# Voice ownership — bounded conversion and gated implementation plan + +> Draft cluster only. Not execution authority. Do not implement until this cluster is re-evaluated and cut into `MISSION.md`. + +Prepared for owner review on 2026-09-07. This document owns the conversion proposal, source inspection, stage sequencing, and proposed acceptance checks. The [ownership design](voice-runtime-ownership.md) remains the sole detailed architectural planning home; it is not promoted by this proposal. Neither the existing mission nor that design is changed here. The successor issue and draft PR are authorized review surfaces; no dependent product implementation, paid campaign, or mission acceptance is implied. + +## Decision requested + +Approve a two-step authority conversion: first establish the supported Flue recording boundary; only after that gate passes, separately approve and commit the bounded product mission covering recording, one delegated clarification, and integrated recovery. The first successful clarification is an internal milestone, not mission completion. Expansion remains a later evidence-gated decision. + +**Current blocking result:** Flue 2.0.3 and the inspected upstream HEAD do not expose the required persistence-only external dialogue contract. A normal signal can carry a waking, non-human handback; it cannot stand in for no-wake recording. Do not implement dependent UI, prompts, delegation, or a substitute log while this boundary is missing. + +Tracker decision is separate from architecture approval. Kostandin Angjellari authorized a new successor issue and draft PR stacked on [PR #9564](https://github.com/hashintel/hash/pull/9564), without modifying that PR or [FE-1580](https://linear.app/hash/issue/FE-1580/reconcile-voice-turn-behavior-on-the-shared-brunch-conversation). [FE-1624](https://linear.app/hash/issue/FE-1624/implement-split-ownership-voice-conversations-with-brunch) is assigned to Kostandin Angjellari and corresponds to `kostandin/fe-1624-split-ownership-voice`. Its planning-only PR targets `ln/fe-1580-reconcile-voice-resumable-workpiece`. This publication is not approval of the mission conversion. The accepted parent authority remains unchanged. + +## Re-evaluated foundation + +### Exact pins and inspection scope + +`gh pr view 9564 --repo hashintel/hash --json headRefOid,headRefName,baseRefName,state` returned current head [a0ca1cbf52ea44420db24cb615c349e151036c14](https://github.com/hashintel/hash/commit/a0ca1cbf52ea44420db24cb615c349e151036c14), open against `ln/fe-1575-resumable-workpiece-petrinaut`. The original local checkout was at [2db4790f19065dc3aa7ff165297d182e6d632a70](https://github.com/hashintel/hash/commit/2db4790f19065dc3aa7ff165297d182e6d632a70). The design's earlier inspected head is [132831f14300c577c5d0b73cea9d817c8e5c6c7d](https://github.com/hashintel/hash/commit/132831f14300c577c5d0b73cea9d817c8e5c6c7d). These are three different baselines; old local source and test totals are not evidence for the current PR head. The successor branch starts at the inspected current PR head in an isolated worktree, preserving the original checkout and its uncommitted files. + +Read root/package `AGENTS.md`, original local `MISSION.md`, the complete original local `MISSION.next.md`, [draft lifecycle](README.md#lifecycle), the design, and [Flue routing](../reference/architecture/flue-routing.md). Inspected exact PR Git objects for mission status/deferrals, the owner witness, transport result selection/tests, panel execution/continuation/isolation changes/tests, fixture/plugin evidence repair, Voice policy/session/bridge, workpiece selection, mounted app route/ownership guard, and the built-runtime test entrypoint. No existing branch was switched or restacked, and no product tests were run for this proposal. `gh stack` was unavailable; the child branch and explicit GitHub base establish the stack without rewriting its parent or siblings. + +At the PR pin Mission 6b is **accepted with explicit limitations**, whereas the older local authority still says live. Consume the pinned accepted record; do not manufacture another close from the local copy. The [witness at the pin](https://github.com/hashintel/hash/blob/a0ca1cbf52ea44420db24cb615c349e151036c14/libs/%40hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/owner-witness-2026-09-07/witness.md) tested an earlier implementation and records narrowed human evidence, not a rerun of the latest head. + +### Repairs and limits the conversion must carry + +| Inspected owner | Protected behavior or material limit | +| --- | --- | +| `packages/transport-aisdk/src/index.ts`, `completedClientToolResults` | Select the latest relevant client-tool step, including a later server-only step; never resend stale cumulative read results as mutation verification. | +| `libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.tsx` | Wait for sibling automatic tools; retain batched continuations through effect replay; replace conversation-owned hooks/callbacks when identity changes. Preserve both new tests: `does not continue while a sibling automatic tool is pending` and `replaces conversation-owned busy state when the identity changes`. | +| Website `prepared-crew-reservation-fixture.ts` and plugin `src/flue.ts` | Revision zero is an unconfirmed hypothesis. A fragment, topic label, inspection request, unrelated message, or agent proposal is not explicit human confirmation. | +| Website Voice policy and bridge | Existing mode is a no-tool, verbatim half-duplex relay. New local wording is an explicit policy delta requiring new authority, not a relaxation hidden in the current mission. Keep no-autoplay and input/output contamination barriers. | +| Core `src/workpiece.ts`, `selectRunbookWorkpiece` | Recovery currently selects assistant `runbook-ir` fences. It does not attest Brunch authorship. Newly recorded Realtime assistant text must not become a workpiece merely by containing such a fence. | +| `apps/brunch-agent/src/app.ts`, `src/http/ownership.ts` | One mounted `/agents/chat/:instanceId` route has a principal/conversation ownership guard. Browser-supplied principal headers are not authenticated actor identity. Do not claim trusted authorship from that guard alone. | + +The current checkout and PR pin do not implement Mission 7's settled `update_workpiece` protocol. Do not invent a competing revision/basis system or import unapproved Mission 7 changes. The first Voice workpiece proof may use the inherited bounded workpiece path only after its Brunch-authorship eligibility is enforced. A later join to Mission 7 requires inspecting its accepted public seam and reconciling ownership explicitly. + +The prepared crew-reservation scenario is diagnostic material, not evidence for general construction, explanation, or customer elicitation quality. General lineage, declared basis, passage identity, compaction, repeatable projection, reviewer revision, and deployment keep their existing planning owners. + +## Flue capability finding + +Inspected upstream release 2.0.3 at [bf86b8726f5ba189844185fdbeca0e194344ded1](https://github.com/withastro/flue/commit/bf86b8726f5ba189844185fdbeca0e194344ded1) and remote HEAD at [832ad2eeaf5e4b07d39749fc669e7ad556238313](https://github.com/withastro/flue/commit/832ad2eeaf5e4b07d39749fc669e7ad556238313). Their difference is documentation-only. This is source/API evidence, not a runtime extension probe or a claim about future releases. + +| Question | Evidence and consequence | +| --- | --- | +| External append without waking Brunch? | Public [SDK client](https://github.com/withastro/flue/blob/832ad2eeaf5e4b07d39749fc669e7ad556238313/packages/sdk/src/client.ts#L47-L98) exposes send/read/wait/abort/history/observe, not external append. [Send](https://github.com/withastro/flue/blob/832ad2eeaf5e4b07d39749fc669e7ad556238313/packages/sdk/src/public/send.ts#L12-L63) admits user or signal submissions. No supported persistence-only dialogue contract was found in either revision. | +| Can `ctx.append` substitute? | No. [Message output](https://github.com/withastro/flue/blob/832ad2eeaf5e4b07d39749fc669e7ad556238313/packages/runtime/src/message-output.ts#L61-L143) is an in-lifecycle signal append that steers the active response, rejects user append, and is not an external dialogue writer. | +| Can a structured handback avoid a synthetic human turn? | Yes, normal `send({ message: { kind: "signal", type, body, attributes, tagName }, uid, idempotencyKey })` is supported. [Signal projection](https://github.com/withastro/flue/blob/832ad2eeaf5e4b07d39749fc669e7ad556238313/packages/runtime/src/conversation-projections.ts#L127-L172) is system/dispatch/diagnostic, not human testimony. This wakes Brunch as intended. It does not solve the missing original dialogue records. | +| Are source/evidence attributes authenticated? | No. They are caller-controlled strings in the [input schema](https://github.com/withastro/flue/blob/832ad2eeaf5e4b07d39749fc669e7ad556238313/packages/runtime/src/runtime/schemas.ts#L28-L70). The application must authenticate the runtime actor, validate delegation/evidence, and construct or verify the handback. A claimed source-agent attribute is not an attestation. | +| Does public abort close post-settlement browser work? | No. [Execution-store abort](https://github.com/withastro/flue/blob/832ad2eeaf5e4b07d39749fc669e7ad556238313/packages/runtime/src/agent-execution-store.ts#L233-L245) marks eligible unsettled submissions, not terminalizing/settled ones. No corresponding durable browser-operation disposition is supplied by this API. A generic Stop signal would not enforce cancellation. | + +The required extension must carry the design's [persistence-only contract](voice-runtime-ownership.md#persistence-only-events): canonical ordered append, durable actor/modality attribution, causal references, stable event identity, identical retry/conflicting payload semantics, hydration, and later model visibility, with no invocation or domain effect. Authentication is a composition obligation, not a requirement that Flue invent a user directory. Do not prescribe private database records or an unearned wire API before an upstream-supported surface exists. + +**Gate result: blocked on supported external recording.** An upstream-supported implementation and distributable pin plus real boundary evidence are needed to change that result. Merely locating an internal reducer, retaining JSON in a browser, or dispatching a signal does not pass. Opening an upstream issue/PR or publishing an extension requires separate external-write authorization. + +**Executable re-entry decision:** FE-1624's owner, Kostandin Angjellari, must either identify a supported upstream candidate or authorize a separately bounded upstream extension effort. That effort must establish maintainer-supported public SDK/router semantics and an inspectable implementation pin; a private fork or approval of this HASH plan alone cannot discharge the supported-contract requirement. Until such a candidate exists, keep the accepted parent mission unchanged and retain this planning packet. Do not create a live implementation mission whose only action is waiting for an unspecified dependency. The first re-entry check is the real no-wake/hydration/attribution test below, not an assumption that an upstream announcement establishes compatibility. + +## Proposed mission conversion envelope + +The following are candidate contents of the six live semantic addresses, not a second live mission. + +| Address | First bounded authority: establish the recording prerequisite | Separately approved product amendment after the prerequisite | +| --- | --- | --- | +| Imperative | Establish whether a supported canonical no-wake recorder can satisfy the first Voice consumer, or return an actionable blocked result. Explicitly an internal prerequisite, not a product-manager-visible advance. | Make one natural clarification update Brunch's workpiece while preserving one continuous typed/spoken conversation, recoverability, and safe effects in the named scenario. | +| Throughline | Supported public SDK/router → same mounted conversation → durable dialogue → fresh-process history → one normal handback admission. No autonomous Realtime or mutation. | Brunch delegation → two recorded Realtime exchanges → agent-authored handback → Brunch validation → workpiece update → fresh-process reconstruction; then modality/interruption/browser-effect recovery gates. | +| Proof | Real built-runtime, faux-provider test counts zero agent calls during recording, reconstructs original identities/attribution from a second process, and exposes those records to the one intended handback invocation. Reject forged authorship/conflicts/cross-conversation access. | The acceptance matrix below plus named-scenario browser/media witness and owner adjudication; the tracer alone does not close the mission. | +| Constraints | The design's protected ownership table and persistence contract; unchanged normal admissions; no private Flue patch, sidecar, synthetic user message, provider-history authority, or paid run. | Same constraints, plus Brunch-only workpiece eligibility and mutation authorization, original call/step results, coherent-state refusal, distinct speech interruption and durable Stop. | +| Fog-line | Supported append availability; trusted runtime actor path; ordering/idempotency across reconnect; how original dialogue reaches later context. Do not design past a missing public contract. | Media durability versus buffering, stale delegation/basis, existing workpiece eligibility, execution/disposition atomicity and reconciliation, useful clarification versus leading questions. | +| Stop or reorient | Required API absent or only private; need to wake Brunch to record; actor identity cannot be validated; canonical reconstruction loses evidence. | Domain strategy moves into Realtime, interpretation is laundered into human evidence, cancelled work revives, effects duplicate, or apparent settlement exceeds authoritative evidence. | + +The owner must explicitly accept the first cut's prerequisite-only outcome rather than accidentally presenting it as the product mission. Its present source-only blocked result is already known; a new implementation plan for that gate becomes executable only when a supported candidate exists. If none exists, retain this proposal and stop dependent work rather than create an empty scaffolding mission. + +### Authority and lifecycle procedure + +1. Use the authorized FE-1624 successor topology. Before conversion, re-query #9564 and inspect any delta. Inspect worktrees/stack before any checkout; do not stash, reset, move, or overwrite the user's local design/spine or unrelated files to make room. The successor starts at the inspected PR head, not local `main` or assumed `origin/main`. +2. Preserve the accepted Mission 6b authority in its archive according to the [archive rules](../mission-archive/README.md), using the pinned accepted version rather than the stale local live version. Preserve all its deferrals and source attribution. Do not edit the original PR or stack siblings as an incidental archive action. +3. Convert only the approved envelope into `MISSION.md`, with one current Status, six required addresses, and Deferred links. Identify precise permitted deltas to no-local-wording/no-local-dialogue constraints. Commit this authority change alone before any dependent implementation or evaluation. +4. Consume this conversion proposal only after every remaining obligation has an explicit surviving home. At a prerequisite-only cut, return unadmitted product sequencing and test leaves to a residual provisional planning home at full fidelity before removing the consumed proposal. Retain the ownership design as residual architecture planning, not duplicate execution authority; preserve its rationale and historical full artifact before later subtraction. +5. Compare every affected planning file before/after for loss or duplicated authority. The design's current bytes and original spine pointer remain preserved during this review. Nothing is archived, consumed, or promoted merely by accepting tracker assignment. + +## Implementation sequence and promotion gates + +All steps below are proposed. Only execute stages admitted by the separately committed mission. Work in the existing owners; do not create a general orchestration framework. New API names and detailed implementation code remain deliberately unspecified because the required public substrate does not exist at the inspected pin. + +### A — Supported recorder and dependable foundation + +- [ ] Re-pin source and dependency, review upstream public contract, and record whether it is supported/released. If absent, retain the blocked verdict and stop. Do not patch installed dependencies. +- [ ] On an approved supported candidate, extend `apps/brunch-agent/test/petrinaut-chat.test.ts` and its `petrinaut-chat.integration.ts` child-process fixture. Use its real built app, mounted route, isolated temporary database, and faux provider; do not introduce another runtime harness. Add the failing no-wake/restart/attribution/conflict tests before integration code. +- [ ] Integrate only the supported route/client contract through `apps/brunch-agent/src/app.ts` and `packages/transport-aisdk` as required by the public seam. Exercise trusted actor enforcement at the app boundary; reject self-asserted Brunch authorship. Ordinary typed and Brunch-owned sends must retain their existing route and admissions. +- [ ] Extend `packages/transport-aisdk/test/{chat-transport,transcript,ui-stream}.test.ts` and core `test/workpiece.test.ts`: local assistant records cannot be parsed as Brunch workpieces, tool requests, results, or validation receipts. Fence text and tool-shaped content are inert evidence. Preserve causal results with dialogue interleaved between calls and results. +- [ ] Run targeted checks, inspect fresh-process records, and present the no-wake contract evidence for the product-amendment gate. No autonomous clarification or product-readiness claim yet. + +### B — Recorded delivery, then one conservative delegation + +- [ ] First wire runtime-authored recording without autonomous follow-ups in website `voice-interview/{openai-realtime-session,realtime-brunch-bridge,voice-turn-controller}.ts`. Record raw finalized transcript separately from normalization, actual generated wording, author, delivery identity/attempt, playback acknowledgements, interruption and unknown tail. Test disconnect before wording persistence; use buffered/text-first delivery if audio would escape the durable record. +- [ ] Compose role-specific material from Brunch core `src/prompts/SYSTEM.md`, `src/skills/elicitation/SKILL.md`, and website `src/server/voice/openai-voice-policy.ts`. Share evidence/uncertainty vocabulary, not the entire domain strategy. Record effective prompt/skill/resource/model versions. Keep domain tools unavailable to Realtime. +- [ ] Add one Brunch-authored clarification scope at the existing core/Flue binding capability boundary: purpose, permitted exploration, evidence/workpiece basis, return conditions, identity/version. Test enforcement and invalidation before relaxing the relay policy. Realtime may acknowledge/rephrase/ask permitted local follow-ups, not select strategy or decide sufficiency. +- [ ] Use a validated application-authored signal for handback through normal admission, referencing original recorded events, scope/version, proposed meaning, uncertainty, and return reason. Check useful answer, conflict, new topic, out-of-scope uncertainty, decline, and Stop; missing or foreign evidence cannot authorize an update. Brunch reads originals and accepts, refuses, or asks again. +- [ ] Run the exact tracer: one delegation, two local exchanges (each containing a user utterance and Realtime response), one logical handback, Brunch-validated workpiece update, then fresh-process reconstruction. Inspect originals, actual wording, attribution, update source, and preserved uncertainty. No general projection claim and no scope-completion UI. + +### C — Integrated recovery before the broader safety claim + +- [ ] Add failing panel and runtime tests for Stop after the Flue step has settled but before its browser operation is claimed. Establish an authorized durable operation disposition on a supported canonical runtime seam; Petrinaut must consult it before claiming work and on recovery. Reject changed-payload reuse of operation identity and preserve original call/step ownership and validated document basis. +- [ ] Distinguish cancelled-before-execution, executing, applied, failed, and uncertain outcomes. Test Stop/claim races and crashes before effect, after effect/before receipt, after receipt/before acknowledgement, and between sibling effects. If no atomic effect/receipt boundary exists, reconcile authoritative document state before retry; unknown is a valid refusal, not permission to replay. +- [ ] Test typed input, voice exit/re-entry, relevant workpiece changes, and explicit Stop invalidating/suspending scope; playback acknowledgements alone do not invalidate it. Fence old connection events and old-tab execution authority. Keep one active execution owner per workpiece; second tab observes until an explicit safe transfer, not active-active execution. +- [ ] Keep speech interruption local to delivery, without implicit durable cancellation. Expose distinct interrupt-speech and Stop-work controls during Voice in the existing panel/control owners. No autoplay on reopen, no silent replay of cancelled work, no claim of rollback for applied work. +- [ ] Add the existing fixture browser mutation to the integrated throughline only with explicit original human evidence and Brunch-selected work. Partial failure retains the prior coherent bundle; a proposal based on an old state cannot overtake unsettled work. Run real browser/media verification and seek owner acceptance of this named-scenario readiness claim. + +### D — Expansion only under new evidence + +The design's [expansion and experiment gates](voice-runtime-ownership.md#migration-stages-and-readiness-gates) retain ownership here; they are not authorized by a green tracer. Compare an improved Brunch relay with split ownership on useful information, unsupported assumptions, repetition, correction effort, and naturalness. Before real paid trials, obtain explicit models/callers, numerical quality/latency thresholds, trial counts, ceiling, and accounting owner. Mission 7's budget is not available. No quality/latency win is inferred from unit tests or preference alone. + +## Candidate acceptance matrix + +Names below specify new assertions to add, not tests claimed to exist or pass. Reuse adjacent existing tests and the built-runtime harness. Tests must inspect structured evidence rather than matching a transcript substring alone. + +| Proposed discriminator | Owner / observable oracle | +| --- | --- | +| `records two local exchanges without invoking Brunch` | App `petrinaut-chat.test.ts`/`.integration.ts`: observe Brunch execution entry and hook activity as well as model requests and submissions before/after four dialogue records. After initialization settles, local appends must schedule no Brunch work, execute no Brunch hooks, and leave IR/document unchanged, including after process replacement. One logical later handback admission and a normal typed send are positive controls proving the execution observer is live. Zero model requests alone is insufficient. If the supported runtime offers no credible execution observation, mark this proof blocked rather than substituting a sleep or provider-call count. | +| `reconstructs attributed originals after process replacement` | Same two-process test over the same isolated database: exact canonical event identities/order/actors/modalities and separate raw/normalized text; subsequent Brunch input includes original evidence, not only the proposal. No browser/provider history used. | +| `deduplicates identical recording and rejects identity conflicts` | App boundary plus transport tests: lost append/admission acknowledgement, duplicate final transcripts/proposals, same key with changed payload, wrong incarnation, cross-conversation references, forged actor, concurrent order, and reconnect. Reuse identity on retry; no blind new admission. | +| `Realtime content cannot update a workpiece or execute tools` | Core `workpiece.test.ts`, transport projections, and real panel tests: inject assistant `runbook-ir`, tool-shaped parts, a forged Brunch validation, leading suggestion, ambiguous assent, and `SDCPN`; no update/effect. Explicit original evidence plus Brunch validation is the positive control. | +| `stale delegation is evidence but not current authority` | Bridge/controller and app admission tests: typed interruption, Stop, new topic, changed workpiece, delayed old connection handback; no unauthorized update. Playback-only records leave an otherwise-current scope valid. | +| `local records preserve causal browser continuation` | Transport `chat-transport.test.ts` and panel tests: mixed server/browser step with later server-only activity, staggered siblings, unrelated later call, local exchanges between request/results, reordered retries, StrictMode effect replay, conversation switch with an old callback. One result per original call; no stale cumulative results. | +| `settled-step Stop survives reopen` | Panel + app persistence + browser integration: Stop pending post-settlement work, replace process/tab, observe durable cancelled disposition, zero effect. Separately prove already-running/applied/uncertain cases report honestly. Do not relabel a completed submission aborted. | +| `partial effects require recovery before retry or settlement` | Actual Petrinaut callback boundary and fixture manifest tests: one sibling applied/another failed, effect before acknowledgement, stale document basis, reconnect; recover receipt or reconcile/refuse. Never advance an incoherent bundle or claim exactly-once effects from send idempotency. | +| `wording and delivery uncertainty survive interruption` | Session/controller tests plus browser capture: recorded actual output differs legitimately from Brunch instructions; cutoff contains acknowledged progress and unknown tail, not invented heard text. Missing final ack, split/folded question marker/prose, late output, no autoplay, explicit replay. | +| `one continuous typed/spoken conversation remains usable` | `voice-preview.integration.test.ts`, `voice-browser-tools.integration.test.tsx`, rendered panel and real microphone witness: no duplicate human turns, no gap-task UI, two distinct accessible interruption/Stop controls, one workpiece, safe modality transfer and stock-assistant isolation. | + +### Verification commands and evidence separation + +Run from repository root on the approved implementation checkout, not the original older checkout. Start with each touched owner's targeted suite, then run the relevant package checks. These are planned commands, not results from this planning session. + +```sh +yarn workspace @hashintel/brunch-agent-transport-aisdk test:unit chat-transport.test.ts transcript.test.ts ui-stream.test.ts +yarn workspace @hashintel/brunch-agent test:unit workpiece.test.ts +yarn workspace @hashintel/petrinaut test:unit ai-assistant-panel.test.tsx +yarn workspace @apps/petrinaut-website test:unit voice-preview.integration.test.ts voice-browser-tools.integration.test.tsx canonical-speech.test.ts realtime-brunch-bridge.test.ts voice-turn-controller.test.ts openai-realtime-session.test.ts +yarn workspace @apps/brunch-agent build +yarn workspace @apps/brunch-agent test:unit petrinaut-chat.test.ts agent-ownership.test.ts prepared-workpiece.integration.test.ts +yarn turbo run build test:unit lint:tsc lint:eslint --filter=@hashintel/brunch-agent --filter=@hashintel/brunch-agent-binding-flue --filter=@hashintel/brunch-agent-plugin-sdcpn --filter=@hashintel/brunch-agent-transport-aisdk --filter=@apps/brunch-agent --filter=@hashintel/petrinaut --filter=@apps/petrinaut-website +yarn workspace @local/petrinaut-arch-docs lint:arch-docs +git diff --check +``` + +Read package instructions and run the repository formatter on changed files only. For product changes, update Petrinaut's `docs/ai-assistant.md`, website README, and affected API documentation; add the required package-scoped patch changeset only for new published consumer behavior. Do not duplicate the foundation's existing changeset as proof of this work. + +Use `yarn dev:brunch` and the named diagnostic fixture for browser verification without silently starting billable turns. Inspect screenshots of the default, Voice-active, interrupted, stopped, error, and reopened states that actually change. Exercise DOM/accessibility semantics for controls. A synthetic media test cannot establish audible naturalness or real microphone behavior. Obtain authorization before billable provider use; a human witness and owner promotion remain explicit gates. + +Retain sanitized canonical snapshots, event/submission/operation identities, workpiece/document hashes, browser route export, generated wording/playback-progress evidence, screenshots, fault-injection results, and exact source/dependency pins. Exclude secrets, credentials, SDP, private model reasoning, and unnecessary raw audio. Classify each claim as implemented, automated evidence, human-witnessed, owner-accepted, or unresolved. Historical witness counts are never a current test result. + +## Residual planning disposition + +| Material not consumed by a prerequisite-only cut | Sole detailed planning owner and re-entry gate | +| --- | --- | +| Ownership policy, continuous-conversation experience, alternative approaches and reasons | [Ownership design](voice-runtime-ownership.md#authority-boundaries); product amendment must name its permitted semantic deltas. | +| Recording fidelity, delegation, handback, prompts/resources, media uncertainty, operation dispositions | Corresponding sections of the ownership design; stages B/C are the first consumers. Execution sequencing and test leaves in this proposal must move intact to residual planning if this proposal is consumed at A. | +| Broad delegation, freer substantive expression, improved-relay comparison | Design expansion/experiment gates; re-enter only after scoped readiness and approved measurements/budget. | +| Mission 6b accepted deferrals and witness limitations | Pinned owner witness and future spine; direct-user attribution re-enters at A/B, post-settlement withholding at C, comparative latency only when its owner-approved criterion applies. Do not call old deferrals passes for this new scope. | +| General revision/basis/lineage/compaction, repeatable projection, reviewer semantics, deployment and optimisation | Existing numbered drafts and shared spine; no competing Voice ledger or wholesale Mission 7 import. Inspect the current accepted consumer seam before integration. | + +## Review checkpoint + +The planning review retained the four ownership boundaries, the continuous-conversation interaction, the full staged recovery obligations, and the distinction between tracer and readiness. It tightened the blocked-stage re-entry decision and the no-wake oracle; it did not approve the mission or establish runtime feasibility. The successor tracker topology is resolved. Mission conversion, resolution of the Flue dependency, paid media evidence, and final product acceptance remain separate decisions. The next decision is obtaining a supported candidate or authorizing the bounded upstream effort above, not speculative Voice code. diff --git a/libs/@hashintel/brunch-agent/docs/mission-drafts/voice-runtime-ownership.md b/libs/@hashintel/brunch-agent/docs/mission-drafts/voice-runtime-ownership.md new file mode 100644 index 00000000000..dddbb43a6a4 --- /dev/null +++ b/libs/@hashintel/brunch-agent/docs/mission-drafts/voice-runtime-ownership.md @@ -0,0 +1,295 @@ +# Voice runtime ownership and conversational delegation + +> Draft cluster only. Not execution authority. Do not implement until this cluster is re-evaluated and cut into `MISSION.md`. + +Design recorded on 2026-09-07 from the [architecture discussion](https://ampcode.com/threads/T-01a07c91-dcec-766d-acca-ad98f239ed26). This is an unallocated design proposal, not a new numbered mission, an implementation plan, or an amendment to the current branch's authority. The permitted target-runtime changes below are design choices, not permission to implement them under the existing mission. + +## Summary: who owns each part of the voice interaction? + +**Recommend split-ownership voice conversation: separate conversational control from domain authority.** + +The user experiences one continuous conversation, not a sequence of gap-filling tasks. Brunch directs the domain work; Realtime handles natural conversation within delegated authority; Flue records the interaction; Petrinaut safely executes tools. + +Every exchange must be recorded, but not every exchange needs to invoke Brunch. Typed and Brunch-owned turns continue through normal admissions. Realtime-local exchanges may use a proposed persistence-only API into the same canonical Flue conversation. When domain interpretation is required, Realtime submits an attributed proposal for Brunch validation. + +A Brunch-defined clarification gap remains one conservative form of delegation and the smallest initial experiment. It is an internal mechanism, not the overall interaction model or a user-facing workflow. + +## Cold-start reads and inspected foundation + +The discussion first queried PR #9564's `headRefOid`, then inspected exact Git objects at [`132831f14300c577c5d0b73cea9d817c8e5c6c7d`](https://github.com/hashintel/hash/commit/132831f14300c577c5d0b73cea9d817c8e5c6c7d). This is the inspected foundation, not a claim about a later PR head or the current working-tree branch. Re-query the head before an implementation cut. + +Read these sources at that revision: + +- [Mission 6b authority](https://github.com/hashintel/hash/blob/132831f14300c577c5d0b73cea9d817c8e5c6c7d/libs/%40hashintel/brunch-agent/MISSION.md) and [owner witness](https://github.com/hashintel/hash/blob/132831f14300c577c5d0b73cea9d817c8e5c6c7d/libs/%40hashintel/brunch-agent/docs/evidence/implementations/voice-resumable-reconciliation/owner-witness-2026-09-07/witness.md). +- `apps/petrinaut-website/src/server/voice/openai-voice-policy.ts` and `src/main/app/voice-interview/{openai-realtime-session,realtime-brunch-bridge,voice-turn-controller,canonical-speech}.ts` for current media and turn ownership. +- `libs/@hashintel/brunch-agent/packages/transport-aisdk/src/{index,transcript,ui-stream}.ts` and `libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.tsx` for causal continuations, projection, execution, and local withholding. +- `apps/petrinaut-website/src/main/app/local-storage-demo/crew-reservation-settled-manifest.ts` for the fixture-specific coherence boundary; Brunch core `src/prompts/SYSTEM.md`, `src/skills/elicitation/SKILL.md`, and the SDCPN plugin for authored responsibilities. +- [Flue routing guidance](../reference/architecture/flue-routing.md) before adding persistence or runtime mechanisms; the [future spine](../../MISSION.next.md) for existing provenance, construction, and deployment planning owners. + +### Existing capabilities versus limits + +| Existing at the inspected revision | Boundary of the claim | +| --- | --- | +| Typed and completed spoken inputs share canonical Brunch/Flue admission. | Spoken text survives hydration; direct spoken-user origin does not. | +| Correlated Brunch prose feeds Realtime speech with acknowledged half-duplex handoff. | Realtime has no tools and cannot independently acknowledge, clarify, or rewrite responses. | +| Browser continuations preserve original calls; result collection selects the latest relevant client-tool step, including mixed server/browser topology. | Preserve this repair when introducing local dialogue; do not reintroduce stale cumulative results. | +| Explicit true-user fixture evidence is required before mutation. | A fragment such as `SDCPN`, an inspection request, or a prepared hypothesis does not authorize a change. | +| The witness records coherent fixture resume, active-submission Stop, and stopped-entry recovery. | Coherence is fixture-specific; post-settlement locally withheld browser work can reappear after reopen. | + +The committed witness records a narrowed accepted local Voice → causal browser mutation → coherent resume → active-submission Stop path. Direct-user attribution after hydration, durable post-settlement withholding, and comparative audible latency remain explicitly deferred. The full pre-registered telemetry bundle was not retained. Witness test results are historical evidence, not checks rerun during this design discussion. + +The witness exposed excessive explanation before a necessary clarification and poor Stop discoverability while Voice was active. These are interaction-design inputs, not evidence that Realtime should own domain strategy. + +## Directions discussed in the call versus later mechanisms + +The call directions below come from the user's account of the meetings, not an independently inspected meeting transcript: + +1. Keep Realtime as the media relay. +2. Let Realtime lead the conversation and delegate to Brunch as a domain service or subagent. +3. Separate text/voice runtime responsibilities while sharing Brunch behavior and session state. The second meeting summary favored Brunch-led elicitation with a conversational voice agent. + +The architecture discussion subsequently proposed **persistence-only events, delegation scopes, structured handbacks, and durable operation dispositions**. These are candidate mechanisms, not established call decisions or capabilities already implemented in #9564. The meeting preference is an architectural hypothesis to evaluate, not empirical proof of better interaction. + +## Visible product advance + +**Release-note hypothesis:** Talk naturally with Brunch, clarify what you mean without repeated handoffs, switch between speaking and typing, and keep the same model and conversation recoverable. + +**Proposed demo:** Open a process conversation, describe an approval rule, answer a natural follow-up, interrupt to correct a detail, and finish the correction by typing. Observe the accepted workpiece and any authorized net change. Reopen the same conversation and continue without repeating the interview, replaying old speech, or duplicating work. An uncertain answer remains visibly unresolved rather than silently changing the model. + +**Previously unavailable:** Realtime cannot currently conduct permitted local clarification independently of a Brunch invocation. The UI should not expose delegation scopes or gap-completion machinery; it remains one assistant, one timeline, one composer, and one shared workpiece. + +## Three approaches and recommendation + +### 1. Improved Brunch-led relay + +Brunch owns both substance and conversational wording. Realtime transcribes and speaks supplied responses. Improve Brunch's brevity, response structure, and playback controls without adding conversational autonomy. + +This is the smallest change and the clearest authority model. Its limitation is that minor rephrasing and follow-ups still require Brunch. Challenge the assumption that awkwardness requires a second conversational model: better Brunch responses may remove much of the strain. Keep this as the baseline and fallback. + +### 2. Realtime-led conversation + +Realtime directs the conversation and delegates domain work to Brunch. It offers the greatest conversational freedom, but deciding which evidence to seek is already elicitation strategy. Brunch's later validation cannot undo a leading question or recover an important question never asked. + +The independently Realtime-led variant conflicts with the required authority boundary. If Brunch must authorize strategic direction, this approach converges toward split ownership. Do not select it merely because post-hoc mutation validation exists. + +### 3. Split-ownership voice conversation — recommended + +Brunch owns the domain agenda and supported conclusions. Realtime owns conversational expression and permitted local interaction. This improves natural follow-ups without creating competing domain authorities or replacing the integrated Brunch/Flue/Petrinaut path. + +The recommendation separates conversational control from domain authority; it does not make the experience fundamentally gap-driven. The hypothesis to test is whether bounded conversational freedom adds enough elicitation value to justify its runtime contracts over an improved relay. + +## Authority boundaries + +| Responsibility | Owner | +| --- | --- | +| Elicitation strategy and evidence sufficiency | Brunch | +| Interpretation, uncertainty, substantive claims, and IR/workpiece updates | Brunch | +| Domain-tool selection | Brunch; requesting a tool is not evidence that its effect succeeded | +| Natural wording, pacing, interruption, acknowledgements, and permitted local follow-ups | Realtime, through application-enforced media and delegation controls | +| Canonical conversation and provenance across modalities | Flue | +| Tool validation, serialization, execution, and recovery | Petrinaut, using authoritative runtime records | +| Prompt, skill, and resource authorship | Brunch-owned sources with explicit role-specific composition | + +Realtime must not independently expand domain strategy, settle an interpretation, or authorize mutations. An acknowledgement such as “Got it” is conversational; it is not a validation receipt or a claim that the model changed. Brunch determines which substantive claims are supported; Realtime expresses them without adding claims or removing consequential qualifications. + +Text/voice consistency means shared evidence, interpretation, and state, not identical independently generated prose. During voice, the transcript shows the actual conversational wording rather than a different hidden Brunch script. Domain artifacts remain separate from their spoken explanation. + +## Current and target architecture + +### Current — inspected #9564 foundation + +```text + Typed input --------------------+ + | + Microphone -> Realtime | + | transcript | + +-----------------+ + v + +-------------------------+ + | Flue normal admission | + | Invokes Brunch | + +------------+------------+ + v + +-------------------------+ + | Brunch | + | Strategy + wording | + | Interpretation + tools | + +------+-----------+------+ + | | + canonical text | tool requests + v v + +-------------+ +--------------------+ + | Chat panel | | Petrinaut | + | Realtime | | Validate / execute | + | speaks text | | Return results | + +-------------+ +---------+----------+ + | + v + Flue continuation + + One canonical Flue conversation +``` + +### Proposed — split conversational and domain ownership + +```text + +--------------------------------+ + | One conversation UI | + | Text / voice / tools / workpiece| + +----------+---------------------+ + | + +--------------+----------------+ + | | + v v + +-------------------------+ +-------------------------+ + | Brunch | | Realtime | + | DOMAIN AUTHORITY |---->| CONVERSATIONAL CONTROL | + | | | | + | Strategy and sufficiency| | Wording and pacing | + | Interpretation and IR |<----| Interruption and ack. | + | Claims and tool choice | | Permitted follow-ups | + +------------+------------+ +------------+------------+ + | delegation / handback | + | | + v v + +--------------------------------------------------------+ + | Flue: ONE CANONICAL CONVERSATION AND PROVENANCE RECORD | + | Normal admissions invoke Brunch | + | Proposed event-only appends record local exchanges | + +---------------------------+----------------------------+ + | + Brunch-selected domain work + v + +----------------------------+ + | Petrinaut | + | Validate / serialize | + | Execute / record / recover | + +-------------+--------------+ + | + v + Shared workpiece / net + Results return to Flue +``` + +These are responsibility boundaries, not new services. Flue recording is not mutation authorization. Provider histories are reconstructible context, not independent conversation authorities. One canonical conversation does not require duplicating document storage inside Flue or pretending the stores already share a transaction. + +## Proposed runtime contracts + +### Persistence-only events + +Typed and Brunch-owned turns retain normal admissions. Realtime-local exchanges append to the same Flue conversation without scheduling Brunch. This requires a supported extension; an unsupported local Flue patch, hidden synthetic user turn, or browser transcript sidecar is not the proposed solution. + +The contract needs authenticated attribution, canonical order and causal references, stable event identities, idempotent same-payload retries, changed-payload conflicts, hydration, and visibility to subsequent Brunch reasoning. Appending text or tool-shaped data cannot execute tools or forge Brunch validation. Runtime code records every exchange, including unsuccessful or interrupted ones; recording cannot depend on the model voluntarily calling an audit tool. + +### Conversational delegation and structured handback + +A delegation scope makes permitted freedom explicit: purpose, relevant evidence/workpiece basis, allowed exploration, return conditions, and an identity/version. The first conservative scope can be a Brunch-defined clarification gap. Realtime chooses wording and permitted follow-ups, then proposes an interpretation rather than marking domain understanding complete. + +Handback is an agent-authored normal admission referencing original exchange events, the delegation basis, proposed meaning, uncertainty, and why Brunch is needed. Return on a useful answer, conflict, new topic, out-of-scope uncertainty, decline, or stop. Brunch reads the evidence and accepts, rejects, or requests more information. Never relabel the proposal as another human message or replace the exchange with its summary. + +Typed instructions, explicit stop, or relevant state changes suspend or invalidate outstanding delegation. Playback acknowledgements must not invalidate it merely because they advance the log. A stale proposal may remain attributable evidence but cannot authorize a current mutation. + +### Durable operation dispositions + +Pending browser work needs a durable disposition independent of whether its originating model step has settled. A generic recorded “stop” does not enforce cancellation: an authorized runtime control action must establish the disposition that Petrinaut consults. + +Distinguish cancelled-before-execution, already executing, applied, failed, and uncertain outcomes. Preserve stable operation identity, original call/step ownership, validated inputs, expected document basis, and effect/result records. Prefer an atomic document-change/receipt boundary where available; otherwise require explicit reconciliation before retry. Serialization and idempotent admission alone do not prove exactly-once effects. + +## End-to-end interaction flows + +### Local voice interaction + +1. Brunch records the delegated conversational purpose and evidence basis. +2. Realtime generates natural wording; the adapter records its authorship, delegation reference, and actual output. +3. Playback is tracked, and each finalized user transcript is recorded once. +4. Realtime continues within permission or submits a structured handback through normal admission. +5. Brunch validates meaning and records the resulting decision, workpiece change, or next delegation. + +### Voice evidence leading to a domain effect + +1. Brunch reads the original evidence behind the proposal and validates its interpretation. +2. The workpiece basis for construction settles before dependent mutation work. +3. Brunch selects a domain operation; Petrinaut validates and serializes execution. +4. The original call receives its own causal result, including refusals, no-ops, and partial failures. +5. Brunch reports the observed outcome. Coherence checks determine what can be claimed as settled and recoverable. + +### Typed input and modality switching + +1. Typed input uses normal admission into the same conversation. +2. Suspend current voice delegation and stop or finish delivery according to the interaction policy; do not implicitly cancel effects. +3. Brunch receives the recorded local exchanges, including unresolved proposals, without duplicating human messages. +4. Brunch continues through the same interpretation, workpiece, and tool boundaries. +5. Returning to voice uses current canonical context and renewed delegation. + +The UI remains one assistant identity and timeline. Attribution belongs in inspectable provenance. Keep interrupt-speech and stop-work controls distinct and available during voice; do not require leaving voice to discover durable Stop. + +## Provenance, cancellation, and recovery + +Preserve five distinct milestones: input recorded/admitted, Brunch step complete, browser operation complete, coherent state settled, and playback complete. A single UI “busy” label must not become their shared runtime meaning. + +Record human transcript and any normalization separately; actual generated wording and its author; explicit decisions and concise rationale; tool requests, attempts, results and effects; playback identities, attempts, progress and uncertainty. Preserve user evidence separately from agent suggestion, interpretation, and assent to supplied wording. Decision records do not depend on obtaining private model reasoning. + +| Event or failure | Required behavior | +| --- | --- | +| Interrupt speech | Stop audio promptly and record the cutoff; preserve admitted domain work unless separately cancelled. | +| Stop work | Durably prevent eligible pending operations and further reasoning; report already-running/applied work without claiming rollback. | +| Append/admission acknowledgement lost | Resolve the original identity; do not create a new logical exchange blindly. | +| Effect applied before result acknowledgement | Recover the receipt or reconcile authoritative document state before retrying. | +| Disconnect or late events from an old connection | Rebuild from canonical evidence and operation state; fence stale authority; no autoplay or implicit cancellation. | + +New speech may be recorded while an existing operation settles, but state-dependent proposals and mutations cannot overtake it. Initially retain one active execution owner per workpiece; another tab observes until ownership transfers. Fresh-tab recovery does not establish active-active safety. + +For the text-level playback requirement, retain full generated wording plus acknowledged playback position and uncertainty, not an invented exact heard prefix. A lost final acknowledgement leaves an unknown delivery tail. OpenAI's [Realtime interruption documentation](https://developers.openai.com/api/docs/guides/realtime-conversations#interruption-and-truncation) does not promise a precisely truncated text transcript. If audio becomes audible before corresponding wording is durable, a crash can leave unrecorded speech; test short-utterance persistence before release, with buffered or text-first rendering as the conservative fallback. Permanent audio retention is not required by this design. + +## Prompt, skill, and resource consistency + +Use shared authored material with explicit role-specific composition: + +- Shared: authorship, uncertainty, vocabulary, evidence discipline, and respecting stop. +- Brunch: strategy, evidence sufficiency, interpretation, workpiece maintenance, substantive claims, and construction. +- Realtime: delivery, acknowledgement semantics, and permitted conversational exploration. +- Resources: versioned shared references with role-appropriate access. + +Do not copy the complete elicitation strategy into Realtime and call that consistency. Start with straightforward composition rather than a general profile compiler. Record effective prompt, skill, resource, and model versions; make upgrades explicit. Behavioral tests are necessary because shared source text cannot guarantee matching model behavior. + +## Migration stages and readiness gates + +| Stage | Change | Required evidence before promotion | +| --- | --- | --- | +| Preserve the foundation | Re-pin #9564 and retain accepted behavior and explicit deferrals. | Causal results, evidence gating, conversation isolation, Stop, and coherent reopen regression coverage. | +| Add recording | Event-only local dialogue and playback records, initially without autonomous clarification. | Fresh-process reconstruction; append does not invoke Brunch or mutate domain state. | +| Delegate one interaction | One conservative clarification scope and structured handback. | Useful natural clarification without evidence laundering or unauthorized effects. | +| Integrate recovery | Durable pending-operation cancellation, modality transfer, reconnect, and interleaving. | Fault-injected contracts and real browser/microphone witnesses. | +| Expand only under evidence | Broader delegated interaction or freer substantive presentation. | Better elicitation quality without weakened provenance, claims, or execution safety. | + +The smallest first experiment is one delegated clarification, two Realtime-local exchanges, one structured handback, one Brunch-validated workpiece update, and fresh-process reconstruction. This is a throughline proof floor, not permission to call the complete target safe. Add browser mutation and interruption races before claiming the integrated product advance. Existing deferrals remain valid for #9564's narrowed claim, not as passes for the broader target. + +## Candidate evidence and required tests + +These are proposed acceptance scenarios, not tests claimed to exist or pass. Reuse the existing test owners rather than introducing a parallel evaluation runtime. + +| Test owner or boundary | Required discriminator | +| --- | --- | +| Supported Flue event API and `apps/brunch-agent` runtime integration | Multiple local events cause zero Brunch invocations; one proposal admits the intended invocation. Reopen reconstructs attribution without browser correlation state. | +| `packages/transport-aisdk/test/chat-transport.test.ts` and transcript tests | Duplicate/conflicting events and proposals preserve identity. Local dialogue between calls/results cannot corrupt mixed server/browser step causality or sibling outcomes. | +| Petrinaut `ai-assistant-panel.test.tsx` and actual tool boundary | Event content cannot forge authorization; race and crash cases prevent duplicate effects or resurrection of durably cancelled work. | +| Website voice session/controller/bridge tests and `voice-browser-tools.integration.test.tsx` | Mode switches, interruptions, stale connections, playback uncertainty, and delegation invalidation preserve ownership and state. | +| Real browser/microphone comparative witness | Improved relay versus split ownership: useful information gained, unsupported assumptions, repetition, correction effort, naturalness, and audible interruption/recovery. | + +Retain the inspected revision's causal-result, explicit-evidence, and conversation-owned callback repairs. Test question identity across split/folded messages: the current selector requires marker/prose co-location, while the witness reports working replay for its scenario. That warrants alternate-topology coverage, not a claim that replay is universally broken. Future question identity should connect delegated intent, actual wording, and playback without depending on a rendered message boundary. + +Inner tests establish schema, identity, and state rules; runtime/host integration tests establish actual boundary crossings; outer microphone/browser witnesses establish audible and user-visible behavior. A future implementation owner must retain the evidence, and the product owner must adjudicate promotion. Set numerical quality/latency thresholds and any paid budget before trials; this draft authorizes neither spending nor a test campaign. Preference or lower latency alone is insufficient to justify degraded evidence quality. + +## Unresolved experiments and stop conditions + +| Uncertainty | Why it matters | Smallest discriminating experiment | +| --- | --- | --- | +| Supported Flue extension | External dialogue must share ordering, hydration, and context without waking Brunch. | Append local user/assistant events, reopen, then invoke Brunch once with original evidence references. | +| Delegation usefulness | Local follow-ups may drift into strategy or repeatedly hand control back. | Compare one bounded interaction against a better-prompted relay, including leading-question and ambiguous-assent controls. | +| Media durability | Generated wording may lag audible delivery. | Interrupt/disconnect at output boundaries and inspect durable wording versus acknowledged playback; measure buffering cost. | +| Durable execution boundary | Browser effects and runtime acknowledgements can separate on failure. | Crash around effect/receipt and Stop/claim boundaries; reconcile the resulting document without duplicate execution. | +| General recovery and explanation | The prepared fixture is not a general workpiece transaction or provenance system. | Extend only on the selected real scenario and integrate with existing revision/basis work rather than inventing a competing ledger. | + +Stop or reorient if the design needs a second conversation authority, promotes Realtime interpretation without Brunch validation, treats a prompt instruction as an execution safeguard, invents missing evidence, revives cancelled work, or produces no useful clarification benefit over the improved relay. Do not add a generalized workflow language, new deployment topology, comprehensive ontology, or full profile compiler merely to implement this split. + +The recommendation remains **split ownership**, with clarification as the first conservative delegation experiment—not a fundamentally gap-driven user experience. diff --git a/libs/@hashintel/brunch-agent/docs/reference/architecture/topology.md b/libs/@hashintel/brunch-agent/docs/reference/architecture/topology.md index 8e636b7eec2..bfd1bc8a77a 100644 --- a/libs/@hashintel/brunch-agent/docs/reference/architecture/topology.md +++ b/libs/@hashintel/brunch-agent/docs/reference/architecture/topology.md @@ -1,6 +1,6 @@ # Topology: verification and specification -**Status: ratified 2026-08-17 (Lu), application layout updated 2026-08-31 — recorded as [ADR-0002](../../adr/0002-topology-and-placement-rules.md); this file remains the living reference.** Verifies the current app/package topology against the three-lane model (cheatsheet, boundary summary), spec §12.2, and Flue's project-layout guide; then specifies where upcoming work lands. Pseudo-style: tree nodes with rules; `✓` complies today, `✗` violates, `→` normative rule for what's next. +**Status: ratified 2026-08-17 (Lu), application layout updated 2026-08-31 and conversation transport updated by FE-1574 / Mission 5 on 2026-09-03 — recorded as [ADR-0002](../../adr/0002-topology-and-placement-rules.md); this file remains the living reference.** Verifies the current app/package topology against the three-lane model (cheatsheet, boundary summary), spec §12.2, and Flue's project-layout guide; then specifies where upcoming work lands. Pseudo-style: tree nodes with rules; `✓` complies today, `✗` violates, `→` normative rule for what's next. ## Verification — the tree as it stands @@ -36,12 +36,13 @@ packages/binding-flue LANE 2 (translate harness ↔ Flue dialect) archive, legacy provisioning, parse-on-read, tmp+rename, per-path queue). One per deploy target per binding. Never: business rules. -packages/transport-aisdk UI REPLY WIRE (substrate-neutral) -└─ index.ts ✓ validates Petrinaut's POST, drives an application-supplied harness turn, - and encodes - harness reply events with `ai` only. Opt-in inspection emits metadata - out-of-band. Never: binding/Flue imports, inference, conversation - rendering, or diagnostics dispatched as user evidence. +packages/transport-aisdk BROWSER FLUE → AI SDK PROJECTION +├─ index.ts ✓ adapts one caller-supplied public `FlueClient` to an AI SDK `ChatTransport`; +│ sends one user message or client-tool-result signal and follows only the +│ admitted submission. Never: `@flue/runtime`, core, plugin, or binding imports. +├─ ui-stream.ts ✓ projects Flue conversation chunks into one finite AI SDK response stream +├─ transcript.ts ✓ projects SDK-maintained canonical state into renderable UI messages +└─ identity.ts ✓ browser-safe principal + logical-conversation identity and ownership headers packages/plugin-gherkin TARGET POLICY + Flue-native contribution bundle (not yet composed) ├─ index.ts ✓ pairing identity only (YAML definition removed 2026-09-02) @@ -70,10 +71,10 @@ apps/brunch-agent LANE 1 SHELL + remote server (imported from a │ ├─ agent.ts ✓ sole directive-marked registration and composition point: generic core, │ │ selected SDCPN/Petrinaut plugin, and deployment instructions │ └─ tools/ping.ts ✓ app-only server-path diagnostic -├─ src/http/ ✓ HTTP authority: assets, route names, ownership guard, local origins, -│ and `/api/chat` composition -├─ src/conversation/ ✓ identity and projection authority: shared payload, client-tool signal, -│ Flue-history transcript, and AI SDK stream projection +├─ src/http/ ✓ HTTP authority: assets, mounted route names, ownership guard, and local origins; +│ `/agents/chat/:instanceId` is the sole Brunch conversation door +├─ src/conversation/ ✓ server identity verification, client-tool catalog, and operator transcript; +│ browser AI SDK projection lives in `transport-aisdk` ├─ src/capture/ ✓ Mission 2 application composition over binding-owned history/store ports; │ no elicitation policy ├─ src/evaluations/runbook/ ✓ runbook experiment drivers, artifact recovery, and headless client; diff --git a/libs/@hashintel/brunch-agent/docs/specs/petrinaut-integration.md b/libs/@hashintel/brunch-agent/docs/specs/petrinaut-integration.md index 15aaa55b7ff..b315a764651 100644 --- a/libs/@hashintel/brunch-agent/docs/specs/petrinaut-integration.md +++ b/libs/@hashintel/brunch-agent/docs/specs/petrinaut-integration.md @@ -1,11 +1,6 @@ # Integration spec: the elicitor behind Petrinaut's chat panel -**Ticket**: FE-1433 (the integration-spec issue) · **Decision record**: ADR-0004 -(`docs/adr/0004-in-petrinaut-staging-and-the-monorepo-import.md`) · **Supersedes**: -`recommendation-demo-vehicle.md` as the September staging plan · **Evidence base**: the -Petrinaut survey (FE-1358, `research/petrinaut-survey.md`), re-verified against -`hashintel/hash` source on 2026-08-18 · **Amended**: FE-1506 (stable UI and voice attach -contract), H-6763 / ADR-0009 (generic composer submission and app-owned voice boundary). +**Ticket**: FE-1433 (the integration-spec issue) · **Decision record**: ADR-0004 (`docs/adr/0004-in-petrinaut-staging-and-the-monorepo-import.md`) · **Supersedes**: `recommendation-demo-vehicle.md` as the September staging plan · **Evidence base**: the Petrinaut survey (FE-1358, `research/petrinaut-survey.md`), re-verified against `hashintel/hash` source on 2026-08-18 · **Amended**: FE-1506 (stable UI and voice attach contract), H-6763 / ADR-0009 (generic composer submission and app-owned voice boundary), and FE-1574 / Mission 5 (one mounted Flue conversation route and browser AI SDK projection). ## Problem Statement @@ -20,26 +15,14 @@ storage. The problem is connecting the second to the first without rebuilding ei ## Solution -The brunch elicitor runs as a **remote server** built on the harness + `binding-flue`. The -demo site swaps its `aiAssistant.transport` to point at that server; everything else in the -panel — rendering, the diagnostics decorator, client-side tool execution — is reused as-is. -The elicitor drives Petrinaut's editor through the **existing UI-executed tool surface** -(schemas imported from `petrinaut-core`), riding the harness's turn-suspension protocol: a -turn ends with tool calls pending, the panel executes them, and the outputs return on the next -dispatch. Sessions, captures, and IRs persist server-side, keyed to an opaque principal the -site supplies from a localStorage UID. The wire contract is the AI SDK v6 UI-message-stream -protocol, produced by a new `transport-aisdk` package that translates harness-level parts to -stream chunks and knows nothing about Flue. +The Brunch elicitor runs as a **long-running Flue server** built on the harness + `binding-flue`; Mission 5 proves the local same-origin path, while remote deployment remains a separate gate. The demo site derives one guarded `/agents/chat/:instanceId` URL from its opaque principal and logical conversation id, creates a public `@flue/sdk` client for that conversation, and supplies Petrinaut with a browser `ChatTransport` that projects Flue conversation events into the AI SDK rendering contract. Everything else in the panel — rendering, the diagnostics decorator, and client-side tool execution — is reused as-is. The elicitor drives Petrinaut's editor through the **existing UI-executed tool surface** (schemas imported from `petrinaut-core`): a response may end with client tool calls pending, the panel executes them, and one `client-tool-result` signal resumes the owning Flue conversation. Flue history is the canonical conversation record; captures and IRs remain in their own server-side stores. ## Seams One primary seam, four supporting ones — all existing except the brunch server's front door, which the design needs anyway: -1. **The ChatTransport wire seam** (primary; the contract-test surface): the AI SDK - UI-message-stream protocol over HTTP/SSE. Everything brunch-side sits behind it; everything - Petrinaut-side sits in front of it. The panel's real behavior is verified once in the - adapter spike and frozen as golden fixtures. +1. **The browser ChatTransport projection seam** (primary; the contract-test surface): `@flue/sdk` owns send, observation, offsets, retry, settlement, and recovery over the mounted Flue route; `transport-aisdk` projects one admitted submission into the finite AI SDK `UIMessageChunk` stream Petrinaut renders. The production-path integration test drives this seam through the real app router without hand-parsing SSE. 2. **The ask/affordance protocol seam** (`core`'s ask-protocol module, per ADR-0002 N1): the external-tool round-trip protocol is tested here, substrate-free. 3. **The storage port seam** (ADR-0002 N5): the owner key is tested as store-level refusals. @@ -57,8 +40,7 @@ which the design needs anyway: The panel and the voice edge attach to Brunch through one stable surface: -1. **Chat stream**: the UI sends `POST /api/chat`; a successful response is an AI SDK v6 - UI-message stream over HTTP/SSE. +1. **Conversation transport**: the browser calls `FlueClient.send()` against the guarded `/agents/chat/:instanceId` route, then follows the admitted submission through the SDK. The host-supplied browser `ChatTransport` projects that Flue stream into the finite AI SDK v6 UI-message stream consumed by `useChat`; the stock Petrinaut `/api/chat` route is a separate fallback and never carries Brunch turns. 2. **Question affordance**: the UI-executed tool is named `brunch_ask`. Its input schema is `{ question: non-empty string }`; its submitted output schema is `{ answer: non-empty string }`. @@ -140,18 +122,8 @@ host application under ADR-0009, while reusable Petrinaut and Brunch packages st **Topology and packaging** -- The elicitor server is a thin host-authored agent (spec §13) around the harness library, - deployed remotely; the demo site's same-origin `/api/chat` route reaches that server without - routing through the stock Petrinaut assistant or its prompt. -- Implemented by FE-1436 (the durable AI SDK transport): package `transport-aisdk` is the - server end of the ui shell's reply transport. It translates - harness-level parts to AI SDK v6 UI-message-stream chunks, using the `ai` package for stream - encoding only (no provider use — inference stays on Pi's adapter layer). Depends on `core`, - `ai`, and `valibot` for external request validation; never on the binding or Flue. This adds - a `transport-*` role prefix to the §12.2 - vocabulary (the glossary's avoided terms `adapter-*`/`wrapper-*` stay avoided). The - implementation and real-panel evidence are recorded in - `transport-aisdk-implementation-2026-08-19.md`. +- The elicitor server is a thin host-authored Flue agent around the harness library. The demo site's same-origin proxy forwards `/agents/chat/*` without changing the Flue protocol; the stock Petrinaut assistant and `/api/chat` prompt remain separate. +- FE-1436 originally introduced `transport-aisdk` as a server-side AI SDK HTTP adapter. FE-1574 / Mission 5 replaced that door: the package is now the browser-side projection from the public Flue client to Petrinaut's AI SDK rendering contract. Its runtime dependencies are exactly `@flue/sdk` and `ai`; it imports neither `@flue/runtime`, core, a plugin, nor a binding. The app supplies its client-tool catalog, and the package owns the shared `client-tool-result` signal representation. - Kernel spec amendments applied with this work, not silently: §12.2 package list gains `transport-aisdk` and records the monorepo import (`@hashintel/brunch-agent`, hash toolchain replacing the Bun workspace at import time); §13's shipping shape and ADR-0002 N3 diff --git a/libs/@hashintel/brunch-agent/packages/core/package.json b/libs/@hashintel/brunch-agent/packages/core/package.json index 5ab4e8a9874..70593a8eb94 100644 --- a/libs/@hashintel/brunch-agent/packages/core/package.json +++ b/libs/@hashintel/brunch-agent/packages/core/package.json @@ -18,9 +18,17 @@ "types": "./src/flue.ts", "import": "./dist/flue.js" }, + "./question-marker": { + "types": "./src/question-marker.ts", + "import": "./dist/question-marker.js" + }, "./storage": { "types": "./src/storage.ts", "import": "./dist/storage.js" + }, + "./workpiece": { + "types": "./src/workpiece.ts", + "import": "./dist/workpiece.js" } }, "scripts": { diff --git a/libs/@hashintel/brunch-agent/packages/core/src/flue.ts b/libs/@hashintel/brunch-agent/packages/core/src/flue.ts index cb020aaf9e0..9d57e9ea9e1 100644 --- a/libs/@hashintel/brunch-agent/packages/core/src/flue.ts +++ b/libs/@hashintel/brunch-agent/packages/core/src/flue.ts @@ -1,6 +1,20 @@ -import { useModel, useSkill } from "@flue/runtime"; +import { + defineTool, + useDataWriter, + useModel, + useSkill, + useTool, +} from "@flue/runtime"; +import * as v from "valibot"; import systemPrompt from "./prompts/SYSTEM.md?raw"; +import { + BRUNCH_QUESTION_DATA_NAME, + BRUNCH_QUESTION_TOOL_NAME, + BrunchQuestionDataSchema, + BrunchQuestionInputSchema, + type BrunchQuestionData, +} from "./question-marker"; import { ELICITATION_SKILL_NAME, elicitationSkill, @@ -10,14 +24,32 @@ import { skillFromMarkdown } from "./skills/skill-markdown"; /** * Mount the contributions owned by Brunch core and return its system prompt. * - * Core contributes the always-on universal prompt and one `elicitation` - * capability skill. It owns no model-facing tool; add one here only when it - * applies independently of the selected modelling formalism and host. + * Core contributes the always-on universal prompt, one `elicitation` + * capability skill, and the formalism-independent question marker. */ export function useBrunchAgent(model: string): string { useModel(model); useSkill(elicitationSkill); + const writeQuestion = useDataWriter(BRUNCH_QUESTION_DATA_NAME, { + schema: BrunchQuestionDataSchema, + }); + useTool(createBrunchQuestionMarkerTool(writeQuestion)); return systemPrompt.replace(/^\s+|\s+$/gu, ""); } +export const createBrunchQuestionMarkerTool = ( + writeQuestion: (question: BrunchQuestionData) => void, +) => + defineTool({ + name: BRUNCH_QUESTION_TOOL_NAME, + description: + "Mark the exact text of a direct question for accessible replay. Call this immediately before including that exact question in ordinary assistant prose. This marker does not ask or answer the question itself.", + input: BrunchQuestionInputSchema, + output: v.object({ marked: v.literal(true) }), + run({ data, toolCallId }) { + writeQuestion({ question: data.question, toolCallId }); + return { output: { marked: true as const } }; + }, + }); + export { ELICITATION_SKILL_NAME, elicitationSkill, skillFromMarkdown }; diff --git a/libs/@hashintel/brunch-agent/packages/core/src/index.ts b/libs/@hashintel/brunch-agent/packages/core/src/index.ts index f4021f55ef0..25fd3fdc75c 100644 --- a/libs/@hashintel/brunch-agent/packages/core/src/index.ts +++ b/libs/@hashintel/brunch-agent/packages/core/src/index.ts @@ -41,6 +41,14 @@ export { toolPrefix, type Operation, } from "./conversation/naming"; +export { + BRUNCH_QUESTION_DATA_NAME, + BRUNCH_QUESTION_TOOL_NAME, + BrunchQuestionDataSchema, + BrunchQuestionInputSchema, + parseBrunchQuestionData, + type BrunchQuestionData, +} from "./question-marker"; export { type HarnessReplyEvent, type ReplyPartKind, diff --git a/libs/@hashintel/brunch-agent/packages/core/src/prompts/SYSTEM.md b/libs/@hashintel/brunch-agent/packages/core/src/prompts/SYSTEM.md index 6c8049566df..99a6c65a011 100644 --- a/libs/@hashintel/brunch-agent/packages/core/src/prompts/SYSTEM.md +++ b/libs/@hashintel/brunch-agent/packages/core/src/prompts/SYSTEM.md @@ -10,6 +10,8 @@ Establish what the result must help the person decide, answer, compare, explain, Use the person's vocabulary and follow concrete cases rather than traversing a schema, template, or target representation. Do not open with a battery of independent questions; deepen one answerable thread at a time and group questions only when they share one frame. +Before asking the person a direct question, call `brunch_mark_question` with the exact question text. Then include the exact same question text in ordinary assistant prose. The marker only makes that text available for accessible replay; it does not wait for or accept the answer, so continue the same response normally after calling it. Do not mark headings, rhetorical questions, or prose that you will not present verbatim. + ## Authorship and uncertainty Keep what the person said distinct from your normalization, inference, assumption, proposal, transformation, or default. Do not invent content, silently increase precision, or treat assent to wording you supplied as independent evidence. When accounts differ, establish whether the relationship is correction, conflict, or contextual coexistence before reconciling them. diff --git a/libs/@hashintel/brunch-agent/packages/core/src/question-marker.ts b/libs/@hashintel/brunch-agent/packages/core/src/question-marker.ts new file mode 100644 index 00000000000..ba6194c63f5 --- /dev/null +++ b/libs/@hashintel/brunch-agent/packages/core/src/question-marker.ts @@ -0,0 +1,28 @@ +import * as v from "valibot"; + +export const BRUNCH_QUESTION_TOOL_NAME = "brunch_mark_question"; +export const BRUNCH_QUESTION_DATA_NAME = "brunch-question"; + +const NonBlankStringSchema = v.pipe( + v.string(), + v.check((value) => /\S/u.test(value), "Expected a non-blank string."), +); + +export const BrunchQuestionInputSchema = v.object({ + question: NonBlankStringSchema, +}); + +export const BrunchQuestionDataSchema = v.object({ + question: NonBlankStringSchema, + toolCallId: NonBlankStringSchema, +}); + +export type BrunchQuestionData = v.InferOutput; + +export const parseBrunchQuestionData = ( + value: unknown, +): BrunchQuestionData | undefined => { + const result = v.safeParse(BrunchQuestionDataSchema, value); + + return result.success ? result.output : undefined; +}; diff --git a/libs/@hashintel/brunch-agent/packages/core/src/workpiece.ts b/libs/@hashintel/brunch-agent/packages/core/src/workpiece.ts new file mode 100644 index 00000000000..988d6cea849 --- /dev/null +++ b/libs/@hashintel/brunch-agent/packages/core/src/workpiece.ts @@ -0,0 +1,223 @@ +/** + * Substrate-neutral selection of the current Markdown workpiece from an + * append-only conversation projection. + */ + +export const preparedWorkpieceSignalType = "brunch.fixture.prepared"; +export const preparedWorkpieceSignalTag = "prepared-fixture"; +export const preparedWorkpieceAuthorship = "test-authored"; +export const preparedWorkpieceClaimBoundary = "prepared-not-model-produced"; +export const preparedWorkpieceInitialDataMode = "validated-fixture-mutation"; +export const runbookIrFence = "runbook-ir"; + +type WorkpieceTextPart = { + readonly text: string; + readonly type: "text"; +}; + +export interface WorkpieceHistoryMessage { + readonly body?: string; + readonly id: string; + readonly parts: readonly ( + | WorkpieceTextPart + | { readonly type: string; readonly [key: string]: unknown } + )[]; + readonly purpose: string; + readonly role: string; + readonly signal?: { + readonly attributes?: Readonly>; + readonly tagName?: string; + readonly type?: string; + }; + readonly submissionId?: string; +} + +export interface WorkpieceHistory { + readonly conversationId: string; + readonly messages: readonly WorkpieceHistoryMessage[]; +} + +export interface PreparedWorkpieceDelivery { + readonly idempotencyKey: string; + readonly message: { + readonly attributes: { + readonly authorship: typeof preparedWorkpieceAuthorship; + readonly claimBoundary: typeof preparedWorkpieceClaimBoundary; + readonly fixtureId: string; + }; + readonly body: string; + readonly kind: "signal"; + readonly tagName: typeof preparedWorkpieceSignalTag; + readonly type: typeof preparedWorkpieceSignalType; + }; +} + +export interface SelectedRunbookWorkpiece { + readonly authorship: "model-produced" | "test-authored"; + readonly content: string; + readonly fixtureId?: string; + /** + * Position in the append-only revision sequence, derived from the history + * itself rather than from whoever observed it: a prepared source is always + * revision zero and each later eligible assistant workpiece adds one. + */ + readonly revision: number; + readonly sourceKind: "assistant" | "prepared-signal"; + readonly sourceMessage: WorkpieceHistoryMessage; + readonly sourceMessageId: string; + readonly sourceSubmissionId?: string; +} + +const runbookIrFencePattern = /```runbook-ir\s*\n([\s\S]*?)```/gu; + +export const latestRunbookIrBlock = (text: string): string | undefined => { + const matches = [...text.matchAll(runbookIrFencePattern)]; + const last = matches.at(-1)?.[1]; + return last === undefined ? undefined : last.trim(); +}; + +const textFrom = (message: WorkpieceHistoryMessage): string => + message.parts + .filter((part): part is WorkpieceTextPart => part.type === "text") + .map((part) => part.text) + .join("\n"); + +const preparedFixtureIdFrom = ( + message: WorkpieceHistoryMessage, +): string | undefined => { + const fixtureId = message.signal?.attributes?.fixtureId; + return typeof fixtureId === "string" && fixtureId.length > 0 + ? fixtureId + : undefined; +}; + +const isPreparedWorkpieceMessage = ( + message: WorkpieceHistoryMessage, +): boolean => + message.role === "system" && + message.purpose === "dispatch" && + message.signal?.tagName === preparedWorkpieceSignalTag && + message.signal.attributes?.authorship === preparedWorkpieceAuthorship && + message.signal.attributes.claimBoundary === preparedWorkpieceClaimBoundary && + preparedFixtureIdFrom(message) !== undefined; + +const selectedFrom = ( + message: WorkpieceHistoryMessage, + source: Pick< + SelectedRunbookWorkpiece, + "authorship" | "revision" | "sourceKind" + >, +): SelectedRunbookWorkpiece | undefined => { + const content = latestRunbookIrBlock(textFrom(message)); + if (content === undefined) return undefined; + + return { + ...source, + content, + sourceMessage: message, + sourceMessageId: message.id, + ...(message.submissionId === undefined + ? {} + : { sourceSubmissionId: message.submissionId }), + }; +}; + +export const createPreparedWorkpieceDelivery = (input: { + readonly body: string; + readonly fixtureId: string; + readonly revision: number; +}): PreparedWorkpieceDelivery => { + if (input.fixtureId.length === 0) { + throw new Error("A prepared workpiece delivery requires a fixture id."); + } + if (latestRunbookIrBlock(input.body) === undefined) { + throw new Error( + "A prepared workpiece delivery requires a full runbook-ir block.", + ); + } + + return { + idempotencyKey: `${preparedWorkpieceSignalTag}:${input.fixtureId}:revision-${input.revision}`, + message: { + kind: "signal", + type: preparedWorkpieceSignalType, + tagName: preparedWorkpieceSignalTag, + body: input.body, + attributes: { + fixtureId: input.fixtureId, + authorship: preparedWorkpieceAuthorship, + claimBoundary: preparedWorkpieceClaimBoundary, + }, + }, + }; +}; + +/** + * Prepared revision zero is a tagged dispatch record. Later assistant + * workpieces win in log order, except for the assistant reply produced by the + * preparation submission itself. + */ +export const selectRunbookWorkpiece = ( + history: WorkpieceHistory, +): SelectedRunbookWorkpiece | undefined => { + const preparedCandidates = history.messages.filter( + (message) => message.signal?.tagName === preparedWorkpieceSignalTag, + ); + if (preparedCandidates.length > 1) { + throw new Error( + `Conversation ${history.conversationId} has more than one prepared workpiece source.`, + ); + } + + const preparedMessage = preparedCandidates.at(0); + if ( + preparedMessage !== undefined && + !isPreparedWorkpieceMessage(preparedMessage) + ) { + throw new Error( + `Conversation ${history.conversationId} has a malformed prepared workpiece source.`, + ); + } + + const preparationSubmissionId = preparedMessage?.submissionId; + let selected: SelectedRunbookWorkpiece | undefined; + + for (const message of history.messages) { + if (message === preparedMessage) { + const preparedWorkpiece = selectedFrom(message, { + authorship: preparedWorkpieceAuthorship, + revision: 0, + sourceKind: "prepared-signal", + }); + if (preparedWorkpiece === undefined) { + throw new Error( + `Conversation ${history.conversationId} has a prepared source without a runbook-ir block.`, + ); + } + const fixtureId = preparedFixtureIdFrom(message); + if (fixtureId === undefined) { + throw new Error( + `Conversation ${history.conversationId} has a malformed prepared workpiece source.`, + ); + } + selected = { ...preparedWorkpiece, fixtureId }; + continue; + } + if ( + message.purpose !== "assistant" || + message.role !== "assistant" || + (preparationSubmissionId !== undefined && + message.submissionId === preparationSubmissionId) + ) { + continue; + } + const assistantWorkpiece = selectedFrom(message, { + authorship: "model-produced", + revision: selected === undefined ? 0 : selected.revision + 1, + sourceKind: "assistant", + }); + if (assistantWorkpiece !== undefined) selected = assistantWorkpiece; + } + + return selected; +}; diff --git a/libs/@hashintel/brunch-agent/packages/core/test/question-marker.test.ts b/libs/@hashintel/brunch-agent/packages/core/test/question-marker.test.ts new file mode 100644 index 00000000000..b1da49f3049 --- /dev/null +++ b/libs/@hashintel/brunch-agent/packages/core/test/question-marker.test.ts @@ -0,0 +1,93 @@ +import { readFile } from "node:fs/promises"; + +import * as v from "valibot"; +import { describe, expect, test, vi } from "vitest"; + +import { createBrunchQuestionMarkerTool } from "../src/flue"; +import { + BRUNCH_QUESTION_DATA_NAME, + BRUNCH_QUESTION_TOOL_NAME, + BrunchQuestionDataSchema, + BrunchQuestionInputSchema, + parseBrunchQuestionData, + type BrunchQuestionData, +} from "../src/question-marker"; + +import type { FlueLogger } from "@flue/runtime"; + +describe("the Brunch question marker", () => { + test("defines one non-interactive tool and data-part identity", () => { + expect(BRUNCH_QUESTION_TOOL_NAME).toBe("brunch_mark_question"); + expect(BRUNCH_QUESTION_DATA_NAME).toBe("brunch-question"); + }); + + test("preserves exact non-blank question text and tool-call identity", () => { + const question = " Which line should run this order? "; + + expect( + v.parse(BrunchQuestionInputSchema, { + question, + }), + ).toEqual({ question }); + expect( + v.parse(BrunchQuestionDataSchema, { + question, + toolCallId: "tool-question-1", + }), + ).toEqual({ question, toolCallId: "tool-question-1" }); + }); + + test("writes the exact marker without terminating or waiting for an answer", async () => { + const writeQuestion = vi.fn<(question: BrunchQuestionData) => void>(); + const tool = createBrunchQuestionMarkerTool(writeQuestion); + + const result = await tool.run({ + data: { question: "Which line should run this order?" }, + log: { + error: vi.fn(), + info: vi.fn(), + warn: vi.fn(), + }, + toolCallId: "tool-question-1", + }); + + expect(writeQuestion).toHaveBeenCalledOnce(); + expect(writeQuestion).toHaveBeenCalledWith({ + question: "Which line should run this order?", + toolCallId: "tool-question-1", + }); + expect(result).toEqual({ output: { marked: true } }); + }); + + test.each([ + { question: "" }, + { question: " " }, + { question: "What matters?", toolCallId: "" }, + { question: "What matters?", toolCallId: " " }, + ])("rejects an incomplete marker: %j", (marker) => { + expect(v.safeParse(BrunchQuestionDataSchema, marker).success).toBe(false); + expect(parseBrunchQuestionData(marker)).toBeUndefined(); + }); + + test("parses exact question data at the client projection boundary", () => { + const marker = { + question: " Which line should run this order? ", + toolCallId: "tool-question-1", + }; + + expect(parseBrunchQuestionData(marker)).toEqual(marker); + expect(parseBrunchQuestionData(null)).toBeUndefined(); + }); + + test("instructs the model to mark and then reproduce the exact question in ordinary prose", async () => { + const systemPrompt = await readFile( + new URL("../src/prompts/SYSTEM.md", import.meta.url), + "utf8", + ); + + expect(systemPrompt).toContain("brunch_mark_question"); + expect(systemPrompt).toContain("exact same question text"); + expect(systemPrompt).toContain("ordinary assistant prose"); + expect(systemPrompt).toContain("does not wait for or accept the answer"); + }); +}); diff --git a/libs/@hashintel/brunch-agent/packages/core/test/workpiece.test.ts b/libs/@hashintel/brunch-agent/packages/core/test/workpiece.test.ts new file mode 100644 index 00000000000..a70df0ae2b1 --- /dev/null +++ b/libs/@hashintel/brunch-agent/packages/core/test/workpiece.test.ts @@ -0,0 +1,177 @@ +import { describe, expect, test } from "vitest"; + +import { + createPreparedWorkpieceDelivery, + preparedWorkpieceAuthorship, + preparedWorkpieceClaimBoundary, + preparedWorkpieceSignalTag, + selectRunbookWorkpiece, + type WorkpieceHistory, + type WorkpieceHistoryMessage, +} from "../src/workpiece"; + +const workpiece = (name: string): string => + `\`\`\`runbook-ir\n# ${name}\n\`\`\``; + +const preparedMessage = ( + id = "prepared", + submissionId = "prepare-submission", +): WorkpieceHistoryMessage => ({ + id, + role: "system", + purpose: "dispatch", + submissionId, + signal: { + tagName: preparedWorkpieceSignalTag, + attributes: { + authorship: preparedWorkpieceAuthorship, + claimBoundary: preparedWorkpieceClaimBoundary, + fixtureId: "crew-reservation-v1", + }, + }, + parts: [{ type: "text", text: workpiece("Prepared") }], +}); + +const assistantMessage = ( + id: string, + submissionId: string, + name: string, +): WorkpieceHistoryMessage => ({ + id, + role: "assistant", + purpose: "assistant", + submissionId, + parts: [{ type: "text", text: workpiece(name) }], +}); + +const history = ( + messages: readonly WorkpieceHistoryMessage[], +): WorkpieceHistory => ({ + conversationId: "conversation", + messages, +}); + +describe("prepared workpiece delivery", () => { + test("carries explicit authorship and a revision-stable idempotency key", () => { + expect( + createPreparedWorkpieceDelivery({ + fixtureId: "crew-reservation-v1", + revision: 0, + body: workpiece("Prepared"), + }), + ).toEqual({ + idempotencyKey: "prepared-fixture:crew-reservation-v1:revision-0", + message: { + kind: "signal", + type: "brunch.fixture.prepared", + tagName: "prepared-fixture", + body: workpiece("Prepared"), + attributes: { + fixtureId: "crew-reservation-v1", + authorship: "test-authored", + claimBoundary: "prepared-not-model-produced", + }, + }, + }); + }); + + test("refuses prepared content without a runbook-ir block", () => { + expect(() => + createPreparedWorkpieceDelivery({ + fixtureId: "crew-reservation-v1", + revision: 0, + body: "# Not fenced", + }), + ).toThrow(/requires a full runbook-ir block/u); + }); +}); + +describe("selectRunbookWorkpiece", () => { + test("selects prepared revision zero with its honest authorship", () => { + expect(selectRunbookWorkpiece(history([preparedMessage()]))).toMatchObject({ + authorship: "test-authored", + content: "# Prepared", + fixtureId: "crew-reservation-v1", + revision: 0, + sourceKind: "prepared-signal", + sourceMessageId: "prepared", + }); + }); + + test("ignores the assistant response to preparation", () => { + expect( + selectRunbookWorkpiece( + history([ + preparedMessage(), + assistantMessage( + "preparation-response", + "prepare-submission", + "Echo", + ), + ]), + ), + ).toMatchObject({ + authorship: "test-authored", + content: "# Prepared", + }); + }); + + test("selects the latest genuine assistant revision", () => { + expect( + selectRunbookWorkpiece( + history([ + preparedMessage(), + assistantMessage("revision-1", "turn-1", "Revision one"), + assistantMessage("revision-2", "turn-2", "Revision two"), + ]), + ), + ).toMatchObject({ + authorship: "model-produced", + content: "# Revision two", + revision: 2, + sourceKind: "assistant", + sourceMessageId: "revision-2", + }); + }); + + test("uses canonical log order when the prepared source follows older assistant text", () => { + expect( + selectRunbookWorkpiece( + history([ + assistantMessage("older", "older-turn", "Older assistant text"), + preparedMessage(), + ]), + ), + ).toMatchObject({ + authorship: "test-authored", + content: "# Prepared", + revision: 0, + sourceMessageId: "prepared", + }); + }); + + test("refuses malformed and duplicate prepared sources", () => { + expect(() => + selectRunbookWorkpiece( + history([ + { + ...preparedMessage(), + signal: { + tagName: preparedWorkpieceSignalTag, + attributes: { authorship: "model-produced" }, + }, + }, + ]), + ), + ).toThrow(/malformed prepared workpiece source/u); + + expect(() => + selectRunbookWorkpiece( + history([ + preparedMessage("prepared-1"), + preparedMessage("prepared-2", "prepare-submission-2"), + ]), + ), + ).toThrow(/more than one prepared workpiece source/u); + }); +}); diff --git a/libs/@hashintel/brunch-agent/packages/core/vite.config.ts b/libs/@hashintel/brunch-agent/packages/core/vite.config.ts index 291e5b9c4bf..d3583e3c839 100644 --- a/libs/@hashintel/brunch-agent/packages/core/vite.config.ts +++ b/libs/@hashintel/brunch-agent/packages/core/vite.config.ts @@ -13,7 +13,11 @@ export default defineConfig({ ), flue: fileURLToPath(new URL("src/flue.ts", import.meta.url)), index: fileURLToPath(new URL("src/index.ts", import.meta.url)), + "question-marker": fileURLToPath( + new URL("src/question-marker.ts", import.meta.url), + ), storage: fileURLToPath(new URL("src/storage.ts", import.meta.url)), + workpiece: fileURLToPath(new URL("src/workpiece.ts", import.meta.url)), }, fileName: (_format, entryName) => `${entryName}.js`, formats: ["es"], diff --git a/libs/@hashintel/brunch-agent/packages/plugin-sdcpn/src/flue.ts b/libs/@hashintel/brunch-agent/packages/plugin-sdcpn/src/flue.ts index 3c48ef1a56f..b0ff2b8e948 100644 --- a/libs/@hashintel/brunch-agent/packages/plugin-sdcpn/src/flue.ts +++ b/libs/@hashintel/brunch-agent/packages/plugin-sdcpn/src/flue.ts @@ -1,4 +1,5 @@ import { + useDelivery, useInitialData, useInstruction, useSkill, @@ -6,22 +7,34 @@ import { } from "@flue/runtime"; import * as v from "valibot"; +import { + preparedWorkpieceInitialDataMode, + preparedWorkpieceSignalType, +} from "@hashintel/brunch-agent/workpiece"; + import sdcpnAppend from "./prompts/APPEND_SYSTEM.md?raw"; import { SDCPN_MODELLING_SKILL_NAME, sdcpnModellingSkill, } from "./skills/sdcpn-modelling/skill"; -import { petrinautConstructionTools } from "./tools/petrinaut-construction"; +import { + petrinautConstructionTools, + petrinautFixtureTools, +} from "./tools/petrinaut-construction"; import { READ_PETRINAUT_DOC_TOOL_NAME, readPetrinautDoc, } from "./tools/read-petrinaut-doc"; export const VALIDATED_CONSTRUCTION_MODE = "validated-construction"; +export const validatedFixtureMutationMode = preparedWorkpieceInitialDataMode; export const sdcpnInitialDataSchema = v.optional( v.object({ - mode: v.literal(VALIDATED_CONSTRUCTION_MODE), + mode: v.picklist([ + VALIDATED_CONSTRUCTION_MODE, + validatedFixtureMutationMode, + ]), }), ); @@ -30,6 +43,7 @@ export type SdcpnInitialData = v.InferOutput; /** Mount the prompt material, skill, and conditional tools owned by the SDCPN plugin. */ export function useSdcpnPlugin(): void { const initialData = useInitialData(); + const delivery = useDelivery(); useInstruction(sdcpnAppend.trim()); useSkill(sdcpnModellingSkill); @@ -44,6 +58,20 @@ This is a construct-only headless conversation. Use only the supplied runbook IR for (const constructionTool of petrinautConstructionTools) { useTool(constructionTool); } + } else if (initialData?.mode === validatedFixtureMutationMode) { + const isPreparedFixtureInitialization = + delivery.kind === "signal" && + delivery.type === preparedWorkpieceSignalType; + useInstruction( + ` +This is a visibly labelled prepared-fixture conversation. Treat its tagged prepared runbook-ir dispatch as test-authored revision zero, maintain the full Markdown workpiece in later responses, preserve explicit unknowns, and do not relabel prepared material as model-produced. The prepared dispatch only initializes the fixture: acknowledge it without emitting a workpiece or beginning construction, then wait for a later true-user message to supply confirmed evidence. A fragment, topic label, request to inspect or explain, or unrelated message is not confirmation and must not authorize a mutation; ask for the missing confirmation instead. After receiving explicit evidence that confirms or corrects the operational fact requiring a net change, emit the full current workpiece in a fenced runbook-ir block before the first construction tool call and again before final delivery. Every later assistant-authored workpiece is model-produced: label that revision accordingly and do not copy revision zero's claim that the current revision is test-authored. Use only the mounted canonical Petrinaut read and least arc mutation when confirmed evidence calls for that change. Read the live document before mutating it, report rejected or no-op outcomes honestly, and do not construct unrelated net content. +`.replace(/^\s+|\s+$/gu, ""), + ); + if (!isPreparedFixtureInitialization) { + for (const fixtureTool of petrinautFixtureTools) { + useTool(fixtureTool); + } + } } } @@ -51,6 +79,8 @@ export { READ_PETRINAUT_DOC_TOOL_NAME, readPetrinautDoc }; export { SDCPN_MODELLING_SKILL_NAME }; export { PETRINAUT_CONSTRUCTION_TOOL_NAMES, + petrinautFixtureToolNames, petrinautConstructionTools, + petrinautFixtureTools, type PetrinautConstructionToolName, } from "./tools/petrinaut-construction"; diff --git a/libs/@hashintel/brunch-agent/packages/plugin-sdcpn/src/tools/petrinaut-construction.ts b/libs/@hashintel/brunch-agent/packages/plugin-sdcpn/src/tools/petrinaut-construction.ts index 9f45f05ad1f..78c4b1f606b 100644 --- a/libs/@hashintel/brunch-agent/packages/plugin-sdcpn/src/tools/petrinaut-construction.ts +++ b/libs/@hashintel/brunch-agent/packages/plugin-sdcpn/src/tools/petrinaut-construction.ts @@ -2,7 +2,10 @@ import { defineTool } from "@flue/runtime"; import * as v from "valibot"; import { AWAITING_CLIENT } from "@hashintel/brunch-agent/client-tools"; -import { petrinautAiTools } from "@hashintel/petrinaut-core/ai"; +import { + normalizePetrinautAiToolInput, + petrinautAiTools, +} from "@hashintel/petrinaut-core/ai"; export const PETRINAUT_CONSTRUCTION_TOOL_NAMES = [ "getLatestNetDefinition", @@ -13,8 +16,14 @@ export const PETRINAUT_CONSTRUCTION_TOOL_NAMES = [ "addArc", ] as const satisfies readonly (keyof typeof petrinautAiTools)[]; +export const petrinautFixtureToolNames = [ + "getLatestNetDefinition", + "addArc", +] as const satisfies readonly (keyof typeof petrinautAiTools)[]; + export type PetrinautConstructionToolName = (typeof PETRINAUT_CONSTRUCTION_TOOL_NAMES)[number]; +type PetrinautFixtureToolName = (typeof petrinautFixtureToolNames)[number]; const issuePathFrom = ( input: Record, @@ -46,15 +55,22 @@ const canonicalInputFor = (toolName: PetrinautConstructionToolName) => { return { description: [ canonicalTool.description, + ...(toolName === "addArc" + ? [ + "A finite numeric-string weight is normalized to a number before canonical validation.", + ] + : []), "Canonical Petrinaut input JSON Schema:", JSON.stringify(jsonSchema), ].join("\n"), schema: v.pipe( v.looseObject({}), v.rawTransform((context) => { - const parsed = canonicalTool.inputSchema.safeParse( + const normalizedInput = normalizePetrinautAiToolInput( + toolName, context.dataset.value, ); + const parsed = canonicalTool.inputSchema.safeParse(normalizedInput); if (parsed.success) return parsed.data; for (const issue of parsed.error.issues) { @@ -91,3 +107,16 @@ const definePetrinautConstructionTool = ( export const petrinautConstructionTools = PETRINAUT_CONSTRUCTION_TOOL_NAMES.map( definePetrinautConstructionTool, ); + +const isPetrinautFixtureTool = ( + tool: (typeof petrinautConstructionTools)[number], +): tool is (typeof petrinautConstructionTools)[number] & { + readonly name: PetrinautFixtureToolName; +} => + petrinautFixtureToolNames.some((fixtureToolName) => { + return fixtureToolName === tool.name; + }); + +export const petrinautFixtureTools = petrinautConstructionTools.filter( + isPetrinautFixtureTool, +); diff --git a/libs/@hashintel/brunch-agent/packages/plugin-sdcpn/test/construction-tools.test.ts b/libs/@hashintel/brunch-agent/packages/plugin-sdcpn/test/construction-tools.test.ts index 1ca9cb0e53a..ce2da8f9260 100644 --- a/libs/@hashintel/brunch-agent/packages/plugin-sdcpn/test/construction-tools.test.ts +++ b/libs/@hashintel/brunch-agent/packages/plugin-sdcpn/test/construction-tools.test.ts @@ -3,9 +3,16 @@ import { describe, expect, test } from "vitest"; import { petrinautAiTools } from "@hashintel/petrinaut-core/ai"; +import { + sdcpnInitialDataSchema, + VALIDATED_CONSTRUCTION_MODE, + validatedFixtureMutationMode, +} from "../src/flue"; import { PETRINAUT_CONSTRUCTION_TOOL_NAMES, + petrinautFixtureToolNames, petrinautConstructionTools, + petrinautFixtureTools, } from "../src/tools/petrinaut-construction"; const toolByName = (toolName: string) => { @@ -18,12 +25,37 @@ const toolByName = (toolName: string) => { }; describe("Petrinaut construction tools", () => { + test("accepts only the ordinary headless and prepared-fixture modes", () => { + expect(v.parse(sdcpnInitialDataSchema, undefined)).toBeUndefined(); + expect( + v.parse(sdcpnInitialDataSchema, { + mode: VALIDATED_CONSTRUCTION_MODE, + }), + ).toEqual({ mode: VALIDATED_CONSTRUCTION_MODE }); + expect( + v.parse(sdcpnInitialDataSchema, { + mode: validatedFixtureMutationMode, + }), + ).toEqual({ mode: validatedFixtureMutationMode }); + expect(() => + v.parse(sdcpnInitialDataSchema, { + mode: "unrestricted-construction", + }), + ).toThrow(/Invalid type/u); + }); + test("exposes exactly the bounded canonical subset", () => { expect(petrinautConstructionTools.map((tool) => tool.name)).toEqual([ ...PETRINAUT_CONSTRUCTION_TOOL_NAMES, ]); }); + test("limits prepared fixtures to one canonical read and arc mutation", () => { + expect(petrinautFixtureTools.map((tool) => tool.name)).toEqual([ + ...petrinautFixtureToolNames, + ]); + }); + test("mechanically carries the canonical input contract", () => { for (const toolName of PETRINAUT_CONSTRUCTION_TOOL_NAMES) { const constructionTool = toolByName(toolName); @@ -55,6 +87,19 @@ describe("Petrinaut construction tools", () => { ); }); + test("normalizes a finite provider numeric-string arc weight", () => { + const addArc = toolByName("addArc"); + const result = v.parse(addArc.input!, { + transitionId: "transition", + arcDirection: "input", + placeId: "place", + weight: "1", + type: "standard", + }); + + expect(result).toMatchObject({ weight: 1 }); + }); + test("retains nested values in canonical validation paths", () => { const addType = toolByName("addType"); const invalidElement = { diff --git a/libs/@hashintel/brunch-agent/packages/transport-aisdk/.oxlintrc.json b/libs/@hashintel/brunch-agent/packages/transport-aisdk/.oxlintrc.json index d7ed5324c29..7d1a38f5c67 100644 --- a/libs/@hashintel/brunch-agent/packages/transport-aisdk/.oxlintrc.json +++ b/libs/@hashintel/brunch-agent/packages/transport-aisdk/.oxlintrc.json @@ -38,8 +38,8 @@ "message": "Brunch libraries must not depend on Petrinaut implementations." }, { - "group": ["@flue/*", "@earendil-works/*"], - "message": "Brunch transports must remain substrate-independent." + "group": ["@flue/!(sdk)", "@earendil-works/*"], + "message": "Brunch transports may depend on the public Flue SDK, but not a runtime or provider substrate." }, { "group": ["@hashintel/brunch-agent/*", "@hashintel/brunch-agent-*"], diff --git a/libs/@hashintel/brunch-agent/packages/transport-aisdk/package.json b/libs/@hashintel/brunch-agent/packages/transport-aisdk/package.json index 97d4b0913ca..03d6d96fe3e 100644 --- a/libs/@hashintel/brunch-agent/packages/transport-aisdk/package.json +++ b/libs/@hashintel/brunch-agent/packages/transport-aisdk/package.json @@ -23,8 +23,8 @@ "test:unit": "vitest run" }, "dependencies": { - "ai": "6.0.182", - "valibot": "1.4.2" + "@flue/sdk": "2.0.3", + "ai": "6.0.182" }, "devDependencies": { "@types/node": "22.18.13", diff --git a/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/client-tool-history.ts b/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/client-tool-history.ts new file mode 100644 index 00000000000..114150c2f83 --- /dev/null +++ b/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/client-tool-history.ts @@ -0,0 +1,104 @@ +import { CLIENT_TOOL_RESULT_SIGNAL } from "./client-tool-result"; + +export interface ClientToolHistoryCall { + readonly input: Readonly>; + readonly toolCallId: string; + readonly toolName: string; +} + +export interface ClientToolHistoryResult { + readonly output: unknown; + readonly toolCallId: string; + readonly toolName: string; +} + +export interface ClientToolHistory { + readonly calls: readonly ClientToolHistoryCall[]; + readonly results: readonly ClientToolHistoryResult[]; +} + +export interface ClientToolHistoryMessage { + readonly parts: readonly unknown[]; + readonly signal?: { + readonly tagName?: string; + readonly type?: string; + }; +} + +const isRecord = (value: unknown): value is Record => + typeof value === "object" && value !== null; + +const callsFrom = ( + messages: readonly ClientToolHistoryMessage[], +): readonly ClientToolHistoryCall[] => + messages.flatMap((message) => + message.parts.flatMap((part) => { + if ( + !isRecord(part) || + part.type !== "dynamic-tool" || + typeof part.toolName !== "string" || + typeof part.toolCallId !== "string" || + !isRecord(part.input) + ) { + return []; + } + return [ + { + input: part.input, + toolCallId: part.toolCallId, + toolName: part.toolName, + }, + ]; + }), + ); + +const resultsFrom = ( + messages: readonly ClientToolHistoryMessage[], +): readonly ClientToolHistoryResult[] => + messages.flatMap((message) => { + if ( + message.signal?.tagName !== CLIENT_TOOL_RESULT_SIGNAL && + message.signal?.type !== CLIENT_TOOL_RESULT_SIGNAL + ) { + return []; + } + + const body = message.parts + .flatMap((part) => + isRecord(part) && part.type === "text" && typeof part.text === "string" + ? [part.text] + : [], + ) + .join(""); + + try { + const parsed: unknown = JSON.parse(body); + if (!Array.isArray(parsed)) return []; + return parsed.flatMap((result) => { + if ( + !isRecord(result) || + typeof result.toolName !== "string" || + typeof result.toolCallId !== "string" || + !("output" in result) + ) { + return []; + } + return [ + { + output: result.output, + toolCallId: result.toolCallId, + toolName: result.toolName, + }, + ]; + }); + } catch { + return []; + } + }); + +export const clientToolHistoryFrom = ( + messages: readonly ClientToolHistoryMessage[], +): ClientToolHistory => ({ + calls: callsFrom(messages), + results: resultsFrom(messages), +}); diff --git a/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/client-tool-result.ts b/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/client-tool-result.ts new file mode 100644 index 00000000000..cce5f17bb38 --- /dev/null +++ b/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/client-tool-result.ts @@ -0,0 +1 @@ +export const CLIENT_TOOL_RESULT_SIGNAL = "client-tool-result"; diff --git a/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/error-text.ts b/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/error-text.ts new file mode 100644 index 00000000000..16b440c79cc --- /dev/null +++ b/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/error-text.ts @@ -0,0 +1,81 @@ +const maxErrorTextLength = 10_000; + +const nonEmptyText = (value: string): string | null => + value.trim().length > 0 ? value : null; + +const isPlainObject = (value: unknown): value is Record => { + if (typeof value !== "object" || value === null || Array.isArray(value)) { + return false; + } + + const prototype = Object.getPrototypeOf(value) as unknown; + return prototype === Object.prototype || prototype === null; +}; + +const serializePlainObject = ( + value: Record, + seen: WeakSet, +): string | null => { + try { + const serialized: unknown = JSON.stringify( + value, + (_key, nestedValue: unknown) => { + if (typeof nestedValue === "bigint") { + return nestedValue.toString(); + } + if (typeof nestedValue !== "object" || nestedValue === null) { + return nestedValue; + } + if (seen.has(nestedValue)) { + return "[Circular]"; + } + seen.add(nestedValue); + return nestedValue; + }, + ); + return typeof serialized === "string" ? serialized : null; + } catch { + return null; + } +}; + +const serializeErrorValue = ( + value: unknown, + seen: WeakSet, +): string | null => { + if (typeof value === "string") { + return nonEmptyText(value); + } + if (value instanceof Error) { + if (seen.has(value)) { + return "[Circular]"; + } + seen.add(value); + + const message = nonEmptyText(value.message); + const cause = + value.cause === undefined ? null : serializeErrorValue(value.cause, seen); + if (message !== null && cause !== null) { + return `${message}\nCaused by: ${cause}`; + } + return message ?? cause; + } + if (isPlainObject(value)) { + return serializePlainObject(value, seen); + } + return null; +}; + +export const serializeErrorText = ( + error: unknown, + fallback = "The chat turn failed.", +): string => { + const serialized = serializeErrorValue(error, new WeakSet()); + if (serialized === null) { + return fallback; + } + if (serialized.length <= maxErrorTextLength) { + return serialized; + } + return `${serialized.slice(0, maxErrorTextLength - 1)}…`; +}; diff --git a/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/headers.ts b/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/headers.ts index 965e5feef1c..91b33c5ae68 100644 --- a/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/headers.ts +++ b/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/headers.ts @@ -1,2 +1,3 @@ -/** Stable browser-to-Brunch principal header owned by the HTTP transport. */ +/** Browser-safe ownership headers for the mounted Brunch conversation route. */ export const BRUNCH_PRINCIPAL_HEADER = "x-brunch-principal"; +export const BRUNCH_CONVERSATION_HEADER = "x-brunch-conversation"; diff --git a/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/identity.ts b/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/identity.ts new file mode 100644 index 00000000000..75cc9628d32 --- /dev/null +++ b/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/identity.ts @@ -0,0 +1,45 @@ +import { BRUNCH_CONVERSATION_HEADER, BRUNCH_PRINCIPAL_HEADER } from "./headers"; + +export interface ConversationIdentity { + readonly conversationId: string; + readonly principalKey: string; +} + +export const identityPayload = ({ + principalKey, + conversationId, +}: ConversationIdentity): Uint8Array => { + const encoder = new TextEncoder(); + const principalBytes = encoder.encode(principalKey); + const conversationBytes = encoder.encode(conversationId); + const payload = new Uint8Array( + principalBytes.length + 1 + conversationBytes.length, + ); + payload.set(principalBytes, 0); + payload[principalBytes.length] = 0; + payload.set(conversationBytes, principalBytes.length + 1); + return payload; +}; + +const hexFromDigest = (digest: ArrayBuffer): string => + [...new Uint8Array(digest)] + .map((byte) => byte.toString(16).padStart(2, "0")) + .join(""); + +/** Browser-safe counterpart to the server's synchronous instance-id hash. */ +export const flueConversationIdWeb = async ( + identity: ConversationIdentity, +): Promise => { + const payload = identityPayload(identity); + const bytes = new ArrayBuffer(payload.byteLength); + new Uint8Array(bytes).set(payload); + const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes); + return hexFromDigest(digest); +}; + +export const agentOwnershipHeaders = ( + identity: ConversationIdentity, +): Record => ({ + [BRUNCH_PRINCIPAL_HEADER]: identity.principalKey, + [BRUNCH_CONVERSATION_HEADER]: identity.conversationId, +}); diff --git a/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/index.ts b/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/index.ts index 5540732335f..350bd172fa8 100644 --- a/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/index.ts +++ b/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/index.ts @@ -1,489 +1,478 @@ -/** - * AI SDK UI-message-stream transport for a Flue-backed chat. - * - * This package owns the HTTP door: principal, CORS, POST validation, and SSE - * encoding. An application supplies the Flue turn. The transport never imports - * Brunch core, a binding, or Flue. - */ - -import { - createUIMessageStream, - createUIMessageStreamResponse, - type UIMessageChunk, -} from "ai"; -import * as v from "valibot"; - -import { BRUNCH_PRINCIPAL_HEADER } from "./headers"; - -export { BRUNCH_PRINCIPAL_HEADER } from "./headers"; - -export interface ConversationIdentity { - readonly conversationId: string; - readonly principalKey: string; -} - -export interface ChatTurnInput extends ConversationIdentity { - readonly idempotencyKey: string; - readonly userMessage: { - readonly id: string; - readonly text: string; - }; -} +import { FlueApiError, FlueExecutionError } from "@flue/sdk"; +import { getToolName, isToolUIPart } from "ai"; + +import { CLIENT_TOOL_RESULT_SIGNAL } from "./client-tool-result"; +import { serializeErrorText } from "./error-text"; +import { createFlueUiStream } from "./ui-stream"; + +import type { + AgentSendResult, + ConversationStreamChunk, + DeliveredMessage, + FlueClient, +} from "@flue/sdk"; +import type { ChatTransport, UIMessage, UIMessageChunk } from "ai"; + +export { + clientToolHistoryFrom, + type ClientToolHistory, + type ClientToolHistoryCall, + type ClientToolHistoryMessage, + type ClientToolHistoryResult, +} from "./client-tool-history"; +export { BRUNCH_CONVERSATION_HEADER, BRUNCH_PRINCIPAL_HEADER } from "./headers"; +export { CLIENT_TOOL_RESULT_SIGNAL } from "./client-tool-result"; +export { + agentOwnershipHeaders, + flueConversationIdWeb, + identityPayload, +} from "./identity"; +export type { ConversationIdentity } from "./identity"; +export { + snapshotToUiMessages, + type SnapshotToUiMessagesOptions, + type UiHistoryMessage, +} from "./transcript"; +export { createFlueUiStream, type FlueUiStreamOptions } from "./ui-stream"; export interface ClientToolResult { readonly toolCallId: string; readonly toolName: string; readonly output: unknown; + readonly source?: "voice"; } -export interface ChatResumeInput extends ConversationIdentity { - readonly assistantMessageId: string; - readonly idempotencyKey: string; - readonly toolResults: readonly ClientToolResult[]; +export interface FlueChatResponseMessageEvent { + readonly messageId: string; + readonly submissionId: AgentSendResult["submissionId"]; } -export type ChatChunkWriter = (chunk: UIMessageChunk) => void; +export interface FlueChatResponseMessageStartedEvent extends FlueChatResponseMessageEvent { + readonly position: Extract< + ConversationStreamChunk, + { type: "message-started" } + >["position"]; +} -export type ChatTurnRunner = ( - input: ChatTurnInput, - write: ChatChunkWriter, -) => Promise; +export interface FlueChatResponseMessageCompletedEvent extends FlueChatResponseMessageEvent { + readonly position: Extract< + ConversationStreamChunk, + { type: "message-completed" } + >["position"]; +} -export type ChatResumeRunner = ( - input: ChatResumeInput, - write: ChatChunkWriter, -) => Promise; +export interface FlueChatTransportOptions { + readonly client: FlueClient; + readonly clientToolNames: ReadonlySet; + readonly mapClientToolInput?: (input: { + readonly input: unknown; + readonly toolName: string; + }) => unknown; + readonly hiddenToolNames?: ReadonlySet; + readonly onAdmission?: (event: { + readonly admission: AgentSendResult; + readonly kind: "client-tool-result" | "user"; + readonly messageId: string; + }) => void; + readonly onResponseMessage?: ( + event: FlueChatResponseMessageStartedEvent, + ) => void; + readonly onResponseMessageCompleted?: ( + event: FlueChatResponseMessageCompletedEvent, + ) => void; +} -export type TransportInspectionEvent = - | { - readonly type: "request-start"; - readonly requestId: string; - readonly conversationId: string; - readonly userMessageId: string; - } - | { - readonly type: "resume-start"; - readonly requestId: string; - readonly conversationId: string; - readonly assistantMessageId: string; - readonly toolCallIds: readonly string[]; - } - | { - readonly type: "history-read"; - readonly requestId: string; - readonly conversationId: string; - } +export type FlueChatAdmissionFailure = + | { readonly kind: "aborted" } + | { readonly kind: "ambiguous" } + | { readonly kind: "rejected"; readonly status: number } | { - readonly type: "request-finish"; - readonly requestId: string; - readonly terminal: "completed" | "failed"; + readonly kind: "submission-conflict"; + readonly status: 409; + readonly submissionId: AgentSendResult["submissionId"]; }; -export interface AiSdkChatHandlerOptions { - readonly runTurn: ChatTurnRunner; - /** - * Client-tool return. Absent, a tool-result follow-up is refused. Present, - * completed client-tool parts on the referenced assistant message resume - * the same conversation. - */ - readonly resumeTurn?: ChatResumeRunner; - /** Snapshot used to hydrate the panel from Flue history after reload. */ - readonly loadHistory?: ( - input: ConversationIdentity, - ) => Promise<{ readonly messages: readonly unknown[] }>; - readonly allowedOrigins?: readonly string[]; - readonly inspect?: (event: TransportInspectionEvent) => void; -} - -const panelPartSchema = v.looseObject({ - type: v.optional(v.unknown()), - text: v.optional(v.unknown()), - toolName: v.optional(v.unknown()), - toolCallId: v.optional(v.unknown()), - state: v.optional(v.unknown()), - output: v.optional(v.unknown()), - providerExecuted: v.optional(v.unknown()), -}); - -const panelMessageSchema = v.looseObject({ - id: v.optional(v.unknown()), - role: v.optional(v.unknown()), - parts: v.optional(v.array(panelPartSchema)), -}); - -const panelPostBodySchema = v.looseObject({ - id: v.optional(v.unknown()), - messageId: v.optional(v.unknown()), - messages: v.optional(v.array(panelMessageSchema)), - trigger: v.optional(v.unknown()), -}); - -type PanelMessage = v.InferOutput; -type PanelPostBody = v.InferOutput; -type PanelPart = NonNullable[number]; - -const transportRequestRefusals = { - invalidChatRequest: { - status: 400, - error: "invalid_chat_request", - }, - invalidPrincipal: { - status: 400, - error: "invalid_principal", - }, - toolResultFollowUpNotSupported: { - status: 422, - error: "tool_result_follow_up_not_supported", - }, -} as const; +const admissionFailureMessage = (failure: FlueChatAdmissionFailure): string => { + switch (failure.kind) { + case "aborted": + return "The local chat submission was cancelled."; + case "ambiguous": + return "Brunch may have accepted the message, but admission could not be confirmed. Reopen the conversation before trying again."; + case "rejected": + return `Brunch rejected the message before admission (HTTP ${failure.status}).`; + case "submission-conflict": + return `The delivery key already belongs to admitted submission ${failure.submissionId}; the changed payload was not admitted.`; + } +}; -type TransportRequestRefusal = - (typeof transportRequestRefusals)[keyof typeof transportRequestRefusals]; +export class FlueChatAdmissionError extends Error { + public readonly failure: FlueChatAdmissionFailure; -const jsonResponse = ( - body: unknown, - status: number, - headers?: Headers, -): Response => Response.json(body, { status, headers }); + public constructor( + failure: FlueChatAdmissionFailure, + options?: { readonly cause?: unknown }, + ) { + super(admissionFailureMessage(failure), options); + this.name = "FlueChatAdmissionError"; + this.failure = failure; + } +} -const corsHeaders = (origin: string): Headers => - new Headers({ - "access-control-allow-origin": origin, - "access-control-allow-methods": "GET, POST, OPTIONS", - "access-control-allow-headers": `content-type, x-request-id, ${BRUNCH_PRINCIPAL_HEADER}`, - vary: "Origin", +const asRecord = (value: unknown): Record | null => + typeof value === "object" && value !== null && !Array.isArray(value) + ? (value as Record) + : null; + +const completedClientToolResults = ( + messages: readonly UIMessage[], + assistantMessageId: string, + clientToolNames: ReadonlySet, +): readonly ClientToolResult[] => { + const assistantMessage = messages.find( + (message) => + message.id === assistantMessageId && message.role === "assistant", + ); + if (assistantMessage === undefined) { + return []; + } + const metadata = asRecord(assistantMessage.metadata); + const voiceToolCallIds = new Set( + Array.isArray(metadata?.voiceToolCallIds) + ? metadata.voiceToolCallIds.filter( + (toolCallId): toolCallId is string => typeof toolCallId === "string", + ) + : [], + ); + if (typeof metadata?.toolCallId === "string") { + voiceToolCallIds.add(metadata.toolCallId); + } + const steps = assistantMessage.parts.reduce< + (typeof assistantMessage.parts)[] + >( + (collected, part) => { + if (part.type === "step-start") { + collected.push([]); + } else { + collected.at(-1)?.push(part); + } + return collected; + }, + [[]], + ); + const latestClientToolStep = steps.findLast((step) => + step.some( + (part) => + isToolUIPart(part) && + clientToolNames.has(getToolName(part)) && + part.providerExecuted !== true, + ), + ); + return (latestClientToolStep ?? []).flatMap((part): ClientToolResult[] => { + if (!isToolUIPart(part)) return []; + const toolName = getToolName(part); + if ( + !clientToolNames.has(toolName) || + part.providerExecuted === true || + part.state !== "output-available" || + part.toolCallId.length === 0 + ) { + return []; + } + return [ + { + toolCallId: part.toolCallId, + toolName, + output: part.output, + ...(voiceToolCallIds.has(part.toolCallId) + ? { source: "voice" as const } + : {}), + }, + ]; }); - -const withHeaders = (response: Response, headers: Headers): Response => { - for (const [name, value] of headers) response.headers.set(name, value); - return response; }; -const userTextFrom = (message: PanelMessage): string | undefined => { - if (!Array.isArray(message.parts)) return undefined; +const finalUserMessage = ( + messages: readonly UIMessage[], +): { readonly id: string; readonly text: string } | undefined => { + const message = messages.at(-1); + if ( + message === undefined || + message.role !== "user" || + message.id.length === 0 || + message.id === "petrinaut-diagnostics-context" + ) { + return undefined; + } const text = message.parts - .filter( - (part): part is { readonly type: "text"; readonly text: string } => - typeof part === "object" && - "type" in part && - part.type === "text" && - "text" in part && - typeof part.text === "string", - ) + .filter((part) => part.type === "text") .map((part) => part.text) .join(""); - return text.length > 0 ? text : undefined; + return text.length > 0 ? { id: message.id, text } : undefined; }; -const toolNameFrom = (part: PanelPart): string | undefined => { - if (part.type === "dynamic-tool" && typeof part.toolName === "string") { - return part.toolName.length > 0 ? part.toolName : undefined; - } - if (typeof part.type === "string" && part.type.startsWith("tool-")) { - const toolName = part.type.slice("tool-".length); - return toolName.length > 0 ? toolName : undefined; - } - return undefined; +const isAbortError = (error: unknown): boolean => + error instanceof Error && error.name === "AbortError"; + +const conflictingSubmissionId = (error: FlueApiError): string | null => { + if (error.status !== 409) return null; + const body = asRecord(error.body); + const errorBody = asRecord(body?.error); + const metadata = asRecord(errorBody?.meta); + return errorBody?.type === "submission_conflict" && + typeof metadata?.submissionId === "string" && + metadata.submissionId.length > 0 + ? metadata.submissionId + : null; }; -/** Panel parts the browser executed. Server tools set `providerExecuted: true`. */ -const isProviderExecutedPanelPart = (part: PanelPart): boolean => - part.providerExecuted === true; - -const isCompletedClientToolPart = (part: PanelPart): boolean => - part.state === "output-available" && - !isProviderExecutedPanelPart(part) && - typeof part.toolCallId === "string" && - part.toolCallId.length > 0 && - toolNameFrom(part) !== undefined; - -type ParsedTransportRequest = - | { readonly kind: "initial"; readonly value: ChatTurnInput } - | { readonly kind: "resume"; readonly value: ChatResumeInput } - | { readonly kind: "refused"; readonly refusal: TransportRequestRefusal }; +const documentedPreAdmissionStatuses = new Set([ + 400, 401, 403, 404, 405, 409, 415, +]); -const parseResumeTurn = ( - body: PanelPostBody, - principalKey: string, -): ParsedTransportRequest => { - if ( - typeof body.id !== "string" || - body.id.length === 0 || - typeof body.messageId !== "string" || - body.messageId.length === 0 || - body.trigger !== "submit-message" || - !Array.isArray(body.messages) - ) { - return { - kind: "refused", - refusal: transportRequestRefusals.invalidChatRequest, - }; +const admissionError = ( + error: unknown, + signal: AbortSignal | undefined, +): FlueChatAdmissionError => { + if (signal?.aborted || isAbortError(error)) { + return new FlueChatAdmissionError({ kind: "aborted" }, { cause: error }); } - - const assistantMessage = body.messages.find( - (candidate) => - candidate.id === body.messageId && candidate.role === "assistant", - ); - const toolResults = (assistantMessage?.parts ?? []) - .filter(isCompletedClientToolPart) - .map((part) => ({ - toolCallId: part.toolCallId as string, - toolName: toolNameFrom(part)!, - output: part.output, - })); - if (toolResults.length === 0) { - return { - kind: "refused", - refusal: transportRequestRefusals.toolResultFollowUpNotSupported, - }; + if (error instanceof FlueApiError) { + const existingSubmissionId = conflictingSubmissionId(error); + if (existingSubmissionId !== null) { + return new FlueChatAdmissionError( + { + kind: "submission-conflict", + status: 409, + submissionId: existingSubmissionId, + }, + { cause: error }, + ); + } + if (documentedPreAdmissionStatuses.has(error.status)) { + return new FlueChatAdmissionError( + { kind: "rejected", status: error.status }, + { cause: error }, + ); + } } - - return { - kind: "resume", - value: { - conversationId: body.id, - assistantMessageId: body.messageId, - idempotencyKey: `${body.id}:tools:${toolResults - .map((result) => result.toolCallId) - .join(",")}`, - principalKey, - toolResults, - }, - }; + return new FlueChatAdmissionError({ kind: "ambiguous" }, { cause: error }); }; -const parseInitialTurn = ( - body: PanelPostBody, - principalKey: string, -): ParsedTransportRequest => { +const streamFailureChunk = ( + error: unknown, + signal: AbortSignal, +): Extract => { if ( - typeof body.id !== "string" || - body.id.length === 0 || - body.trigger !== "submit-message" + signal.aborted || + isAbortError(error) || + (error instanceof FlueExecutionError && error.failure === "aborted") ) { return { - kind: "refused", - refusal: transportRequestRefusals.invalidChatRequest, - }; - } - if (!Array.isArray(body.messages)) { - return { - kind: "refused", - refusal: transportRequestRefusals.invalidChatRequest, + type: "abort", + reason: + error instanceof FlueExecutionError + ? "The chat turn was stopped." + : "The local chat stream was cancelled.", }; } - - const message = body.messages.at(-1) as PanelMessage | undefined; - if ( - message?.role !== "user" || - typeof message.id !== "string" || - message.id.length === 0 || - message.id === "petrinaut-diagnostics-context" - ) { - return { - kind: "refused", - refusal: transportRequestRefusals.invalidChatRequest, - }; - } - const text = userTextFrom(message); - if (text === undefined) { - return { - kind: "refused", - refusal: transportRequestRefusals.invalidChatRequest, - }; - } - return { - kind: "initial", - value: { - conversationId: body.id, - idempotencyKey: `${body.id}:${message.id}`, - principalKey, - userMessage: { id: message.id, text }, - }, + type: "error", + errorText: + error instanceof FlueExecutionError && + error.failure === "terminal_event_missing" + ? "The chat stream ended before the turn settled." + : serializeErrorText(error), }; }; -const readPrincipal = (request: Request): string | TransportRequestRefusal => { - const principalKey = request.headers.get(BRUNCH_PRINCIPAL_HEADER)?.trim(); - if ( - principalKey === undefined || - principalKey.length === 0 || - principalKey.length > 256 - ) { - return transportRequestRefusals.invalidPrincipal; - } - return principalKey; -}; - -export const createAiSdkChatHandler = - (options: AiSdkChatHandlerOptions) => - async (request: Request): Promise => { - const origin = request.headers.get("origin"); - const crossOriginHeaders = - origin !== null && options.allowedOrigins?.includes(origin) === true - ? corsHeaders(origin) - : undefined; - if (origin !== null && crossOriginHeaders === undefined) { - return jsonResponse({ error: "origin_not_allowed" }, 403); - } - if (request.method === "OPTIONS") { - return new Response(null, { status: 204, headers: crossOriginHeaders }); - } +const streamSubmission = ( + options: FlueChatTransportOptions, + admission: AgentSendResult, + continuationMessageId: string | undefined, + abortSignal: AbortSignal | undefined, +): ReadableStream => { + const localAbort = new AbortController(); + const signal = + abortSignal === undefined + ? localAbort.signal + : AbortSignal.any([abortSignal, localAbort.signal]); + // Shared with `cancel()`: a consumer that cancels the stream closes its + // controller immediately, so the detached `wait()` settlement below must not + // write or close again afterwards. + let closed = false; + + return new ReadableStream({ + start(controller) { + let terminalEmitted = false; + let responseMessage: + | { + readonly effectiveId: string; + readonly flueId: string; + } + | undefined; + const close = (): void => { + if (closed) return; + closed = true; + controller.close(); + }; + const write = (chunk: UIMessageChunk): void => { + if (closed) return; + const projected = + chunk.type === "start" && continuationMessageId !== undefined + ? { ...chunk, messageId: continuationMessageId } + : chunk; + controller.enqueue(projected); + if ( + projected.type === "finish" || + projected.type === "error" || + projected.type === "abort" + ) { + terminalEmitted = true; + } + }; + const projector = createFlueUiStream({ + submissionId: admission.submissionId, + clientToolNames: options.clientToolNames, + mapClientToolInput: options.mapClientToolInput, + hiddenToolNames: options.hiddenToolNames, + write, + }); - const principal = readPrincipal(request); - if (typeof principal !== "string") { - return jsonResponse( - { error: principal.error }, - principal.status, - crossOriginHeaders, - ); - } + void options.client + .wait(admission, { + signal, + onEvent: (event) => { + if ( + event.type === "message-started" && + event.submissionId === admission.submissionId + ) { + // Report the id the consumer sees: a client-tool continuation is + // projected onto the assistant message it resumes. + responseMessage = { + effectiveId: continuationMessageId ?? event.messageId, + flueId: event.messageId, + }; + options.onResponseMessage?.({ + messageId: responseMessage.effectiveId, + position: event.position, + submissionId: admission.submissionId, + }); + } + projector.accept(event); + if ( + event.type === "message-completed" && + event.messageId === responseMessage?.flueId + ) { + options.onResponseMessageCompleted?.({ + messageId: responseMessage.effectiveId, + position: event.position, + submissionId: admission.submissionId, + }); + } + }, + }) + .then(close) + .catch((error: unknown) => { + if (!terminalEmitted) { + write(streamFailureChunk(error, signal)); + } + close(); + }); + }, + cancel(reason) { + closed = true; + localAbort.abort(reason); + }, + }); +}; - if (request.method === "GET") { - const conversationId = new URL(request.url).searchParams - .get("id") - ?.trim(); - if (conversationId === undefined || conversationId.length === 0) { - return jsonResponse( - { error: transportRequestRefusals.invalidChatRequest.error }, - transportRequestRefusals.invalidChatRequest.status, - crossOriginHeaders, - ); - } - if (options.loadHistory === undefined) { - return jsonResponse( - { error: "method_not_allowed" }, - 405, - crossOriginHeaders, - ); - } - const requestId = - request.headers.get("x-request-id") || crypto.randomUUID(); - options.inspect?.({ - type: "history-read", - requestId, - conversationId, - }); - const history = await options.loadHistory({ - conversationId, - principalKey: principal, - }); - return jsonResponse(history, 200, crossOriginHeaders); +export const createFlueChatTransport = < + UiMessage extends UIMessage = UIMessage, +>( + options: FlueChatTransportOptions, +): ChatTransport => ({ + reconnectToStream: async () => null, + sendMessages: async ({ trigger, messageId, messages, abortSignal }) => { + if (trigger !== "submit-message") { + throw new Error("Regenerating a Flue conversation is not supported."); } - if (request.method !== "POST") { - return jsonResponse( - { error: "method_not_allowed" }, - 405, - crossOriginHeaders, - ); + const toolResults = + messageId === undefined + ? [] + : completedClientToolResults( + messages, + messageId, + options.clientToolNames, + ).toSorted((left, right) => + left.toolCallId < right.toolCallId + ? -1 + : left.toolCallId > right.toolCallId + ? 1 + : 0, + ); + const userMessage = + messageId === undefined ? finalUserMessage(messages) : undefined; + const message: DeliveredMessage = + messageId === undefined + ? (() => { + if (userMessage === undefined) { + throw new Error("The submitted user message has no text."); + } + return { kind: "user", body: userMessage.text }; + })() + : (() => { + if (toolResults.length === 0) { + throw new Error( + "The client-tool follow-up has no completed result.", + ); + } + return { + kind: "signal", + type: CLIENT_TOOL_RESULT_SIGNAL, + tagName: CLIENT_TOOL_RESULT_SIGNAL, + body: JSON.stringify(toolResults), + attributes: { + toolCallIds: toolResults + .map((result) => result.toolCallId) + .join(","), + ...(toolResults.some(({ source }) => source === "voice") + ? { + voiceToolCallIds: toolResults + .filter(({ source }) => source === "voice") + .map(({ toolCallId }) => toolCallId) + .join(","), + } + : {}), + }, + }; + })(); + const idempotencyKey = + messageId === undefined + ? `ai-sdk:user:${userMessage!.id}` + : `ai-sdk:client-tools:${messageId}:${toolResults + .map(({ toolCallId }) => toolCallId) + .sort() + .join(",")}`; + if (Array.from(idempotencyKey).length > 256) { + throw new Error("The submitted message identity is too long."); } - let body: unknown; + let admission: AgentSendResult; try { - body = await request.json(); - } catch { - return jsonResponse( - { error: "invalid_chat_request" }, - 400, - crossOriginHeaders, - ); - } - const validatedBody = v.safeParse(panelPostBodySchema, body); - if (!validatedBody.success) { - const refusal = transportRequestRefusals.invalidChatRequest; - return jsonResponse( - { error: refusal.error }, - refusal.status, - crossOriginHeaders, - ); - } - const postBody = validatedBody.output; - const parsed = - postBody.messageId !== undefined && options.resumeTurn !== undefined - ? parseResumeTurn(postBody, principal) - : postBody.messageId !== undefined - ? ({ - kind: "refused", - refusal: transportRequestRefusals.toolResultFollowUpNotSupported, - } as const) - : parseInitialTurn(postBody, principal); - if (parsed.kind === "refused") { - return jsonResponse( - { error: parsed.refusal.error }, - parsed.refusal.status, - crossOriginHeaders, - ); - } - - const requestId = - request.headers.get("x-request-id") || crypto.randomUUID(); - const continuationMessageId = - parsed.kind === "resume" ? parsed.value.assistantMessageId : undefined; - - if (parsed.kind === "resume") { - options.inspect?.({ - type: "resume-start", - requestId, - conversationId: parsed.value.conversationId, - assistantMessageId: parsed.value.assistantMessageId, - toolCallIds: parsed.value.toolResults.map( - (result) => result.toolCallId, - ), - }); - } else { - options.inspect?.({ - type: "request-start", - requestId, - conversationId: parsed.value.conversationId, - userMessageId: parsed.value.userMessage.id, + admission = await options.client.send({ + idempotencyKey, + message, + signal: abortSignal, }); + } catch (error) { + throw admissionError(error, abortSignal); } - - const run = - parsed.kind === "resume" - ? (write: ChatChunkWriter) => options.resumeTurn!(parsed.value, write) - : (write: ChatChunkWriter) => options.runTurn(parsed.value, write); - - let terminalEmitted = false; - const stream = createUIMessageStream({ - execute: async ({ writer }) => { - try { - await run((chunk) => { - if (chunk.type === "start" && continuationMessageId !== undefined) { - writer.write({ ...chunk, messageId: continuationMessageId }); - } else { - writer.write(chunk); - } - if ( - chunk.type === "finish" || - chunk.type === "error" || - chunk.type === "abort" - ) { - terminalEmitted = true; - } - }); - options.inspect?.({ - type: "request-finish", - requestId, - terminal: "completed", - }); - } catch (error) { - if (terminalEmitted) return; - options.inspect?.({ - type: "request-finish", - requestId, - terminal: "failed", - }); - throw error; - } - }, - onError: () => "The chat turn failed.", + options.onAdmission?.({ + admission, + kind: messageId === undefined ? "user" : "client-tool-result", + messageId: messageId ?? userMessage!.id, }); - - const response = createUIMessageStreamResponse({ stream }); - return crossOriginHeaders === undefined - ? response - : withHeaders(response, crossOriginHeaders); - }; + return streamSubmission(options, admission, messageId, abortSignal); + }, +}); diff --git a/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/transcript.ts b/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/transcript.ts new file mode 100644 index 00000000000..517a64080dc --- /dev/null +++ b/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/transcript.ts @@ -0,0 +1,292 @@ +import { CLIENT_TOOL_RESULT_SIGNAL } from "./client-tool-result"; + +import type { + FlueConversationMessage, + FlueConversationPart, + FlueConversationState, +} from "@flue/sdk"; +import type { UIMessage } from "ai"; + +type UiMessagePart = UIMessage["parts"][number]; + +export interface UiHistoryMessageMetadata { + readonly source?: "voice"; + readonly voiceToolCallIds?: readonly string[]; + readonly stopped?: true; +} + +export type UiHistoryMessage = Omit< + UIMessage, + "metadata" | "parts" | "role" +> & { + metadata?: UiHistoryMessageMetadata; + role: Extract; + parts: UiMessagePart[]; +}; + +export interface SnapshotToUiMessagesOptions { + readonly clientToolNames: ReadonlySet; + readonly mapClientToolInput?: (input: { + readonly input: unknown; + readonly toolName: string; + }) => unknown; + readonly hiddenToolNames?: ReadonlySet; +} + +const unhandledConversationPart = (part: never): never => { + throw new Error(`Unhandled Flue conversation part: ${JSON.stringify(part)}`); +}; + +const isFlueDataPart = ( + part: FlueConversationPart, +): part is Extract => + part.type.startsWith("data-"); + +const isRecord = (value: unknown): value is Record => + typeof value === "object" && value !== null; + +interface ClientToolResult { + readonly output: unknown; + readonly source?: "voice"; +} + +const clientToolResultsFrom = ( + snapshot: Pick, + signalName: string, +): ReadonlyMap => { + const resultsByCallId = new Map(); + for (const message of snapshot.messages) { + if (message.purpose !== "dispatch") continue; + if (message.signal?.tagName !== signalName) continue; + const text = message.parts + .filter( + (part): part is Extract => + part.type === "text", + ) + .map((part) => part.text) + .join(""); + let parsed: unknown; + try { + parsed = JSON.parse(text) as unknown; + } catch { + continue; + } + if (!Array.isArray(parsed)) continue; + for (const result of parsed) { + if ( + !isRecord(result) || + typeof result.toolCallId !== "string" || + !("output" in result) + ) { + continue; + } + resultsByCallId.set(result.toolCallId, { + output: result.output, + ...(result.source === "voice" ? { source: "voice" } : {}), + }); + } + } + return resultsByCallId; +}; + +const toolPartFrom = ( + part: Extract, + options: SnapshotToUiMessagesOptions, + clientResults: ReadonlyMap, +): UiMessagePart => { + const isClientTool = options.clientToolNames.has(part.toolName); + const hasClientOutput = clientResults.has(part.toolCallId); + const input = + isClientTool && options.mapClientToolInput !== undefined + ? options.mapClientToolInput({ + input: part.input, + toolName: part.toolName, + }) + : part.input; + if (part.state === "output-error") { + return { + type: `tool-${part.toolName}`, + toolCallId: part.toolCallId, + state: "output-error", + input, + errorText: part.errorText, + ...(isClientTool ? {} : { providerExecuted: true }), + }; + } + if (isClientTool && !hasClientOutput) { + return { + type: `tool-${part.toolName}`, + toolCallId: part.toolCallId, + state: "input-available", + input, + }; + } + const output = isClientTool + ? clientResults.get(part.toolCallId)?.output + : part.state === "output-available" + ? part.output + : undefined; + if (output !== undefined || hasClientOutput) { + return { + type: `tool-${part.toolName}`, + toolCallId: part.toolCallId, + state: "output-available", + input, + output, + ...(isClientTool ? {} : { providerExecuted: true }), + }; + } + return { + type: `tool-${part.toolName}`, + toolCallId: part.toolCallId, + state: "input-available", + input, + ...(isClientTool ? {} : { providerExecuted: true }), + }; +}; + +const partsFrom = ( + message: FlueConversationMessage, + options: SnapshotToUiMessagesOptions, + clientResults: ReadonlyMap, +): UiMessagePart[] => { + const parts: UiMessagePart[] = []; + for (const part of message.parts) { + if (part.type === "text") { + parts.push({ type: "text", text: part.text, state: "done" }); + continue; + } + if (part.type === "reasoning") { + parts.push({ type: "reasoning", text: part.text, state: "done" }); + continue; + } + if (part.type === "dynamic-tool") { + if (options.hiddenToolNames?.has(part.toolName) === true) continue; + parts.push(toolPartFrom(part, options, clientResults)); + continue; + } + if (part.type === "file") { + parts.push({ + type: "file", + mediaType: part.mediaType, + url: part.url ?? "", + ...(part.filename === undefined ? {} : { filename: part.filename }), + }); + continue; + } + if (isFlueDataPart(part)) { + parts.push({ type: part.type, data: part.data }); + continue; + } + unhandledConversationPart(part); + } + return parts; +}; + +export const snapshotToUiMessages = ( + snapshot: Pick & + Partial>, + options: SnapshotToUiMessagesOptions, +): UiHistoryMessage[] => { + const clientResults = clientToolResultsFrom( + snapshot, + CLIENT_TOOL_RESULT_SIGNAL, + ); + const messages: UiHistoryMessage[] = []; + const abortedSubmissions = new Set( + snapshot.settlements + ?.filter(({ outcome }) => outcome === "aborted") + .flatMap(({ submissionId, answeredBySubmissionId }) => + answeredBySubmissionId === undefined + ? [submissionId] + : [submissionId, answeredBySubmissionId], + ), + ); + // The live stream projects a client-tool continuation onto the assistant + // message it resumes; the snapshot records that continuation as a separate + // Flue message behind the `client-tool-result` dispatch, so fold it back. + let resumableAssistant: UiHistoryMessage | undefined; + let awaitingClientResult = false; + let continuationPending = false; + for (const message of snapshot.messages) { + if ( + message.purpose === "dispatch" && + message.signal?.tagName === CLIENT_TOOL_RESULT_SIGNAL + ) { + awaitingClientResult = false; + continuationPending = resumableAssistant !== undefined; + continue; + } + if (message.display !== "visible") continue; + if (message.purpose !== "user" && message.purpose !== "assistant") continue; + if (message.role !== "user" && message.role !== "assistant") continue; + const parts = partsFrom(message, options, clientResults); + if (message.role === "user") { + resumableAssistant = undefined; + awaitingClientResult = false; + continuationPending = false; + } + if (parts.length === 0) continue; + const foldsIntoPrevious = + message.role === "assistant" && + (awaitingClientResult || continuationPending) && + resumableAssistant !== undefined; + const voiceToolCallIds = + message.role === "assistant" + ? message.parts.flatMap((part) => + part.type === "dynamic-tool" && + clientResults.get(part.toolCallId)?.source === "voice" + ? [part.toolCallId] + : [], + ) + : []; + const stopped = + message.role === "assistant" && + message.submissionId !== undefined && + abortedSubmissions.has(message.submissionId); + const metadata: UiHistoryMessageMetadata = { + ...(voiceToolCallIds.length > 0 + ? { source: "voice" as const, voiceToolCallIds } + : {}), + ...(stopped ? { stopped: true as const } : {}), + }; + awaitingClientResult = + message.role === "assistant" && + !stopped && + message.parts.some( + (part) => + part.type === "dynamic-tool" && + options.clientToolNames.has(part.toolName) && + !clientResults.has(part.toolCallId), + ); + if (foldsIntoPrevious && resumableAssistant !== undefined) { + resumableAssistant.parts.push(...parts); + if (voiceToolCallIds.length > 0 || stopped) { + const combinedOrigins = [ + ...new Set([ + ...(resumableAssistant.metadata?.voiceToolCallIds ?? []), + ...voiceToolCallIds, + ]), + ]; + resumableAssistant.metadata = { + ...resumableAssistant.metadata, + ...metadata, + ...(combinedOrigins.length > 0 + ? { voiceToolCallIds: combinedOrigins } + : {}), + }; + } + continuationPending = false; + continue; + } + const projected: UiHistoryMessage = { + id: message.id, + role: message.role, + parts, + ...(voiceToolCallIds.length > 0 || stopped ? { metadata } : {}), + }; + messages.push(projected); + if (message.role === "assistant") resumableAssistant = projected; + } + return messages; +}; diff --git a/apps/brunch-agent/src/conversation/ui-stream.ts b/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/ui-stream.ts similarity index 80% rename from apps/brunch-agent/src/conversation/ui-stream.ts rename to libs/@hashintel/brunch-agent/packages/transport-aisdk/src/ui-stream.ts index da9cf93a524..90f8c3ee1f4 100644 --- a/apps/brunch-agent/src/conversation/ui-stream.ts +++ b/libs/@hashintel/brunch-agent/packages/transport-aisdk/src/ui-stream.ts @@ -1,14 +1,16 @@ -/** Project Flue live conversation chunks into AI SDK UI-message-stream chunks. */ - -import { type ConversationStreamChunk } from "@flue/sdk"; - -import { providerExecutedFor } from "./client-tools.ts"; +import { serializeErrorText } from "./error-text"; +import type { AgentSendResult, ConversationStreamChunk } from "@flue/sdk"; import type { UIMessageChunk } from "ai"; export interface FlueUiStreamOptions { - readonly submissionId: string; + readonly submissionId: AgentSendResult["submissionId"]; readonly clientToolNames: ReadonlySet; + readonly mapClientToolInput?: (input: { + readonly input: unknown; + readonly toolName: string; + }) => unknown; + readonly hiddenToolNames?: ReadonlySet; readonly write: (chunk: UIMessageChunk) => void; } @@ -31,6 +33,7 @@ export const createFlueUiStream = ( let turnId: string | undefined; let partOrdinal = 0; let streamingPart: StreamingPart | undefined; + const hiddenToolCallIds = new Set(); const pendingClientToolCallIds = new Set(); const finishPart = (): void => { @@ -71,6 +74,13 @@ export const createFlueUiStream = ( if (messageId === undefined) { messageId = chunk.messageId; options.write({ type: "start", messageId }); + } else if ( + chunk.messageId !== messageId && + pendingClientToolCallIds.size > 0 + ) { + // Flue may append a waiting reply after yielding to the browser. + // An empty trailing AI SDK step would strand the client tool. + return; } finishTurn(); turnId = chunk.turnId ?? `${messageId}:turn`; @@ -91,7 +101,7 @@ export const createFlueUiStream = ( case "failed": options.write({ type: "error", - errorText: "The chat turn failed.", + errorText: serializeErrorText(chunk.error), }); break; case "aborted": @@ -109,9 +119,6 @@ export const createFlueUiStream = ( case "conversation-reset": case "message-appended": case "stream-checkpoint": - // Observe/reconnect machinery, not assistant-message content. This - // projector emits one AI SDK assistant message for one Flue - // submission; these chunks are not parts of that message. return; case "message-delta": { if (!accepting || messageId === undefined) return; @@ -131,20 +138,30 @@ export const createFlueUiStream = ( if (!accepting || messageId === undefined) return; if (chunk.messageId !== messageId) return; finishPart(); + if (options.hiddenToolNames?.has(chunk.toolName) === true) { + hiddenToolCallIds.add(chunk.toolCallId); + return; + } const isClientTool = options.clientToolNames.has(chunk.toolName); if (isClientTool) pendingClientToolCallIds.add(chunk.toolCallId); - const providerExecuted = providerExecutedFor(isClientTool); options.write({ type: "tool-input-available", toolCallId: chunk.toolCallId, toolName: chunk.toolName, - input: chunk.input, - ...(providerExecuted === undefined ? {} : { providerExecuted }), + input: + isClientTool && options.mapClientToolInput !== undefined + ? options.mapClientToolInput({ + input: chunk.input, + toolName: chunk.toolName, + }) + : chunk.input, + ...(isClientTool ? {} : { providerExecuted: true }), }); return; } case "tool-output": { if (!accepting || messageId === undefined) return; + if (hiddenToolCallIds.has(chunk.toolCallId)) return; if (pendingClientToolCallIds.has(chunk.toolCallId)) return; options.write({ type: "tool-output-available", @@ -156,6 +173,7 @@ export const createFlueUiStream = ( } case "tool-output-error": { if (!accepting || messageId === undefined) return; + if (hiddenToolCallIds.has(chunk.toolCallId)) return; if (pendingClientToolCallIds.has(chunk.toolCallId)) return; options.write({ type: "tool-output-error", diff --git a/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/chat-handler.test.ts b/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/chat-handler.test.ts deleted file mode 100644 index 4274cec5132..00000000000 --- a/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/chat-handler.test.ts +++ /dev/null @@ -1,246 +0,0 @@ -/** - * Wire contracts for the Flue ↔ AI SDK chat door: principal, initial turns, - * and correlated client-tool resume. - */ - -import { describe, expect, test } from "vitest"; - -import { - createAiSdkChatHandler, - type ChatResumeInput, - type TransportInspectionEvent, -} from "../src/index"; - -import type { UIMessageChunk } from "ai"; - -const responseChunks = async ( - response: Response, -): Promise => - (await response.text()) - .trim() - .split("\n\n") - .slice(0, -1) - .map((frame) => JSON.parse(frame.slice("data: ".length)) as UIMessageChunk); - -const post = (body: unknown): Request => - new Request("http://brunch.test/api/chat", { - method: "POST", - headers: { - "content-type": "application/json", - "x-brunch-principal": "principal-mission-1", - "x-request-id": "request-mission-1", - }, - body: typeof body === "string" ? body : JSON.stringify(body), - }); - -const initialPost = { - id: "conversation-mission-1", - trigger: "submit-message", - messages: [ - { - id: "user-mission-1", - role: "user", - parts: [{ type: "text", text: "Is the server in the loop?" }], - }, - ], -}; - -const clientToolResumePost = { - id: "conversation-mission-1", - trigger: "submit-message", - messageId: "assistant-mission-1", - messages: [ - { - id: "user-mission-1", - role: "user", - parts: [{ type: "text", text: "How does simulation view work?" }], - }, - { - id: "assistant-mission-1", - role: "assistant", - parts: [ - { type: "step-start" }, - { - type: "tool-readPetrinautDoc", - toolCallId: "tool-doc-1", - state: "output-available", - input: { doc: "simulate-view" }, - output: "# Simulate view\nRun the net.", - }, - ], - }, - ], -}; - -test("refuses a valid turn without the UI shell principal", async () => { - let dispatched = false; - const handler = createAiSdkChatHandler({ - async runTurn() { - dispatched = true; - }, - }); - - const response = await handler( - new Request("http://brunch.test/api/chat", { - method: "POST", - headers: { "content-type": "application/json" }, - body: JSON.stringify(initialPost), - }), - ); - - expect(response.status).toBe(400); - expect(await response.json()).toEqual({ error: "invalid_principal" }); - expect(dispatched).toBe(false); -}); - -test("streams application-written chunks for an initial user turn", async () => { - const inspections: TransportInspectionEvent[] = []; - const handler = createAiSdkChatHandler({ - inspect: (event) => inspections.push(event), - async runTurn(input, write) { - expect(input.userMessage.text).toBe("Is the server in the loop?"); - write({ type: "start", messageId: "assistant-mission-1" }); - write({ type: "text-start", id: "text-1" }); - write({ type: "text-delta", id: "text-1", delta: "pong" }); - write({ type: "text-end", id: "text-1" }); - write({ type: "finish", finishReason: "stop" }); - }, - }); - - const response = await handler(post(initialPost)); - expect(response.status).toBe(200); - const chunks = await responseChunks(response); - expect(chunks.find((chunk) => chunk.type === "text-delta")).toMatchObject({ - delta: "pong", - }); - expect(chunks.at(-1)).toMatchObject({ type: "finish", finishReason: "stop" }); - expect(inspections[0]).toMatchObject({ type: "request-start" }); - expect(inspections.at(-1)).toMatchObject({ - type: "request-finish", - terminal: "completed", - }); -}); - -describe("client-tool resume", () => { - test("resumes with correlated client-tool outputs", async () => { - const resumed: ChatResumeInput[] = []; - const handler = createAiSdkChatHandler({ - async runTurn() { - throw new Error("the initial-turn path must not run for a follow-up"); - }, - async resumeTurn(input, write) { - resumed.push(input); - write({ type: "start", messageId: "assistant-next" }); - write({ type: "text-start", id: "text-2" }); - write({ - type: "text-delta", - id: "text-2", - delta: "Simulate view runs the net.", - }); - write({ type: "text-end", id: "text-2" }); - write({ type: "finish", finishReason: "stop" }); - }, - }); - - const response = await handler(post(clientToolResumePost)); - expect(response.status).toBe(200); - expect(resumed).toEqual([ - { - conversationId: "conversation-mission-1", - assistantMessageId: "assistant-mission-1", - idempotencyKey: "conversation-mission-1:tools:tool-doc-1", - principalKey: "principal-mission-1", - toolResults: [ - { - toolCallId: "tool-doc-1", - toolName: "readPetrinautDoc", - output: "# Simulate view\nRun the net.", - }, - ], - }, - ]); - const chunks = await responseChunks(response); - expect(chunks[0]).toEqual({ - type: "start", - messageId: "assistant-mission-1", - }); - }); - - test("refuses every follow-up when no resume seam is configured", async () => { - const handler = createAiSdkChatHandler({ async runTurn() {} }); - const response = await handler(post(clientToolResumePost)); - expect(response.status).toBe(422); - expect(await response.json()).toEqual({ - error: "tool_result_follow_up_not_supported", - }); - }); - - test("skips provider-executed tool parts when looking for a client resume", async () => { - let resumed = false; - const handler = createAiSdkChatHandler({ - async runTurn() {}, - async resumeTurn() { - resumed = true; - }, - }); - const response = await handler( - post({ - ...clientToolResumePost, - messages: [ - clientToolResumePost.messages[0], - { - id: "assistant-mission-1", - role: "assistant", - parts: [ - { - type: "tool-ping", - toolCallId: "tool-ping-1", - state: "output-available", - providerExecuted: true, - input: {}, - output: { ok: true }, - }, - ], - }, - ], - }), - ); - expect(response.status).toBe(422); - expect(resumed).toBe(false); - }); -}); - -test("refuses history without the UI shell principal", async () => { - const handler = createAiSdkChatHandler({ async runTurn() {} }); - const response = await handler( - new Request("http://brunch.test/api/chat?id=conversation-mission-1", { - method: "GET", - }), - ); - expect(response.status).toBe(400); - expect(await response.json()).toEqual({ error: "invalid_principal" }); -}); - -test("loads Flue history on GET for the same principal and conversation id", async () => { - const handler = createAiSdkChatHandler({ - async runTurn() {}, - async loadHistory(input) { - expect(input).toEqual({ - conversationId: "conversation-mission-1", - principalKey: "principal-mission-1", - }); - return { messages: [{ id: "user-1", role: "user", parts: [] }] }; - }, - }); - - const response = await handler( - new Request("http://brunch.test/api/chat?id=conversation-mission-1", { - method: "GET", - headers: { "x-brunch-principal": "principal-mission-1" }, - }), - ); - expect(response.status).toBe(200); - expect(await response.json()).toEqual({ - messages: [{ id: "user-1", role: "user", parts: [] }], - }); -}); diff --git a/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/chat-transport.test.ts b/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/chat-transport.test.ts new file mode 100644 index 00000000000..f56078bdf6c --- /dev/null +++ b/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/chat-transport.test.ts @@ -0,0 +1,756 @@ +import { FlueApiError, FlueExecutionError } from "@flue/sdk"; +import { expect, test, vi } from "vitest"; + +import { createFlueChatTransport } from "../src"; + +import type { FlueChatTransportOptions } from "../src"; +import type { + AgentSendResult, + ConversationStreamChunk, + FlueClient, +} from "@flue/sdk"; +import type { ChatTransport, UIMessage, UIMessageChunk } from "ai"; + +const admission: AgentSendResult = { + streamUrl: "http://brunch.test/stream", + offset: "offset-1", + submissionId: "submission-1", + uid: "uid-1", +}; + +const position = (index: number) => ({ batch: 1, index }); + +const completedEvents: readonly ConversationStreamChunk[] = [ + { + type: "message-started", + conversationId: "conversation-1", + messageId: "assistant-1", + submissionId: admission.submissionId, + turnId: "turn-1", + position: position(0), + }, + { + type: "message-delta", + conversationId: "conversation-1", + messageId: "assistant-1", + kind: "text", + delta: "Canonical reply.", + position: position(1), + }, + { + type: "message-completed", + conversationId: "conversation-1", + messageId: "assistant-1", + position: position(2), + }, + { + type: "submission-settled", + conversationId: "conversation-1", + submissionId: admission.submissionId, + outcome: "completed", + position: position(3), + }, +]; + +const clientWith = ( + events: readonly ConversationStreamChunk[], +): { + readonly client: FlueClient; + readonly send: ReturnType>; +} => { + const send = vi.fn(async () => admission); + const wait = vi.fn(async (_admission, options) => { + // Preserve protocol order while exercising the stateful projector. + // eslint-disable-next-line no-await-in-loop + for (const event of events) await options?.onEvent?.(event); + }); + return { + client: { send, wait } as Pick as FlueClient, + send, + }; +}; + +const readChunks = async ( + stream: ReadableStream, +): Promise => { + const chunks: UIMessageChunk[] = []; + const reader = stream.getReader(); + for (;;) { + // A stream reader is necessarily consumed in sequence. + // eslint-disable-next-line no-await-in-loop + const result = await reader.read(); + if (result.done) return chunks; + chunks.push(result.value); + } +}; + +const sendOptions = ( + messages: UIMessage[], + messageId?: string, +): Parameters["sendMessages"]>[0] => ({ + trigger: "submit-message", + chatId: "conversation-1", + messageId, + messages, + abortSignal: undefined, +}); + +test("submits results from the latest assistant step with completed client tools", async () => { + const { client, send } = clientWith(completedEvents); + const transport = createFlueChatTransport({ + client, + clientToolNames: new Set(["getLatestNetDefinition", "addArc"]), + }); + + await readChunks( + await transport.sendMessages( + sendOptions( + [ + { + id: "assistant-original", + role: "assistant", + parts: [ + { type: "step-start" }, + { + type: "dynamic-tool", + toolName: "getLatestNetDefinition", + toolCallId: "read-before-1", + state: "output-available", + input: {}, + output: { revision: 0 }, + }, + { type: "step-start" }, + { + type: "dynamic-tool", + toolName: "getLatestNetDefinition", + toolCallId: "read-before-2", + state: "output-available", + input: {}, + output: { revision: 0 }, + }, + { type: "step-start" }, + { + type: "dynamic-tool", + toolName: "addArc", + toolCallId: "mutation-latest", + state: "output-available", + input: {}, + output: { applied: true }, + }, + { type: "step-start" }, + { + type: "dynamic-tool", + toolName: "activate_skill", + toolCallId: "server-tool-later", + state: "output-available", + input: {}, + output: { activated: true }, + providerExecuted: true, + }, + ], + }, + ], + "assistant-original", + ), + ), + ); + + expect(send).toHaveBeenCalledWith( + expect.objectContaining({ + message: { + kind: "signal", + type: "client-tool-result", + tagName: "client-tool-result", + body: JSON.stringify([ + { + toolCallId: "mutation-latest", + toolName: "addArc", + output: { applied: true }, + }, + ]), + attributes: { toolCallIds: "mutation-latest" }, + }, + signal: undefined, + }), + ); +}); + +test("keeps reordered cumulative tool results byte-identical for idempotent retry", async () => { + const { client, send } = clientWith(completedEvents); + const transport = createFlueChatTransport({ + client, + clientToolNames: new Set(["readPetrinautDoc"]), + }); + const parts: UIMessage["parts"] = ["tool-b", "tool-a"].map((toolCallId) => ({ + type: "dynamic-tool", + toolName: "readPetrinautDoc", + toolCallId, + state: "output-available", + input: {}, + output: toolCallId, + })); + for (const ordered of [parts, [...parts].reverse()]) { + await readChunks( + await transport.sendMessages( + sendOptions( + [{ id: "assistant-original", role: "assistant", parts: ordered }], + "assistant-original", + ), + ), + ); + } + expect(send.mock.calls[0]?.[0]).toEqual(send.mock.calls[1]?.[0]); +}); + +test("admits one user message and projects a finite per-turn stream", async () => { + const { client, send } = clientWith(completedEvents); + const transport = createFlueChatTransport({ + client, + clientToolNames: new Set(["readPetrinautDoc"]), + }); + + const stream = await transport.sendMessages( + sendOptions([ + { + id: "user-1", + role: "user", + parts: [{ type: "text", text: "Run the transport tracer." }], + }, + ]), + ); + + expect(send).toHaveBeenCalledOnce(); + expect(send).toHaveBeenCalledWith({ + idempotencyKey: "ai-sdk:user:user-1", + message: { kind: "user", body: "Run the transport tracer." }, + signal: undefined, + }); + expect((await readChunks(stream)).map((chunk) => chunk.type)).toEqual([ + "start", + "start-step", + "text-start", + "text-delta", + "text-end", + "finish-step", + "finish", + ]); +}); + +test("admits one client-tool result signal and resumes its assistant id", async () => { + const { client, send } = clientWith(completedEvents); + const transport = createFlueChatTransport({ + client, + clientToolNames: new Set(["readPetrinautDoc"]), + }); + + const stream = await transport.sendMessages( + sendOptions( + [ + { + id: "assistant-original", + role: "assistant", + parts: [ + { + type: "dynamic-tool", + toolName: "readPetrinautDoc", + toolCallId: "tool-1", + state: "output-available", + input: { doc: "ai-assistant" }, + output: "The guide.", + }, + ], + }, + ], + "assistant-original", + ), + ); + + expect(send).toHaveBeenCalledWith({ + idempotencyKey: "ai-sdk:client-tools:assistant-original:tool-1", + message: { + kind: "signal", + type: "client-tool-result", + tagName: "client-tool-result", + body: JSON.stringify([ + { + toolCallId: "tool-1", + toolName: "readPetrinautDoc", + output: "The guide.", + }, + ]), + attributes: { toolCallIds: "tool-1" }, + }, + signal: undefined, + }); + expect((await readChunks(stream))[0]).toEqual({ + type: "start", + messageId: "assistant-original", + }); +}); + +test("derives the same idempotency key for exact AI SDK retries", async () => { + const { client, send } = clientWith(completedEvents); + const transport = createFlueChatTransport({ + client, + clientToolNames: new Set(), + }); + const options = sendOptions([ + { + id: "stable-user-message", + role: "user", + parts: [{ type: "text", text: "Admit this once." }], + }, + ]); + + await transport.sendMessages(options); + await transport.sendMessages(options); + + expect(send).toHaveBeenCalledTimes(2); + expect(send.mock.calls.map(([input]) => input.idempotencyKey)).toEqual([ + "ai-sdk:user:stable-user-message", + "ai-sdk:user:stable-user-message", + ]); +}); + +test("starts with history-only reconnection", async () => { + const { client } = clientWith([]); + const transport = createFlueChatTransport({ + client, + clientToolNames: new Set(), + }); + + await expect( + transport.reconnectToStream({ chatId: "conversation-1" }), + ).resolves.toBeNull(); +}); + +test.each([ + [ + "failed", + new Error("Elicitor tool failed.", { + cause: { field: "answer", reason: "Required" }, + }), + { + type: "error", + errorText: + 'Elicitor tool failed.\nCaused by: {"field":"answer","reason":"Required"}', + }, + ], + [ + "aborted", + new FlueExecutionError({ + target: "agent_submission", + targetId: admission.submissionId, + failure: "aborted", + }), + { type: "abort", reason: "The chat turn was stopped." }, + ], + [ + "missing terminal event", + new FlueExecutionError({ + target: "agent_submission", + targetId: admission.submissionId, + failure: "terminal_event_missing", + }), + { + type: "error", + errorText: "The chat stream ended before the turn settled.", + }, + ], +])( + "maps a %s wait rejection into the finite UI stream", + async (_label, waitError, expected) => { + const send = vi.fn(async () => admission); + const wait = vi.fn(async () => { + throw waitError; + }); + const transport = createFlueChatTransport({ + client: { send, wait } as Pick as FlueClient, + clientToolNames: new Set(), + }); + + const stream = await transport.sendMessages( + sendOptions([ + { + id: "user-1", + role: "user", + parts: [{ type: "text", text: "Map the outcome." }], + }, + ]), + ); + + expect(await readChunks(stream)).toEqual([expected]); + }, +); + +test("keeps caller cancellation distinct from durable abort", async () => { + const abortController = new AbortController(); + const send = vi.fn(async () => admission); + const wait = vi.fn( + async (_admission, options) => + new Promise((_resolve, reject) => { + options?.signal?.addEventListener( + "abort", + () => reject(new DOMException("cancelled", "AbortError")), + { once: true }, + ); + }), + ); + const transport = createFlueChatTransport({ + client: { send, wait } as Pick as FlueClient, + clientToolNames: new Set(), + }); + const stream = await transport.sendMessages({ + ...sendOptions([ + { + id: "user-1", + role: "user", + parts: [{ type: "text", text: "Cancel only this observer." }], + }, + ]), + abortSignal: abortController.signal, + }); + + abortController.abort(); + + await expect(readChunks(stream)).resolves.toEqual([ + { type: "abort", reason: "The local chat stream was cancelled." }, + ]); +}); + +test("classifies documented rejection and ambiguous admission without retrying", async () => { + const rejectedSend = vi.fn(async () => { + throw new FlueApiError(403, ""); + }); + const ambiguousSend = vi.fn(async () => { + throw new TypeError("connection lost after request write"); + }); + const createTransport = (send: FlueClient["send"]) => + createFlueChatTransport({ + client: { send } as Pick as FlueClient, + clientToolNames: new Set(), + }); + const options = sendOptions([ + { + id: "user-1", + role: "user", + parts: [{ type: "text", text: "Admit once." }], + }, + ]); + + await expect( + createTransport(rejectedSend).sendMessages(options), + ).rejects.toMatchObject({ + failure: { kind: "rejected", status: 403 }, + message: "Brunch rejected the message before admission (HTTP 403).", + name: "FlueChatAdmissionError", + }); + await expect( + createTransport(ambiguousSend).sendMessages(options), + ).rejects.toMatchObject({ + failure: { kind: "ambiguous" }, + message: + "Brunch may have accepted the message, but admission could not be confirmed. Reopen the conversation before trying again.", + name: "FlueChatAdmissionError", + }); + expect(rejectedSend).toHaveBeenCalledOnce(); + expect(ambiguousSend).toHaveBeenCalledOnce(); +}); + +test.each([ + ["server failure", new FlueApiError(500, "")], + ["unknown response", new FlueApiError(418, "")], +] as const)( + "treats a %s after request write as ambiguous", + async (_label, error) => { + const send = vi.fn(async () => { + throw error; + }); + const transport = createFlueChatTransport({ + client: { send } as Pick as FlueClient, + clientToolNames: new Set(), + }); + + await expect( + transport.sendMessages( + sendOptions([ + { + id: "user-ambiguous", + role: "user", + parts: [{ type: "text", text: "Do not retry this." }], + }, + ]), + ), + ).rejects.toMatchObject({ + failure: { kind: "ambiguous" }, + name: "FlueChatAdmissionError", + }); + expect(send).toHaveBeenCalledOnce(); + }, +); + +test("classifies an explicit local admission abort without retrying", async () => { + const send = vi.fn(async () => { + throw new DOMException("cancelled", "AbortError"); + }); + const transport = createFlueChatTransport({ + client: { send } as Pick as FlueClient, + clientToolNames: new Set(), + }); + + await expect( + transport.sendMessages( + sendOptions([ + { + id: "user-aborted", + role: "user", + parts: [{ type: "text", text: "Cancel locally." }], + }, + ]), + ), + ).rejects.toMatchObject({ + failure: { kind: "aborted" }, + name: "FlueChatAdmissionError", + }); + expect(send).toHaveBeenCalledOnce(); +}); + +test("reports one admission and its correlated response message completion", async () => { + const { client } = clientWith(completedEvents); + const onAdmission = + vi.fn>(); + const onResponseMessage = + vi.fn>(); + const onResponseMessageCompleted = + vi.fn< + NonNullable + >(); + const transport = createFlueChatTransport({ + client, + clientToolNames: new Set(), + onAdmission, + onResponseMessage, + onResponseMessageCompleted, + }); + + const stream = await transport.sendMessages( + sendOptions([ + { + id: "user-1", + role: "user", + parts: [{ type: "text", text: "Track this response." }], + }, + ]), + ); + await readChunks(stream); + + expect(onAdmission).toHaveBeenCalledOnce(); + expect(onAdmission).toHaveBeenCalledWith({ + admission, + kind: "user", + messageId: "user-1", + }); + expect(onResponseMessage).toHaveBeenCalledOnce(); + expect(onResponseMessage).toHaveBeenCalledWith({ + messageId: "assistant-1", + position: position(0), + submissionId: admission.submissionId, + }); + expect(onResponseMessageCompleted).toHaveBeenCalledOnce(); + expect(onResponseMessageCompleted).toHaveBeenCalledWith({ + messageId: "assistant-1", + position: position(2), + submissionId: admission.submissionId, + }); +}); + +test("stays silent after the consumer cancels the per-turn stream", async () => { + let waitSignal: AbortSignal | undefined; + const send = vi.fn(async () => admission); + const wait = vi.fn( + async (_admission, options) => + new Promise((_resolve, reject) => { + waitSignal = options?.signal; + options?.signal?.addEventListener( + "abort", + () => reject(new DOMException("cancelled", "AbortError")), + { once: true }, + ); + }), + ); + const transport = createFlueChatTransport({ + client: { send, wait } as Pick as FlueClient, + clientToolNames: new Set(), + }); + const stream = await transport.sendMessages( + sendOptions([ + { + id: "user-1", + role: "user", + parts: [{ type: "text", text: "Cancel from the reader." }], + }, + ]), + ); + + const reader = stream.getReader(); + await reader.cancel(); + // Let the rejected `wait()` settle; an enqueue on the cancelled controller + // would surface here as an unhandled rejection. + await new Promise((resolve) => setTimeout(resolve, 0)); + + expect(waitSignal?.aborted).toBe(true); + await expect(reader.closed).resolves.toBeUndefined(); +}); + +test("reports a client-tool continuation and completion against the resumed assistant id", async () => { + const { client } = clientWith(completedEvents); + const onResponseMessage = + vi.fn>(); + const onResponseMessageCompleted = + vi.fn< + NonNullable + >(); + const transport = createFlueChatTransport({ + client, + clientToolNames: new Set(["readPetrinautDoc"]), + onResponseMessage, + onResponseMessageCompleted, + }); + + const stream = await transport.sendMessages( + sendOptions( + [ + { + id: "assistant-original", + role: "assistant", + parts: [ + { + type: "dynamic-tool", + toolName: "readPetrinautDoc", + toolCallId: "tool-1", + state: "output-available", + input: { doc: "ai-assistant" }, + output: "The guide.", + }, + ], + }, + ], + "assistant-original", + ), + ); + await readChunks(stream); + + expect(onResponseMessage).toHaveBeenCalledOnce(); + expect(onResponseMessage).toHaveBeenCalledWith({ + messageId: "assistant-original", + position: position(0), + submissionId: admission.submissionId, + }); + expect(onResponseMessageCompleted).toHaveBeenCalledOnce(); + expect(onResponseMessageCompleted).toHaveBeenCalledWith({ + messageId: "assistant-original", + position: position(2), + submissionId: admission.submissionId, + }); +}); + +test("replays a stable typed or Voice message with the same idempotency key", async () => { + const seenKeys = new Set(); + let admittedTurns = 0; + const send = vi.fn(async (options) => { + const key = options.idempotencyKey; + if (key === undefined || !seenKeys.has(key)) { + admittedTurns += 1; + if (key !== undefined) seenKeys.add(key); + return admission; + } + return { ...admission, deduplicated: true }; + }); + const wait = vi.fn(async () => undefined); + const onAdmission = + vi.fn>(); + const transport = createFlueChatTransport({ + client: { send, wait } as Pick as FlueClient, + clientToolNames: new Set(), + onAdmission, + }); + const typedTurn = sendOptions([ + { + id: "typed-message-1", + role: "user", + parts: [{ type: "text", text: "Admit this once." }], + }, + ]); + + const firstStream = await transport.sendMessages(typedTurn); + const replayedStream = await transport.sendMessages(typedTurn); + await Promise.all([readChunks(firstStream), readChunks(replayedStream)]); + + expect(send).toHaveBeenNthCalledWith( + 1, + expect.objectContaining({ idempotencyKey: "ai-sdk:user:typed-message-1" }), + ); + expect(send).toHaveBeenNthCalledWith( + 2, + expect.objectContaining({ idempotencyKey: "ai-sdk:user:typed-message-1" }), + ); + expect(admittedTurns).toBe(1); + expect(onAdmission).toHaveBeenNthCalledWith(2, { + admission: { ...admission, deduplicated: true }, + kind: "user", + messageId: "typed-message-1", + }); + + const voiceTurn = sendOptions([ + { + id: "voice-realtime:7:item%2F1:0", + role: "user", + parts: [{ type: "text", text: "Voice transcript." }], + }, + ]); + await readChunks(await transport.sendMessages(voiceTurn)); + expect(send).toHaveBeenLastCalledWith( + expect.objectContaining({ + idempotencyKey: "ai-sdk:user:voice-realtime:7:item%2F1:0", + }), + ); +}); + +test("reports an idempotency conflict as a definite existing admission", async () => { + const send = vi.fn(async () => { + throw new FlueApiError(409, { + error: { + details: "", + message: "The delivery key already names another payload.", + meta: { submissionId: "submission-existing" }, + type: "submission_conflict", + }, + }); + }); + const transport = createFlueChatTransport({ + client: { send } as Pick as FlueClient, + clientToolNames: new Set(), + }); + + await expect( + transport.sendMessages( + sendOptions([ + { + id: "user-conflict", + role: "user", + parts: [{ type: "text", text: "Changed payload." }], + }, + ]), + ), + ).rejects.toMatchObject({ + failure: { + kind: "submission-conflict", + status: 409, + submissionId: "submission-existing", + }, + message: + "The delivery key already belongs to admitted submission submission-existing; the changed payload was not admitted.", + name: "FlueChatAdmissionError", + }); + expect(send).toHaveBeenCalledOnce(); +}); diff --git a/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/client-tool-history.test.ts b/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/client-tool-history.test.ts new file mode 100644 index 00000000000..bfc3abd64c8 --- /dev/null +++ b/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/client-tool-history.test.ts @@ -0,0 +1,64 @@ +import { describe, expect, test } from "vitest"; + +import { CLIENT_TOOL_RESULT_SIGNAL, clientToolHistoryFrom } from "../src/index"; + +describe("clientToolHistoryFrom", () => { + test("projects generic calls and correlated client result envelopes", () => { + expect( + clientToolHistoryFrom([ + { + parts: [ + { + type: "dynamic-tool", + toolName: "addArc", + toolCallId: "call-1", + input: { placeId: "place-1" }, + }, + ], + }, + { + signal: { tagName: CLIENT_TOOL_RESULT_SIGNAL }, + parts: [ + { + type: "text", + text: JSON.stringify([ + { + toolName: "addArc", + toolCallId: "call-1", + output: { applied: true }, + }, + ]), + }, + ], + }, + ]), + ).toEqual({ + calls: [ + { + input: { placeId: "place-1" }, + toolCallId: "call-1", + toolName: "addArc", + }, + ], + results: [ + { + output: { applied: true }, + toolCallId: "call-1", + toolName: "addArc", + }, + ], + }); + }); + + test("ignores malformed calls and result bodies", () => { + expect( + clientToolHistoryFrom([ + { parts: [{ type: "dynamic-tool", toolName: "addArc" }] }, + { + signal: { type: CLIENT_TOOL_RESULT_SIGNAL }, + parts: [{ type: "text", text: "not-json" }], + }, + ]), + ).toEqual({ calls: [], results: [] }); + }); +}); diff --git a/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/fixtures/panel-client-tool.post.json b/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/fixtures/panel-client-tool.post.json deleted file mode 100644 index 08568ea97d9..00000000000 --- a/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/fixtures/panel-client-tool.post.json +++ /dev/null @@ -1,26 +0,0 @@ -{ - "id": "conversation-mission-1", - "trigger": "submit-message", - "messageId": "assistant-mission-1", - "messages": [ - { - "id": "user-mission-1", - "role": "user", - "parts": [{ "type": "text", "text": "How does the AI assistant work?" }] - }, - { - "id": "assistant-mission-1", - "role": "assistant", - "parts": [ - { "type": "step-start" }, - { - "type": "tool-readPetrinautDoc", - "toolCallId": "tool-doc-1", - "state": "output-available", - "input": { "doc": "ai-assistant" }, - "output": "# AI Assistant\nThe assistant can read its own documentation pages." - } - ] - } - ] -} diff --git a/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/fixtures/panel-initial.post.json b/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/fixtures/panel-initial.post.json deleted file mode 100644 index b771e13bd0f..00000000000 --- a/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/fixtures/panel-initial.post.json +++ /dev/null @@ -1,16 +0,0 @@ -{ - "id": "m5z0GU9KJPzhOTlx", - "messages": [ - { - "parts": [ - { - "type": "text", - "text": "Run the FE-1435 transport probe." - } - ], - "id": "6ddgGkjhSxGjOtiv", - "role": "user" - } - ], - "trigger": "submit-message" -} diff --git a/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/golden.test.ts b/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/golden.test.ts deleted file mode 100644 index 8bc0f08ea9c..00000000000 --- a/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/golden.test.ts +++ /dev/null @@ -1,49 +0,0 @@ -import { readFileSync } from "node:fs"; -import { join } from "node:path"; - -import { expect, test } from "vitest"; - -import type { ChatTransport, UIMessage } from "ai"; - -type SendMessagesOptions = Parameters< - ChatTransport["sendMessages"] ->[0]; - -type PanelPostBody = { - readonly id: SendMessagesOptions["chatId"]; - readonly messageId?: SendMessagesOptions["messageId"]; - readonly messages: SendMessagesOptions["messages"]; - readonly trigger: SendMessagesOptions["trigger"]; -}; - -const FIXTURES = join(import.meta.dirname, "fixtures"); - -const readPostBody = (name: string): PanelPostBody => - JSON.parse(readFileSync(join(FIXTURES, name), "utf8")) as PanelPostBody; - -test("validates the load-bearing fields in the complete initial panel POST fixture", () => { - const body = readPostBody("panel-initial.post.json"); - expect(body.trigger).toBe("submit-message"); - expect(body.messages).toHaveLength(1); - expect(body.messages[0]?.role).toBe("user"); - expect(body.messages[0]?.parts).toEqual([ - { type: "text", text: "Run the FE-1435 transport probe." }, - ]); -}); - -test("validates the load-bearing fields in the read-only client-tool follow-up fixture", () => { - const body = readPostBody("panel-client-tool.post.json"); - expect(body.trigger).toBe("submit-message"); - expect(body.messageId).toBe("assistant-mission-1"); - const assistant = body.messages.find( - (message) => message.id === body.messageId, - ); - expect(assistant?.role).toBe("assistant"); - expect( - assistant?.parts.find((part) => part.type === "tool-readPetrinautDoc"), - ).toMatchObject({ - type: "tool-readPetrinautDoc", - toolCallId: "tool-doc-1", - state: "output-available", - }); -}); diff --git a/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/transcript.test.ts b/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/transcript.test.ts new file mode 100644 index 00000000000..e9bbc3d38fc --- /dev/null +++ b/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/transcript.test.ts @@ -0,0 +1,481 @@ +import { expect, test } from "vitest"; + +import { CLIENT_TOOL_RESULT_SIGNAL, snapshotToUiMessages } from "../src"; + +import type { FlueConversationSnapshot } from "@flue/sdk"; + +const snapshotWithPendingClientTool: FlueConversationSnapshot = { + v: 1, + conversationId: "conversation-1", + offset: "0", + messages: [ + { + id: "assistant-1", + role: "assistant", + purpose: "assistant", + display: "visible", + parts: [ + { + type: "dynamic-tool", + toolCallId: "tool-doc-1", + toolName: "readPetrinautDoc", + state: "output-available", + input: { doc: "ai-assistant" }, + output: { awaiting: "client" }, + }, + ], + }, + ], + settlements: [], +}; + +const projectionOptions = { + clientToolNames: new Set(["readPetrinautDoc"]), + hiddenToolNames: new Set(["brunch_mark_question"]), +}; + +test("retains Voice origins from folded continuation messages", () => { + const messages: FlueConversationSnapshot["messages"] = []; + for (const ordinal of [1, 2]) { + messages.push( + { + id: `assistant-${ordinal}`, + role: "assistant", + purpose: "assistant", + display: "visible", + parts: [ + { + type: "dynamic-tool", + toolCallId: `tool-${ordinal}`, + toolName: "readPetrinautDoc", + state: "output-available", + input: { doc: "ai-assistant" }, + output: { awaiting: "client" }, + }, + ], + }, + { + id: `signal-${ordinal}`, + role: "system", + purpose: "dispatch", + display: "hidden", + signal: { tagName: CLIENT_TOOL_RESULT_SIGNAL }, + parts: [ + { + type: "text", + state: "done", + text: JSON.stringify([ + { + toolCallId: `tool-${ordinal}`, + output: "A spoken answer", + source: "voice", + }, + ]), + }, + ], + }, + ); + } + expect(snapshotToUiMessages({ messages }, projectionOptions)).toMatchObject([ + { + id: "assistant-1", + metadata: { source: "voice", voiceToolCallIds: ["tool-1", "tool-2"] }, + }, + ]); +}); + +test("marks only the durably aborted assistant response stopped after reopen", () => { + const snapshot: FlueConversationSnapshot = { + ...snapshotWithPendingClientTool, + messages: [ + { + id: "partial", + role: "assistant", + purpose: "assistant", + display: "visible", + submissionId: "stopped-turn", + parts: [{ type: "text", state: "done", text: "Partial reply" }], + }, + { + id: "next-user", + role: "user", + purpose: "user", + display: "visible", + parts: [{ type: "text", state: "done", text: "Continue" }], + }, + { + id: "complete", + role: "assistant", + purpose: "assistant", + display: "visible", + submissionId: "next-turn", + parts: [{ type: "text", state: "done", text: "Complete reply" }], + }, + ], + settlements: [ + { submissionId: "stopped-turn", outcome: "aborted" }, + { submissionId: "next-turn", outcome: "completed" }, + ], + }; + const projected = snapshotToUiMessages(snapshot, projectionOptions); + expect(projected.find(({ id }) => id === "partial")?.metadata).toEqual({ + stopped: true, + }); + expect( + projected.find(({ id }) => id === "complete")?.metadata, + ).toBeUndefined(); + expect( + projected.find(({ id }) => id === "next-user")?.metadata, + ).toBeUndefined(); +}); + +test("leaves an unfinished client tool available to run", () => { + expect( + snapshotToUiMessages(snapshotWithPendingClientTool, projectionOptions), + ).toEqual([ + { + id: "assistant-1", + role: "assistant", + parts: [ + { + type: "tool-readPetrinautDoc", + toolCallId: "tool-doc-1", + state: "input-available", + input: { doc: "ai-assistant" }, + }, + ], + }, + ]); +}); + +test("keeps a pending client tool on the final assistant message", () => { + const snapshot: FlueConversationSnapshot = { + ...snapshotWithPendingClientTool, + messages: [ + ...snapshotWithPendingClientTool.messages, + { + id: "assistant-waiting", + role: "assistant", + purpose: "assistant", + display: "visible", + parts: [ + { + type: "text", + text: "Waiting for the browser.", + state: "done", + }, + ], + }, + ], + }; + + expect(snapshotToUiMessages(snapshot, projectionOptions)).toEqual([ + { + id: "assistant-1", + role: "assistant", + parts: [ + { + type: "tool-readPetrinautDoc", + toolCallId: "tool-doc-1", + state: "input-available", + input: { doc: "ai-assistant" }, + }, + { + type: "text", + text: "Waiting for the browser.", + state: "done", + }, + ], + }, + ]); +}); + +test("uses a recorded browser result even when it is null", () => { + const snapshot: FlueConversationSnapshot = { + ...snapshotWithPendingClientTool, + messages: [ + ...snapshotWithPendingClientTool.messages, + { + id: "signal-1", + role: "system", + purpose: "dispatch", + display: "hidden", + signal: { tagName: CLIENT_TOOL_RESULT_SIGNAL }, + parts: [ + { + type: "text", + text: '[{"toolCallId":"tool-doc-1","toolName":"readPetrinautDoc","output":null}]', + state: "done", + }, + ], + }, + ], + }; + + expect(snapshotToUiMessages(snapshot, projectionOptions)[0]?.parts).toEqual([ + { + type: "tool-readPetrinautDoc", + toolCallId: "tool-doc-1", + state: "output-available", + input: { doc: "ai-assistant" }, + output: null, + }, + ]); +}); + +test("reconstructs durable voice provenance for each browser result", () => { + const snapshot: FlueConversationSnapshot = { + ...snapshotWithPendingClientTool, + messages: [ + { + ...snapshotWithPendingClientTool.messages[0]!, + parts: [ + ...snapshotWithPendingClientTool.messages[0]!.parts, + { + type: "dynamic-tool", + toolCallId: "tool-doc-2", + toolName: "readPetrinautDoc", + state: "output-available", + input: { doc: "ai-assistant" }, + output: { awaiting: "client" }, + }, + ], + }, + { + id: "signal-voice-results", + role: "system", + purpose: "dispatch", + display: "hidden", + signal: { tagName: CLIENT_TOOL_RESULT_SIGNAL }, + parts: [ + { + type: "text", + text: JSON.stringify([ + { + toolCallId: "tool-doc-1", + toolName: "readPetrinautDoc", + output: "First guide", + source: "voice", + }, + { + toolCallId: "tool-doc-2", + toolName: "readPetrinautDoc", + output: "Second guide", + source: "voice", + }, + ]), + state: "done", + }, + ], + }, + ], + }; + + expect(snapshotToUiMessages(snapshot, projectionOptions)).toEqual([ + expect.objectContaining({ + id: "assistant-1", + metadata: { + source: "voice", + voiceToolCallIds: ["tool-doc-1", "tool-doc-2"], + }, + }), + ]); +}); + +test("keeps Flue data parts on the AI SDK message", () => { + const snapshot: FlueConversationSnapshot = { + v: 1, + conversationId: "conversation-1", + offset: "0", + messages: [ + { + id: "assistant-1", + role: "assistant", + purpose: "assistant", + display: "visible", + parts: [ + { type: "text", text: "Here is the order.", state: "done" }, + { + type: "data-orderCard", + data: { orderId: "42", status: "loaded" }, + }, + ], + }, + ], + settlements: [], + }; + + expect(snapshotToUiMessages(snapshot, projectionOptions)).toEqual([ + { + id: "assistant-1", + role: "assistant", + parts: [ + { type: "text", text: "Here is the order.", state: "done" }, + { type: "data-orderCard", data: { orderId: "42", status: "loaded" } }, + ], + }, + ]); +}); + +test("keeps a rehydrated server tool provider-executed while it still runs", () => { + const snapshot: FlueConversationSnapshot = { + ...snapshotWithPendingClientTool, + messages: [ + { + id: "assistant-1", + role: "assistant", + purpose: "assistant", + display: "visible", + parts: [ + { + type: "dynamic-tool", + toolCallId: "tool-sweep-1", + toolName: "brunch_sweep", + state: "input-available", + input: { range: "all" }, + }, + ], + }, + ], + }; + + expect(snapshotToUiMessages(snapshot, projectionOptions)[0]?.parts).toEqual([ + { + type: "tool-brunch_sweep", + toolCallId: "tool-sweep-1", + state: "input-available", + input: { range: "all" }, + providerExecuted: true, + }, + ]); +}); + +test("folds a client-tool continuation into the assistant message it resumed", () => { + const snapshot: FlueConversationSnapshot = { + ...snapshotWithPendingClientTool, + messages: [ + { + id: "user-1", + role: "user", + purpose: "user", + display: "visible", + parts: [{ type: "text", text: "Read the guide.", state: "done" }], + }, + ...snapshotWithPendingClientTool.messages, + { + id: "signal-1", + role: "system", + purpose: "dispatch", + display: "hidden", + signal: { tagName: CLIENT_TOOL_RESULT_SIGNAL }, + parts: [ + { + type: "text", + text: '[{"toolCallId":"tool-doc-1","toolName":"readPetrinautDoc","output":"The guide."}]', + state: "done", + }, + ], + }, + { + id: "assistant-2", + role: "assistant", + purpose: "assistant", + display: "visible", + parts: [{ type: "text", text: "The guide says hello.", state: "done" }], + }, + { + id: "user-2", + role: "user", + purpose: "user", + display: "visible", + parts: [{ type: "text", text: "Thanks.", state: "done" }], + }, + { + id: "assistant-3", + role: "assistant", + purpose: "assistant", + display: "visible", + parts: [{ type: "text", text: "You are welcome.", state: "done" }], + }, + ], + }; + + expect(snapshotToUiMessages(snapshot, projectionOptions)).toEqual([ + { + id: "user-1", + role: "user", + parts: [{ type: "text", text: "Read the guide.", state: "done" }], + }, + { + id: "assistant-1", + role: "assistant", + parts: [ + { + type: "tool-readPetrinautDoc", + toolCallId: "tool-doc-1", + state: "output-available", + input: { doc: "ai-assistant" }, + output: "The guide.", + }, + { type: "text", text: "The guide says hello.", state: "done" }, + ], + }, + { + id: "user-2", + role: "user", + parts: [{ type: "text", text: "Thanks.", state: "done" }], + }, + { + id: "assistant-3", + role: "assistant", + parts: [{ type: "text", text: "You are welcome.", state: "done" }], + }, + ]); +}); + +test("hides a question-marker tool while retaining its durable data", () => { + const question = "Which line should run this order?"; + const snapshot: FlueConversationSnapshot = { + v: 1, + conversationId: "conversation-1", + offset: "0", + messages: [ + { + id: "assistant-question", + role: "assistant", + purpose: "assistant", + display: "visible", + parts: [ + { + type: "dynamic-tool", + toolCallId: "tool-question-1", + toolName: "brunch_mark_question", + state: "output-available", + input: { question }, + output: { marked: true }, + }, + { + type: "data-brunch-question", + data: { question, toolCallId: "tool-question-1" }, + }, + { type: "text", text: question, state: "done" }, + ], + }, + ], + settlements: [], + }; + + expect(snapshotToUiMessages(snapshot, projectionOptions)).toEqual([ + { + id: "assistant-question", + role: "assistant", + parts: [ + { + type: "data-brunch-question", + data: { question, toolCallId: "tool-question-1" }, + }, + { type: "text", text: question, state: "done" }, + ], + }, + ]); +}); diff --git a/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/ui-stream.test.ts b/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/ui-stream.test.ts new file mode 100644 index 00000000000..b145c4d896a --- /dev/null +++ b/libs/@hashintel/brunch-agent/packages/transport-aisdk/test/ui-stream.test.ts @@ -0,0 +1,360 @@ +import { expect, test } from "vitest"; + +import { createFlueUiStream } from "../src"; + +import type { ConversationStreamChunk } from "@flue/sdk"; +import type { UIMessageChunk } from "ai"; + +const position = (index: number) => ({ batch: 1, index }); + +const project = ( + chunks: readonly ConversationStreamChunk[], + hiddenToolNames: ReadonlySet = new Set(), +): UIMessageChunk[] => { + const written: UIMessageChunk[] = []; + const projector = createFlueUiStream({ + submissionId: "submission-1", + clientToolNames: new Set(["readPetrinautDoc"]), + hiddenToolNames, + write: (chunk) => written.push(chunk), + }); + for (const chunk of chunks) projector.accept(chunk); + return written; +}; + +test("projects data and metadata onto the AI SDK stream", () => { + const written = project([ + { + type: "message-started", + conversationId: "conversation-1", + messageId: "message-1", + submissionId: "submission-1", + turnId: "turn-1", + position: position(0), + }, + { + type: "message-metadata", + conversationId: "conversation-1", + messageId: "message-1", + metadata: { elapsedMs: 17 }, + position: position(1), + }, + { + type: "data-part", + conversationId: "conversation-1", + messageId: "message-1", + name: "orderCard", + data: { orderId: "42", status: "loaded" }, + position: position(2), + }, + { + type: "submission-settled", + conversationId: "conversation-1", + submissionId: "submission-1", + outcome: "completed", + position: position(3), + }, + ]); + + expect(written).toContainEqual({ + type: "message-metadata", + messageMetadata: { elapsedMs: 17 }, + }); + expect(written).toContainEqual({ + type: "data-orderCard", + data: { orderId: "42", status: "loaded" }, + }); +}); + +test("hides an implementation tool while preserving its data marker", () => { + const written = project( + [ + { + type: "message-started", + conversationId: "conversation-1", + messageId: "message-1", + submissionId: "submission-1", + turnId: "turn-1", + position: position(0), + }, + { + type: "tool-input", + conversationId: "conversation-1", + messageId: "message-1", + toolCallId: "tool-question-1", + toolName: "brunch_mark_question", + input: { question: "Which line should run this order?" }, + position: position(1), + }, + { + type: "data-part", + conversationId: "conversation-1", + messageId: "message-1", + name: "brunch-question", + data: { + question: "Which line should run this order?", + toolCallId: "tool-question-1", + }, + position: position(2), + }, + { + type: "tool-output", + conversationId: "conversation-1", + toolCallId: "tool-question-1", + output: { marked: true }, + position: position(3), + }, + { + type: "submission-settled", + conversationId: "conversation-1", + submissionId: "submission-1", + outcome: "completed", + position: position(4), + }, + ], + new Set(["brunch_mark_question"]), + ); + + expect(written).toContainEqual({ + type: "data-brunch-question", + data: { + question: "Which line should run this order?", + toolCallId: "tool-question-1", + }, + }); + expect( + written.some( + (chunk) => + chunk.type === "tool-input-available" || + chunk.type === "tool-output-available" || + chunk.type === "tool-output-error", + ), + ).toBe(false); +}); + +test("ignores observation catch-up chunks in a submission stream", () => { + const written = project([ + { + type: "message-started", + conversationId: "conversation-1", + messageId: "message-1", + submissionId: "submission-1", + turnId: "turn-1", + position: position(0), + }, + { + type: "stream-checkpoint", + incarnation: "incarnation-1", + }, + { + type: "conversation-reset", + conversationId: "conversation-1", + snapshot: { + v: 1, + conversationId: "conversation-1", + offset: "0", + messages: [], + settlements: [], + }, + position: position(1), + }, + { + type: "message-appended", + conversationId: "conversation-1", + message: { + id: "user-1", + role: "user", + purpose: "user", + display: "visible", + parts: [{ type: "text", text: "Hello.", state: "done" }], + }, + position: position(2), + }, + { + type: "submission-settled", + conversationId: "conversation-1", + submissionId: "submission-1", + outcome: "completed", + position: position(3), + }, + ]); + + expect(written.map((chunk) => chunk.type)).toEqual([ + "start", + "start-step", + "finish-step", + "finish", + ]); +}); + +test("maps client-tool input before exposing it to the AI SDK", () => { + const written: UIMessageChunk[] = []; + const projector = createFlueUiStream({ + submissionId: "submission-1", + clientToolNames: new Set(["addArc"]), + mapClientToolInput: ({ input }) => ({ ...(input as object), weight: 1 }), + write: (chunk) => written.push(chunk), + }); + projector.accept({ + type: "message-started", + conversationId: "conversation-1", + messageId: "message-1", + submissionId: "submission-1", + turnId: "turn-1", + position: position(0), + }); + projector.accept({ + type: "tool-input", + conversationId: "conversation-1", + messageId: "message-1", + toolCallId: "call-1", + toolName: "addArc", + input: { weight: "1" }, + position: position(1), + }); + + expect(written).toContainEqual({ + type: "tool-input-available", + toolCallId: "call-1", + toolName: "addArc", + input: { weight: 1 }, + }); +}); + +test("keeps a pending client tool in the final projected step", () => { + const written = project([ + { + type: "message-started", + conversationId: "conversation-1", + messageId: "assistant-tool-call", + submissionId: "submission-1", + turnId: "turn-tool-call", + position: position(0), + }, + { + type: "tool-input", + conversationId: "conversation-1", + messageId: "assistant-tool-call", + toolCallId: "call-1", + toolName: "readPetrinautDoc", + input: { doc: "ai-assistant" }, + position: position(1), + }, + { + type: "message-completed", + conversationId: "conversation-1", + messageId: "assistant-tool-call", + position: position(2), + }, + { + type: "message-started", + conversationId: "conversation-1", + messageId: "assistant-waiting", + submissionId: "submission-1", + turnId: "turn-waiting", + position: position(3), + }, + { + type: "message-delta", + conversationId: "conversation-1", + messageId: "assistant-waiting", + kind: "text", + delta: "Waiting for the browser.", + position: position(4), + }, + { + type: "message-completed", + conversationId: "conversation-1", + messageId: "assistant-waiting", + position: position(5), + }, + { + type: "submission-settled", + conversationId: "conversation-1", + submissionId: "submission-1", + outcome: "completed", + position: position(6), + }, + ]); + + expect(written).toEqual([ + { type: "start", messageId: "assistant-tool-call" }, + { type: "start-step" }, + { + type: "tool-input-available", + toolCallId: "call-1", + toolName: "readPetrinautDoc", + input: { doc: "ai-assistant" }, + }, + { type: "finish-step" }, + { type: "finish", finishReason: "tool-calls" }, + ]); +}); + +test.each([ + { + error: new Error("Elicitor failed.", { + cause: "The requested field is required.", + }), + expected: "Elicitor failed.\nCaused by: The requested field is required.", + shape: "Error with cause", + }, + { + error: "The elicitor rejected the answer.", + expected: "The elicitor rejected the answer.", + shape: "string", + }, + { + error: { field: "answer", reason: "Required" }, + expected: '{"field":"answer","reason":"Required"}', + shape: "plain object", + }, + { + error: 503, + expected: "The chat turn failed.", + shape: "unsupported value", + }, + { + error: "", + expected: "The chat turn failed.", + shape: "empty string", + }, +])("preserves a failed submission's $shape error", ({ error, expected }) => { + const written = project([ + { + type: "submission-settled", + conversationId: "conversation-1", + submissionId: "submission-1", + outcome: "failed", + error, + position: position(0), + }, + ]); + + expect(written).toEqual([{ type: "error", errorText: expected }]); + expect(written).not.toContainEqual({ + type: "error", + errorText: "[object Object]", + }); +}); + +test("bounds cyclic failed-submission objects", () => { + const cyclicError: Record = { reason: "Recursive failure" }; + cyclicError.self = cyclicError; + cyclicError.payload = "x".repeat(20_000); + + const written = project([ + { + type: "submission-settled", + conversationId: "conversation-1", + submissionId: "submission-1", + outcome: "failed", + error: cyclicError, + position: position(0), + }, + ]); + + const failure = written.find((chunk) => chunk.type === "error"); + expect(failure?.errorText).toContain('"self":"[Circular]"'); + expect(failure?.errorText.length).toBeLessThanOrEqual(10_000); +}); diff --git a/libs/@hashintel/brunch-agent/packages/transport-aisdk/vite.config.ts b/libs/@hashintel/brunch-agent/packages/transport-aisdk/vite.config.ts index a23d137f9ac..843fd00f762 100644 --- a/libs/@hashintel/brunch-agent/packages/transport-aisdk/vite.config.ts +++ b/libs/@hashintel/brunch-agent/packages/transport-aisdk/vite.config.ts @@ -15,7 +15,7 @@ export default defineConfig({ formats: ["es"], }, rolldownOptions: { - external: ["ai", "valibot"], + external: ["@flue/sdk", "ai"], }, sourcemap: true, }, diff --git a/libs/@hashintel/petrinaut-core/src/ai.test.ts b/libs/@hashintel/petrinaut-core/src/ai.test.ts index 26f38c743e1..06f9ac185f0 100644 --- a/libs/@hashintel/petrinaut-core/src/ai.test.ts +++ b/libs/@hashintel/petrinaut-core/src/ai.test.ts @@ -5,6 +5,7 @@ import { aiCommandActionInputSchemas, createPetrinautAiWritableCallbacks, getLatestNetDefinitionToolName, + normalizePetrinautAiToolInput, petrinautAiPrompt, petrinautAiToolInputSchemas, petrinautAiTools, @@ -46,6 +47,17 @@ describe("Petrinaut AI core exports", () => { expect(petrinautAiTools).toHaveProperty("applyAutoLayout"); }); + test("normalizes an addArc weight serialized as text", () => { + expect( + normalizePetrinautAiToolInput("addArc", { + transitionId: "transition", + arcDirection: "input", + weight: "1", + type: "standard", + }), + ).toMatchObject({ weight: 1 }); + }); + test("latest net definition tool documents extension settings", () => { expect( petrinautAiTools[getLatestNetDefinitionToolName].description, diff --git a/libs/@hashintel/petrinaut-core/src/ai.ts b/libs/@hashintel/petrinaut-core/src/ai.ts index 2e3f1bc5397..686ebbaf6b5 100644 --- a/libs/@hashintel/petrinaut-core/src/ai.ts +++ b/libs/@hashintel/petrinaut-core/src/ai.ts @@ -213,6 +213,27 @@ export type PetrinautAiToolInput = z.input< (typeof petrinautAiTools)[Name]["inputSchema"] >; +const isRecord = (value: unknown): value is Record => + typeof value === "object" && value !== null; + +/** + * Normalize the narrow structured values that text-oriented providers may + * serialize before applying the canonical Petrinaut tool schema. + */ +export const normalizePetrinautAiToolInput = ( + toolName: PetrinautAiToolName, + input: unknown, +): unknown => { + if (toolName !== "addArc" || !isRecord(input)) return input; + let normalized = input; + + if (typeof normalized.weight === "string") { + const weight = Number(normalized.weight); + if (Number.isFinite(weight)) normalized = { ...normalized, weight }; + } + return normalized; +}; + /** * Writable tool callbacks exposed to the AI: every mutation, plus the subset * of commands registered in {@link aiCommandActionInputSchemas}. Read-only diff --git a/libs/@hashintel/petrinaut/docs/ai-assistant.md b/libs/@hashintel/petrinaut/docs/ai-assistant.md index 4d4d3828282..a7209260ae4 100644 --- a/libs/@hashintel/petrinaut/docs/ai-assistant.md +++ b/libs/@hashintel/petrinaut/docs/ai-assistant.md @@ -16,31 +16,41 @@ The assistant panel only renders in **Edit** mode. Switching to **Simulate** mod While a response is streaming you can: - Watch the model's text and reasoning appear live. The **Reasoning** block is collapsible; while it is streaming, it auto-opens, shows a shimmer effect, and (once attached timing information arrives) an elapsed timer. -- Press **Stop AI response** (the send button turns into a stop icon) to halt the current response. +- Press **Stop AI response** (the send button turns into a stop icon) to halt the current response. A host with durable conversation execution can record that stop before Petrinaut cancels its local stream; without that host capability, Stop is local cancellation only. A Stop pressed while the assistant is reading or editing the net also withholds browser tools that have not started and the follow-up reply that would otherwise start automatically. Already-applied changes are not rolled back. - Type your next message in the composer -- it is queued for after the current response ends. -The application embedding Petrinaut may place an additional control beside the message box. For -example, a host can offer another way to enter finalized text. Text submitted by that control -behaves like text sent with the keyboard: it joins the same conversation and, when an inline -question is waiting for an answer, completes that question rather than starting an unrelated -message. A host can explicitly submit a separate message instead when the text is a correction or -other follow-up that must not answer the pending question. -If the host offers voice input, a finalized spoken turn is held while an existing response -finishes and is submitted when the conversation is ready. +The application embedding Petrinaut may place an additional control beside the message box. For example, a host can offer another way to enter finalized text. Text submitted by that control behaves like text sent with the keyboard: it joins the same conversation and, when an inline question is waiting for an answer, completes that question rather than starting an unrelated message. A host can explicitly submit a separate message instead when the text is a correction or other follow-up that must not answer the pending question. +If the host offers voice input, only a finalized transcript captured while Voice owns the input turn can be submitted. Voice waits while an existing response finishes or yields through the host's handoff control. -If an assistant request fails, Petrinaut shows the error in a brief toast rather than adding it to -the conversation. Retry from the composer when the assistant is ready. +If an assistant request fails, Petrinaut shows the complete error in a persistent toast rather than adding it to the conversation. Long errors wrap, diagnostic details can be copied, and the toast stays open until you close it. Retry from the composer when the assistant is ready. + +Hosts may provide canonical conversation rehydration. In that case, reopening the same assistant shows its settled and stopped turns without resubmitting a message or replaying Voice audio. Voice markers attached to client-tool results survive that history. A direct spoken user message remains in the transcript after reopening, but its **Voice** chip may not be restored by the current Brunch host. Durably aborted assistant entries retain their **Response stopped** label even after later completed replies. If Brunch had already completed a tool-call step when Stop withheld its browser follow-up, that local decision has no durable cancellation record: reopening can recover the tool as pending work. Do not treat that local withholding as a reload-safe cancellation. + +### Prepared local demo fixture + +The local Petrinaut development demo offers a labelled crew-reservation fixture when Brunch is +configured. Opening it restores a test-authored Markdown workpiece, a non-empty final-inspection +net, and their canonical Brunch conversation. The status panel distinguishes prepared text from +model-produced revisions and states the fixture's non-claims. + +The document is mirrored to browser local storage automatically; there is no separate Save action. +Wait for the status panel to report a settled bundle before reopening the same fixture in another +tab. A refused status leaves the previous coherent bundle selected and names the failed history, +workpiece, mutation-correlation, or document check instead of claiming that partial state settled. When the Brunch voice preview is enabled and available, an empty composer shows a waveform action titled **Start voice mode**. Typing non-whitespace text replaces it with **Send**. The same dynamic action appears in the first-run prompt and the assistant panel; if voice is unavailable, the empty composer retains a disabled **Send** action. Starting Voice mode keeps the transcript in place and -opens the existing one-time disclosure above the composer. Review that OpenAI processes live -audio and speaks the interviewer's words while Petrinaut keeps finalized answers in the conversation -rather than the audio. You can check your microphone before confirming that you understand and -selecting **Start voice mode**. Petrinaut remembers that acknowledgement in this browser for the -current disclosure version, so later uses of **Start voice mode** start directly. If browser storage -is unavailable or the disclosure changes, Petrinaut asks again. +opens the existing one-time disclosure. Voice selected from the first-run prompt starts compact: the +disclosure and microphone check appear in a card immediately above a **Voice setup** dock, while the +AI header, transcript, and composer stay hidden. Select **Expand voice setup** to restore the full +panel. Voice started from the composer keeps that full panel visible. Review that OpenAI processes +live audio and speaks the interviewer's words while Petrinaut keeps finalized answers in the +conversation rather than the audio. You can check your microphone before confirming that you +understand and selecting **Start voice mode**. Petrinaut remembers that acknowledgement in this +browser for the current disclosure version, so later uses of **Start voice mode** start directly. If +browser storage is unavailable or the disclosure changes, Petrinaut asks again. While a session runs, the composer is replaced by a low-profile Voice dock at the foot of the panel: a ribbon that fades out at both ends and one short state -- **Connecting**, **Listening**, @@ -51,36 +61,42 @@ flicker above the line. While the assistant speaks the ribbon takes on a restrai motion instead, colour crossfading as the turn changes hands, so which side holds it is readable at a glance. It flattens to near a line whenever nobody holds the turn. -The conversation itself stays still. Spoken turns are written to it as they happen, because that is -what runs the tools that edit the net, but they stay hidden until the session ends rather than -scrolling the transcript mid-sentence. **Show transcription in chat** lets them through as they land -instead; turning it off holds them back again, and it starts off with each session. Two things are -never held back either way: anything you typed, and any inline question waiting for your answer. When -the session ends, the held turns appear together under a **Voice session · N turns** divider. Only -finalized answers and canonical Brunch text become chat history; provisional transcription and -Realtime audio are ephemeral. Finalized spoken user messages carry a small **Voice** chip in front of -the words themselves, and the exact inline answer completed by speech carries the same chip, so Voice -provenance remains visible without duplicating an answer. - -The microphone stays on while the interviewer speaks, so speaking naturally interrupts the audio -and starts listening to you; you do not need to select an interrupt action. Semantic voice detection -finishes each answer automatically after a natural pause and is tuned to allow longer thinking -pauses. There is no required done-speaking action. - -Every session control lives in the dock: **Show transcription in chat** on the left, and on the right -**Mute microphone** (**Unmute microphone** once muted) beside **End voice mode**. Muting stops -sending audio without ending the turn, so the assistant plays out whatever it is saying and unmuting -drops you straight back into the conversation. **Resume voice mode** replaces the microphone action -while a session is paused, and **Reconnect voice mode** replaces it after a failure. Nothing is added -to the canvas toolbar. Sending non-empty typed text from the +Spoken turns appear in the conversation as soon as their finalized text arrives, so the transcript +stays current while the session runs and tools that edit the net remain visible. Select **Collapse +voice session** to reduce the panel to the Voice dock alone; this hides the AI header, transcript, and +host Voice region without ending the session. Select **Expand voice session** to restore them. Ending +Voice while collapsed also closes the AI panel; ending Voice while expanded returns to the text +composer. Only finalized answers and canonical Brunch text become chat history; provisional +transcription and Realtime audio are ephemeral. Finalized spoken user messages carry a small +**Voice** chip in front of the words themselves, and the exact inline answer completed by speech +carries the same chip, so Voice provenance remains visible without duplicating an answer while the +session is mounted. + +Voice is half-duplex. The microphone is closed while the interviewer speaks or the assistant is +working, which prevents playback from becoming a false answer. Select **Your turn** to interrupt: +the dock shows the handoff as thinking while it clears pending audio and waits for the provider to +finish cancellation, then opens a fresh input turn. Audio captured before that completed handoff is +discarded. Semantic voice detection finishes your answer automatically after a natural pause, so +there is no required done-speaking action. Duplicate, empty, failed, or unavailable transcripts are +not submitted; the dock asks you to try again. An overlong answer instead asks for a shorter response. +Provisional words remain display-only until the provider completes their transcript. + +Every session control lives in the dock: **Collapse voice session** / **Expand voice session** and +**Voice playback options** on the left, and the available handoff, microphone, recovery, and end +actions on the right. +**Read full response** becomes available after the matching response and speech have both finished +and replays every exact retained canonical segment in order. **Repeat question** uses the same +availability gates and replays only exact question text explicitly marked by Brunch. It stays +disabled when that marker is missing or does not match finalized assistant text rather than +guessing that the final segment is a question. +Playback stays unavailable during active capture, submission, cancellation, pause, and errors. **Mute microphone** becomes +**Unmute microphone** once muted, and your latest choice applies when a handoff settles. **Resume voice mode** +replaces the microphone action while a session is paused, and **Reconnect voice mode** replaces it +after a failure. Nothing is added to the canvas toolbar. Sending non-empty typed text from the composer or first-run prompt ends Voice mode before it sends the message once through the same conversation; repeated send actions are ignored while that short handoff completes. -The interviewer uses a warm, calm, curious, and professionally neutral voice and treats you as the -authority on your system. Brunch still chooses every question and interview decision; OpenAI only -delivers its words. The question and finalized response shown in the Petrinaut conversation are -authoritative. Spoken audio is generated from that Brunch text but may not be verbatim. Interrupting -audio does not undo the visible response or change the interview's saved history. +The interviewer uses a warm, calm, curious, and professionally neutral voice and treats you as the authority on your system. Brunch still chooses every question and interview decision; OpenAI only transcribes your completed input and delivers Brunch's words. The question and finalized response shown in the Petrinaut conversation are authoritative. The speech request receives that exact Brunch text in part order; synthesized audio is generated from it but is not a verbatim recording. Interrupting audio does not undo the visible response or change the interview's saved history. Closing the AI panel pauses microphone capture and active speech, then hides the dock until you reopen the panel. The same mounted session stays paused; choose **Resume voice mode** when you are @@ -88,8 +104,8 @@ ready. **Clear AI chat** is unavailable while a Voice session is active. If voice cannot continue, the status reads **Voice interrupted** and the actionable error arrives as -a toast that names the microphone, connection, or Voice failure in one sentence, followed by any -diagnostic reference in parentheses. **Reconnect voice mode** replaces the microphone action until +a persistent toast that names the microphone, connection, or Voice failure in one sentence, followed +by any diagnostic reference in parentheses. **Reconnect voice mode** replaces the microphone action until the session recovers. For microphone permission or device errors, allow access or connect/select a microphone before reconnecting. For an interrupted request, network error, or timeout, check the connection and reconnect. If the preview is unavailable, continue with the text composer. An invalid @@ -98,13 +114,11 @@ diagnostic record do not contain your transcript or the response being spoken. I failures use a content-free `interview-correlation`, `interview-response`, or `interview-submission` code so an operator can distinguish them without receiving your answer. -When no interview is active, **Clear AI chat** via the delete button in the top right of the panel -wipes the conversation, stops any in-flight stream, and tells the host app to forget the messages -(if the host persists them). +When no interview is active and the host permits clearing, **Clear AI chat** via the delete button in the top right of the panel wipes the local conversation, stops any in-flight stream, and tells the host app to forget the messages if it persists them. Hosts with canonical history may disable this control. The Brunch panel disables it because clearing only the browser view would not delete Flue history and the conversation would return on rehydration. ## What the assistant can do -The assistant has tools for inspecting and modifying the current net. You'll see one card per tool call inline in the conversation: +The assistant has tools for inspecting and modifying the current net. You'll see one card per tool call inline in the conversation. A failed tool card leads with its complete error instead of hiding it behind a hover tooltip: - **Read tools** (neutral, expandable) –– for checking the current net state and active Petrinaut extensions at any point, for compilation errors, and for reading the user guide. - **Mutation tools** (green for additions/updates, red for deletions) -- "Added place X", "Updated transition Y", "Removed metric Z", and so on. Multiple successive mutations group under a collapsible "N changes" header. diff --git a/libs/@hashintel/petrinaut/src/main.ts b/libs/@hashintel/petrinaut/src/main.ts index 97bac2f2784..f45791cb13d 100644 --- a/libs/@hashintel/petrinaut/src/main.ts +++ b/libs/@hashintel/petrinaut/src/main.ts @@ -98,5 +98,6 @@ export { Petrinaut } from "./ui/petrinaut"; export type { PetrinautAiAssistant, PetrinautAiChatTransport, + PetrinautAiStopResult, PetrinautProps, } from "./ui/petrinaut"; diff --git a/libs/@hashintel/petrinaut/src/panda-preset.ts b/libs/@hashintel/petrinaut/src/panda-preset.ts index 2cdc120abf8..7d4ab7bd23c 100644 --- a/libs/@hashintel/petrinaut/src/panda-preset.ts +++ b/libs/@hashintel/petrinaut/src/panda-preset.ts @@ -122,10 +122,6 @@ export const petrinautPandaPreset = { from: { opacity: "1", transform: "translateX(0)" }, to: { opacity: "0", transform: "translateX(100px)" }, }, - petrinautVoiceReveal: { - from: { opacity: "0", transform: "translateY(10px)" }, - to: { opacity: "1", transform: "translateY(0)" }, - }, petrinautVoiceSwap: { from: { opacity: "0" }, to: { opacity: "1" }, diff --git a/libs/@hashintel/petrinaut/src/react/notifications/context.ts b/libs/@hashintel/petrinaut/src/react/notifications/context.ts index 9911f709022..5f508982ae4 100644 --- a/libs/@hashintel/petrinaut/src/react/notifications/context.ts +++ b/libs/@hashintel/petrinaut/src/react/notifications/context.ts @@ -3,6 +3,7 @@ import { createContext } from "react"; export type NotificationTone = "error" | "neutral" | "success"; export type AddNotificationInput = { + detail?: string; message: string; tone?: NotificationTone; durationMs?: number; diff --git a/libs/@hashintel/petrinaut/src/react/notifications/provider.test.tsx b/libs/@hashintel/petrinaut/src/react/notifications/provider.test.tsx new file mode 100644 index 00000000000..1dda6521daa --- /dev/null +++ b/libs/@hashintel/petrinaut/src/react/notifications/provider.test.tsx @@ -0,0 +1,76 @@ +/** + * @vitest-environment jsdom + */ +import { + cleanup, + fireEvent, + render, + screen, + waitFor, +} from "@testing-library/react"; +import { use } from "react"; +import { afterEach, expect, test, vi } from "vitest"; + +import { NotificationsContext } from "./context"; +import { NotificationsProvider } from "./provider"; +import { notificationsToaster } from "./toaster"; + +afterEach(() => { + cleanup(); + vi.restoreAllMocks(); +}); + +test("keeps error notifications open while preserving the default for other tones", async () => { + const createToast = vi.spyOn(notificationsToaster, "create"); + const Trigger = () => { + const { addNotification } = use(NotificationsContext); + + return ( + <> + + + + ); + }; + + render( + + + , + ); + + fireEvent.click(screen.getByRole("button", { name: "Error" })); + fireEvent.click(screen.getByRole("button", { name: "Success" })); + + await waitFor(() => expect(createToast).toHaveBeenCalledTimes(2)); + expect(createToast).toHaveBeenNthCalledWith(1, { + description: "The complete elicitor failure.", + duration: Infinity, + id: "notification-0", + title: "AI assistant error", + type: "error", + }); + expect(createToast).toHaveBeenNthCalledWith(2, { + description: undefined, + duration: 3000, + id: "notification-1", + title: "Saved", + type: "success", + }); +}); diff --git a/libs/@hashintel/petrinaut/src/react/notifications/provider.tsx b/libs/@hashintel/petrinaut/src/react/notifications/provider.tsx index f6d39467b8b..945584fe104 100644 --- a/libs/@hashintel/petrinaut/src/react/notifications/provider.tsx +++ b/libs/@hashintel/petrinaut/src/react/notifications/provider.tsx @@ -16,22 +16,28 @@ export const NotificationsProvider = ({ }: { children: ReactNode; }) => { - function dismissNotification(id: string) { + const dismissNotification = (id: string) => { queueMicrotask(() => { notificationsToaster.dismiss(id); }); - } + }; - function addNotification({ + const addNotification = ({ + detail, durationMs, message, tone = "success", - }: AddNotificationInput) { - const id = `notification-${nextNotificationId++}`; - const effectiveDurationMs = durationMs ?? DEFAULT_NOTIFICATION_DURATION_MS; + }: AddNotificationInput) => { + const id = `notification-${nextNotificationId}`; + nextNotificationId += 1; + const effectiveDurationMs = + tone === "error" + ? Infinity + : (durationMs ?? DEFAULT_NOTIFICATION_DURATION_MS); queueMicrotask(() => { notificationsToaster.create({ + description: detail, duration: effectiveDurationMs, id, title: message, @@ -40,7 +46,7 @@ export const NotificationsProvider = ({ }); return id; - } + }; useEffect(() => { return () => { diff --git a/libs/@hashintel/petrinaut/src/react/notifications/toaster.tsx b/libs/@hashintel/petrinaut/src/react/notifications/toaster.tsx index bc26dc8403b..fd2261b2033 100644 --- a/libs/@hashintel/petrinaut/src/react/notifications/toaster.tsx +++ b/libs/@hashintel/petrinaut/src/react/notifications/toaster.tsx @@ -5,7 +5,7 @@ import { createToaster, } from "@ark-ui/react/toast"; -import { usePortalContainerRef } from "@hashintel/ds-components"; +import { Button, usePortalContainerRef } from "@hashintel/ds-components"; import { css } from "@hashintel/ds-helpers/css"; export const notificationsToaster = createToaster({ @@ -24,10 +24,11 @@ const toastRootStyle = css({ transition: "[translate 300ms, scale 300ms, opacity 300ms, box-shadow 300ms]", transitionTimingFunction: "[cubic-bezier(0.21, 1.02, 0.73, 1)]", display: "flex", - alignItems: "center", + alignItems: "flex-start", + gap: "2", minHeight: "[26px]", width: "[max-content]", - maxWidth: "[320px]", + maxWidth: "[min(480px, calc(100vw - 32px))]", borderRadius: "lg", boxShadow: "[0 8px 24px rgba(0, 0, 0, 0.24)]", paddingX: "4", @@ -44,23 +45,93 @@ const toastRootStyle = css({ }, }); +const toastContentStyle = css({ + display: "flex", + flex: "[1]", + minWidth: "[0]", + flexDirection: "column", + gap: "1", +}); + const toastTitleStyle = css({ overflow: "hidden", - textOverflow: "ellipsis", - whiteSpace: "nowrap", + overflowWrap: "anywhere", + lineClamp: "4", fontSize: "xs", fontWeight: "medium", lineHeight: "[14px]", }); +const toastDescriptionStyle = css({ + maxHeight: "[240px]", + overflow: "auto", + overflowWrap: "anywhere", + whiteSpace: "pre-wrap", + fontSize: "xs", + lineHeight: "[18px]", + userSelect: "text", +}); + +const toastActionsStyle = css({ + display: "flex", + flexShrink: "[0]", + gap: "1", +}); + +const toastActionStyle = css({ + color: "neutral.s00", + _hover: { + color: "neutral.s00", + }, +}); + export const NotificationsToaster = () => ( - {(toast) => ( - - {toast.title} - - )} + {(toast) => { + const detail = + typeof toast.description === "string" ? toast.description : undefined; + + return ( + +
+ + {toast.title} + + {detail && ( + + {detail} + + )} +
+
+ {detail && ( +
+ + ); + }} ); diff --git a/libs/@hashintel/petrinaut/src/react/voice-session/store.ts b/libs/@hashintel/petrinaut/src/react/voice-session/store.ts index bcdc4e0ee48..73e502c20bb 100644 --- a/libs/@hashintel/petrinaut/src/react/voice-session/store.ts +++ b/libs/@hashintel/petrinaut/src/react/voice-session/store.ts @@ -7,9 +7,12 @@ import type { export type VoiceSessionActions = { end: () => void; pause: () => void; + readFullResponse?: () => void; reconnect: () => void; + repeatQuestion?: () => void; resume: () => void; setMicrophoneMuted: (muted: boolean) => void; + takeTurn?: () => Promise | void; }; export type VoiceSessionSnapshot = { diff --git a/libs/@hashintel/petrinaut/src/react/voice-session/types.ts b/libs/@hashintel/petrinaut/src/react/voice-session/types.ts index bd1a26f425e..b72bee75f8c 100644 --- a/libs/@hashintel/petrinaut/src/react/voice-session/types.ts +++ b/libs/@hashintel/petrinaut/src/react/voice-session/types.ts @@ -16,10 +16,18 @@ export type PetrinautAiVoiceSessionPhase = * effect: it changes at microphone-sampling rate. */ export type PetrinautAiVoiceSessionState = { + /** Whether the current canonical assistant response is safe to replay. */ + canReadFullResponse?: boolean; + /** Whether the final segment of the canonical response is safe to repeat. */ + canRepeatQuestion?: boolean; + /** Whether the user can cancel Voice output and start their turn. */ + canTakeTurn?: boolean; errorMessage: string | null; /** Whether microphone capture is muted independently of whose turn it is. */ microphoneMuted: boolean; /** Normalized 0–1 input level driving the listening indicator. */ microphoneLevel: number; + /** Recoverable feedback about an utterance which was not submitted. */ + notice?: string | null; phase: PetrinautAiVoiceSessionPhase; }; diff --git a/libs/@hashintel/petrinaut/src/react/voice-session/use-voice-session.ts b/libs/@hashintel/petrinaut/src/react/voice-session/use-voice-session.ts index a95671ce61d..3f88e964621 100644 --- a/libs/@hashintel/petrinaut/src/react/voice-session/use-voice-session.ts +++ b/libs/@hashintel/petrinaut/src/react/voice-session/use-voice-session.ts @@ -62,3 +62,43 @@ export const useVoiceSessionActions = (): VoiceSessionActions | null => { () => null, ); }; + +export const useVoiceSessionCanReadFullResponse = (): boolean => { + const store = use(VoiceSessionContext); + + return useSyncExternalStore( + store.subscribe, + () => store.getSnapshot().state?.canReadFullResponse ?? false, + () => false, + ); +}; + +export const useVoiceSessionCanRepeatQuestion = (): boolean => { + const store = use(VoiceSessionContext); + + return useSyncExternalStore( + store.subscribe, + () => store.getSnapshot().state?.canRepeatQuestion ?? false, + () => false, + ); +}; + +export const useVoiceSessionCanTakeTurn = (): boolean => { + const store = use(VoiceSessionContext); + + return useSyncExternalStore( + store.subscribe, + () => store.getSnapshot().state?.canTakeTurn ?? false, + () => false, + ); +}; + +export const useVoiceSessionNotice = (): string | null => { + const store = use(VoiceSessionContext); + + return useSyncExternalStore( + store.subscribe, + () => store.getSnapshot().state?.notice ?? null, + () => null, + ); +}; diff --git a/libs/@hashintel/petrinaut/src/ui/index.ts b/libs/@hashintel/petrinaut/src/ui/index.ts index 911f54e83de..7c30734bff9 100644 --- a/libs/@hashintel/petrinaut/src/ui/index.ts +++ b/libs/@hashintel/petrinaut/src/ui/index.ts @@ -17,6 +17,7 @@ export type { export type { PetrinautAiAssistant, PetrinautAiChatTransport, + PetrinautAiStopResult, PetrinautProps, } from "./petrinaut"; export type { diff --git a/libs/@hashintel/petrinaut/src/ui/petrinaut.tsx b/libs/@hashintel/petrinaut/src/ui/petrinaut.tsx index cf99c1bbb1d..35857da9b77 100644 --- a/libs/@hashintel/petrinaut/src/ui/petrinaut.tsx +++ b/libs/@hashintel/petrinaut/src/ui/petrinaut.tsx @@ -48,7 +48,11 @@ import type { export type PetrinautAiChatTransport = PetrinautAiTransport; +export type PetrinautAiStopResult = "already-settled" | "stop-requested"; + export type PetrinautAiAssistant = { + /** Whether the panel may clear this conversation. Defaults to true. */ + canClearMessages?: boolean; /** Optional host-owned identity; `useChat` generates one when omitted. */ conversationId?: string; /** Host-owned dynamic tools that render inline in the AI conversation. */ @@ -56,6 +60,11 @@ export type PetrinautAiAssistant = { messages?: PetrinautAiMessage[]; onClearMessages?: () => void; onMessages?: (messages: PetrinautAiMessage[]) => void; + /** + * Requests a host-owned durable stop. When omitted, Stop only cancels the + * panel's local response stream. + */ + requestStop?: () => Promise; /** Render a host-owned control inside the assistant composer. */ renderComposerControl?: PetrinautAiComposerControl; /** Render one persistent, provider-neutral Voice mode. */ diff --git a/libs/@hashintel/petrinaut/src/ui/types/ai-assistant-composer-control.ts b/libs/@hashintel/petrinaut/src/ui/types/ai-assistant-composer-control.ts index 5369be4c639..0f7f8da56f0 100644 --- a/libs/@hashintel/petrinaut/src/ui/types/ai-assistant-composer-control.ts +++ b/libs/@hashintel/petrinaut/src/ui/types/ai-assistant-composer-control.ts @@ -10,7 +10,11 @@ export type { PetrinautAiVoiceSessionPhase, PetrinautAiVoiceSessionState }; /** The active way a user is providing input to the AI assistant. */ export type PetrinautAiInputMode = "text" | "voice"; -/** Current lifecycle state of Petrinaut's AI SDK conversation. */ +/** + * Current lifecycle state of Petrinaut's conversation. Stays busy across the + * automatic follow-up to a step that ended in client tool calls, so hosts + * never read the SDK's momentary `ready` between them as the end of a turn. + */ export type PetrinautAiComposerStatus = | "submitted" | "streaming" @@ -37,6 +41,8 @@ export type PetrinautAiComposerControlContext = { conversationId: string; messages: PetrinautAiMessage[]; status: PetrinautAiComposerStatus; + /** Logical response stopped, including a withheld follow-up; not a Flue settlement claim. */ + stopped?: boolean; /** Call from an event handler or effect, never while rendering. */ stop: () => Promise; /** Call from an event handler or effect, never while rendering. */ @@ -61,12 +67,18 @@ export type PetrinautAiVoiceModeControls = { reconnect: () => void; /** Resumes microphone capture after `pause`. */ resume: () => void; + /** Replays the exact retained canonical assistant response when available. */ + readFullResponse?: () => void; + /** Replays only the exact question selected by the host's canonical marker. */ + repeatQuestion?: () => void; /** * Stops or restarts microphone capture while the session keeps running, so * the assistant carries on speaking. Unlike `pause`, which suspends the * whole session when Petrinaut closes the panel. */ setMicrophoneMuted: (muted: boolean) => void; + /** Cancels Voice output and hands the live microphone turn to the user. */ + takeTurn?: () => Promise | void; }; /** Stable controls and conversation state supplied to a host-owned Voice mode. */ @@ -99,7 +111,14 @@ export type PetrinautAiVoiceModeContext = PetrinautAiComposerControlContext & { params: Omit< Parameters[0], "source" - >, + > & { + /** + * Withdraws a retained turn that has not been submitted yet, for example + * when the Voice session ends while chat is still busy. A turn already + * handed to the composer is not cancelled. + */ + readonly signal?: AbortSignal; + }, ) => Promise; }; diff --git a/libs/@hashintel/petrinaut/src/ui/views/Editor/components/voice-session-labels.ts b/libs/@hashintel/petrinaut/src/ui/views/Editor/components/voice-session-labels.ts index eaf5dabb078..0e2f843924b 100644 --- a/libs/@hashintel/petrinaut/src/ui/views/Editor/components/voice-session-labels.ts +++ b/libs/@hashintel/petrinaut/src/ui/views/Editor/components/voice-session-labels.ts @@ -26,10 +26,23 @@ export const voiceSessionStatusLabel = ( }; export const voiceSessionActionLabels = { + collapse: "Collapse voice session", end: "End voice mode", + expand: "Expand voice session", mute: "Mute microphone", pause: "Pause voice mode", + playbackOptions: "Voice playback options", + readFullResponse: "Read full response", reconnect: "Reconnect voice mode", + repeatQuestion: "Repeat question", resume: "Resume voice mode", + takeTurn: "Your turn", unmute: "Unmute microphone", } as const; + +export const voiceSetupLabels = { + collapse: "Collapse voice setup", + expand: "Expand voice setup", + region: "Voice setup", + status: "Voice setup", +} as const; diff --git a/libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.test.tsx b/libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.test.tsx index 4c39bb19062..a680b181f08 100644 --- a/libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.test.tsx +++ b/libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.test.tsx @@ -7,15 +7,17 @@ import { fireEvent, render, screen, + within, waitFor, } from "@testing-library/react"; -import { useEffect } from "react"; -import { afterEach, describe, expect, test, vi } from "vitest"; +import { StrictMode, useEffect } from "react"; +import { afterEach, beforeAll, describe, expect, test, vi } from "vitest"; import { DEFAULT_PETRINAUT_EXTENSIONS, createJsonDocHandle, createPetrinaut, + getLatestNetDefinitionToolName, type SDCPN, } from "@hashintel/petrinaut-core"; @@ -31,7 +33,11 @@ import { type SDCPNContextValue, } from "../../../../react/state/sdcpn-context"; import { definePetrinautAiInteractiveTool } from "../../../types/ai-interactive-tool"; -import { addMappedToolOutput, AiAssistantPanel } from "./ai-assistant-panel"; +import { + addMappedToolOutput, + AiAssistantPanel, + safelyAddToolOutput, +} from "./ai-assistant-panel"; import type { PetrinautAiAssistant } from "../../../petrinaut"; import type { @@ -48,6 +54,18 @@ import type { UIMessageChunk } from "ai"; let voiceModeMounts = 0; let voiceModeUnmounts = 0; +beforeAll(() => { + vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockReturnValue(null); + vi.stubGlobal( + "ResizeObserver", + class { + public disconnect() {} + public observe() {} + public unobserve() {} + }, + ); +}); + const emptySDCPN: SDCPN = { places: [], transitions: [], @@ -164,6 +182,7 @@ const renderTestPanel = ({ initialMessage, onInitialInteractionModeConsumed, petriNetDefinition = emptySDCPN, + strictMode = false, }: { aiAssistant: PetrinautAiAssistant; editorContext?: EditorContextValue; @@ -171,6 +190,7 @@ const renderTestPanel = ({ initialMessage?: string; onInitialInteractionModeConsumed?: () => void; petriNetDefinition?: SDCPN; + strictMode?: boolean; }) => { const handle = createJsonDocHandle({ id: "ai-assistant-panel-test", @@ -214,10 +234,14 @@ const renderTestPanel = ({ ); - const rendered = render(renderPanel(aiAssistant, editorContext)); + const rendered = render( + renderPanel(aiAssistant, editorContext), + strictMode ? { wrapper: StrictMode } : undefined, + ); return { ...rendered, + instance, rerenderPanel: ( nextAiAssistant: PetrinautAiAssistant, nextEditorContext = editorContext, @@ -245,164 +269,486 @@ afterEach(() => { }); describe("AiAssistantPanel composer submissions", () => { - test("invalidates registered Voice controls before typed submit while active publication is pending", async () => { - const events: string[] = []; - let finishVoiceEnd: (() => void) | undefined; - const endVoice = vi.fn(() => { - events.push("end"); - return new Promise((resolve) => { - finishVoiceEnd = resolve; - }); - }); - const sendMessages = vi.fn(() => { - events.push("submit"); - return Promise.resolve( - streamChunks( - textChunks("pending-active-handoff", "Pending handoff accepted"), - ), - ); - }); - const VoiceMode = ({ - context, - }: { - context: PetrinautAiVoiceModeContext; - }) => { - const { registerVoiceModeControls } = context; - - useEffect( - () => - registerVoiceModeControls({ - end: endVoice, - pause: vi.fn(), - reconnect: vi.fn(), - resume: vi.fn(), - setMicrophoneMuted: vi.fn(), - }), - [registerVoiceModeControls], - ); - - return ( - - ); + test("disables Clear when the host owns canonical conversation history", () => { + const transport: PetrinautAiTransport = { + reconnectToStream: () => Promise.resolve(null), + sendMessages: async () => new ReadableStream(), }; renderTestPanel({ aiAssistant: { - renderVoiceMode: (context) => , - transport: { - reconnectToStream: () => Promise.resolve(null), - sendMessages, - }, + canClearMessages: false, + messages: [ + { + id: "assistant-canonical", + role: "assistant", + parts: [{ type: "text", text: "Canonical history" }], + }, + ], + transport, }, }); - fireEvent.click( - screen.getByRole("button", { - name: "Select voice before active publication", - }), + expect( + screen.getByRole("button", { + name: "Clear AI chat", + }).disabled, + ).toBe(true); + }); + + test("hydrates asynchronous host messages once for each conversation", async () => { + const sendMessages = vi.fn( + async () => new ReadableStream(), ); - const textarea = screen.getByRole("textbox", { - name: "Message AI assistant", + const transport: PetrinautAiTransport = { + reconnectToStream: () => Promise.resolve(null), + sendMessages, + }; + const { rerenderPanel } = renderTestPanel({ + aiAssistant: { + conversationId: "conversation-1", + transport, + }, }); - fireEvent.change(textarea, { - target: { value: "Typed during activation" }, + + expect(screen.queryByText("Rehydrated first conversation")).toBeNull(); + + rerenderPanel({ + conversationId: "conversation-1", + messages: [ + { + id: "assistant-history-1", + role: "assistant", + parts: [{ type: "text", text: "Rehydrated first conversation" }], + }, + ], + transport, }); - const sendButton = screen.getByRole("button", { name: "Send message" }); - fireEvent.click(sendButton); - fireEvent.click(sendButton); - fireEvent.keyDown(textarea, { key: "Enter" }); - expect(events).toEqual(["end"]); + expect( + await screen.findByText("Rehydrated first conversation"), + ).not.toBeNull(); expect(sendMessages).not.toHaveBeenCalled(); - await act(async () => finishVoiceEnd?.()); - await screen.findByText("Pending handoff accepted"); + rerenderPanel({ + conversationId: "conversation-2", + messages: [ + { + id: "assistant-history-2", + role: "assistant", + parts: [{ type: "text", text: "Rehydrated second conversation" }], + }, + ], + transport, + }); - expect(events).toEqual(["end", "submit"]); - expect(endVoice).toHaveBeenCalledOnce(); - expect(sendMessages).toHaveBeenCalledOnce(); + expect( + await screen.findByText("Rehydrated second conversation"), + ).not.toBeNull(); + expect(screen.queryByText("Rehydrated first conversation")).toBeNull(); + expect(sendMessages).not.toHaveBeenCalled(); }); - test("invalidates active Voice mode before submitting initial CTA text", async () => { - const events: string[] = []; - let finishVoiceEnd: (() => void) | undefined; - const endVoice = vi.fn(() => { - events.push("end"); - return new Promise((resolve) => { - finishVoiceEnd = resolve; - }); - }); - const sendMessages = vi.fn(() => { - events.push("submit"); - return Promise.resolve( - streamChunks(textChunks("cta-handoff", "CTA handoff accepted")), - ); + test("replays StrictMode effects without stranding an initially recovered tool", async () => { + const sendMessages = vi.fn(async () => + streamChunks([ + ...textChunks("reply", "Done."), + { type: "finish", finishReason: "stop" }, + ]), + ); + renderTestPanel({ + strictMode: true, + aiAssistant: { + conversationId: "strict-history", + messages: [ + { + id: "strict-call", + role: "assistant", + parts: [ + { + type: "tool-readPetrinautDoc", + toolCallId: "strict-read", + state: "input-available", + input: { doc: "ai-assistant" }, + }, + ], + }, + ], + transport: { reconnectToStream: async () => null, sendMessages }, + }, }); - const VoiceMode = ({ - context, - }: { - context: PetrinautAiVoiceModeContext; - }) => { - const { - inputMode, - registerVoiceModeControls, - setVoiceActive: publishVoiceActive, - } = context; + await waitFor(() => expect(sendMessages).toHaveBeenCalledOnce()); + }); - useEffect( - () => - registerVoiceModeControls({ - end: endVoice, - pause: vi.fn(), - reconnect: vi.fn(), - resume: vi.fn(), - setMicrophoneMuted: vi.fn(), - }), - [registerVoiceModeControls], - ); - useEffect(() => { - if (inputMode === "voice") { - publishVoiceActive(true); - } - }, [inputMode, publishVoiceActive]); + test("does not carry a stopped browser generation into a different conversation", async () => { + let latest: PetrinautAiComposerControlContext | undefined; + const sendMessages = vi.fn(async () => + streamChunks([ + ...textChunks("reply", "Done."), + { type: "finish", finishReason: "stop" }, + ]), + ); + const config = (conversationId: string): PetrinautAiAssistant => ({ + conversationId, + messages: [ + { + id: `${conversationId}-call`, + role: "assistant", + parts: [ + { + type: "tool-readPetrinautDoc", + toolCallId: `${conversationId}-read`, + state: "input-available", + input: { doc: "ai-assistant" }, + }, + ], + }, + ], + transport: { reconnectToStream: async () => null, sendMessages }, + requestStop: async () => "already-settled", + renderComposerControl: (context) => { + latest = context; + return null; + }, + }); + const { rerenderPanel } = renderTestPanel({ aiAssistant: config("first") }); + await act(async () => { + await latest?.stop(); + }); + await waitFor(() => expect(latest?.stopped).toBe(true)); + expect(sendMessages).not.toHaveBeenCalled(); + rerenderPanel(config("second")); + await waitFor(() => expect(sendMessages).toHaveBeenCalledOnce()); + expect(sendMessages.mock.calls[0]?.[0].chatId).toBe("second"); + }); - return
{`Voice mode ${inputMode}`}
; + test("does not deliver a previous conversation's asynchronous browser result into its replacement", async () => { + let releaseLayout: (() => void) | undefined; + const sendMessages = vi.fn(async () => + streamChunks([ + ...textChunks("reply", "Done."), + { type: "finish", finishReason: "stop" }, + ]), + ); + const transport: PetrinautAiTransport = { + reconnectToStream: async () => null, + sendMessages, }; - const aiAssistant: PetrinautAiAssistant = { - renderVoiceMode: (context) => , - transport: { - reconnectToStream: () => Promise.resolve(null), - sendMessages, + const { instance, rerenderPanel } = renderTestPanel({ + aiAssistant: { + conversationId: "old-layout", + messages: [ + { + id: "layout-call", + role: "assistant", + parts: [ + { + type: "tool-applyAutoLayout", + toolCallId: "old-layout", + state: "input-available", + input: { askUserFirst: false }, + }, + ], + }, + ], + transport, }, - }; - const rendered = renderTestPanel({ - aiAssistant, - initialInteractionMode: "voice", }); - await screen.findByText("Voice mode voice"); + const applyAutoLayout = instance.commands.applyAutoLayout.bind( + instance.commands, + ); + const layout = vi + .spyOn(instance.commands, "applyAutoLayout") + .mockImplementation(async () => { + await new Promise((resolve) => { + releaseLayout = resolve; + }); + return applyAutoLayout(); + }); + await waitFor(() => expect(releaseLayout).toBeDefined()); + rerenderPanel({ + conversationId: "replacement", + messages: [ + { + id: "replacement-history", + role: "assistant", + parts: [{ type: "text", text: "Settled replacement" }], + }, + ], + transport, + }); + await act(async () => { + releaseLayout?.(); + await layout.mock.results[0]?.value; + // Drain the explicit continuation timer following the awaited command. + await new Promise((resolve) => { + setTimeout(resolve, 20); + }); + }); + expect(sendMessages).not.toHaveBeenCalled(); + }); - rendered.rerenderPanelWithInitialRequest( - "text", - "Create the support workflow", + test("executes one automatic tool call recovered from host history", async () => { + const requestMessages: PetrinautAiMessage[][] = []; + const sendMessages = vi.fn( + ({ messages }) => { + requestMessages.push(structuredClone(messages)); + return Promise.resolve( + streamChunks([ + { type: "start-step" }, + { type: "text-start", id: "resumed" }, + { + type: "text-delta", + id: "resumed", + delta: "Live net received.", + }, + { type: "text-end", id: "resumed" }, + ]), + ); + }, ); + const transport: PetrinautAiTransport = { + reconnectToStream: () => Promise.resolve(null), + sendMessages, + }; + const { rerenderPanel } = renderTestPanel({ + aiAssistant: { + conversationId: "conversation-with-pending-tool", + messages: [], + transport, + }, + petriNetDefinition: nonEmptySDCPN, + }); + const pendingMessages: PetrinautAiMessage[] = [ + { + id: "assistant-pending-net-read", + role: "assistant", + parts: [ + { + type: "tool-getLatestNetDefinition", + state: "input-available", + toolCallId: "pending-net-read", + input: {}, + }, + ], + }, + ]; - expect(events).toEqual(["end"]); - expect(sendMessages).not.toHaveBeenCalled(); + rerenderPanel({ + conversationId: "conversation-with-pending-tool", + messages: pendingMessages, + transport, + }); - await act(async () => finishVoiceEnd?.()); - await screen.findByText("CTA handoff accepted"); + expect(await screen.findByText("Live net received.")).not.toBeNull(); + await waitFor(() => expect(sendMessages).toHaveBeenCalledOnce()); + const submittedTool = requestMessages[0]?.[0]?.parts[0]; + expect(submittedTool).toMatchObject({ + type: "tool-getLatestNetDefinition", + state: "output-available", + toolCallId: "pending-net-read", + output: { + title: "AI assistant panel test", + definition: nonEmptySDCPN, + extensions: DEFAULT_PETRINAUT_EXTENSIONS, + }, + }); - expect(events).toEqual(["end", "submit"]); - expect(endVoice).toHaveBeenCalledOnce(); + rerenderPanel({ + conversationId: "conversation-with-pending-tool", + messages: pendingMessages, + transport, + }); expect(sendMessages).toHaveBeenCalledOnce(); }); - test("invalidates active Voice mode before submitting typed text exactly once", async () => { - const events: string[] = []; + test("continues through consecutive automatic client tools", async () => { + const requestMessages: PetrinautAiMessage[][] = []; + const sendMessages = vi.fn( + ({ messages }) => { + requestMessages.push(structuredClone(messages)); + if (requestMessages.length <= 2) { + const toolCallId = `automatic-net-read-${requestMessages.length}`; + return Promise.resolve( + streamChunks([ + { type: "start-step" }, + { + type: "tool-input-available", + toolCallId, + toolName: getLatestNetDefinitionToolName, + input: {}, + }, + { type: "finish-step" }, + { type: "finish", finishReason: "tool-calls" }, + ]), + ); + } + return Promise.resolve( + streamChunks( + textChunks("automatic-complete", "Construction complete"), + ), + ); + }, + ); + + renderTestPanel({ + aiAssistant: { + transport: { + reconnectToStream: () => Promise.resolve(null), + sendMessages, + }, + }, + initialMessage: "Construct the net", + petriNetDefinition: nonEmptySDCPN, + }); + + await waitFor(() => expect(sendMessages).toHaveBeenCalledTimes(3)); + expect(await screen.findByText("Construction complete")).not.toBeNull(); + expect( + requestMessages[1]?.flatMap((message) => message.parts), + ).toContainEqual( + expect.objectContaining({ + state: "output-available", + toolCallId: "automatic-net-read-1", + }), + ); + expect( + requestMessages[2]?.flatMap((message) => message.parts), + ).toContainEqual( + expect.objectContaining({ + state: "output-available", + toolCallId: "automatic-net-read-2", + }), + ); + }); + + test("submits multiple automatic tool outputs in one continuation", async () => { + const requestMessages: PetrinautAiMessage[][] = []; + const sendMessages = vi.fn( + ({ messages }) => { + requestMessages.push(structuredClone(messages)); + if (requestMessages.length === 1) { + return Promise.resolve( + streamChunks([ + { type: "start-step" }, + { + type: "tool-input-available", + toolCallId: "batched-net-read-1", + toolName: getLatestNetDefinitionToolName, + input: {}, + }, + { + type: "tool-input-available", + toolCallId: "batched-net-read-2", + toolName: getLatestNetDefinitionToolName, + input: {}, + }, + { type: "finish-step" }, + { type: "finish", finishReason: "tool-calls" }, + ]), + ); + } + return Promise.resolve( + streamChunks(textChunks("batch-complete", "Both reads received")), + ); + }, + ); + + renderTestPanel({ + aiAssistant: { + transport: { + reconnectToStream: () => Promise.resolve(null), + sendMessages, + }, + }, + initialMessage: "Read the net twice", + petriNetDefinition: nonEmptySDCPN, + }); + + await waitFor(() => expect(sendMessages).toHaveBeenCalledTimes(2)); + expect(await screen.findByText("Both reads received")).not.toBeNull(); + const continuationParts = requestMessages[1]?.flatMap( + (message) => message.parts, + ); + expect(continuationParts).toContainEqual( + expect.objectContaining({ + state: "output-available", + toolCallId: "batched-net-read-1", + }), + ); + expect(continuationParts).toContainEqual( + expect.objectContaining({ + state: "output-available", + toolCallId: "batched-net-read-2", + }), + ); + }); + + test("does not continue while a sibling automatic tool is pending", async () => { + let releaseLayout: (() => void) | undefined; + const sendMessages = vi.fn(() => + Promise.resolve( + streamChunks([ + { type: "start-step" }, + { + type: "tool-input-available", + toolCallId: "staggered-net-read", + toolName: getLatestNetDefinitionToolName, + input: {}, + }, + { + type: "tool-input-available", + toolCallId: "staggered-layout", + toolName: "applyAutoLayout", + input: { askUserFirst: false }, + }, + { type: "finish-step" }, + { type: "finish", finishReason: "tool-calls" }, + ]), + ), + ); + + renderTestPanel({ + aiAssistant: { + transport: { + reconnectToStream: () => Promise.resolve(null), + sendMessages, + }, + }, + initialMessage: "Read and lay out the net", + petriNetDefinition: nonEmptySDCPN, + }); + const instance = testInstances.at(-1); + if (instance === undefined) { + throw new Error("Expected the panel to create a Petrinaut instance."); + } + const layout = vi + .spyOn(instance.commands, "applyAutoLayout") + .mockImplementation(async () => { + await new Promise((resolve) => { + releaseLayout = resolve; + }); + return { commitCount: 0 }; + }); + + await waitFor(() => expect(releaseLayout).toBeDefined()); + await act( + () => + new Promise((resolve) => { + setTimeout(resolve, 20); + }), + ); + expect(sendMessages).toHaveBeenCalledOnce(); + + await act(async () => { + releaseLayout?.(); + await layout.mock.results[0]?.value; + }); + }); + + test("invalidates registered Voice controls before typed submit while active publication is pending", async () => { + const events: string[] = []; let finishVoiceEnd: (() => void) | undefined; - let latestVoiceContext: PetrinautAiVoiceModeContext | undefined; const endVoice = vi.fn(() => { events.push("end"); return new Promise((resolve) => { @@ -412,7 +758,9 @@ describe("AiAssistantPanel composer submissions", () => { const sendMessages = vi.fn(() => { events.push("submit"); return Promise.resolve( - streamChunks(textChunks("typed-handoff", "Typed handoff accepted")), + streamChunks( + textChunks("pending-active-handoff", "Pending handoff accepted"), + ), ); }); const VoiceMode = ({ @@ -435,24 +783,15 @@ describe("AiAssistantPanel composer submissions", () => { ); return ( - ); }; renderTestPanel({ aiAssistant: { - renderVoiceMode: (context) => { - latestVoiceContext = context; - return ; - }, + renderVoiceMode: (context) => , transport: { reconnectToStream: () => Promise.resolve(null), sendMessages, @@ -461,12 +800,16 @@ describe("AiAssistantPanel composer submissions", () => { }); fireEvent.click( - screen.getByRole("button", { name: "Activate voice session" }), + screen.getByRole("button", { + name: "Select voice before active publication", + }), ); const textarea = screen.getByRole("textbox", { name: "Message AI assistant", }); - fireEvent.change(textarea, { target: { value: "Typed takeover" } }); + fireEvent.change(textarea, { + target: { value: "Typed during activation" }, + }); const sendButton = screen.getByRole("button", { name: "Send message" }); fireEvent.click(sendButton); fireEvent.click(sendButton); @@ -474,28 +817,105 @@ describe("AiAssistantPanel composer submissions", () => { expect(events).toEqual(["end"]); expect(sendMessages).not.toHaveBeenCalled(); - expect(textarea.value).toBe("Typed takeover"); - expect(textarea.disabled).toBe(true); - expect(latestVoiceContext?.inputMode).toBe("text"); await act(async () => finishVoiceEnd?.()); - await screen.findByText("Typed handoff accepted"); + await screen.findByText("Pending handoff accepted"); expect(events).toEqual(["end", "submit"]); + expect(endVoice).toHaveBeenCalledOnce(); expect(sendMessages).toHaveBeenCalledOnce(); - expect(document.activeElement).toBe(textarea); }); - test("preserves typed text when Voice invalidation throws synchronously", async () => { - let latestVoiceContext: PetrinautAiVoiceModeContext | undefined; + test("invalidates active Voice mode before submitting initial CTA text", async () => { + const events: string[] = []; + let finishVoiceEnd: (() => void) | undefined; const endVoice = vi.fn(() => { - throw new Error("Voice invalidation failed."); + events.push("end"); + return new Promise((resolve) => { + finishVoiceEnd = resolve; + }); }); - const sendMessages = vi.fn(() => - Promise.resolve( - streamChunks(textChunks("unexpected-handoff", "Unexpected submit")), - ), + const sendMessages = vi.fn(() => { + events.push("submit"); + return Promise.resolve( + streamChunks(textChunks("cta-handoff", "CTA handoff accepted")), + ); + }); + const VoiceMode = ({ + context, + }: { + context: PetrinautAiVoiceModeContext; + }) => { + const { + inputMode, + registerVoiceModeControls, + setVoiceActive: publishVoiceActive, + } = context; + + useEffect( + () => + registerVoiceModeControls({ + end: endVoice, + pause: vi.fn(), + reconnect: vi.fn(), + resume: vi.fn(), + setMicrophoneMuted: vi.fn(), + }), + [registerVoiceModeControls], + ); + useEffect(() => { + if (inputMode === "voice") { + publishVoiceActive(true); + } + }, [inputMode, publishVoiceActive]); + + return
{`Voice mode ${inputMode}`}
; + }; + const aiAssistant: PetrinautAiAssistant = { + renderVoiceMode: (context) => , + transport: { + reconnectToStream: () => Promise.resolve(null), + sendMessages, + }, + }; + const rendered = renderTestPanel({ + aiAssistant, + initialInteractionMode: "voice", + }); + await screen.findByText("Voice mode voice"); + + rendered.rerenderPanelWithInitialRequest( + "text", + "Create the support workflow", ); + + expect(events).toEqual(["end"]); + expect(sendMessages).not.toHaveBeenCalled(); + + await act(async () => finishVoiceEnd?.()); + await screen.findByText("CTA handoff accepted"); + + expect(events).toEqual(["end", "submit"]); + expect(endVoice).toHaveBeenCalledOnce(); + expect(sendMessages).toHaveBeenCalledOnce(); + }); + + test("invalidates active Voice mode before submitting typed text exactly once", async () => { + const events: string[] = []; + let finishVoiceEnd: (() => void) | undefined; + let latestVoiceContext: PetrinautAiVoiceModeContext | undefined; + const endVoice = vi.fn(() => { + events.push("end"); + return new Promise((resolve) => { + finishVoiceEnd = resolve; + }); + }); + const sendMessages = vi.fn(() => { + events.push("submit"); + return Promise.resolve( + streamChunks(textChunks("typed-handoff", "Typed handoff accepted")), + ); + }); const VoiceMode = ({ context, }: { @@ -523,7 +943,7 @@ describe("AiAssistantPanel composer submissions", () => { context.setInputMode("voice"); }} > - Activate failing voice session + Activate voice session ); }; @@ -542,18 +962,99 @@ describe("AiAssistantPanel composer submissions", () => { }); fireEvent.click( - screen.getByRole("button", { name: "Activate failing voice session" }), + screen.getByRole("button", { name: "Activate voice session" }), ); const textarea = screen.getByRole("textbox", { name: "Message AI assistant", }); - fireEvent.change(textarea, { target: { value: "Keep this draft" } }); - fireEvent.click(screen.getByRole("button", { name: "Send message" })); - await act(async () => {}); + fireEvent.change(textarea, { target: { value: "Typed takeover" } }); + const sendButton = screen.getByRole("button", { name: "Send message" }); + fireEvent.click(sendButton); + fireEvent.click(sendButton); + fireEvent.keyDown(textarea, { key: "Enter" }); - expect(endVoice).toHaveBeenCalledOnce(); + expect(events).toEqual(["end"]); expect(sendMessages).not.toHaveBeenCalled(); - expect(textarea.value).toBe("Keep this draft"); + expect(textarea.value).toBe("Typed takeover"); + expect(textarea.disabled).toBe(true); + expect(latestVoiceContext?.inputMode).toBe("text"); + + await act(async () => finishVoiceEnd?.()); + await screen.findByText("Typed handoff accepted"); + + expect(events).toEqual(["end", "submit"]); + expect(sendMessages).toHaveBeenCalledOnce(); + expect(document.activeElement).toBe(textarea); + }); + + test("preserves typed text when Voice invalidation throws synchronously", async () => { + let latestVoiceContext: PetrinautAiVoiceModeContext | undefined; + const endVoice = vi.fn(() => { + throw new Error("Voice invalidation failed."); + }); + const sendMessages = vi.fn(() => + Promise.resolve( + streamChunks(textChunks("unexpected-handoff", "Unexpected submit")), + ), + ); + const VoiceMode = ({ + context, + }: { + context: PetrinautAiVoiceModeContext; + }) => { + const { registerVoiceModeControls } = context; + + useEffect( + () => + registerVoiceModeControls({ + end: endVoice, + pause: vi.fn(), + reconnect: vi.fn(), + resume: vi.fn(), + setMicrophoneMuted: vi.fn(), + }), + [registerVoiceModeControls], + ); + + return ( + + ); + }; + + renderTestPanel({ + aiAssistant: { + renderVoiceMode: (context) => { + latestVoiceContext = context; + return ; + }, + transport: { + reconnectToStream: () => Promise.resolve(null), + sendMessages, + }, + }, + }); + + fireEvent.click( + screen.getByRole("button", { name: "Activate failing voice session" }), + ); + const textarea = screen.getByRole("textbox", { + name: "Message AI assistant", + }); + fireEvent.change(textarea, { target: { value: "Keep this draft" } }); + fireEvent.click(screen.getByRole("button", { name: "Send message" })); + await act(async () => {}); + + expect(endVoice).toHaveBeenCalledOnce(); + expect(sendMessages).not.toHaveBeenCalled(); + expect(textarea.value).toBe("Keep this draft"); expect(textarea.disabled).toBe(false); expect(latestVoiceContext?.inputMode).toBe("voice"); expect(screen.getByText("Voice invalidation failed.")).not.toBeNull(); @@ -1069,6 +1570,181 @@ describe("AiAssistantPanel composer submissions", () => { expect(voiceModeUnmounts).toBe(0); }); + test("forwards optional host Voice actions to the production dock", async () => { + const takeTurn = vi.fn(); + const repeatQuestion = vi.fn(); + const readFullResponse = vi.fn(); + const VoiceMode = ({ + context, + replayAllowed, + }: { + context: PetrinautAiVoiceModeContext; + replayAllowed: boolean; + }) => { + const { registerVoiceModeControls, reportVoiceSessionState } = context; + + useEffect( + () => + registerVoiceModeControls({ + end: async () => undefined, + pause: vi.fn(), + readFullResponse, + reconnect: vi.fn(), + repeatQuestion, + resume: vi.fn(), + setMicrophoneMuted: vi.fn(), + takeTurn, + }), + [registerVoiceModeControls], + ); + useEffect(() => { + reportVoiceSessionState({ + canReadFullResponse: replayAllowed, + canRepeatQuestion: replayAllowed, + canTakeTurn: true, + errorMessage: null, + microphoneLevel: 0, + microphoneMuted: false, + phase: "speaking", + }); + return () => reportVoiceSessionState(null); + }, [replayAllowed, reportVoiceSessionState]); + + return null; + }; + const aiAssistant = (replayAllowed: boolean): PetrinautAiAssistant => ({ + renderVoiceMode: (context) => ( + + ), + transport: { + reconnectToStream: () => Promise.resolve(null), + sendMessages: vi.fn(), + }, + }); + + const rendered = renderTestPanel({ aiAssistant: aiAssistant(true) }); + + fireEvent.click(await screen.findByRole("button", { name: "Your turn" })); + expect(takeTurn).toHaveBeenCalledOnce(); + + fireEvent.click( + screen.getByRole("button", { name: "Voice playback options" }), + ); + const repeatQuestionItem = await screen.findByRole("menuitem", { + name: "Repeat question", + }); + expect(repeatQuestionItem.getAttribute("aria-disabled")).not.toBe("true"); + const repeatQuestionMenu = screen.getByRole("menu"); + fireEvent.keyDown(repeatQuestionMenu, { key: "ArrowDown" }); + await waitFor(() => + expect(repeatQuestionMenu.getAttribute("aria-activedescendant")).toBe( + repeatQuestionItem.id, + ), + ); + fireEvent.keyDown(repeatQuestionMenu, { key: "Enter" }); + await waitFor(() => expect(repeatQuestion).toHaveBeenCalledOnce()); + + fireEvent.click( + screen.getByRole("button", { name: "Voice playback options" }), + ); + const readFullResponseItem = await screen.findByRole("menuitem", { + name: "Read full response", + }); + expect(readFullResponseItem.getAttribute("aria-disabled")).not.toBe("true"); + const readFullResponseMenu = screen.getByRole("menu"); + fireEvent.keyDown(readFullResponseMenu, { key: "End" }); + await waitFor(() => + expect(readFullResponseMenu.getAttribute("aria-activedescendant")).toBe( + readFullResponseItem.id, + ), + ); + fireEvent.keyDown(readFullResponseMenu, { key: "Enter" }); + await waitFor(() => expect(readFullResponse).toHaveBeenCalledOnce()); + + rendered.rerenderPanel(aiAssistant(false), editorContextValue); + fireEvent.click( + await screen.findByRole("button", { name: "Voice playback options" }), + ); + expect( + ( + await screen.findByRole("menuitem", { name: "Repeat question" }) + ).getAttribute("aria-disabled"), + ).toBe("true"); + expect( + screen + .getByRole("menuitem", { name: "Read full response" }) + .getAttribute("aria-disabled"), + ).toBe("true"); + }); + + test("retires missing and unmounted optional host Voice actions", async () => { + const VoiceMode = ({ + context, + }: { + context: PetrinautAiVoiceModeContext; + }) => { + const { registerVoiceModeControls, reportVoiceSessionState } = context; + + useEffect( + () => + registerVoiceModeControls({ + end: async () => undefined, + pause: vi.fn(), + reconnect: vi.fn(), + resume: vi.fn(), + setMicrophoneMuted: vi.fn(), + }), + [registerVoiceModeControls], + ); + useEffect(() => { + reportVoiceSessionState({ + canReadFullResponse: true, + canRepeatQuestion: true, + canTakeTurn: true, + errorMessage: null, + microphoneLevel: 0, + microphoneMuted: false, + phase: "speaking", + }); + return () => reportVoiceSessionState(null); + }, [reportVoiceSessionState]); + + return null; + }; + const aiAssistant = (mounted: boolean): PetrinautAiAssistant => ({ + renderVoiceMode: (context) => + mounted ? : null, + transport: { + reconnectToStream: () => Promise.resolve(null), + sendMessages: vi.fn(), + }, + }); + const rendered = renderTestPanel({ aiAssistant: aiAssistant(true) }); + + expect(screen.queryByRole("button", { name: "Your turn" })).toBeNull(); + fireEvent.click( + await screen.findByRole("button", { name: "Voice playback options" }), + ); + expect( + ( + await screen.findByRole("menuitem", { name: "Repeat question" }) + ).getAttribute("aria-disabled"), + ).toBe("true"); + expect( + screen + .getByRole("menuitem", { name: "Read full response" }) + .getAttribute("aria-disabled"), + ).toBe("true"); + + rendered.rerenderPanel(aiAssistant(false), editorContextValue); + + await waitFor(() => + expect( + screen.queryByRole("region", { name: "Voice session" }), + ).toBeNull(), + ); + }); + test("ends active Voice mode when the unified composer returns to text", () => { voiceModeMounts = 0; voiceModeUnmounts = 0; @@ -1116,6 +1792,10 @@ describe("AiAssistantPanel composer submissions", () => { fireEvent.click(screen.getByRole("button", { name: "Start voice mode" })); expect(screen.getByText("Voice mode voice")).not.toBeNull(); + expect(screen.queryByRole("region", { name: "Voice setup" })).toBeNull(); + expect( + screen.getByRole("textbox", { name: "Message AI assistant" }), + ).not.toBeNull(); fireEvent.click(screen.getByRole("button", { name: "Voice mode voice" })); expect( @@ -1127,7 +1807,7 @@ describe("AiAssistantPanel composer submissions", () => { expect(sendMessages).not.toHaveBeenCalled(); }); - test("defers and consumes an initial Voice mode once, then falls back to text", () => { + test("opens initial Voice setup compact once, then falls back to text", () => { let latestInputMode = "text"; const onInitialInteractionModeConsumed = vi.fn(); const aiAssistant: PetrinautAiAssistant = { @@ -1158,6 +1838,27 @@ describe("AiAssistantPanel composer submissions", () => { expect(latestInputMode).toBe("voice"); expect(onInitialInteractionModeConsumed).toHaveBeenCalledOnce(); + expect(screen.getByText("Voice mode")).not.toBeNull(); + const composer = screen.getByRole("textbox", { + hidden: true, + name: "Message AI assistant", + }); + const composerWrap = composer.closest("form")?.parentElement; + expect(composerWrap?.className).toContain("d_none"); + + const setupDock = screen.getByRole("region", { name: "Voice setup" }); + fireEvent.click( + within(setupDock).getByRole("button", { name: "Expand voice setup" }), + ); + + expect(screen.queryByRole("region", { name: "Voice setup" })).toBeNull(); + expect(composerWrap?.className).not.toContain("d_none"); + expect(screen.getByRole("textbox", { name: "Message AI assistant" })).toBe( + composer, + ); + expect( + screen.getByRole("button", { name: "Close AI assistant" }), + ).not.toBeNull(); const unavailableAssistant: PetrinautAiAssistant = { transport: aiAssistant.transport, @@ -1171,6 +1872,78 @@ describe("AiAssistantPanel composer submissions", () => { expect(onInitialInteractionModeConsumed).toHaveBeenCalledOnce(); }); + test("ends collapsed Voice and closes the panel without pausing", async () => { + const events: string[] = []; + const endVoice = vi.fn(async () => { + events.push("end"); + }); + const pauseVoice = vi.fn(() => events.push("pause")); + const setAiAssistantOpen = vi.fn(() => events.push("close")); + const VoiceMode = ({ + context, + }: { + context: PetrinautAiVoiceModeContext; + }) => { + const { + inputMode, + registerVoiceModeControls, + reportVoiceSessionState, + setVoiceActive, + } = context; + + useEffect( + () => + registerVoiceModeControls({ + end: endVoice, + pause: pauseVoice, + reconnect: vi.fn(), + resume: vi.fn(), + setMicrophoneMuted: vi.fn(), + }), + [registerVoiceModeControls], + ); + useEffect(() => { + if (inputMode !== "voice") { + return; + } + setVoiceActive(true); + reportVoiceSessionState({ + errorMessage: null, + microphoneLevel: 0, + microphoneMuted: false, + phase: "listening", + }); + }, [inputMode, reportVoiceSessionState, setVoiceActive]); + + return null; + }; + + renderTestPanel({ + aiAssistant: { + renderVoiceMode: (context) => , + transport: { + reconnectToStream: () => Promise.resolve(null), + sendMessages: vi.fn(), + }, + }, + editorContext: { + ...editorContextValue, + setAiAssistantOpen, + }, + initialInteractionMode: "voice", + }); + + const dock = await screen.findByRole("region", { name: "Voice session" }); + fireEvent.click( + within(dock).getByRole("button", { name: "End voice mode" }), + ); + + expect(events).toEqual(["end", "close"]); + expect(endVoice).toHaveBeenCalledOnce(); + expect(pauseVoice).not.toHaveBeenCalled(); + expect(setAiAssistantOpen).toHaveBeenCalledWith(false); + }); + test("accepts one voice input while generic chat is streaming and submits it after settlement", async () => { let firstStreamController: | ReadableStreamDefaultController @@ -1273,7 +2046,10 @@ describe("AiAssistantPanel composer submissions", () => { expect(latestVoiceContext?.status).toBe("streaming"); expect(latestVoiceContext?.canAcceptVoiceInput).toBe(true); expect(requests[1]?.at(-1)).toMatchObject({ - metadata: { source: "voice", toolCallId: "queued-question" }, + metadata: { + source: "voice", + voiceToolCallIds: ["queued-question"], + }, role: "assistant", }); expect( @@ -1570,109 +2346,800 @@ describe("AiAssistantPanel composer submissions", () => { fireEvent.click( screen.getByRole("button", { name: "Stop from host control" }), ); - - await waitFor(() => expect(aborted).toHaveBeenCalledOnce()); - expect(await screen.findByText("Response stopped")).not.toBeNull(); + + await waitFor(() => expect(aborted).toHaveBeenCalledOnce()); + expect(await screen.findByText("Response stopped")).not.toBeNull(); + }); + + test("records a durable Stop before cancelling the local stream", async () => { + const localCancellation = vi.fn(); + const transport: PetrinautAiTransport = { + reconnectToStream: () => Promise.resolve(null), + sendMessages: vi.fn( + ({ + abortSignal, + }: Parameters[0]) => + Promise.resolve( + new ReadableStream({ + start(controller) { + controller.enqueue({ type: "start-step" }); + controller.enqueue({ type: "text-start", id: "partial" }); + controller.enqueue({ + type: "text-delta", + id: "partial", + delta: "Durably stopping", + }); + abortSignal?.addEventListener("abort", () => { + localCancellation(); + controller.error(new DOMException("Aborted", "AbortError")); + }); + }, + }), + ), + ), + }; + const requestStop = vi.fn(async () => "stop-requested" as const); + + renderTestPanel({ + aiAssistant: { requestStop, transport }, + initialMessage: "Start durable work", + }); + await screen.findByText("Durably stopping"); + + fireEvent.click(screen.getByRole("button", { name: "Stop AI response" })); + + await waitFor(() => expect(requestStop).toHaveBeenCalledOnce()); + await waitFor(() => expect(localCancellation).toHaveBeenCalledOnce()); + expect(requestStop.mock.invocationCallOrder[0]).toBeLessThan( + localCancellation.mock.invocationCallOrder[0]!, + ); + expect(await screen.findByText("Response stopped")).not.toBeNull(); + }); + + test("keeps a response completed before the durable Stop race", async () => { + const localCancellation = vi.fn(); + let streamController: + | ReadableStreamDefaultController + | undefined; + const transport: PetrinautAiTransport = { + reconnectToStream: () => Promise.resolve(null), + sendMessages: vi.fn( + ({ + abortSignal, + }: Parameters[0]) => + Promise.resolve( + new ReadableStream({ + start(controller) { + streamController = controller; + controller.enqueue({ type: "start-step" }); + controller.enqueue({ type: "text-start", id: "answer" }); + controller.enqueue({ + type: "text-delta", + id: "answer", + delta: "Completed response", + }); + abortSignal?.addEventListener("abort", localCancellation); + }, + }), + ), + ), + }; + const requestStop = vi.fn(async () => { + streamController?.enqueue({ type: "text-end", id: "answer" }); + streamController?.enqueue({ type: "finish-step" }); + streamController?.enqueue({ type: "finish", finishReason: "stop" }); + streamController?.close(); + return "already-settled" as const; + }); + + renderTestPanel({ + aiAssistant: { requestStop, transport }, + initialMessage: "Race a completed response", + }); + await screen.findByText("Completed response"); + + fireEvent.click(screen.getByRole("button", { name: "Stop AI response" })); + + await waitFor(() => expect(requestStop).toHaveBeenCalledOnce()); + await waitFor(() => + expect( + screen.getByRole("button", { name: "Send message" }), + ).toHaveProperty("disabled", true), + ); + expect(localCancellation).not.toHaveBeenCalled(); + expect(screen.queryByText("Response stopped")).toBeNull(); + }); + + test("withholds the client-tool follow-up when a durable Stop lands after a tool-calls step", async () => { + let streamController: + | ReadableStreamDefaultController + | undefined; + const sendMessages = vi.fn(() => + Promise.resolve( + new ReadableStream({ + start(controller) { + streamController = controller; + controller.enqueue({ type: "start-step" }); + controller.enqueue({ type: "text-start", id: "preamble" }); + controller.enqueue({ + type: "text-delta", + id: "preamble", + delta: "Checking the net", + }); + }, + }), + ), + ); + const requestStop = vi.fn(async () => { + // The step settles as a tool-calls step while the durable Stop is in + // flight, so Flue has nothing left to abort and reports already-settled. + streamController?.enqueue({ type: "text-end", id: "preamble" }); + streamController?.enqueue({ + type: "tool-input-available", + toolCallId: "stopped-mutation", + toolName: "updatePlace", + input: { placeId: "place-1", update: { name: "MustNotApply" } }, + }); + streamController?.enqueue({ type: "finish-step" }); + streamController?.enqueue({ type: "finish", finishReason: "tool-calls" }); + streamController?.close(); + return "already-settled" as const; + }); + + renderTestPanel({ + aiAssistant: { + requestStop, + transport: { + reconnectToStream: () => Promise.resolve(null), + sendMessages, + }, + }, + initialMessage: "Stop me mid-tool", + petriNetDefinition: nonEmptySDCPN, + }); + await screen.findByText("Checking the net"); + + fireEvent.click(screen.getByRole("button", { name: "Stop AI response" })); + + await waitFor(() => expect(requestStop).toHaveBeenCalledOnce()); + expect(await screen.findByText("Response stopped")).not.toBeNull(); + // Let both deferred execution and any follow-up drain: withholding only + // the send is insufficient if the mutation already ran after Stop. + await act(() => new Promise((resolve) => setTimeout(resolve, 20))); + expect(testInstances.at(-1)?.definition.get().places[0]?.name).toBe( + "PlaceOne", + ); + expect(sendMessages).toHaveBeenCalledOnce(); + expect(screen.getByRole("button", { name: "Send message" })).toHaveProperty( + "disabled", + true, + ); + }); + + test("reports a textless automatic browser failure to hosts and its matching tool", async () => { + let latest: PetrinautAiComposerControlContext | undefined; + const sendMessages = vi.fn(async () => + streamChunks([ + { type: "start-step" }, + { + type: "tool-input-available", + toolCallId: "invalid-doc", + toolName: "readPetrinautDoc", + input: { doc: "not-a-guide-page" }, + }, + { type: "finish-step" }, + { type: "finish", finishReason: "tool-calls" }, + ]), + ); + renderTestPanel({ + aiAssistant: { + transport: { reconnectToStream: async () => null, sendMessages }, + renderComposerControl: (context) => { + latest = context; + return null; + }, + }, + initialMessage: "Read the guide", + }); + await waitFor(() => expect(latest?.status).toBe("error")); + await waitFor(() => + expect(latest?.messages.at(-1)?.parts).toContainEqual( + expect.objectContaining({ + toolCallId: "invalid-doc", + state: "output-error", + errorText: expect.any(String) as unknown, + }), + ), + ); + expect(sendMessages).toHaveBeenCalledOnce(); + }); + + test("does not execute tools from a durably stopped reopened response", async () => { + const sendMessages = vi.fn(async () => + streamChunks([]), + ); + renderTestPanel({ + aiAssistant: { + messages: [ + { + id: "stopped", + role: "assistant", + metadata: { stopped: true }, + parts: [ + { + type: "tool-updatePlace", + toolCallId: "stopped-mutation", + state: "input-available", + input: { placeId: "place-1", update: { name: "MustNotApply" } }, + }, + ], + }, + ], + transport: { reconnectToStream: async () => null, sendMessages }, + }, + petriNetDefinition: nonEmptySDCPN, + }); + await act(() => new Promise((resolve) => setTimeout(resolve, 30))); + expect(testInstances.at(-1)?.definition.get().places[0]?.name).toBe( + "PlaceOne", + ); + expect(sendMessages).not.toHaveBeenCalled(); + expect(screen.getByText("Response stopped")).not.toBeNull(); + }); + + test("keeps hosts seeing a busy conversation between a tool-calls step and its follow-up", async () => { + const observedStatuses: PetrinautAiComposerControlContext["status"][] = []; + let requestCount = 0; + const transport: PetrinautAiTransport = { + reconnectToStream: () => Promise.resolve(null), + sendMessages: vi.fn(() => { + requestCount += 1; + return Promise.resolve( + streamChunks( + requestCount === 1 + ? [ + ...textChunks("preamble", "Checking the net"), + { + type: "tool-input-available", + toolCallId: "net-read-1", + toolName: "getLatestNetDefinition", + input: {}, + }, + { type: "finish-step" }, + { type: "finish", finishReason: "tool-calls" }, + ] + : [ + ...textChunks("reply", "The net has one place"), + { type: "finish-step" }, + { type: "finish", finishReason: "stop" }, + ], + ), + ); + }), + }; + + renderTestPanel({ + aiAssistant: { + renderComposerControl: (context) => { + observedStatuses.push(context.status); + return null; + }, + transport, + }, + initialMessage: "Read the net", + petriNetDefinition: nonEmptySDCPN, + }); + await screen.findByText("The net has one place"); + + // The SDK reports `ready` between the tool-calls step and the follow-up it + // sends automatically; a host must not read that gap as the turn's end. + const firstBusy = observedStatuses.findIndex( + (status) => status === "submitted" || status === "streaming", + ); + const lastBusy = observedStatuses.findLastIndex( + (status) => status === "submitted" || status === "streaming", + ); + expect(firstBusy).toBeGreaterThanOrEqual(0); + expect( + observedStatuses + .slice(firstBusy, lastBusy + 1) + .filter((status) => status === "ready"), + ).toEqual([]); + expect(observedStatuses.at(-1)).toBe("ready"); + }); + + test("replaces conversation-owned busy state when the identity changes", async () => { + let requestCount = 0; + const statuses: string[] = []; + const transport: PetrinautAiTransport = { + reconnectToStream: () => Promise.resolve(null), + sendMessages: vi.fn(() => { + requestCount += 1; + if (requestCount > 1) { + return new Promise>(() => {}); + } + return Promise.resolve( + streamChunks([ + ...textChunks("preamble", "Checking the net"), + { + type: "tool-input-available", + toolCallId: "net-read-1", + toolName: "getLatestNetDefinition", + input: {}, + }, + { type: "finish-step" }, + { type: "finish", finishReason: "tool-calls" }, + ]), + ); + }), + }; + const createAiAssistant = ( + conversationId: string, + ): PetrinautAiAssistant => ({ + conversationId, + renderComposerControl: (context) => { + statuses.push(`${context.conversationId}:${context.status}`); + return ( + + ); + }, + transport, + }); + const rendered = renderTestPanel({ + aiAssistant: createAiAssistant("conversation-1"), + petriNetDefinition: nonEmptySDCPN, + }); + + fireEvent.click(screen.getByRole("button", { name: "Read net" })); + await waitFor(() => expect(statuses).toContain("conversation-1:submitted")); + + rendered.rerenderPanel(createAiAssistant("conversation-2")); + + await waitFor(() => expect(statuses.at(-1)).toBe("conversation-2:ready")); + }); + + test("does not carry an idle host stop into a later incidental abort", async () => { + let requestCount = 0; + const transport: PetrinautAiTransport = { + reconnectToStream: () => Promise.resolve(null), + sendMessages: vi.fn(() => { + requestCount += 1; + if (requestCount === 1) { + return Promise.resolve( + streamChunks([ + { type: "start-step" }, + { + type: "tool-input-available", + dynamic: true, + toolCallId: "confirmation-1", + toolName: "confirmAction", + input: { question: "Continue?" }, + }, + ]), + ); + } + + return Promise.resolve( + new ReadableStream({ + start(controller) { + controller.enqueue({ type: "start-step" }); + controller.enqueue({ + type: "text-start", + id: "interrupted-follow-up", + }); + controller.enqueue({ + type: "text-delta", + id: "interrupted-follow-up", + delta: "Partial follow-up", + }); + setTimeout(() => { + controller.error(new DOMException("Aborted", "AbortError")); + }, 0); + }, + }), + ); + }), + }; + const hostTool = definePetrinautAiInteractiveTool({ + toolName: "confirmAction", + inputSchema: { + parse: (raw: unknown) => raw as { question: string }, + }, + outputSchema: { + parse: (raw: unknown) => raw as { confirmed: boolean }, + }, + component: ({ input, submit }) => ( + + ), + }); + + renderTestPanel({ + aiAssistant: { + interactiveTools: [hostTool], + renderComposerControl: ({ status, stop }) => ( + <> + + {status} + + ), + transport, + }, + initialMessage: "Ask for confirmation", + }); + + await screen.findByRole("button", { name: "Continue?" }); + await waitFor(() => + expect(screen.getByTestId("host-status").textContent).toBe("ready"), + ); + + fireEvent.click(screen.getByRole("button", { name: "Stop while idle" })); + fireEvent.click(screen.getByRole("button", { name: "Continue?" })); + + await waitFor(() => + expect(transport.sendMessages).toHaveBeenCalledTimes(2), + ); + await waitFor(() => + expect(screen.getByTestId("host-status").textContent).toBe("ready"), + ); + expect(screen.queryByText("Response stopped")).toBeNull(); + }); + + test("does not let a late durable Stop cancel a newer turn", async () => { + let firstStreamController: + | ReadableStreamDefaultController + | undefined; + let secondStreamController: + | ReadableStreamDefaultController + | undefined; + const secondCancellation = vi.fn(); + let requestCount = 0; + const transport: PetrinautAiTransport = { + reconnectToStream: () => Promise.resolve(null), + sendMessages: vi.fn( + ({ + abortSignal, + }: Parameters[0]) => { + requestCount += 1; + if (requestCount === 1) { + return Promise.resolve( + new ReadableStream({ + start(controller) { + firstStreamController = controller; + controller.enqueue({ type: "start-step" }); + controller.enqueue({ type: "text-start", id: "first" }); + controller.enqueue({ + type: "text-delta", + id: "first", + delta: "First partial", + }); + }, + }), + ); + } + return Promise.resolve( + new ReadableStream({ + start(controller) { + secondStreamController = controller; + abortSignal?.addEventListener("abort", secondCancellation); + controller.enqueue({ type: "start-step" }); + controller.enqueue({ type: "text-start", id: "second" }); + controller.enqueue({ + type: "text-delta", + id: "second", + delta: "Second turn", + }); + }, + }), + ); + }, + ), + }; + let resolveStop: ((result: "stop-requested") => void) | undefined; + const requestStop = vi.fn( + () => + new Promise<"stop-requested">((resolve) => { + resolveStop = resolve; + }), + ); + + renderTestPanel({ + aiAssistant: { + renderComposerControl: ({ status: hostStatus, submitText }) => ( + <> + + {hostStatus} + + ), + requestStop, + transport, + }, + initialMessage: "First", + }); + await screen.findByText("First partial"); + + fireEvent.click(screen.getByRole("button", { name: "Stop AI response" })); + await waitFor(() => expect(requestStop).toHaveBeenCalledOnce()); + + // The first response completes on its own while the durable stop is + // still in flight, and the user starts another turn. + await act(async () => { + firstStreamController?.enqueue({ type: "text-end", id: "first" }); + firstStreamController?.enqueue({ type: "finish-step" }); + firstStreamController?.enqueue({ type: "finish", finishReason: "stop" }); + firstStreamController?.close(); + }); + await waitFor(() => + expect(screen.getByTestId("host-status").textContent).toBe("ready"), + ); + fireEvent.click(screen.getByRole("button", { name: "Send second" })); + await screen.findByText("Second turn"); + + // The stale Stop result lands while the second turn is still streaming. + await act(async () => { + resolveStop?.("stop-requested"); + }); + expect(screen.getByTestId("host-status").textContent).toBe("streaming"); + expect(secondCancellation).not.toHaveBeenCalled(); + + await act(async () => { + secondStreamController?.enqueue({ type: "text-end", id: "second" }); + secondStreamController?.close(); + }); + await waitFor(() => + expect(screen.getByTestId("host-status").textContent).toBe("ready"), + ); + expect(screen.queryByText("Response stopped")).toBeNull(); + }); + + test("does not surface a late durable Stop failure on a newer turn", async () => { + let firstStreamController: + | ReadableStreamDefaultController + | undefined; + let secondStreamController: + | ReadableStreamDefaultController + | undefined; + const secondCancellation = vi.fn(); + let requestCount = 0; + const transport: PetrinautAiTransport = { + reconnectToStream: () => Promise.resolve(null), + sendMessages: vi.fn( + ({ + abortSignal, + }: Parameters[0]) => { + requestCount += 1; + const isFirst = requestCount === 1; + return Promise.resolve( + new ReadableStream({ + start(controller) { + if (isFirst) { + firstStreamController = controller; + } else { + secondStreamController = controller; + abortSignal?.addEventListener("abort", secondCancellation); + } + const id = isFirst ? "first" : "second"; + controller.enqueue({ type: "start-step" }); + controller.enqueue({ type: "text-start", id }); + controller.enqueue({ + type: "text-delta", + id, + delta: isFirst ? "First partial" : "Second turn", + }); + }, + }), + ); + }, + ), + }; + let rejectStop: ((reason: Error) => void) | undefined; + const requestStop = vi.fn( + () => + new Promise<"stop-requested">((_resolve, reject) => { + rejectStop = reject; + }), + ); + + renderTestPanel({ + aiAssistant: { + renderComposerControl: ({ status: hostStatus, submitText }) => ( + <> + + {hostStatus} + + ), + requestStop, + transport, + }, + initialMessage: "First", + }); + await screen.findByText("First partial"); + + fireEvent.click(screen.getByRole("button", { name: "Stop AI response" })); + await waitFor(() => expect(requestStop).toHaveBeenCalledOnce()); + await act(async () => { + firstStreamController?.enqueue({ type: "text-end", id: "first" }); + firstStreamController?.close(); + }); + await waitFor(() => + expect(screen.getByTestId("host-status").textContent).toBe("ready"), + ); + fireEvent.click(screen.getByRole("button", { name: "Send second" })); + await screen.findByText("Second turn"); + + await act(async () => { + rejectStop?.(new Error("Durable stop failed")); + }); + expect(screen.getByTestId("host-status").textContent).toBe("streaming"); + expect(secondCancellation).not.toHaveBeenCalled(); + expect(screen.queryByText(/Durable stop failed/u)).toBeNull(); + + await act(async () => { + secondStreamController?.enqueue({ type: "text-end", id: "second" }); + secondStreamController?.close(); + }); + await waitFor(() => + expect(screen.getByTestId("host-status").textContent).toBe("ready"), + ); + expect(screen.queryByText(/Durable stop failed/u)).toBeNull(); }); - test("does not carry an idle host stop into a later incidental abort", async () => { - let requestCount = 0; + test("withdraws a retained voice input when its signal aborts", async () => { + let streamController: + | ReadableStreamDefaultController + | undefined; const transport: PetrinautAiTransport = { reconnectToStream: () => Promise.resolve(null), - sendMessages: vi.fn(() => { - requestCount += 1; - if (requestCount === 1) { - return Promise.resolve( - streamChunks([ - { type: "start-step" }, - { - type: "tool-input-available", - dynamic: true, - toolCallId: "confirmation-1", - toolName: "confirmAction", - input: { question: "Continue?" }, - }, - ]), - ); - } - - return Promise.resolve( + sendMessages: vi.fn(() => + Promise.resolve( new ReadableStream({ start(controller) { + streamController = controller; controller.enqueue({ type: "start-step" }); - controller.enqueue({ - type: "text-start", - id: "interrupted-follow-up", - }); + controller.enqueue({ type: "text-start", id: "busy" }); controller.enqueue({ type: "text-delta", - id: "interrupted-follow-up", - delta: "Partial follow-up", + id: "busy", + delta: "Still answering", }); - setTimeout(() => { - controller.error(new DOMException("Aborted", "AbortError")); - }, 0); }, }), - ); - }), - }; - const hostTool = definePetrinautAiInteractiveTool({ - toolName: "confirmAction", - inputSchema: { - parse: (raw: unknown) => raw as { question: string }, - }, - outputSchema: { - parse: (raw: unknown) => raw as { confirmed: boolean }, - }, - component: ({ input, submit }) => ( - + ), ), - }); + }; + let latestVoiceContext: PetrinautAiVoiceModeContext | undefined; renderTestPanel({ aiAssistant: { - interactiveTools: [hostTool], - renderComposerControl: ({ status, stop }) => ( - <> - - {status} - - ), + renderVoiceMode: (context) => { + latestVoiceContext = context; + return null; + }, transport, }, - initialMessage: "Ask for confirmation", + initialMessage: "Begin", }); + await screen.findByText("Still answering"); + await waitFor(() => expect(latestVoiceContext?.status).toBe("streaming")); - await screen.findByRole("button", { name: "Continue?" }); + const withdrawal = new AbortController(); + const retained = latestVoiceContext!.submitVoiceInput({ + signal: withdrawal.signal, + text: "Stale voice input", + }); await waitFor(() => - expect(screen.getByTestId("host-status").textContent).toBe("ready"), + expect(latestVoiceContext?.canAcceptVoiceInput).toBe(false), ); - fireEvent.click(screen.getByRole("button", { name: "Stop while idle" })); - fireEvent.click(screen.getByRole("button", { name: "Continue?" })); + withdrawal.abort(); + await expect(retained).rejects.toMatchObject({ name: "AbortError" }); await waitFor(() => - expect(transport.sendMessages).toHaveBeenCalledTimes(2), - ); - await waitFor(() => - expect(screen.getByTestId("host-status").textContent).toBe("ready"), + expect(latestVoiceContext?.canAcceptVoiceInput).toBe(true), ); - expect(screen.queryByText("Response stopped")).toBeNull(); + + await act(async () => { + streamController?.enqueue({ type: "text-end", id: "busy" }); + streamController?.close(); + }); + await waitFor(() => expect(latestVoiceContext?.status).toBe("ready")); + expect(transport.sendMessages).toHaveBeenCalledTimes(1); + expect(screen.queryByText("Stale voice input")).toBeNull(); + }); + + test("waits to hydrate until the host snapshot carries a turn submitted first", async () => { + const transport: PetrinautAiTransport = { + reconnectToStream: () => Promise.resolve(null), + sendMessages: vi.fn(() => + Promise.resolve( + streamChunks([ + { type: "start", messageId: "assistant-live-1" }, + ...textChunks("live", "Live answer"), + { type: "finish-step" }, + { type: "finish", finishReason: "stop" }, + ]), + ), + ), + }; + const { rerenderPanel } = renderTestPanel({ + aiAssistant: { conversationId: "conversation-1", transport }, + initialMessage: "Ask before history loads", + }); + await screen.findByText("Live answer"); + + // The observation publishes a snapshot that predates the live turn. + rerenderPanel({ + conversationId: "conversation-1", + messages: [ + { + id: "assistant-history-1", + role: "assistant", + parts: [{ type: "text", text: "Older history" }], + }, + ], + transport, + }); + await act(async () => {}); + expect(screen.getByText("Live answer")).not.toBeNull(); + expect(screen.queryByText("Older history")).toBeNull(); + + // Once the snapshot carries the live reply too, canonical history wins. + rerenderPanel({ + conversationId: "conversation-1", + messages: [ + { + id: "assistant-history-1", + role: "assistant", + parts: [{ type: "text", text: "Older history" }], + }, + { + id: "user-live-1", + role: "user", + parts: [{ type: "text", text: "Ask before history loads" }], + }, + { + id: "assistant-live-1", + role: "assistant", + parts: [{ type: "text", text: "Live answer" }], + }, + ], + transport, + }); + expect(await screen.findByText("Older history")).not.toBeNull(); + expect(screen.getByText("Live answer")).not.toBeNull(); + expect(transport.sendMessages).toHaveBeenCalledTimes(1); }); test("maps keyboard text to one unresolved host tool before sending another message", async () => { @@ -1830,6 +3297,51 @@ describe("AiAssistantPanel composer submissions", () => { ); }); + test("preserves the already-normalized Voice payload at the panel boundary", async () => { + const requestMessages: PetrinautAiMessage[][] = []; + const transport: PetrinautAiTransport = { + reconnectToStream: () => Promise.resolve(null), + sendMessages: vi.fn(({ messages }) => { + requestMessages.push(structuredClone(messages)); + return Promise.resolve( + streamChunks(textChunks("voice-response", "Voice message accepted")), + ); + }), + }; + + renderTestPanel({ + aiAssistant: { + renderComposerControl: ({ submitText }) => ( + + ), + transport, + }, + }); + + fireEvent.click( + screen.getByRole("button", { name: "Submit normalized Voice payload" }), + ); + await screen.findByText("Voice message accepted"); + + expect(requestMessages[0]?.at(-1)).toMatchObject({ + id: "voice-realtime:3:item-1:0", + metadata: { source: "voice" }, + parts: [{ text: " Already normalized upstream ", type: "text" }], + role: "user", + }); + }); + test("marks the exact pending tool as voice-origin without a user message", async () => { const requestMessages: PetrinautAiMessage[][] = []; const onMessages = vi.fn(); @@ -1908,7 +3420,10 @@ describe("AiAssistantPanel composer submissions", () => { ), ); expect(containingMessage).toMatchObject({ - metadata: { source: "voice", toolCallId: "question-voice" }, + metadata: { + source: "voice", + voiceToolCallIds: ["question-voice"], + }, }); expect( containingMessage?.parts.find( @@ -1932,12 +3447,139 @@ describe("AiAssistantPanel composer submissions", () => { expect(onMessages.mock.lastCall?.[0]).toEqual( expect.arrayContaining([ expect.objectContaining({ - metadata: { source: "voice", toolCallId: "question-voice" }, + metadata: { + source: "voice", + voiceToolCallIds: ["question-voice"], + }, }), ]), ); }); + test("retains every voice tool origin on one assistant message", async () => { + let latestMessages = [ + { + id: "assistant-voice-questions", + parts: [ + { + input: { question: "Who approves it?" }, + state: "input-available", + toolCallId: "voice-question-1", + toolName: "answerQuestion", + type: "dynamic-tool", + }, + { + input: { question: "Who acts next?" }, + state: "input-available", + toolCallId: "voice-question-2", + toolName: "answerQuestion", + type: "dynamic-tool", + }, + ], + role: "assistant", + }, + ] as unknown as PetrinautAiMessage[]; + const updateMessages = ( + updater: (messages: PetrinautAiMessage[]) => PetrinautAiMessage[], + ) => { + latestMessages = updater(latestMessages); + }; + const addToolOutput = vi.fn().mockResolvedValue(undefined); + + for (const toolCallId of ["voice-question-1", "voice-question-2"]) { + await addMappedToolOutput({ + addToolOutput, + currentMessages: latestMessages, + params: { + output: { answer: toolCallId }, + tool: "answerQuestion", + toolCallId, + }, + source: "voice", + updateMessages, + }); + } + + expect(latestMessages[0]?.metadata).toEqual({ + source: "voice", + voiceToolCallIds: ["voice-question-1", "voice-question-2"], + }); + }); + + test("preserves sibling voice provenance when another tool output rejects", async () => { + let latestMessages = [ + { + id: "assistant-voice-questions", + parts: [ + { + input: { question: "Who approves it?" }, + state: "input-available", + toolCallId: "voice-question-1", + toolName: "answerQuestion", + type: "dynamic-tool", + }, + { + input: { question: "Who acts next?" }, + state: "input-available", + toolCallId: "voice-question-2", + toolName: "answerQuestion", + type: "dynamic-tool", + }, + ], + role: "assistant", + }, + ] as unknown as PetrinautAiMessage[]; + const updateMessages = ( + updater: (messages: PetrinautAiMessage[]) => PetrinautAiMessage[], + ) => { + latestMessages = updater(latestMessages); + }; + let rejectFirstSubmission: ((reason?: unknown) => void) | undefined; + const addToolOutput = vi + .fn() + .mockImplementationOnce( + () => + new Promise((_resolve, reject) => { + rejectFirstSubmission = reject; + }), + ) + .mockResolvedValueOnce(undefined); + + const firstSubmission = addMappedToolOutput({ + addToolOutput, + currentMessages: latestMessages, + params: { + output: { answer: "The shift lead" }, + tool: "answerQuestion", + toolCallId: "voice-question-1", + }, + source: "voice", + updateMessages, + }); + const firstSubmissionRejection = expect(firstSubmission).rejects.toThrow( + "First voice tool output rejected.", + ); + + await addMappedToolOutput({ + addToolOutput, + currentMessages: latestMessages, + params: { + output: { answer: "The release manager" }, + tool: "answerQuestion", + toolCallId: "voice-question-2", + }, + source: "voice", + updateMessages, + }); + rejectFirstSubmission?.(new Error("First voice tool output rejected.")); + await firstSubmissionRejection; + + expect(latestMessages[0]?.metadata).toEqual({ + source: "voice", + voiceToolCallIds: ["voice-question-2"], + }); + }); + test("rolls back failed tool provenance before a typed retry", async () => { let latestMessages = [ { @@ -2012,6 +3654,34 @@ describe("AiAssistantPanel composer submissions", () => { expect(latestMessages[0]?.metadata).toBeUndefined(); }); + test("reports browser tool-output rejections through the AI SDK error state", async () => { + const addToolOutput = vi + .fn() + .mockRejectedValueOnce(new Error("The browser tool rejected its output.")) + .mockResolvedValueOnce(undefined); + + safelyAddToolOutput( + addToolOutput as Parameters[0], + { + tool: getLatestNetDefinitionToolName, + toolCallId: "tool-browser-failure", + output: { + definition: emptySDCPN, + extensions: DEFAULT_PETRINAUT_EXTENSIONS, + title: "Failure fixture", + }, + }, + ); + + await waitFor(() => expect(addToolOutput).toHaveBeenCalledTimes(2)); + expect(addToolOutput).toHaveBeenLastCalledWith({ + errorText: "The browser tool rejected its output.", + state: "output-error", + tool: getLatestNetDefinitionToolName, + toolCallId: "tool-browser-failure", + }); + }); + test("sends review chips as messages while an interactive tool is pending", async () => { const requestMessages: PetrinautAiMessage[][] = []; const transport: PetrinautAiTransport = { diff --git a/libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.tsx b/libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.tsx index df83042ed1b..0979fd72005 100644 --- a/libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.tsx +++ b/libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel.tsx @@ -1,11 +1,23 @@ import { useChat } from "@ai-sdk/react"; -import { generateId, lastAssistantMessageIsCompleteWithToolCalls } from "ai"; -import { use, useCallback, useEffect, useRef, useState } from "react"; +import { + generateId, + getStaticToolName, + isToolUIPart, + lastAssistantMessageIsCompleteWithToolCalls, + type ChatOnToolCallCallback, +} from "ai"; +import { + use, + useCallback, + useEffect, + useLayoutEffect, + useRef, + useState, +} from "react"; import { aiCommandActionInputSchemas, type AiCommandActionName, - createPetrinautAiWritableCallbacks, getLatestNetDefinitionToolName, getNetCompilationErrorsToolName, mutationActionInputSchemas as petrinautAiMutationToolInputSchemas, @@ -37,6 +49,7 @@ import { REVIEW_CHIPS, STARTER_CHIPS, } from "./ai-assistant-panel/ai-assistant-contents/prompt-chips"; +import { applyPetrinautAiMutation } from "./ai-assistant-panel/apply-petrinaut-ai-mutation"; import { createDiagnosticsAwareAiTransport } from "./ai-assistant-panel/create-diagnostics-aware-ai-transport"; import { createReasoningTimingAwareAiTransport } from "./ai-assistant-panel/create-reasoning-timing-aware-ai-transport"; import { finalizeStreamingMessageParts } from "./ai-assistant-panel/finalize-streaming-message-parts"; @@ -51,13 +64,13 @@ import { type AiToolCall, type AiToolTarget, summarizeApplyAutoLayout, - summarizePetrinautAiToolCall, toPetrinautAiToolOutput, } from "./ai-assistant-panel/tool-summaries"; import type { PetrinautAiAssistant } from "../../../petrinaut"; import type { PetrinautAiComposerControlContext, + PetrinautAiComposerStatus, PetrinautAiComposerSubmitTextResult, PetrinautAiInputMode, PetrinautAiVoiceModeContext, @@ -72,6 +85,10 @@ export type { PetrinautAiTransport, } from "./ai-assistant-panel/types"; +type PetrinautAiToolCall = Parameters< + ChatOnToolCallCallback +>[0]["toolCall"]; + const selectTarget = ( target: AiToolTarget, actions: Pick, @@ -100,9 +117,49 @@ type QueuedVoiceInput = { PetrinautAiVoiceModeContext["submitVoiceInput"] >[0]; readonly reject: (reason?: unknown) => void; + /** Detaches the input's abort listener once the queue no longer owns it. */ + readonly release: () => void; readonly resolve: (result: PetrinautAiComposerSubmitTextResult) => void; }; +type PetrinautAiMessagePart = PetrinautAiMessage["parts"][number]; +type RunnableStaticToolPart = Extract< + PetrinautAiMessagePart, + { state: "input-available" } +> & { type: `tool-${string}` }; + +/** A static browser tool call the panel still owes an execution for. */ +const isRunnableStaticToolPart = ( + part: PetrinautAiMessagePart, +): part is RunnableStaticToolPart => + isToolUIPart(part) && + part.type !== "dynamic-tool" && + part.providerExecuted !== true && + part.state === "input-available"; + +/** + * True when the last assistant message ends in static tool calls the panel + * will execute and then continue, so the turn is not over even though the AI + * SDK reports `ready`. + */ +const hasRunnableStaticToolCalls = ( + messages: PetrinautAiMessage[], +): boolean => { + const message = messages.at(-1); + return ( + message?.role === "assistant" && + !message.metadata?.stopped && + message.parts.some((part) => isRunnableStaticToolPart(part)) + ); +}; + +const voiceInputWithdrawn = (signal: AbortSignal | undefined): unknown => + signal?.reason ?? + new DOMException( + "The voice input was withdrawn before submission.", + "AbortError", + ); + const markVoiceToolOrigin = ( messages: PetrinautAiMessage[], messageId: string, @@ -110,10 +167,30 @@ const markVoiceToolOrigin = ( ): PetrinautAiMessage[] => messages.map((message) => message.id === messageId - ? { - ...message, - metadata: { ...message.metadata, source: "voice", toolCallId }, - } + ? (() => { + const previousToolCallIds = + message.metadata?.source === "voice" + ? [ + ...(message.metadata.voiceToolCallIds ?? []), + ...(message.metadata.toolCallId + ? [message.metadata.toolCallId] + : []), + ] + : []; + const { toolCallId: _legacyToolCallId, ...previousMetadata } = + message.metadata ?? {}; + + return { + ...message, + metadata: { + ...previousMetadata, + source: "voice", + voiceToolCallIds: [ + ...new Set([...previousToolCallIds, toolCallId]), + ], + }, + }; + })() : message, ); @@ -126,7 +203,25 @@ const isPetrinautAiCommandToolName = ( toolName: string, ): toolName is AiCommandActionName => toolName in aiCommandActionInputSchemas; -const safelyAddToolOutput = ( +const browserToolErrorText = (error: unknown): string => { + if (error instanceof Error && error.message.trim().length > 0) { + return error.message; + } + if (typeof error === "string" && error.trim().length > 0) { + return error; + } + try { + const serialized: unknown = JSON.stringify(error); + if (typeof serialized === "string" && serialized.length > 0) { + return serialized; + } + } catch { + // Fall through to the stable fallback for cyclic values. + } + return "The browser tool failed."; +}; + +export const safelyAddToolOutput = ( addToolOutput: ReturnType< typeof useChat >["addToolOutput"], @@ -134,10 +229,16 @@ const safelyAddToolOutput = ( ReturnType>["addToolOutput"] >[0], ) => { - // Failures here surface in the UI as an errored tool call (with the - // error message on hover), so we just swallow the rejection to avoid an - // unhandled-promise warning. - void Promise.resolve(addToolOutput(params)).catch(() => {}); + void Promise.resolve(addToolOutput(params)).catch((error: unknown) => { + void Promise.resolve( + addToolOutput({ + errorText: browserToolErrorText(error), + state: "output-error", + tool: params.tool, + toolCallId: params.toolCallId, + }), + ).catch(() => {}); + }); }; const addDynamicToolOutput = ( @@ -202,8 +303,42 @@ export const addMappedToolOutput = async ({ latestMessages.map((message) => message.id === containingMessage.id && message.metadata?.source === "voice" && - message.metadata.toolCallId === params.toolCallId - ? { ...message, metadata: previousMetadata } + (message.metadata.voiceToolCallIds?.includes(params.toolCallId) === + true || + message.metadata.toolCallId === params.toolCallId) + ? (() => { + const attributionAlreadyPresent = + previousMetadata?.source === "voice" && + (previousMetadata.voiceToolCallIds?.includes( + params.toolCallId, + ) === true || + previousMetadata.toolCallId === params.toolCallId); + const voiceToolCallIds = [ + ...(message.metadata.voiceToolCallIds ?? []), + ...(message.metadata.toolCallId + ? [message.metadata.toolCallId] + : []), + ]; + const remainingVoiceToolCallIds = attributionAlreadyPresent + ? voiceToolCallIds + : voiceToolCallIds.filter( + (candidateToolCallId) => + candidateToolCallId !== params.toolCallId, + ); + if (remainingVoiceToolCallIds.length === 0) { + return { ...message, metadata: previousMetadata }; + } + const { toolCallId: _legacyToolCallId, ...metadata } = + message.metadata; + + return { + ...message, + metadata: { + ...metadata, + voiceToolCallIds: [...new Set(remainingVoiceToolCallIds)], + }, + }; + })() : message, ), ); @@ -247,25 +382,6 @@ const waitForDiagnosticsRefresh = async ({ }); }; -const applyPetrinautAiMutation = ({ - aiToolCall, - instance, -}: { - aiToolCall: Extract; - instance: Petrinaut; -}): AiToolOutput => { - const definition = instance.definition.get(); - const toolCallbacks = createPetrinautAiWritableCallbacks(instance); - const summary = summarizePetrinautAiToolCall(aiToolCall, { definition }); - const callback = toolCallbacks[aiToolCall.toolName] as ( - input: typeof aiToolCall.input, - ) => void; - - callback(aiToolCall.input); - - return toPetrinautAiToolOutput(summary); -}; - const applyPetrinautAiCommand = async ({ aiToolCall, instance, @@ -284,19 +400,21 @@ const applyPetrinautAiCommand = async ({ } }; -export const AiAssistantPanel = ({ - aiAssistant, - initialInteractionMode, - initialMessage, - onInitialInteractionModeConsumed, - onInitialMessageConsumed, -}: { +interface AiAssistantPanelProps { aiAssistant: PetrinautAiAssistant; initialInteractionMode?: PetrinautAiInputMode | null; initialMessage?: string | null; onInitialInteractionModeConsumed?: () => void; onInitialMessageConsumed?: () => void; -}) => { +} + +const ConversationAiAssistantPanel = ({ + aiAssistant, + initialInteractionMode, + initialMessage, + onInitialInteractionModeConsumed, + onInitialMessageConsumed, +}: AiAssistantPanelProps) => { // The wrapped AI transport closes over several refs (diagnostics version, // pending mutation version, diagnostics context) so the transport's // `sendMessages` can read the latest values when it eventually runs. React @@ -333,12 +451,19 @@ export const AiAssistantPanel = ({ const [composerFocusRequest, setComposerFocusRequest] = useState(0); const [interactionMode, setInteractionMode] = useState("text"); + const [voiceDockCollapsed, setVoiceDockCollapsed] = useState(false); const interactionModeRef = useRef("text"); const selectInteractionMode = useCallback( - (nextMode: PetrinautAiInputMode) => { + ( + nextMode: PetrinautAiInputMode, + options: { collapseVoiceDock?: boolean } = {}, + ) => { const previousMode = interactionModeRef.current; interactionModeRef.current = nextMode; setInteractionMode(nextMode); + setVoiceDockCollapsed( + nextMode === "voice" && options.collapseVoiceDock === true, + ); if (previousMode === "voice" && nextMode === "text") { setComposerFocusRequest((request) => request + 1); } @@ -436,6 +561,11 @@ export const AiAssistantPanel = ({ // response. Cleared whenever a new turn begins so it never lingers across // sends or a fresh conversation. const [stopped, setStopped] = useState(false); + // The SDK reports `ready` between a step that ended in client tool calls and + // the follow-up it sends automatically. That gap is not the end of the turn, + // so hosts keep seeing a busy conversation until the follow-up starts or a + // Stop withholds it. + const [continuationPending, setContinuationPending] = useState(false); const requestInputMode = useCallback( (nextMode: PetrinautAiInputMode) => { @@ -486,9 +616,16 @@ export const AiAssistantPanel = ({ // invalidates the host's active generation. end: () => requestInputMode("text"), pause: () => controls.pause(), + ...(controls.readFullResponse + ? { readFullResponse: () => controls.readFullResponse?.() } + : {}), reconnect: () => controls.reconnect(), + ...(controls.repeatQuestion + ? { repeatQuestion: () => controls.repeatQuestion?.() } + : {}), resume: () => controls.resume(), setMicrophoneMuted: (muted) => controls.setMicrophoneMuted(muted), + ...(controls.takeTurn ? { takeTurn: () => controls.takeTurn?.() } : {}), }); return () => { @@ -503,7 +640,281 @@ export const AiAssistantPanel = ({ ); const stopRequestedRef = useRef(false); + // Advances on composer submissions and conversation changes so late work + // cannot settle, stop, or continue a replacement turn. + const submissionGenerationRef = useRef(0); + const toolHostIdentityRef = useRef(null); const pendingSubmissionRecoveryRef = useRef<(() => void) | null>(null); + const hydratedConversationIdRef = useRef(null); + const automaticToolCallExecutionsRef = useRef(new Set()); + const pendingAutomaticToolCallExecutionsRef = useRef(new Set()); + const automaticToolTerminationRef = useRef<{ + generation: number; + kind: "stopped" | "failed"; + } | null>(null); + const automaticToolExecutionTimersRef = useRef( + new Map, string>(), + ); + // AI SDK's implicit addToolOutput continuation races its stream-to-ready + // cleanup. Static browser tools instead await output and explicitly continue. + const automaticToolContinuationTimerRef = useRef | null>(null); + const suppressedAutomaticSendsRef = useRef(0); + const addToolOutputRef = useRef< + ReturnType>["addToolOutput"] | null + >(null); + const sendAutomaticToolContinuationRef = useRef<(() => Promise) | null>( + null, + ); + // Stop was pressed during the step that just ended in client tool calls. + // Flue had nothing left to abort once that step settled, so withholding the + // follow-up is what makes the Stop real. + const withholdContinuationForStop = () => { + stopRequestedRef.current = false; + setContinuationPending(false); + setStreamError(null); + setStopped(true); + }; + const automaticToolTurnIsTerminated = (generation: number): boolean => { + const termination = automaticToolTerminationRef.current; + if (termination?.generation !== generation) return false; + if (termination.kind === "stopped") withholdContinuationForStop(); + return true; + }; + const automaticToolTurnIsTerminatedRef = useLatest( + automaticToolTurnIsTerminated, + ); + const addAutomaticToolOutputForGeneration = async ( + params: Parameters< + ReturnType>["addToolOutput"] + >[0], + generation: number, + executionConversationId: string, + ): Promise => { + const executionKey = `${executionConversationId}:${params.toolCallId}`; + const canContinue = () => + generation === submissionGenerationRef.current && + executionConversationId === toolHostIdentityRef.current && + !automaticToolTurnIsTerminated(generation); + if (!canContinue()) { + pendingAutomaticToolCallExecutionsRef.current.delete(executionKey); + return; + } + const currentAddToolOutput = addToolOutputRef.current; + if (currentAddToolOutput === null) { + throw new Error("The AI assistant tool host is not ready."); + } + pendingAutomaticToolCallExecutionsRef.current.delete(executionKey); + // Prevent addToolOutput's fire-and-forget continuation from racing the + // explicit continuation chained to its promise below. + suppressedAutomaticSendsRef.current += 1; + await Promise.resolve() + .then(() => currentAddToolOutput(params)) + .then( + () => { + suppressedAutomaticSendsRef.current -= 1; + }, + (caught: unknown) => { + suppressedAutomaticSendsRef.current -= 1; + throw caught; + }, + ); + + if (!canContinue()) return; + }; + + const executeToolCall: ChatOnToolCallCallback = async ({ + toolCall, + }) => { + const generation = submissionGenerationRef.current; + const executionConversationId = toolHostIdentityRef.current; + if (executionConversationId === null) { + throw new Error("The AI assistant tool host is not ready."); + } + const addAutomaticToolOutput = ( + params: Parameters[0], + ) => + addAutomaticToolOutputForGeneration( + params, + generation, + executionConversationId, + ); + if (!instance) { + throw new Error( + "The AI assistant cannot run without an editor instance.", + ); + } + + if (toolCall.dynamic) { + resolveDynamicInteractiveTool( + toolCall.toolName, + toolCall.input, + aiAssistant.interactiveTools ?? [], + ); + return; + } + + if (toolCall.toolName === getLatestNetDefinitionToolName) { + await addAutomaticToolOutput({ + tool: toolCall.toolName, + toolCallId: toolCall.toolCallId, + output: { + title: titleRef.current, + definition: instance.definition.get(), + extensions: instance.extensions, + }, + }); + return; + } + + if (toolCall.toolName === getNetCompilationErrorsToolName) { + await waitForDiagnosticsRefresh({ + consumePendingMutationDiagnosticsVersion: () => { + const pendingVersion = pendingMutationDiagnosticsVersionRef.current; + pendingMutationDiagnosticsVersionRef.current = null; + return pendingVersion; + }, + diagnosticsVersionRef, + }); + await addAutomaticToolOutput({ + tool: toolCall.toolName, + toolCallId: toolCall.toolCallId, + output: diagnosticsContextRef.current, + }); + return; + } + + if (toolCall.toolName === readPetrinautDocToolName) { + const { doc } = readPetrinautDocToolInputSchema.parse(toolCall.input); + await addAutomaticToolOutput({ + tool: toolCall.toolName, + toolCallId: toolCall.toolCallId, + output: petrinautDocsContent[doc], + }); + return; + } + + if (toolCall.toolName === setNetTitleToolName) { + const setNetTitleReadOnlyReason = readOnlyReasonRef.current; + if (setNetTitleReadOnlyReason !== null) { + await addAutomaticToolOutput({ + tool: toolCall.toolName, + toolCallId: toolCall.toolCallId, + output: { + applied: false, + blocked: setNetTitleReadOnlyReason.kind, + reason: formatReadOnlyReason(setNetTitleReadOnlyReason), + } satisfies AiToolOutput, + }); + return; + } + + const parsedSetNetTitleInput = setNetTitleToolInputSchema.parse( + toolCall.input, + ); + const previousTitle = titleRef.current; + setTitle(parsedSetNetTitleInput.title); + + await addAutomaticToolOutput({ + tool: toolCall.toolName, + toolCallId: toolCall.toolCallId, + output: { + applied: true, + title: `Renamed net to "${parsedSetNetTitleInput.title}"`, + detail: + previousTitle && previousTitle !== parsedSetNetTitleInput.title + ? `Previous title: ${previousTitle}` + : undefined, + } satisfies AiToolOutput, + }); + return; + } + + const toolName = toolCall.toolName; + if ( + !isPetrinautAiMutationToolName(toolName) && + !isPetrinautAiCommandToolName(toolName) + ) { + throw new Error(`Unknown AI tool: ${String(toolName as string)}`); + } + + const currentReadOnlyReason = readOnlyReasonRef.current; + if (currentReadOnlyReason !== null) { + const isSimulateAllowedMutation = + isPetrinautAiMutationToolName(toolName) && + simulateModeAllowedMutationNames.has(toolName); + const allowedDespiteReadOnly = + isSimulateAllowedMutation && + currentReadOnlyReason.kind !== "host-readonly"; + + if (!allowedDespiteReadOnly) { + await addAutomaticToolOutput({ + tool: toolName, + toolCallId: toolCall.toolCallId, + output: { + applied: false, + blocked: currentReadOnlyReason.kind, + reason: formatReadOnlyReason(currentReadOnlyReason), + } satisfies AiToolOutput, + }); + return; + } + } + + if (isPetrinautAiCommandToolName(toolName)) { + const commandInput = aiCommandActionInputSchemas[toolName].parse( + toolCall.input, + ); + if ( + getInteractiveTool(toolName, commandInput, aiAssistant.interactiveTools) + ) { + return; + } + + pendingMutationDiagnosticsVersionRef.current = + diagnosticsVersionRef.current; + + const aiToolCall = { + toolName, + input: commandInput, + } as Extract; + + const output = await applyPetrinautAiCommand({ + aiToolCall, + instance, + }); + await addAutomaticToolOutput({ + tool: toolName, + toolCallId: toolCall.toolCallId, + output, + }); + return; + } + + const toolInput = petrinautAiMutationToolInputSchemas[toolName].parse( + toolCall.input, + ); + + pendingMutationDiagnosticsVersionRef.current = + diagnosticsVersionRef.current; + + const aiToolCall = { + toolName, + input: toolInput, + } as Extract; + + const output = applyPetrinautAiMutation({ + aiToolCall, + instance, + }); + + await addAutomaticToolOutput({ + tool: toolName, + toolCallId: toolCall.toolCallId, + output, + }); + }; const { error, @@ -512,7 +923,7 @@ export const AiAssistantPanel = ({ addToolOutput, sendMessage, setMessages, - status, + status: chatStatus, stop, } = useChat({ ...(aiAssistant.conversationId === undefined @@ -520,7 +931,25 @@ export const AiAssistantPanel = ({ : { id: aiAssistant.conversationId }), messages: aiAssistant.messages, transport: diagnosticsTransportState.transport, - sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls, + // Interactive tools retain AI SDK's native continuation; static tools + // suppress it while addAutomaticToolOutput owns the explicit chain. + sendAutomaticallyWhen: ({ messages: currentMessages }) => { + if ( + suppressedAutomaticSendsRef.current !== 0 || + !lastAssistantMessageIsCompleteWithToolCalls({ + messages: currentMessages, + }) + ) { + return false; + } + if (!stopRequestedRef.current) { + // Left pending until the follow-up's own status change lands, so hosts + // never observe the `ready` between this check and that request. + return true; + } + withholdContinuationForStop(); + return false; + }, // Without throttling, every reasoning-delta / text-delta chunk triggers a // full re-render of `AiAssistantContents`, and the SDK `structuredClone`s // the active message on each one. For a long markdown reply that locks @@ -535,8 +964,19 @@ export const AiAssistantPanel = ({ pendingSubmissionRecoveryRef.current = null; recoverPendingSubmission?.(); }, - onFinish: ({ messages: finishedMessages, isAbort }) => { + onFinish: ({ messages: finishedMessages, isAbort, isError }) => { pendingSubmissionRecoveryRef.current = null; + // A step that ended in client tool calls is followed automatically by + // the SDK unless it was aborted or errored; that follow-up is still part + // of this turn. + const followUpPending = + !isAbort && + !isError && + (lastAssistantMessageIsCompleteWithToolCalls({ + messages: finishedMessages, + }) || + hasRunnableStaticToolCalls(finishedMessages)); + setContinuationPending(followUpPending); if (isAbort) { // The SDK fires `onFinish` for every abort. Only act on a deliberate // Stop — clearing the chat or unmounting also aborts, and those paths @@ -560,202 +1000,237 @@ export const AiAssistantPanel = ({ return; } + aiAssistant.onMessages?.(finishedMessages); + if (followUpPending) { + // The turn is not over: a Stop pressed during this step must still be + // able to withhold the follow-up, so its intent survives this step. + return; + } + // A response that runs to completion clears any pending Stop intent so a // later incidental abort can't replay the deliberate-stop path, and // drops a stale "Response stopped" note left over from an earlier turn. stopRequestedRef.current = false; setStreamError(null); setStopped(false); - aiAssistant.onMessages?.(finishedMessages); }, - onToolCall: async ({ toolCall }) => { - if (!instance) { - throw new Error( - "The AI assistant cannot run without an editor instance.", - ); - } - - if (toolCall.dynamic) { - resolveDynamicInteractiveTool( - toolCall.toolName, - toolCall.input, - aiAssistant.interactiveTools ?? [], - ); - return; - } - - if (toolCall.toolName === getLatestNetDefinitionToolName) { - safelyAddToolOutput(addToolOutput, { - tool: toolCall.toolName, - toolCallId: toolCall.toolCallId, - output: { - title: titleRef.current, - definition: instance.definition.get(), - extensions: instance.extensions, - }, - }); - return; + // AI SDK does not auto-submit outputs added while a response is still + // streaming. The ready-state effect below owns static tool execution. + onToolCall: ({ toolCall }) => + toolCall.dynamic ? executeToolCall({ toolCall }) : undefined, + }); + useLayoutEffect(() => { + toolHostIdentityRef.current = conversationId; + addToolOutputRef.current = addToolOutput; + sendAutomaticToolContinuationRef.current = () => sendMessage(); + return () => { + if (addToolOutputRef.current === addToolOutput) { + addToolOutputRef.current = null; } + sendAutomaticToolContinuationRef.current = null; + toolHostIdentityRef.current = null; + }; + }, [addToolOutput, conversationId, sendMessage]); + useEffect(() => { + if ( + chatStatus !== "ready" || + !continuationPending || + pendingAutomaticToolCallExecutionsRef.current.size > 0 || + !lastAssistantMessageIsCompleteWithToolCalls({ messages }) || + automaticToolContinuationTimerRef.current !== null + ) { + return; + } - if (toolCall.toolName === getNetCompilationErrorsToolName) { - await waitForDiagnosticsRefresh({ - consumePendingMutationDiagnosticsVersion: () => { - const pendingVersion = pendingMutationDiagnosticsVersionRef.current; - pendingMutationDiagnosticsVersionRef.current = null; - return pendingVersion; - }, - diagnosticsVersionRef, - }); - safelyAddToolOutput(addToolOutput, { - tool: toolCall.toolName, - toolCallId: toolCall.toolCallId, - output: diagnosticsContextRef.current, - }); + const generation = submissionGenerationRef.current; + automaticToolContinuationTimerRef.current = setTimeout(() => { + automaticToolContinuationTimerRef.current = null; + if ( + generation !== submissionGenerationRef.current || + toolHostIdentityRef.current !== conversationId || + automaticToolTurnIsTerminatedRef.current(generation) + ) { return; } - - if (toolCall.toolName === readPetrinautDocToolName) { - const { doc } = readPetrinautDocToolInputSchema.parse(toolCall.input); - safelyAddToolOutput(addToolOutput, { - tool: toolCall.toolName, - toolCallId: toolCall.toolCallId, - output: petrinautDocsContent[doc], - }); + const sendContinuation = sendAutomaticToolContinuationRef.current; + if (sendContinuation === null) { + setContinuationPending(false); + setStreamError(new Error("The AI assistant tool host is not ready.")); return; } - - if (toolCall.toolName === setNetTitleToolName) { - const setNetTitleReadOnlyReason = readOnlyReasonRef.current; - if (setNetTitleReadOnlyReason !== null) { - safelyAddToolOutput(addToolOutput, { - tool: toolCall.toolName, - toolCallId: toolCall.toolCallId, - output: { - applied: false, - blocked: setNetTitleReadOnlyReason.kind, - reason: formatReadOnlyReason(setNetTitleReadOnlyReason), - } satisfies AiToolOutput, - }); - return; - } - - const parsedSetNetTitleInput = setNetTitleToolInputSchema.parse( - toolCall.input, + void sendContinuation().catch((caught: unknown) => { + if (generation !== submissionGenerationRef.current) return; + setContinuationPending(false); + setStreamError( + caught instanceof Error ? caught : new Error(String(caught)), ); - const previousTitle = titleRef.current; - setTitle(parsedSetNetTitleInput.title); - - safelyAddToolOutput(addToolOutput, { - tool: toolCall.toolName, - toolCallId: toolCall.toolCallId, - output: { - applied: true, - title: `Renamed net to "${parsedSetNetTitleInput.title}"`, - detail: - previousTitle && previousTitle !== parsedSetNetTitleInput.title - ? `Previous title: ${previousTitle}` - : undefined, - } satisfies AiToolOutput, - }); - return; + }); + }, 0); + }, [ + automaticToolTurnIsTerminatedRef, + chatStatus, + continuationPending, + conversationId, + messages, + ]); + useEffect( + () => () => { + for (const [ + timer, + executionKey, + ] of automaticToolExecutionTimersRef.current) { + clearTimeout(timer); + // Cancelled-before-start work is claimable on StrictMode's next setup. + automaticToolCallExecutionsRef.current.delete(executionKey); + pendingAutomaticToolCallExecutionsRef.current.delete(executionKey); } - - const toolName = toolCall.toolName; - if ( - !isPetrinautAiMutationToolName(toolName) && - !isPetrinautAiCommandToolName(toolName) - ) { - throw new Error(`Unknown AI tool: ${String(toolName as string)}`); - } - - const currentReadOnlyReason = readOnlyReasonRef.current; - if (currentReadOnlyReason !== null) { - // Scenario and metric mutations stay live in simulate mode and - // during an active simulation — the Simulate panel itself drives - // them, so `usePetrinautMutations` only blocks them when the host - // is fully read-only. Mirror that here so the assistant can do - // what the UI already permits. - const isSimulateAllowedMutation = - isPetrinautAiMutationToolName(toolName) && - simulateModeAllowedMutationNames.has(toolName); - const allowedDespiteReadOnly = - isSimulateAllowedMutation && - currentReadOnlyReason.kind !== "host-readonly"; - - if (!allowedDespiteReadOnly) { - safelyAddToolOutput(addToolOutput, { - tool: toolName, - toolCallId: toolCall.toolCallId, - output: { - applied: false, - blocked: currentReadOnlyReason.kind, - reason: formatReadOnlyReason(currentReadOnlyReason), - } satisfies AiToolOutput, - }); - return; - } + automaticToolExecutionTimersRef.current.clear(); + if (automaticToolContinuationTimerRef.current !== null) { + clearTimeout(automaticToolContinuationTimerRef.current); + automaticToolContinuationTimerRef.current = null; } + }, + [conversationId], + ); + const executeToolCallRef = useLatest(executeToolCall); + const submissionConversationIdRef = useRef(conversationId); + useLayoutEffect(() => { + if (submissionConversationIdRef.current === conversationId) return; + submissionConversationIdRef.current = conversationId; + submissionGenerationRef.current += 1; + stopRequestedRef.current = false; + setContinuationPending(false); + setStreamError(null); + setStopped(false); + }, [conversationId]); + const status: PetrinautAiComposerStatus = + chatStatus === "ready" && streamError !== null + ? "error" + : continuationPending && chatStatus === "ready" + ? "submitted" + : chatStatus; - if (isPetrinautAiCommandToolName(toolName)) { - const commandInput = aiCommandActionInputSchemas[toolName].parse( - toolCall.input, - ); - if ( - getInteractiveTool( - toolName, - commandInput, - aiAssistant.interactiveTools, - ) - ) { - // Defer: the surface will render the widget and call - // onInteractiveToolSubmit when the user decides. - return; - } + useEffect(() => { + if ( + aiAssistant.messages === undefined || + status !== "ready" || + hydratedConversationIdRef.current === conversationId + ) { + return; + } + if (aiAssistant.messages.length === 0 && messages.length === 0) { + return; + } + // A turn submitted before the host's history arrived is already visible + // locally. A snapshot that predates it would erase that turn and latch, so + // wait for a snapshot that carries every locally streamed reply. + const canonicalMessageIds = new Set( + aiAssistant.messages.map((message) => message.id), + ); + if ( + messages.some( + (message) => + message.role === "assistant" && !canonicalMessageIds.has(message.id), + ) + ) { + return; + } + hydratedConversationIdRef.current = conversationId; + setMessages(aiAssistant.messages); + }, [aiAssistant.messages, conversationId, messages, setMessages, status]); - pendingMutationDiagnosticsVersionRef.current = - diagnosticsVersionRef.current; + useEffect(() => { + // Keyed on the SDK's own status: the derived composer status stays busy + // for exactly the continuation this effect drives. + if (chatStatus !== "ready") { + return; + } - const aiToolCall = { - toolName, - input: commandInput, - } as Extract; + for (const message of messages) { + if (message.metadata?.stopped) continue; + for (const part of message.parts) { + if (!isRunnableStaticToolPart(part)) { + continue; + } - const output = await applyPetrinautAiCommand({ - aiToolCall, - instance, - }); - safelyAddToolOutput(addToolOutput, { - tool: toolName, - toolCallId: toolCall.toolCallId, - output, - }); - return; + const toolCall = { + dynamic: false, + input: part.input, + toolCallId: part.toolCallId, + toolName: getStaticToolName(part), + } as Extract; + const executionKey = `${conversationId}:${toolCall.toolCallId}`; + if (automaticToolCallExecutionsRef.current.has(executionKey)) continue; + automaticToolCallExecutionsRef.current.add(executionKey); + pendingAutomaticToolCallExecutionsRef.current.add(executionKey); + const generation = submissionGenerationRef.current; + // Hydrated calls have no onFinish; claim both their execution and busy + // state before scheduling, so another render cannot queue them again. + setContinuationPending(true); + const timer = setTimeout(() => { + automaticToolExecutionTimersRef.current.delete(timer); + if ( + generation !== submissionGenerationRef.current || + toolHostIdentityRef.current !== conversationId + ) { + pendingAutomaticToolCallExecutionsRef.current.delete(executionKey); + return; + } + if (automaticToolTurnIsTerminatedRef.current(generation)) { + pendingAutomaticToolCallExecutionsRef.current.delete(executionKey); + return; + } + void Promise.resolve() + .then(() => executeToolCallRef.current({ toolCall })) + .catch(async (caught: unknown) => { + pendingAutomaticToolCallExecutionsRef.current.delete( + executionKey, + ); + if ( + generation !== submissionGenerationRef.current || + toolHostIdentityRef.current !== conversationId + ) + return; + if (automaticToolTurnIsTerminatedRef.current(generation)) return; + automaticToolTerminationRef.current = { + generation, + kind: "failed", + }; + setContinuationPending(false); + setStreamError( + caught instanceof Error + ? caught + : new Error(browserToolErrorText(caught)), + ); + // A static failure belongs to this call, not just the toast. Do + // not let recording its error trigger an implicit continuation. + suppressedAutomaticSendsRef.current += 1; + await Promise.resolve() + .then(() => + addToolOutputRef.current?.({ + tool: toolCall.toolName, + toolCallId: toolCall.toolCallId, + state: "output-error", + errorText: browserToolErrorText(caught), + }), + ) + .catch(() => {}) + .then(() => { + suppressedAutomaticSendsRef.current -= 1; + }); + }); + }, 0); + automaticToolExecutionTimersRef.current.set(timer, executionKey); } - - const toolInput = petrinautAiMutationToolInputSchemas[toolName].parse( - toolCall.input, - ); - - pendingMutationDiagnosticsVersionRef.current = - diagnosticsVersionRef.current; - - const aiToolCall = { - toolName, - input: toolInput, - } as Extract; - - const output = applyPetrinautAiMutation({ - aiToolCall, - instance, - }); - - safelyAddToolOutput(addToolOutput, { - tool: toolName, - toolCallId: toolCall.toolCallId, - output, - }); - }, - }); + } + }, [ + automaticToolTurnIsTerminatedRef, + chatStatus, + conversationId, + executeToolCallRef, + messages, + toolHostIdentityRef, + ]); const composerSubmissionStateRef = useLatest({ addToolOutput, @@ -799,8 +1274,8 @@ export const AiAssistantPanel = ({ target?: "auto" | "message"; text: string; }): Promise => { - const trimmed = text.trim(); - if (!trimmed) { + const submissionText = source === "voice" ? text : text.trim(); + if (!submissionText.trim()) { const submissionError = new Error( "AI assistant text must not be empty.", ); @@ -879,7 +1354,7 @@ export const AiAssistantPanel = ({ try { output = mappedToolCall.mapText({ input: mappedToolCall.input, - text: trimmed, + text: submissionText, }); } catch (caught) { const submissionError = @@ -894,6 +1369,7 @@ export const AiAssistantPanel = ({ setStreamError(null); setStopped(false); stopRequestedRef.current = false; + submissionGenerationRef.current += 1; composerToolSubmissionsRef.current.add(mappedToolCall.toolCallId); try { await addMappedToolOutput({ @@ -928,10 +1404,11 @@ export const AiAssistantPanel = ({ setStreamError(null); setStopped(false); stopRequestedRef.current = false; + submissionGenerationRef.current += 1; await submitMessage({ id: messageId, ...(source === "voice" ? { metadata: { source } } : {}), - parts: [{ text: trimmed, type: "text" }], + parts: [{ text: submissionText, type: "text" }], role: "user", }); return { kind: "message", messageId }; @@ -939,7 +1416,11 @@ export const AiAssistantPanel = ({ [composerSubmissionStateRef], ); - const stopStateRef = useLatest({ status, stop }); + const stopStateRef = useLatest({ + requestStop: aiAssistant.requestStop, + status, + stop, + }); const submitVoiceInput = useCallback< PetrinautAiVoiceModeContext["submitVoiceInput"] @@ -960,11 +1441,28 @@ export const AiAssistantPanel = ({ return submitText({ ...voiceInput, source: "voice" }); } + const { signal } = voiceInput; + if (signal?.aborted) { + return Promise.reject(voiceInputWithdrawn(signal)); + } + setVoiceInputQueued(true); return new Promise((resolve, reject) => { + const withdraw = (): void => { + // Only the entry still holding this input may be withdrawn; a + // dequeued input has already been handed to the composer. + if (queuedVoiceInputRef.current?.input !== voiceInput) { + return; + } + queuedVoiceInputRef.current = null; + setVoiceInputQueued(false); + reject(voiceInputWithdrawn(signal)); + }; + signal?.addEventListener("abort", withdraw, { once: true }); queuedVoiceInputRef.current = { input: voiceInput, reject, + release: () => signal?.removeEventListener("abort", withdraw), resolve, }; }); @@ -980,6 +1478,7 @@ export const AiAssistantPanel = ({ if (status === "error") { queuedVoiceInputRef.current = null; setVoiceInputQueued(false); + queued.release(); queued.reject(new Error("Voice mode could not accept that input.")); return; } @@ -989,6 +1488,7 @@ export const AiAssistantPanel = ({ queuedVoiceInputRef.current = null; setVoiceInputQueued(false); + queued.release(); void submitText({ ...queued.input, source: "voice" }).then( (result) => queued.resolve(result), (caught: unknown) => queued.reject(caught), @@ -997,9 +1497,9 @@ export const AiAssistantPanel = ({ useEffect( () => () => { - queuedVoiceInputRef.current?.reject( - new Error("The voice conversation changed."), - ); + const queued = queuedVoiceInputRef.current; + queued?.release(); + queued?.reject(new Error("The voice conversation changed.")); queuedVoiceInputRef.current = null; setVoiceInputQueued(false); }, @@ -1008,13 +1508,40 @@ export const AiAssistantPanel = ({ // Like submitText, stop is exposed to host controls and must stay stable. const stopComposer = useCallback(async () => { - const { status: currentStatus, stop: stopCurrentResponse } = - stopStateRef.current; + const { + requestStop, + status: currentStatus, + stop: stopCurrentResponse, + } = stopStateRef.current; if (currentStatus !== "submitted" && currentStatus !== "streaming") { return; } + const generation = submissionGenerationRef.current; + automaticToolTerminationRef.current = { generation, kind: "stopped" }; stopRequestedRef.current = true; + if (requestStop !== undefined) { + try { + const result = await requestStop(); + if (submissionGenerationRef.current !== generation) { + // A newer turn started while the durable stop was in flight; that + // turn owns its own Stop and must not inherit this result. + return; + } + if (result === "stop-requested") { + await stopCurrentResponse(); + } + } catch (caught) { + if (submissionGenerationRef.current !== generation) { + return; + } + stopRequestedRef.current = false; + setStreamError( + caught instanceof Error ? caught : new Error(String(caught)), + ); + } + return; + } await stopCurrentResponse(); }, [stopStateRef]); @@ -1115,12 +1642,14 @@ export const AiAssistantPanel = ({ return; } - selectInteractionMode( + const nextMode = initialInteractionMode === "voice" && - aiAssistant.renderVoiceMode === undefined + aiAssistant.renderVoiceMode === undefined ? "text" - : initialInteractionMode, - ); + : initialInteractionMode; + selectInteractionMode(nextMode, { + collapseVoiceDock: nextMode === "voice", + }); consumedInitialInteractionModeRef.current = initialInteractionMode; onInitialInteractionModeConsumed?.(); }, [ @@ -1193,6 +1722,7 @@ export const AiAssistantPanel = ({ conversationId, messages, status, + stopped, stop: stopComposer, submitText, }; @@ -1217,7 +1747,9 @@ export const AiAssistantPanel = ({ return ( { + submissionGenerationRef.current += 1; // Clearing aborts any in-flight response too, which fires `onFinish` // with `isAbort`. Drop the stop flag first so that handler treats this // as an incidental abort and doesn't repopulate or persist the @@ -1238,6 +1771,7 @@ export const AiAssistantPanel = ({ setInput(""); setStreamError(null); setStopped(false); + setContinuationPending(false); setMessages([]); aiAssistant.onMessages?.([]); aiAssistant.onClearMessages?.(); @@ -1246,6 +1780,7 @@ export const AiAssistantPanel = ({ voiceModeControlsRef.current?.pause(); setAiAssistantOpen(false); }} + onCollapsedVoiceEnd={() => setAiAssistantOpen(false)} onInputChange={setInput} onInputModeChange={selectInteractionMode} onInteractiveToolSubmit={({ toolCallId, toolName, output }) => { @@ -1324,13 +1859,23 @@ export const AiAssistantPanel = ({ void stopComposer(); }} onSubmit={submitComposerInput} + onVoiceDockCollapsedChange={setVoiceDockCollapsed} promptChips={promptChips} rightOffset={hasSelection ? propertiesPanelWidth + PANEL_MARGIN : 0} status={status} stopped={stopped} voiceHandoffPending={voiceHandoffPending} + voiceDockCollapsed={voiceDockCollapsed} voiceMode={voiceMode} voiceModeAvailable={aiAssistant.renderVoiceMode !== undefined} /> ); }; + +/** Replace every conversation-owned hook and callback together when identity changes. */ +export const AiAssistantPanel = (props: AiAssistantPanelProps) => ( + +); diff --git a/libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel/ai-assistant-contents.stories.tsx b/libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel/ai-assistant-contents.stories.tsx index c21fe5af927..c6e9c98b7b3 100644 --- a/libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel/ai-assistant-contents.stories.tsx +++ b/libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel/ai-assistant-contents.stories.tsx @@ -1,4 +1,5 @@ import { type ReactNode, useState } from "react"; +import { userEvent, within } from "storybook/test"; import { Button } from "@hashintel/ds-components"; import { css } from "@hashintel/ds-helpers/css"; @@ -244,6 +245,7 @@ const HostVoiceSlotPreview = () => ( const Frame = ({ error, + initialVoiceDockCollapsed = false, inputMode = "text", messages, status = "ready", @@ -253,6 +255,7 @@ const Frame = ({ voiceSession, }: { error?: Error; + initialVoiceDockCollapsed?: boolean; inputMode?: "text" | "voice"; messages: PetrinautAiMessage[]; status?: "submitted" | "streaming" | "ready" | "error"; @@ -262,6 +265,9 @@ const Frame = ({ voiceSession?: PetrinautAiVoiceSessionState; }) => { const [input, setInput] = useState(""); + const [voiceDockCollapsed, setVoiceDockCollapsed] = useState( + initialVoiceDockCollapsed, + ); // Stands in for the host, which reports session state rather than rendering // the live surfaces itself. const [voiceSessionStore] = useState(() => { @@ -291,8 +297,10 @@ const Frame = ({ onInputModeChange={() => {}} onStop={() => {}} onSubmit={() => setInput("")} + onVoiceDockCollapsedChange={setVoiceDockCollapsed} status={status} stopped={stopped} + voiceDockCollapsed={voiceDockCollapsed} voiceMode={voiceMode} voiceModeAvailable={voiceModeAvailable} /> @@ -330,6 +338,18 @@ export const VoiceModeAwaitingConsent: Story = { ), }; +export const VoiceModeAwaitingConsentCompact: Story = { + render: () => ( + } + voiceModeAvailable + /> + ), +}; + export const VoiceSessionListening: Story = { render: () => ( ( + } + voiceModeAvailable + voiceSession={liveSession({ microphoneLevel: 0.6 })} + /> + ), + play: async ({ canvasElement }) => { + await userEvent.click( + within(canvasElement).getByRole("button", { + name: "Collapse voice session", + }), + ); + }, +}; + export const VoiceSessionSpeaking: Story = { render: () => ( + ...singleToolCallMessage, + parts: singleToolCallMessage.parts.map((part) => part.type.startsWith("tool-") ? { ...part, diff --git a/libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel/ai-assistant-contents.test.tsx b/libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel/ai-assistant-contents.test.tsx index ee2d2d8c6f7..7bfb76a8df4 100644 --- a/libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel/ai-assistant-contents.test.tsx +++ b/libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel/ai-assistant-contents.test.tsx @@ -44,26 +44,84 @@ vi.mock("react-markdown", async (importOriginal) => { }); const noop = () => {}; +const initialClipboardDescriptor = Object.getOwnPropertyDescriptor( + navigator, + "clipboard", +); // The voice ribbon asks for a 2D context on mount. jsdom has no canvas, and // answering with `null` takes the same branch a browser without one would, // instead of letting jsdom log a not-implemented error per render. beforeAll(() => { vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockReturnValue(null); + vi.stubGlobal( + "ResizeObserver", + class { + public disconnect() {} + public observe() {} + public unobserve() {} + }, + ); }); afterEach(() => { cleanup(); vi.clearAllMocks(); vi.useRealTimers(); + if (initialClipboardDescriptor === undefined) { + Reflect.deleteProperty(navigator, "clipboard"); + } else { + Object.defineProperty(navigator, "clipboard", initialClipboardDescriptor); + } }); describe("AiAssistantContents", () => { + test("labels stopped history after a later completed reply without global Stop state", () => { + render( + + + , + ); + expect(screen.getByText("Partial reply")).not.toBeNull(); + expect(screen.getByText("Later completed reply")).not.toBeNull(); + expect(screen.getAllByText("Response stopped")).toHaveLength(1); + }); + test("shows assistant errors as toasts instead of transcript messages", async () => { + const writeText = vi.fn().mockResolvedValue(undefined); + Object.defineProperty(navigator, "clipboard", { + configurable: true, + value: { writeText }, + }); render( { ); const toast = await waitFor(() => { - const element = document.querySelector( + const element = document.querySelector( '[data-scope="toast"][data-part="root"]', ); expect(element).not.toBeNull(); return element!; }); - expect(toast.textContent).toBe("Failed to fetch"); + expect( + toast.querySelector('[data-scope="toast"][data-part="title"]') + ?.textContent, + ).toBe("AI assistant error"); + expect( + toast.querySelector('[data-scope="toast"][data-part="description"]') + ?.textContent, + ).toBe( + 'Elicitor failed.\nCaused by: {"field":"answer","reason":"Required"}', + ); + fireEvent.click( + within(toast).getByRole("button", { name: "Copy details" }), + ); + expect(writeText).toHaveBeenCalledWith( + 'Elicitor failed.\nCaused by: {"field":"answer","reason":"Required"}', + ); expect( within(screen.getByTestId("ai-transcript")).queryByText( - "Failed to fetch", + "AI assistant error", ), ).toBeNull(); + fireEvent.click( + within(toast).getByRole("button", { name: "Close notification" }), + ); + await waitFor(() => + expect(toast.getAttribute("data-state")).toBe("closed"), + ); }); test("keeps one Voice mode slot mounted above the composer when the panel closes", () => { @@ -137,8 +216,9 @@ describe("AiAssistantContents", () => { expect(voiceModeUnmounts).toBe(0); }); - test("swaps the composer for the dock while a session runs, and defers its spoken turns", () => { + test("shows spoken turns live and collapses an active session without unmounting the panel", () => { const store = createVoiceSessionStore(); + const onCollapsedVoiceEnd = vi.fn(); const actions = { end: vi.fn(), pause: vi.fn(), @@ -160,21 +240,55 @@ describe("AiAssistantContents", () => { parts: [{ type: "text", text: "Earlier answer" }], }, ] as PetrinautAiMessage[]; - const renderWith = (messages: PetrinautAiMessage[]) => ( - - - - ); + const liveMessages = [ + ...earlierMessages, + { + id: "spoken-user", + metadata: { source: "voice" }, + role: "user", + parts: [{ type: "text", text: "Spoken request" }], + }, + { + id: "spoken-assistant", + role: "assistant", + parts: [{ type: "text", text: "Spoken reply" }], + }, + { + id: "typed-user", + role: "user", + parts: [{ type: "text", text: "Typed aside" }], + }, + ] as PetrinautAiMessage[]; + const VoiceContents = ({ + inputMode = "voice", + messages, + }: { + inputMode?: "text" | "voice"; + messages: PetrinautAiMessage[]; + }) => { + const [collapsed, setCollapsed] = useState(false); + + return ( + + Host Voice controls} + /> + + ); + }; - const { rerender } = render(renderWith(earlierMessages)); + const { rerender } = render(); const dock = screen.getByRole("region", { name: "Voice session" }); expect(within(dock).getByText("Listening")).not.toBeNull(); @@ -182,69 +296,139 @@ describe("AiAssistantContents", () => { screen.queryByRole("textbox", { name: "Message AI assistant" }), ).toBeNull(); expect(screen.getByText("Earlier answer")).not.toBeNull(); + expect( + within(dock) + .getByRole("button", { name: "Collapse voice session" }) + .getAttribute("aria-expanded"), + ).toBeNull(); - rerender( - renderWith([ - ...earlierMessages, - { - id: "spoken-user", - metadata: { source: "voice" }, - role: "user", - parts: [{ type: "text", text: "Spoken request" }], - }, - { - id: "spoken-assistant", - role: "assistant", - parts: [{ type: "text", text: "Spoken reply" }], - }, - { - id: "typed-user", - role: "user", - parts: [{ type: "text", text: "Typed aside" }], - }, - ] as PetrinautAiMessage[]), - ); + rerender(); - expect(screen.queryByText("Spoken request")).toBeNull(); - expect(screen.queryByText("Spoken reply")).toBeNull(); + expect(screen.getByText("Spoken request")).not.toBeNull(); + expect(screen.getByText("Spoken reply")).not.toBeNull(); expect(screen.getByText("Typed aside")).not.toBeNull(); - // The dock's transcription action writes the held turns into the chat - // mid-session, and holds them back again when it is turned off. + const transcript = screen.getByTestId("ai-transcript"); + const voiceMode = screen.getByTestId("ai-voice-mode"); + const header = screen + .getByRole("button", { name: "Close AI assistant" }) + .closest("div")!; + + fireEvent.click( + within(dock).getByRole("button", { name: "Collapse voice session" }), + ); + + expect(screen.getByTestId("ai-transcript")).toBe(transcript); + expect(screen.getByTestId("ai-voice-mode")).toBe(voiceMode); + expect( + screen + .getByRole("button", { name: "Close AI assistant", hidden: true }) + .closest("div"), + ).toBe(header); + expect(transcript.className).toContain("d_none"); + expect(voiceMode.className).toContain("d_none"); + expect(header.className).toContain("d_none"); + fireEvent.click( - within(dock).getByRole("button", { name: "Show transcription in chat" }), + within(dock).getByRole("button", { name: "End voice mode" }), ); + + expect(actions.end).toHaveBeenCalledOnce(); + expect(onCollapsedVoiceEnd).toHaveBeenCalledOnce(); + + fireEvent.click( + within(dock).getByRole("button", { name: "Expand voice session" }), + ); + + expect(transcript.className).not.toContain("d_none"); + expect(voiceMode.className).not.toContain("d_none"); + expect(header.className).not.toContain("d_none"); expect(screen.getByText("Spoken request")).not.toBeNull(); - expect(screen.getByText("Spoken reply")).not.toBeNull(); - expect(screen.queryByText("Voice session · 1 turn")).toBeNull(); fireEvent.click( - within(dock).getByRole("button", { name: "Hide transcription in chat" }), + within(dock).getByRole("button", { name: "End voice mode" }), ); - expect(screen.queryByText("Spoken request")).toBeNull(); + + expect(actions.end).toHaveBeenCalledTimes(2); + expect(onCollapsedVoiceEnd).toHaveBeenCalledOnce(); act(() => store.setState(null)); + rerender(); expect(screen.getByText("Spoken request")).not.toBeNull(); expect(screen.getByText("Spoken reply")).not.toBeNull(); - expect(screen.getByText("Voice session · 1 turn")).not.toBeNull(); expect(screen.queryByRole("region", { name: "Voice session" })).toBeNull(); expect( screen.getByRole("textbox", { name: "Message AI assistant" }), ).not.toBeNull(); }); - test("keeps the session's controls in the dock", () => { + test("stacks Voice setup above its compact dock while keeping the full panel mounted", () => { + const onVoiceDockCollapsedChange = vi.fn(); + render( + Permission + } + />, + ); + + const permission = screen.getByRole("region", { + name: "Voice mode consent", + }); + const setupDock = screen.getByRole("region", { name: "Voice setup" }); + expect(permission.parentElement?.nextElementSibling).toBe( + setupDock.parentElement, + ); + expect(screen.getByTestId("ai-transcript").className).toContain("d_none"); + expect( + screen + .getByRole("button", { name: "Close AI assistant", hidden: true }) + .closest("div")?.className, + ).toContain("d_none"); + expect( + screen.getByRole("textbox", { + hidden: true, + name: "Message AI assistant", + }), + ).not.toBeNull(); + + const expandButton = within(setupDock).getByRole("button", { + name: "Expand voice setup", + }); + expect(expandButton.getAttribute("aria-expanded")).toBeNull(); + fireEvent.click(expandButton); + + expect(onVoiceDockCollapsedChange).toHaveBeenCalledWith(false); + }); + + test("keeps handoff and canonical playback controls in the Voice dock", async () => { const store = createVoiceSessionStore(); const actions = { end: vi.fn(), pause: vi.fn(), + readFullResponse: vi.fn(), reconnect: vi.fn(), + repeatQuestion: vi.fn(), resume: vi.fn(), setMicrophoneMuted: vi.fn(), + takeTurn: vi.fn(), }; store.setActions(actions); store.setState({ + canReadFullResponse: true, + canRepeatQuestion: true, + canTakeTurn: true, errorMessage: null, microphoneLevel: 0.4, microphoneMuted: false, @@ -273,9 +457,45 @@ describe("AiAssistantContents", () => { fireEvent.click( within(dock).getByRole("button", { name: "End voice mode" }), ); + fireEvent.click(within(dock).getByRole("button", { name: "Your turn" })); expect(actions.setMicrophoneMuted).toHaveBeenCalledWith(true); expect(actions.end).toHaveBeenCalledOnce(); + expect(actions.takeTurn).toHaveBeenCalledOnce(); + + fireEvent.click( + within(dock).getByRole("button", { name: "Voice playback options" }), + ); + const repeatQuestion = await screen.findByRole("menuitem", { + name: "Repeat question", + }); + const repeatMenu = screen.getByRole("menu"); + fireEvent.keyDown(repeatMenu, { key: "ArrowDown" }); + await waitFor(() => + expect(repeatMenu.getAttribute("aria-activedescendant")).toBe( + repeatQuestion.id, + ), + ); + fireEvent.keyDown(repeatMenu, { key: "Enter" }); + await waitFor(() => expect(actions.repeatQuestion).toHaveBeenCalledOnce()); + + fireEvent.click( + within(dock).getByRole("button", { name: "Voice playback options" }), + ); + const readFullResponse = await screen.findByRole("menuitem", { + name: "Read full response", + }); + const fullResponseMenu = screen.getByRole("menu"); + fireEvent.keyDown(fullResponseMenu, { key: "End" }); + await waitFor(() => + expect(fullResponseMenu.getAttribute("aria-activedescendant")).toBe( + readFullResponse.id, + ), + ); + fireEvent.keyDown(fullResponseMenu, { key: "Enter" }); + await waitFor(() => + expect(actions.readFullResponse).toHaveBeenCalledOnce(), + ); act(() => { store.setState({ @@ -292,6 +512,20 @@ describe("AiAssistantContents", () => { ); expect(actions.setMicrophoneMuted).toHaveBeenLastCalledWith(false); + + act(() => { + store.setState({ + errorMessage: null, + microphoneLevel: 0, + microphoneMuted: false, + notice: "We didn't catch that. Please try again.", + phase: "listening", + }); + }); + expect( + within(dock).getAllByText("We didn't catch that. Please try again."), + ).not.toHaveLength(0); + expect(dock.getAttribute("data-voice-notice")).toBe("visible"); }); test("shows a voice recovery failure as a toast", async () => { @@ -319,15 +553,16 @@ describe("AiAssistantContents", () => { ); const toast = await waitFor(() => { - const element = document.querySelector( + const element = document.querySelector( '[data-scope="toast"][data-part="root"]', ); expect(element).not.toBeNull(); return element!; }); - expect(toast.textContent).toBe( - "Microphone unavailable. Check your browser permissions.", - ); + expect( + toast.querySelector('[data-scope="toast"][data-part="title"]') + ?.textContent, + ).toBe("Microphone unavailable. Check your browser permissions."); }); test("does not repeat a voice error toast until the session recovers", () => { @@ -554,7 +789,7 @@ describe("AiAssistantContents", () => { ).toBeNull(); }); - test("marks only the exact submitted interactive-tool answer named by voice metadata", () => { + test("marks every submitted interactive-tool answer named by voice metadata", () => { const hostTool = definePetrinautAiInteractiveTool({ toolName: "answerQuestion", inputSchema: { @@ -570,7 +805,10 @@ describe("AiAssistantContents", () => { const messages = [ { id: "assistant-questions", - metadata: { source: "voice", toolCallId: "question-voice" }, + metadata: { + source: "voice", + voiceToolCallIds: ["question-voice-1", "question-voice-2"], + }, role: "assistant", parts: [ { @@ -585,10 +823,18 @@ describe("AiAssistantContents", () => { type: "dynamic-tool", toolName: "answerQuestion", state: "output-available", - toolCallId: "question-voice", + toolCallId: "question-voice-1", input: { question: "Who approves it?" }, output: { answer: "The shift lead" }, }, + { + type: "dynamic-tool", + toolName: "answerQuestion", + state: "output-available", + toolCallId: "question-voice-2", + input: { question: "Who acts next?" }, + output: { answer: "The dispatcher" }, + }, ], }, ] as unknown as PetrinautAiMessage[]; @@ -606,13 +852,18 @@ describe("AiAssistantContents", () => { />, ); - expect( - within( - screen - .getByText("question-voice: The shift lead") - .closest("[data-tool-call-id]")!, - ).getByTestId("voice-input-provenance"), - ).not.toBeNull(); + for (const [toolCallId, answer] of [ + ["question-voice-1", "The shift lead"], + ["question-voice-2", "The dispatcher"], + ]) { + expect( + within( + screen + .getByText(`${toolCallId}: ${answer}`) + .closest("[data-tool-call-id]")!, + ).getByTestId("voice-input-provenance"), + ).not.toBeNull(); + } expect( within( screen @@ -620,7 +871,7 @@ describe("AiAssistantContents", () => { .closest("[data-tool-call-id]")!, ).queryByTestId("voice-input-provenance"), ).toBeNull(); - expect(screen.getAllByTestId("voice-input-provenance")).toHaveLength(1); + expect(screen.getAllByTestId("voice-input-provenance")).toHaveLength(2); expect(screen.queryByText("The shift lead", { exact: true })).toBeNull(); expect(container.querySelectorAll('[data-role="user"]')).toHaveLength(0); }); @@ -1594,7 +1845,7 @@ describe("AiAssistantContents", () => { expect(screen.getByRole("button", { name: /2 changes/u })).not.toBeNull(); }); - test("labels failed tool calls as errored", () => { + test("shows failed tool-call errors inline", () => { const messages: PetrinautAiMessage[] = [ { id: "assistant-1", @@ -1625,9 +1876,11 @@ describe("AiAssistantContents", () => { />, ); - expect( - screen.getByRole("button", { name: /deleteItemsByIds errored/u }), - ).not.toBeNull(); + const tool = screen.getByRole("button", { + name: /Validation failed.*deleteItemsByIds/u, + }); + expect(tool).not.toBeNull(); + expect(tool.getAttribute("title")).toBeNull(); }); test("expands deleted item summaries", () => { diff --git a/libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel/ai-assistant-contents.tsx b/libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel/ai-assistant-contents.tsx index 22c62fa18a5..9ab974abe20 100644 --- a/libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel/ai-assistant-contents.tsx +++ b/libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel/ai-assistant-contents.tsx @@ -1,5 +1,4 @@ import { - Fragment, memo, type ReactNode, type RefObject, @@ -14,9 +13,11 @@ import ReactMarkdown from "react-markdown"; import { Button, Icon } from "@hashintel/ds-components"; import { css, cva } from "@hashintel/ds-helpers/css"; -import { NotificationsContext } from "../../../../../react/notifications/context"; +import { + NotificationsContext, + type AddNotificationInput, +} from "../../../../../react/notifications/context"; import { EditorContext } from "../../../../../react/state/editor-context"; -import { VoiceSessionContext } from "../../../../../react/voice-session/context"; import { useVoiceSessionErrorMessage, useVoiceSessionPhase, @@ -24,7 +25,7 @@ import { import { AiAssistantIcon } from "../../../../components/ai-assistant-icon"; import { ResizeHandle } from "../../../../resize/resize-handle"; import { AiVoiceModeIcon } from "../../components/ai-voice-mode-button"; -import { partitionVoiceSessionMessages } from "./ai-assistant-contents/defer-voice-messages"; +import { voiceSetupLabels } from "../../components/voice-session-labels"; import { aiFooterMinHeight } from "./ai-assistant-contents/footer-height"; import { getMessageRenderItems } from "./ai-assistant-contents/get-message-render-items"; import { @@ -37,7 +38,7 @@ import { AiAssistantToolList, type OnInteractiveToolSubmit, } from "./ai-assistant-contents/tool-list"; -import { LiveVoiceDock } from "./ai-assistant-contents/voice-dock"; +import { LiveVoiceDock, VoiceDock } from "./ai-assistant-contents/voice-dock"; import { VoiceInputProvenance } from "./ai-assistant-contents/voice-input-provenance"; import type { PetrinautAiInputMode } from "../../../../types/ai-assistant-composer-control"; @@ -49,6 +50,11 @@ type AiAssistantStatus = "submitted" | "streaming" | "ready" | "error"; const EMPTY_INTERACTIVE_TOOLS: readonly PetrinautAiInteractiveTool[] = []; +const errorNotification = ( + message: string, + detail?: string, +): AddNotificationInput => ({ detail, message, tone: "error" }); + export type AiAssistantContentsProps = { clearMessagesDisabled?: boolean; composerControl?: ReactNode; @@ -61,6 +67,7 @@ export type AiAssistantContentsProps = { messages: PetrinautAiMessage[]; onClearMessages?: () => void; onClose: () => void; + onCollapsedVoiceEnd?: () => void; onInputModeChange?: (mode: PetrinautAiInputMode) => void; onInputChange: (value: string) => void; onInteractiveToolSubmit?: OnInteractiveToolSubmit; @@ -68,11 +75,13 @@ export type AiAssistantContentsProps = { onSendPrompt?: (prompt: string) => void; onStop: () => void; onSubmit: () => void; + onVoiceDockCollapsedChange?: (collapsed: boolean) => void; promptChips?: PromptChip[]; rightOffset?: number; status: AiAssistantStatus; stopped?: boolean; voiceHandoffPending?: boolean; + voiceDockCollapsed?: boolean; voiceMode?: ReactNode; voiceModeAvailable?: boolean; }; @@ -89,6 +98,9 @@ const shellStyle = cva({ }, }, variants: { + collapsed: { + true: {}, + }, open: { true: { top: "0", @@ -115,6 +127,16 @@ const shellStyle = cva({ }, }, }, + compoundVariants: [ + { + collapsed: true, + open: true, + css: { + top: "[auto]", + height: "auto", + }, + }, + ], }); // Tracks the card's inset within the padded shell, so the resize handle @@ -259,40 +281,6 @@ const messageStyle = cva({ textAlign: "right", }, }, - // Spoken turns land in the transcript together once the session ends, so - // they arrive with a single entrance rather than appearing out of nowhere. - revealed: { - true: { - animationName: "[petrinautVoiceReveal]", - animationDuration: "[420ms]", - animationTimingFunction: "[cubic-bezier(0.22, 0.9, 0.3, 1)]", - "@media (prefers-reduced-motion: reduce)": { - animationName: "[none]", - }, - }, - }, - }, -}); - -const voiceSessionMetaStyle = css({ - display: "flex", - alignItems: "center", - gap: "2", - paddingX: "1", - color: "neutral.s90", - fontSize: "xs", - fontWeight: "medium", - _before: { - flex: "[1]", - height: "[1px]", - backgroundColor: "neutral.a30", - content: '""', - }, - _after: { - flex: "[1]", - height: "[1px]", - backgroundColor: "neutral.a30", - content: '""', }, }); @@ -439,12 +427,10 @@ const AiAssistantMessage = memo( handlersRef, interactiveTools, message, - revealed = false, }: { handlersRef: MessageHandlersRef; interactiveTools: readonly PetrinautAiInteractiveTool[]; message: PetrinautAiMessage; - revealed?: boolean; }) => { const role = message.role === "user" ? "user" : "assistant"; const renderItems = getMessageRenderItems(message, interactiveTools); @@ -457,7 +443,7 @@ const AiAssistantMessage = memo( return (
@@ -506,6 +492,9 @@ const AiAssistantMessage = memo( } })} {hasVoiceOrigin && firstTextKey === null && } + {role === "assistant" && message.metadata?.stopped && ( +
Response stopped
+ )}
); }, @@ -524,6 +513,7 @@ export const AiAssistantContents = ({ messages, onClearMessages, onClose, + onCollapsedVoiceEnd, onInputModeChange, onInputChange, onInteractiveToolSubmit, @@ -531,16 +521,17 @@ export const AiAssistantContents = ({ onSendPrompt, onStop, onSubmit, + onVoiceDockCollapsedChange, promptChips, rightOffset = 0, status, stopped = false, voiceHandoffPending = false, + voiceDockCollapsed = false, voiceMode, voiceModeAvailable = false, }: AiAssistantContentsProps) => { const { addNotification } = use(NotificationsContext); - const voiceSessionStore = use(VoiceSessionContext); const voiceSessionPhase = useVoiceSessionPhase(); const voiceSessionErrorMessage = useVoiceSessionErrorMessage(); const isVoiceSessionLive = voiceSessionPhase !== null; @@ -599,76 +590,8 @@ export const AiAssistantContents = ({ variant: "solid", }; - // Index of the first message belonging to the current or most recent voice - // session. Everything from here on is held back while that session runs, and - // revealed together once it ends. - const [sessionBaselineIndex, setSessionBaselineIndex] = useState< - number | null - >(() => - voiceSessionStore.getSnapshot().state === null ? null : messages.length, - ); - - // Off by default: the dock's transcription action writes spoken turns into - // the conversation as they land instead of holding them to the end. - const [transcriptionShown, setTranscriptionShown] = useState(false); - - const messageCountRef = useRef(messages.length); - useEffect(() => { - messageCountRef.current = messages.length; - }, [messages]); - - // Read from the store rather than from a render effect, so the baseline is - // captured on the event that starts the session instead of a render that - // happens to observe it. - useEffect(() => { - let wasLive = voiceSessionStore.getSnapshot().state !== null; - - return voiceSessionStore.subscribe(() => { - const isLive = voiceSessionStore.getSnapshot().state !== null; - if (isLive === wasLive) { - return; - } - wasLive = isLive; - - if (isLive) { - setSessionBaselineIndex(messageCountRef.current); - setTranscriptionShown(false); - } - }); - }, [voiceSessionStore]); - - const isHoldingVoiceTurns = isVoiceSessionLive && !transcriptionShown; - - const sessionPartition = - sessionBaselineIndex === null - ? null - : partitionVoiceSessionMessages({ - deferredFromIndex: sessionBaselineIndex, - interactiveTools, - messages, - }); - - const visibleMessages = - isHoldingVoiceTurns && sessionPartition !== null - ? sessionPartition.visible - : messages; - - // Held turns become "revealed" once they are let through — by the - // transcription action mid-session, or by the session ending — so they carry - // the entrance animation either way. - const revealedIds = new Set( - isHoldingVoiceTurns || sessionPartition === null - ? [] - : sessionPartition.deferred.map((message) => message.id), - ); - // The divider counts a finished session, so it waits for the session to end - // rather than growing a turn at a time under a live transcription. - const firstRevealedMessageId = isVoiceSessionLive - ? undefined - : visibleMessages.find((message) => revealedIds.has(message.id))?.id; - const revealedVoiceTurnCount = visibleMessages.filter( - (message) => revealedIds.has(message.id) && message.role === "user", - ).length; + const isVoiceDockCollapsed = + voiceDockCollapsed && (isVoiceSessionLive || inputMode === "voice"); // Held in editor state, not here: the bottom toolbar and the viewport // controls have to keep clear of this panel, and cannot read a local value. @@ -689,10 +612,7 @@ export const AiAssistantContents = ({ return; } notifiedErrorRef.current = error; - addNotification({ - message: error.message, - tone: "error", - }); + addNotification(errorNotification("AI assistant error", error.message)); }, [addNotification, error]); // Voice failures (microphone denied, connection dropped) are reported by the @@ -712,10 +632,7 @@ export const AiAssistantContents = ({ } notifiedVoiceErrorRef.current = voiceSessionErrorMessage; - addNotification({ - message: voiceSessionErrorMessage, - tone: "error", - }); + addNotification(errorNotification(voiceSessionErrorMessage)); }, [addNotification, voiceSessionErrorMessage, voiceSessionPhase]); const inputRef = useRef(null); @@ -813,7 +730,10 @@ export const AiAssistantContents = ({