@particle-academy/prism-harness 0.3.0 → 0.5.0

package/README.md

@@ -115,6 +115,117 @@ new ModeRegistry({
 A value that is not a map is refused when the mode is resolved, with
 `mode_malformed`.
 
+## What your model client receives
+
+`request.messages` is the thread, oldest first, in the shape the PHP reference
+stores Prism's messages:
+
+| `type` | Carries |
+|---|---|
+| `user` | `content`, and `additional_content` when the turn has attachments |
+| `assistant` | `content`, `tool_calls` (`id`, `name`, `arguments`, `result_id`, `reasoning_id`, `reasoning_summary`), `additional_content`, `tool_approval_requests` |
+| `tool_result` | `tool_results` (`tool_call_id`, `tool_name`, `args`, `result`, `tool_call_result_id`, `artifacts`), `tool_approval_responses` |
+
+Consecutive tool result rows reach the client as one, so each call's result is
+sent to the provider once. Return a call's provider ids as `resultId`,
+`reasoningId` and `reasoningSummary`, and provider state for the turn as
+`additionalContent`: they are recorded and come back in `messages`.
+
+## Structured turns
+
+When the answer is a document rather than prose, hand the turn a schema:
+
+```ts
+const schema = {
+  name: 'plan',
+  type: 'object',
+  properties: {
+    title: { type: 'string' },
+    steps: { type: 'array', items: { type: 'string' } },
+  },
+  required: ['title', 'steps'],
+};
+
+const response = await runtime.sendStructured(session, 'Plan the release', schema);
+
+response.structured; // { title: 'Ship it', steps: ['write', 'test'] }
+response.text; // the document as the model wrote it
+```
+
+It is the same run as `send()` — the mode's system prompt, its tools, the step
+budget, the events — asking the provider for structured output. Your client
+receives the schema as `request.schema` and returns what it parsed as
+`response.structured`; with `prism-ts` that is `Prism.structured().withSchema()`
+and the response's `structured`.
+
+**The thread keeps the text, with the parsed object beside it.** The assistant
+message is the raw document, and `structured` rides along in the row's
+`additional_content`. A later turn replays the conversation as messages and reads
+the text, so a thread that contains a structured answer reads like any other.
+
+**A document that misses the schema is refused, not repaired.**
+
+```ts
+try {
+  const plan = (await runtime.sendStructured(session, brief, schema)).structured;
+} catch (error) {
+  if (error instanceof HarnessError) {
+    error.code; // structured_schema_violation, or structured_unreadable
+    error.problems; // every way it missed, not the first
+    error.document; // what the model actually said
+  }
+}
+```
+
+Nothing is coerced, nothing is trimmed to the fields that fit, and the result is
+never an empty document. An empty plan settles a batch as `done`, which reads
+exactly like a considered answer of "nothing to propose" — the failure this
+refusal exists to prevent. The exchange is still recorded, and the run is marked
+failed: a thread that omits the answer it did not like cannot explain the retry
+sitting next to it. The run row and the `run.failed` event name the CODE, not the
+message — the message quotes the values that missed, and an event carrying those
+would ship model output to every listener, which is the same reason tool
+arguments are names-only here.
+
+The check reads the schema's own JSON Schema, so a hand-written schema is held to
+the same terms. `schemaProblems()` is exported if you want it directly. It checks
+declared types, required keys, enum members, array items, and — where a schema
+closes itself — keys nobody declared. It does not read `$ref`, `allOf`, `oneOf`
+or the numeric and string facets; what it cannot read, it passes, rather than
+reporting a constraint it did not actually check. The same rules as the PHP
+reference, message for message, so a document refused in one language is refused
+in the other for the same stated reason.
+
+## Approvals
+
+A mode names the tools a person must approve:
+
+```ts
+guarded: { system_prompt: '...', tools: ['read', 'delete'], requires_approval: ['delete'] },
+```
+
+A step that calls one stops with `finishReason: 'awaiting_approval'`. The calls
+that need nobody have already run. Record a decision for every pending approval,
+then resume with an empty prompt:
+
+```ts
+const response = await runtime.send(session, 'Clean up the failed run');
+
+if (response.finishReason === 'awaiting_approval') {
+  for (const pending of response.pendingApprovals) {
+    await recordApproval(session, pending.id, true); // or false, 'not on production'
+  }
+
+  await runtime.send(session, '');
+}
+```
+
+On resume the approved calls run once and denied calls return their reason, and
+then the model continues. The model is not asked to make the calls again. A
+pending call with no decision is refused with "No approval response provided".
+A call that has a result never runs again. Who may approve is your application's
+decision: authorize before calling `recordApproval()`.
+
 ## Agent task lists
 
 An agent given a goal has to keep working across many requests. It needs a list

package/dist/errors.d.ts

@@ -68,12 +68,30 @@ export type HarnessErrorCode =
 /** A turn attachment carries no bytes, no file id and no chunks. */
  | 'attachment_empty'
 /** Attachments were offered with an empty prompt, which sends no user message. */
- | 'attachment_without_prompt';
+ | 'attachment_without_prompt'
+/** A structured turn came back with text holding no readable document. */
+ | 'structured_unreadable'
+/** A structured turn returned a document its schema refuses. */
+ | 'structured_schema_violation';
 export interface HarnessErrorOptions {
     cause?: unknown;
+    /** The model's own text, on a structured failure. See `HarnessError.document`. */
+    document?: string;
+    /** Every way a document missed its schema, on a structured failure. */
+    problems?: readonly string[];
 }
 export declare class HarnessError extends Error {
     readonly code: HarnessErrorCode;
+    /**
+     * The model's own text, on a structured failure.
+     *
+     * It travels on the error because the first question anyone asks is "what did
+     * it actually say", and an error that answers it turns a support thread into
+     * a log line. It is model output: log it where you log model output.
+     */
+    readonly document?: string;
+    /** Every way a document missed its schema, rather than only the first. */
+    readonly problems: readonly string[];
     constructor(code: HarnessErrorCode, message: string, options?: HarnessErrorOptions);
     static sessionLocked(key: string, waitSeconds: number): HarnessError;
     /**
@@ -216,4 +234,20 @@ export declare class HarnessError extends Error {
     static attachmentEmpty(index: number): HarnessError;
     /** An empty prompt resumes a paused run and sends no user message, so attachments would vanish. */
     static attachmentWithoutPrompt(): HarnessError;
+    /**
+     * A structured turn whose text held no document at all.
+     *
+     * Separate from the schema violation because the caller's next move differs:
+     * an apology in prose or a truncated answer is a prompting or a budget
+     * problem, and a document with the wrong shape is a schema one.
+     */
+    static structuredUnreadable(document: string): HarnessError;
+    /**
+     * Valid JSON, wrong shape.
+     *
+     * NOT coerced, not trimmed to the fields that fit, and never an empty
+     * document: one that fails the contract arriving as `{}` reads to the code
+     * receiving it exactly like a considered answer of "nothing".
+     */
+    static structuredSchemaViolation(document: string, problems: readonly string[]): HarnessError;
 }

package/dist/errors.js

@@ -1,9 +1,21 @@
 export class HarnessError extends Error {
     code;
+    /**
+     * The model's own text, on a structured failure.
+     *
+     * It travels on the error because the first question anyone asks is "what did
+     * it actually say", and an error that answers it turns a support thread into
+     * a log line. It is model output: log it where you log model output.
+     */
+    document;
+    /** Every way a document missed its schema, rather than only the first. */
+    problems;
     constructor(code, message, options = {}) {
         super(message, options);
         this.name = 'HarnessError';
         this.code = code;
+        this.document = options.document;
+        this.problems = options.problems ?? [];
     }
     static sessionLocked(key, waitSeconds) {
         return new HarnessError('session_locked', `Could not acquire the lock on session [${key}] within ${waitSeconds}s. ` +
@@ -220,4 +232,24 @@ export class HarnessError extends Error {
         return new HarnessError('attachment_without_prompt', 'Attachments need a prompt to travel with. An empty prompt resumes a paused run and sends no user ' +
             'message, so these attachments would be dropped without a word.');
     }
+    /**
+     * A structured turn whose text held no document at all.
+     *
+     * Separate from the schema violation because the caller's next move differs:
+     * an apology in prose or a truncated answer is a prompting or a budget
+     * problem, and a document with the wrong shape is a schema one.
+     */
+    static structuredUnreadable(document) {
+        return new HarnessError('structured_unreadable', 'The model returned no readable document for a structured turn. Its text is on this error as document.', { document });
+    }
+    /**
+     * Valid JSON, wrong shape.
+     *
+     * NOT coerced, not trimmed to the fields that fit, and never an empty
+     * document: one that fails the contract arriving as `{}` reads to the code
+     * receiving it exactly like a considered answer of "nothing".
+     */
+    static structuredSchemaViolation(document, problems) {
+        return new HarnessError('structured_schema_violation', `The model returned a document that does not satisfy the schema: ${problems.join(' ')}`, { document, problems });
+    }
 }

package/dist/index.d.ts

@@ -24,7 +24,10 @@ export type { HarnessEvent, HarnessListener, RunFailed, RunFinished, RunStarted
 export { diagnose } from './doctor.js';
 export type { DoctorFinding, DoctorReport, DoctorSubjects } from './doctor.js';
 export { AgentRuntime, recordApproval } from './runtime.js';
-export type { AgentResponse, AgentRuntimeOptions, LlmClient, LlmRequest, LlmResponse, LlmToolCall, PendingApproval, } from './runtime.js';
+export { assistantRow, threadView, toolResultEntry, toolResultRow } from './thread-rows.js';
+export type { ApprovalDecisionEntry, ApprovalRequestEntry, AssistantRow, ToolCallInput, ToolCallRow, ToolResultEntry, ToolResultRow, } from './thread-rows.js';
+export type { AgentResponse, AgentRuntimeOptions, LlmClient, LlmRequest, LlmResponse, LlmToolCall, PendingApproval, StructuredAgentResponse, } from './runtime.js';
+export { schemaName, schemaProblems } from './structured.js';
 export { DEFAULT_LEASE_SECONDS, TASK_STATES, asAgentTask, attributesToRecord, canonicalTaskJson, isTaskState, isTerminalState, recordToAttributes, taskRecordFrom, withAgentTask, } from './tasks.js';
 export type { AgentTask, AgentTaskAttributeSource, AgentTaskAttributes, AgentTaskRecord, AgentTaskSource, LeasedAgentTask, TaskOutcome, TaskState, } from './tasks.js';
 export { StoreTaskSource, StoredAgentTask } from './store-task-source.js';

package/dist/index.js

@@ -13,6 +13,8 @@ export { ToolAuthorizer, ToolRegistry, authorizedTool } from './tools.js';
 export { HarnessEvents } from './events.js';
 export { diagnose } from './doctor.js';
 export { AgentRuntime, recordApproval } from './runtime.js';
+export { assistantRow, threadView, toolResultEntry, toolResultRow } from './thread-rows.js';
+export { schemaName, schemaProblems } from './structured.js';
 export { DEFAULT_LEASE_SECONDS, TASK_STATES, asAgentTask, attributesToRecord, canonicalTaskJson, isTaskState, isTerminalState, recordToAttributes, taskRecordFrom, withAgentTask, } from './tasks.js';
 export { StoreTaskSource, StoredAgentTask } from './store-task-source.js';
 export { agentCompletionTool } from './task-tools.js';

package/dist/runtime.d.ts

@@ -1,4 +1,4 @@
-import type { JsonObject } from './json.js';
+import type { JsonObject, JsonValue } from './json.js';
 import type { HarnessEvents } from './events.js';
 import type { ModeRegistry } from './modes.js';
 import type { Session } from './session.js';
@@ -28,11 +28,29 @@ export interface LlmRequest {
      * interpret them.
      */
     providerOptions: Readonly<JsonObject>;
+    /**
+     * The JSON Schema a structured turn asks the answer to satisfy.
+     *
+     * Absent on an ordinary turn. A client passes it to its provider's structured
+     * mode (for prism-ts, `Prism.structured().withSchema()`) and returns what it
+     * parsed as `structured`; the harness checks that against this same schema
+     * before the caller sees it.
+     */
+    schema?: Readonly<JsonObject>;
 }
 export interface LlmToolCall {
     id: string;
     name: string;
     arguments: JsonObject;
+    /**
+     * The ids a provider keys the call's result and reasoning by, when they differ
+     * from `id`. OpenAI's Responses API answers a `function_call` by its `call_id`,
+     * and replays the reasoning item it came from by id. Recorded on the call, as
+     * prism's ToolCall stores them, so the next request can send them back.
+     */
+    resultId?: string | null;
+    reasoningId?: string | null;
+    reasoningSummary?: readonly JsonValue[] | null;
 }
 export interface LlmResponse {
     text: string;
@@ -49,6 +67,14 @@ export interface LlmResponse {
      * straight through and read it back from `messages`.
      */
     additionalContent?: Readonly<JsonObject>;
+    /**
+     * The document a structured turn parsed out of `text`.
+     *
+     * Null when the text held none — an apology in prose, a truncated answer, a
+     * fence that never closed. The harness tells that case apart from a document
+     * with the wrong shape, because the caller's next move differs.
+     */
+    structured?: JsonValue | null;
 }
 export type LlmClient = (request: LlmRequest) => Promise<LlmResponse>;
 export interface AgentResponse {
@@ -63,8 +89,21 @@ export interface AgentResponse {
     /** Set when the run stopped because the tree ran out of budget, or was cancelled. */
     stoppedBecause: string | null;
 }
+/**
+ * One structured run's result: the document, and the text it was read from.
+ *
+ * BOTH, not one. `structured` is what the caller asked for, and `text` is what
+ * the model actually sent — which is also exactly what the thread stored, so a
+ * transcript and a parse can be compared rather than trusted.
+ */
+export interface StructuredAgentResponse extends AgentResponse {
+    /** Checked against the schema before it got here; a run that could not produce one threw. */
+    structured: JsonValue;
+}
 export interface PendingApproval {
+    /** The APPROVAL id: what `recordApproval()` answers. Not the tool call id. */
     id: string;
+    toolCallId: string;
     tool: string;
     arguments: JsonObject;
 }
@@ -75,24 +114,6 @@ export interface AgentRuntimeOptions {
     authorizer?: ToolAuthorizer;
     events?: HarnessEvents;
 }
-/**
- * The loop: prompt in, turns out, everything recorded.
- *
- * Three properties matter more than the mechanics.
- *
- * **Every step is checked against the budget BEFORE it is taken**, not after.
- * Checking afterwards means the step that broke the limit has already been
- * paid for, which makes a budget a report rather than a control.
- *
- * **An approval stops the run and is written to the THREAD**, not held in
- * memory. That is what makes it survive: the approval a person grants this
- * morning is a durable row, so the worker that resumes tonight — a different
- * process, possibly after a deploy — reads the same answer.
- *
- * **A tool that needs approval and has none DOES NOT RUN.** Failing closed is
- * the only safe direction: an unanswered approval that executed anyway is
- * exactly the outcome the whole mechanism exists to prevent.
- */
 export declare class AgentRuntime {
     #private;
     constructor(options: AgentRuntimeOptions);
@@ -105,6 +126,28 @@ export declare class AgentRuntime {
      * second instruction competing with the one the tool call came from.
      */
     send(session: Session, prompt: string, toolNames?: readonly string[], context?: RunContext, additionalContent?: readonly unknown[]): Promise<AgentResponse>;
+    /**
+     * A turn whose answer is a document.
+     *
+     * The same run as `send()` — same mode, same tools, same budget, same events,
+     * same approvals — with a schema the answer has to satisfy. The schema
+     * travels on the request for the client to hand its provider, and what comes
+     * back is checked against it here before the caller sees it.
+     *
+     * WHAT THE THREAD KEEPS IS THE TEXT, with the parsed document beside it as
+     * `structured` in the assistant row's `additional_content`. Never instead of
+     * it: a later turn replays this conversation as messages, and a transcript
+     * that reads differently because of the SHAPE of the request that produced it
+     * is a difference nothing reports.
+     *
+     * A FAILED DOCUMENT IS STILL RECORDED, and then thrown. The exchange
+     * happened, and a thread that omits the answer it did not like cannot explain
+     * the retry sitting next to it. The run is marked failed and `run.failed` is
+     * emitted, as for any other failure.
+     *
+     * @throws HarnessError `structured_unreadable` or `structured_schema_violation`
+     */
+    sendStructured(session: Session, prompt: string, schema: Readonly<JsonObject>, toolNames?: readonly string[], context?: RunContext, additionalContent?: readonly unknown[]): Promise<StructuredAgentResponse>;
 }
 /**
  * Answer a pending approval, durably.
@@ -114,5 +157,11 @@ export declare class AgentRuntime {
  * already scoped to a participant, so nobody can answer another participant's
  * approval through it, but "this user may approve THIS action" is a question
  * only the host can answer. Authorize before calling.
+ *
+ * Nothing runs until the next `send()`, which acts on every decision recorded
+ * by then and refuses any pending call still without one. With several pending,
+ * record them all first.
+ *
+ * `approvalId` is `PendingApproval.id`, not the tool call id.
  */
 export declare function recordApproval(session: Session, approvalId: string, approved: boolean, reason?: string | null): Promise<void>;

package/dist/runtime.js

@@ -1,6 +1,8 @@
 import { randomUUID } from 'node:crypto';
+import { assistantRow, threadView, toolResultEntry, toolResultRow, } from './thread-rows.js';
 import { admitAttachments } from './attachments.js';
 import { HarnessError } from './errors.js';
+import { schemaName, schemaProblems } from './structured.js';
 import { RunBudget, RunContext } from './subagents.js';
 /**
  * The loop: prompt in, turns out, everything recorded.
@@ -20,6 +22,10 @@ import { RunBudget, RunContext } from './subagents.js';
  * the only safe direction: an unanswered approval that executed anyway is
  * exactly the outcome the whole mechanism exists to prevent.
  */
+/** How long resolving approvals may hold the session lock: long enough for a tool to run. */
+const RESOLUTION_LOCK_SECONDS = 300;
+/** How long a second worker waits for that lock before giving up without running anything. */
+const RESOLUTION_WAIT_SECONDS = 30;
 export class AgentRuntime {
     #client;
     #modes;
@@ -42,6 +48,35 @@ export class AgentRuntime {
      * second instruction competing with the one the tool call came from.
      */
     async send(session, prompt, toolNames, context, additionalContent = []) {
+        return await this.#turn(session, prompt, toolNames, context, additionalContent);
+    }
+    /**
+     * A turn whose answer is a document.
+     *
+     * The same run as `send()` — same mode, same tools, same budget, same events,
+     * same approvals — with a schema the answer has to satisfy. The schema
+     * travels on the request for the client to hand its provider, and what comes
+     * back is checked against it here before the caller sees it.
+     *
+     * WHAT THE THREAD KEEPS IS THE TEXT, with the parsed document beside it as
+     * `structured` in the assistant row's `additional_content`. Never instead of
+     * it: a later turn replays this conversation as messages, and a transcript
+     * that reads differently because of the SHAPE of the request that produced it
+     * is a difference nothing reports.
+     *
+     * A FAILED DOCUMENT IS STILL RECORDED, and then thrown. The exchange
+     * happened, and a thread that omits the answer it did not like cannot explain
+     * the retry sitting next to it. The run is marked failed and `run.failed` is
+     * emitted, as for any other failure.
+     *
+     * @throws HarnessError `structured_unreadable` or `structured_schema_violation`
+     */
+    async sendStructured(session, prompt, schema, toolNames, context, additionalContent = []) {
+        const response = await this.#turn(session, prompt, toolNames, context, additionalContent, schema);
+        // Narrowed by #turn: with a schema it always returns the structured shape.
+        return response;
+    }
+    async #turn(session, prompt, toolNames, context, additionalContent = [], schema) {
         // Refused before a run exists: a bad attachment is a mistake in the call,
         // and it should not cost a run, events or budget.
         const attachments = admitAttachments(prompt, additionalContent);
@@ -67,20 +102,38 @@ export class AgentRuntime {
             depth: run.depth,
             at: new Date().toISOString(),
         });
-        if (prompt !== '') {
-            // With attachments, the shape prism-ts's UserMessage.toObject() writes: the
-            // media parts, then the turn's own text as a trailing text part, which
-            // fromObject() strips back off. Without them, unchanged.
-            const turn = attachments.length === 0
-                ? { type: 'user', content: prompt }
-                : { type: 'user', content: prompt, additional_content: [...attachments, { text: prompt }], additional_attributes: {} };
-            await thread.record([turn], runId);
-        }
         try {
-            return await this.#loop(session, mode, run, runId, provider, model, toolNames);
+            const resolved = await this.#tools.resolve(toolNames ?? mode.tools, session);
+            const offered = this.#authorizer ? await this.#authorizer.allowed(session, resolved) : [...resolved.values()];
+            const called = [];
+            // Decisions recorded since the run stopped are acted on FIRST, before a
+            // new prompt is recorded, so the results land after the calls they answer
+            // rather than after the new turn.
+            await this.#resolveApprovals(session, mode, offered, runId, called);
+            if (prompt !== '') {
+                // With attachments, the shape prism-ts's UserMessage.toObject() writes:
+                // the media parts, then the turn's own text as a trailing text part,
+                // which fromObject() strips back off. Without them, unchanged.
+                const turn = attachments.length === 0
+                    ? { type: 'user', content: prompt }
+                    : { type: 'user', content: prompt, additional_content: [...attachments, { text: prompt }], additional_attributes: {} };
+                await thread.record([turn], runId);
+            }
+            return await this.#loop(session, mode, run, runId, provider, model, offered, called, schema);
         }
         catch (error) {
-            const failure = error instanceof Error ? error.message : String(error);
+            // THE MODEL'S OWN WORDS DO NOT BELONG IN A RUN ROW OR AN EVENT. A schema
+            // violation names the values that missed, so its message carries pieces
+            // of the document — and an event carrying those would put model output in
+            // every listener's telemetry, which is the same reason tool arguments are
+            // names-only here. The document is already in the thread, in full, where
+            // it is read deliberately rather than shipped by default. An error that
+            // holds one records its CODE.
+            const failure = error instanceof HarnessError && error.document !== undefined
+                ? error.code
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
             await session.failRun(runId, failure);
             this.#events?.emit({
                 type: 'run.failed',
@@ -93,13 +146,8 @@ export class AgentRuntime {
             throw error;
         }
     }
-    async #loop(session, mode, run, runId, provider, model, toolNames) {
+    async #loop(session, mode, run, runId, provider, model, offered, called, schema) {
         const thread = session.thread();
-        const resolved = await this.#tools.resolve(toolNames ?? mode.tools, session);
-        const offered = this.#authorizer
-            ? await this.#authorizer.allowed(session, resolved)
-            : [...resolved.values()];
-        const called = [];
         let text = '';
         let finishReason = 'stop';
         for (;;) {
@@ -111,79 +159,163 @@ export class AgentRuntime {
             }
             const response = await this.#client({
                 systemPrompt: mode.systemPrompt,
-                messages: (await thread.messages()).map((entry) => entry.message),
+                messages: threadView((await thread.messages()).map((entry) => entry.message)),
                 tools: offered,
                 provider,
                 model,
                 providerOptions: mode.providerOptions,
+                ...(schema === undefined ? {} : { schema }),
             });
             run.ledger.recordSteps(1);
             run.ledger.recordCost(response.costUsd ?? null);
             text = response.text;
             finishReason = response.finishReason;
             const toolCalls = response.toolCalls ?? [];
+            const gated = toolCalls.filter((call) => mode.needsApproval(call.name));
+            const requests = gated.map((call) => ({
+                approval_id: `apr_${randomUUID().replaceAll('-', '')}`,
+                tool_call_id: call.id,
+            }));
             // The next step's request is built from this row, so it keeps what a
-            // provider needs to be sent back: each call's arguments (a tool_use without
-            // its input is refused) and the provider state for the turn (G-58).
-            await thread.record([
-                {
-                    type: 'assistant',
-                    content: response.text,
-                    tool_calls: toolCalls.map((call) => ({ id: call.id, name: call.name, arguments: call.arguments })),
-                    additional_content: { ...(response.additionalContent ?? {}) },
-                },
-            ], runId);
+            // provider needs sent back: each call's arguments and provider ids, the
+            // turn's provider state, and the approvals it is waiting on (G-58).
+            const answering = schema !== undefined && toolCalls.length === 0;
+            const metadata = answering
+                ? { ...(response.additionalContent ?? {}), structured: response.structured ?? null }
+                : response.additionalContent;
+            await thread.record([assistantRow(response.text, toolCalls, metadata, requests)], runId);
             if (toolCalls.length === 0) {
-                return await this.#finish(session, runId, called, finishReason, text, run, null);
+                if (schema !== undefined) {
+                    // Recorded first, then checked: the exchange happened either way, and
+                    // a failure here fails the run through the caller's catch.
+                    this.#assertDocument(schema, response);
+                }
+                const finished = await this.#finish(session, runId, called, finishReason, text, run, null);
+                if (schema === undefined)
+                    return finished;
+                const structured = { ...finished, structured: response.structured };
+                return structured;
             }
-            const pending = await this.#pendingApprovals(session, mode, toolCalls);
-            if (pending.length > 0) {
-                // FAILS CLOSED. The run stops here and the request is already in the
-                // thread, so a different process can pick it up after a human answers.
-                await thread.record([{ type: 'tool_approval_request', approvals: pending }], runId);
+            // The calls that need nobody run now, as in the reference, and their
+            // results are recorded even when the step then stops for a person.
+            const results = [];
+            for (const call of toolCalls.filter((candidate) => !gated.includes(candidate))) {
+                called.push(call.name);
+                results.push(await this.#invoke(offered, call));
+            }
+            if (results.length > 0) {
+                await thread.record([toolResultRow(results)], runId);
+            }
+            if (requests.length > 0) {
+                // FAILS CLOSED. The gated calls have not run, and the requests are in
+                // the thread, so a different process can resume after a person answers.
                 return {
                     runId,
                     text,
                     steps: run.ledger.steps,
                     toolCalls: called,
                     finishReason: 'awaiting_approval',
-                    pendingApprovals: pending,
+                    pendingApprovals: gated.map((call, index) => ({
+                        id: requests[index].approval_id,
+                        toolCallId: call.id,
+                        tool: call.name,
+                        arguments: call.arguments,
+                    })),
                     stoppedBecause: null,
                 };
             }
-            for (const call of toolCalls) {
-                called.push(call.name);
-                await thread.record([await this.#invoke(offered, call)], runId);
-            }
         }
     }
     /**
-     * Which of these calls needs a human, and has not had one.
+     * Act on the decisions recorded for the last turn that stopped for a person.
      *
-     * An approval already answered in the thread is NOT asked again — that is the
-     * whole point of recording it durably. An answered-and-denied approval is
-     * also not asked again; it is simply not executed.
+     * The model is NOT asked again. Asked again, a provider issues the call
+     * afresh under a new id, and a decision recorded against the old one never
+     * matches. The calls that stopped the run are answered where they are:
+     *
+     * - approved: run, once;
+     * - denied: the reason, as the result the model sees;
+     * - no decision: refused, "No approval response provided". Record every
+     *   decision before resuming.
+     *
+     * A call that already has a result is done and never runs again, whatever
+     * its decision says. The results are recorded as one tool result row holding
+     * every result and decision for the turn, as the reference writes it.
+     */
+    async #resolveApprovals(session, mode, offered, runId, called) {
+        // A read without the lock first: nearly every send() has nothing to resolve
+        // and should not wait on the session lock to find that out.
+        if ((await this.#unresolved(session, mode)) === null)
+            return;
+        // Then under the session lock, reading again inside it. Two workers resuming
+        // the same session at once would otherwise both find the approved call with
+        // no result, and both run it. The second now waits, finds the result the
+        // first recorded, and runs nothing. If it cannot get the lock it throws
+        // SessionLocked, and nothing runs.
+        await session.lock(async (live) => {
+            const work = await this.#unresolved(live, mode);
+            if (work === null)
+                return;
+            const resolved = [];
+            for (const call of work.calls) {
+                const input = { id: call.id, name: call.name, arguments: call.arguments, resultId: call.result_id };
+                const approvalId = work.approvalIds.get(call.id);
+                const decision = approvalId === undefined ? undefined : work.decisions.get(approvalId);
+                if (decision?.approved === true) {
+                    called.push(call.name);
+                    resolved.push(await this.#runApproved(offered, input));
+                }
+                else {
+                    resolved.push(toolResultEntry(input, decision === undefined ? 'No approval response provided' : (decision.reason ?? 'User denied tool execution')));
+                }
+            }
+            await live.thread().record([toolResultRow([...work.results.values(), ...resolved], [...work.decisions.values()])], runId);
+        }, RESOLUTION_LOCK_SECONDS, RESOLUTION_WAIT_SECONDS);
+    }
+    /**
+     * The gated calls of the last tool-calling turn that have no result yet, with
+     * what is needed to answer them, or null when there are none.
      */
-    async #pendingApprovals(session, mode, toolCalls) {
-        const gated = toolCalls.filter((call) => mode.needsApproval(call.name));
-        if (gated.length === 0)
-            return [];
-        const answered = await this.#answeredApprovals(session);
-        return gated
-            .filter((call) => !answered.has(call.id))
-            .map((call) => ({ id: call.id, tool: call.name, arguments: call.arguments }));
+    async #unresolved(session, mode) {
+        const view = threadView((await session.thread().messages()).map((entry) => entry.message));
+        let index = view.length - 1;
+        while (index >= 0 && !(view[index].type === 'assistant' && view[index].tool_calls.length > 0)) {
+            index -= 1;
+        }
+        if (index === -1)
+            return null;
+        const assistant = view[index];
+        const answered = view.slice(index + 1).find((row) => row.type === 'tool_result');
+        const results = new Map((answered?.tool_results ?? []).map((entry) => [entry.tool_call_id, entry]));
+        const decisions = new Map((answered?.tool_approval_responses ?? []).map((entry) => [entry.approval_id, entry]));
+        const approvalIds = new Map(assistant.tool_approval_requests.map((request) => [request.tool_call_id, request.approval_id]));
+        // A call that has a result is DONE, whatever its decision says. A call that
+        // needs nobody is not this method's to run.
+        const calls = assistant.tool_calls.filter((call) => !results.has(call.id) && (approvalIds.has(call.id) || mode.needsApproval(call.name)));
+        return calls.length === 0 ? null : { calls, results, decisions, approvalIds };
     }
-    async #answeredApprovals(session) {
-        const answered = new Map();
-        for (const entry of await session.thread().messages()) {
-            if (entry.message.type !== 'tool_approval_response')
-                continue;
-            const id = entry.message.approval_id;
-            const approved = entry.message.approved;
-            if (typeof id === 'string')
-                answered.set(id, approved === true);
+    /**
+     * Run a call a person approved, or record why it could not run.
+     *
+     * Recorded rather than thrown. Resolution runs at the start of every send(),
+     * so a call that throws here, because its tool is no longer offered to this
+     * run or the authorizer now refuses it, would throw again on every later
+     * send(), and the session could never move on. The approval stands, but the
+     * call does not run.
+     */
+    async #runApproved(offered, call) {
+        if (!offered.some((tool) => tool.name === call.name)) {
+            return toolResultEntry(call, `Not run: ${call.name} is not available to this run.`);
+        }
+        try {
+            return await this.#invoke(offered, call);
+        }
+        catch (error) {
+            if (error instanceof HarnessError && error.code === 'call_not_authorized') {
+                return toolResultEntry(call, `Not run: this call to ${call.name} is not authorized.`);
+            }
+            throw error;
         }
-        return answered;
     }
     async #invoke(offered, call) {
         const tool = offered.find((candidate) => candidate.name === call.name);
@@ -192,12 +324,7 @@ export class AgentRuntime {
         }
         try {
             const result = await tool.handle(call.arguments);
-            return {
-                type: 'tool_result',
-                tool_call_id: call.id,
-                name: call.name,
-                result: typeof result === 'string' ? result : JSON.stringify(result ?? null),
-            };
+            return toolResultEntry(call, typeof result === 'string' ? result : JSON.stringify(result ?? null));
         }
         catch (error) {
             // A failed tool is a RESULT, not a crashed run: the model can often
@@ -205,13 +332,23 @@ export class AgentRuntime {
             // call is different and is left to propagate — see `authorizedTool`.
             if (error instanceof HarnessError && error.code === 'call_not_authorized')
                 throw error;
-            return {
-                type: 'tool_result',
-                tool_call_id: call.id,
-                name: call.name,
-                result: `The tool failed: ${error instanceof Error ? error.message : String(error)}`,
-                failed: true,
-            };
+            return toolResultEntry(call, `The tool failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Refuse a document the caller cannot use, naming which of the two it is.
+     *
+     * Text holding no document at all and a document with the wrong shape are
+     * separate codes because the next move differs: the first is a prompting or
+     * budget problem, the second a schema one.
+     */
+    #assertDocument(schema, response) {
+        if (response.structured === undefined || response.structured === null) {
+            throw HarnessError.structuredUnreadable(response.text);
+        }
+        const problems = schemaProblems(schema, response.structured, schemaName(schema));
+        if (problems.length > 0) {
+            throw HarnessError.structuredSchemaViolation(response.text, problems);
         }
     }
     async #finish(session, runId, called, finishReason, text, run, stoppedBecause) {
@@ -245,15 +382,14 @@ export class AgentRuntime {
  * already scoped to a participant, so nobody can answer another participant's
  * approval through it, but "this user may approve THIS action" is a question
  * only the host can answer. Authorize before calling.
+ *
+ * Nothing runs until the next `send()`, which acts on every decision recorded
+ * by then and refuses any pending call still without one. With several pending,
+ * record them all first.
+ *
+ * `approvalId` is `PendingApproval.id`, not the tool call id.
  */
 export async function recordApproval(session, approvalId, approved, reason = null) {
     const run = await session.run();
-    await session.thread().record([
-        {
-            type: 'tool_approval_response',
-            approval_id: approvalId,
-            approved,
-            reason,
-        },
-    ], run?.id ?? null);
+    await session.thread().record([toolResultRow([], [{ approval_id: approvalId, approved, reason }])], run?.id ?? null);
 }

package/dist/structured.d.ts

@@ -0,0 +1,37 @@
+import type { JsonObject, JsonValue } from './json.js';
+/**
+ * Does a document the model returned actually satisfy the schema it was given?
+ *
+ * A provider that supports strict structured output answers yes by
+ * construction. Most do not, and the ones that do can still be pointed at a
+ * model or an endpoint where the mode is unavailable — so the question has to
+ * be asked here, once, on the way back.
+ *
+ * WHY THIS IS NOT COERCION. The tempting alternative is to keep the fields that
+ * fit and drop the rest, which turns a wrong answer into a plausible one: a
+ * planning agent that returns a document missing its `nodes` array becomes a
+ * plan with no steps, and an empty plan settles a batch as done.
+ *
+ * WHAT IT CHECKS is what a JSON schema says without needing a resolver: the
+ * declared type, the required keys, the members of an enum, the items of an
+ * array, and, where a schema closes itself to additions, keys nobody declared.
+ *
+ * WHAT IT DOES NOT CHECK: `$ref`, `allOf`, `oneOf`, `not`, and the numeric and
+ * string facets (`minimum`, `pattern`, `minLength`). Each would be a partial
+ * implementation of a specification this package has no business owning, and a
+ * partial validator that reports nothing for a constraint it cannot read is
+ * worse than one whose limits are written down. What it cannot read, it passes.
+ *
+ * The same rules as `Prism\Harness\Structured\SchemaCheck` in the PHP
+ * reference, message for message, so a document refused in one language is
+ * refused in the others for the same stated reason.
+ */
+export declare function schemaProblems(schema: JsonObject, document: JsonValue, name?: string): string[];
+/**
+ * What to call the document in a problem message.
+ *
+ * A schema that names itself — Prism's `ObjectSchema` writes `name` — gets its
+ * own name in the path, so `plan.steps[1].do` reads the way the schema's author
+ * wrote it. Anything else is just "document".
+ */
+export declare function schemaName(schema: Readonly<JsonObject>): string;

package/dist/structured.js

@@ -0,0 +1,158 @@
+/**
+ * Does a document the model returned actually satisfy the schema it was given?
+ *
+ * A provider that supports strict structured output answers yes by
+ * construction. Most do not, and the ones that do can still be pointed at a
+ * model or an endpoint where the mode is unavailable — so the question has to
+ * be asked here, once, on the way back.
+ *
+ * WHY THIS IS NOT COERCION. The tempting alternative is to keep the fields that
+ * fit and drop the rest, which turns a wrong answer into a plausible one: a
+ * planning agent that returns a document missing its `nodes` array becomes a
+ * plan with no steps, and an empty plan settles a batch as done.
+ *
+ * WHAT IT CHECKS is what a JSON schema says without needing a resolver: the
+ * declared type, the required keys, the members of an enum, the items of an
+ * array, and, where a schema closes itself to additions, keys nobody declared.
+ *
+ * WHAT IT DOES NOT CHECK: `$ref`, `allOf`, `oneOf`, `not`, and the numeric and
+ * string facets (`minimum`, `pattern`, `minLength`). Each would be a partial
+ * implementation of a specification this package has no business owning, and a
+ * partial validator that reports nothing for a constraint it cannot read is
+ * worse than one whose limits are written down. What it cannot read, it passes.
+ *
+ * The same rules as `Prism\Harness\Structured\SchemaCheck` in the PHP
+ * reference, message for message, so a document refused in one language is
+ * refused in the others for the same stated reason.
+ */
+export function schemaProblems(schema, document, name = 'document') {
+    return check(schema, document, name);
+}
+function check(schema, value, path) {
+    if (Array.isArray(schema.anyOf)) {
+        return checkAnyOf(schema.anyOf, value, path);
+    }
+    if (Array.isArray(schema.enum)) {
+        return schema.enum.some((member) => member === value)
+            ? []
+            : [`${path} is ${describe(value)}, which is not one of ${members(schema.enum)}.`];
+    }
+    const types = declaredTypes(schema);
+    if (types.length === 0) {
+        // Nothing declared to check against. A schema that says nothing about a
+        // value cannot be violated by it.
+        return [];
+    }
+    if (!types.some((type) => matches(type, value))) {
+        return [`${path} is ${describe(value)}, and the schema asks for ${members(types)}.`];
+    }
+    if (types.includes('object') && isObject(value)) {
+        return checkObject(schema, value, path);
+    }
+    if (types.includes('array') && Array.isArray(value)) {
+        return checkArray(schema, value, path);
+    }
+    return [];
+}
+function checkAnyOf(branches, value, path) {
+    for (const branch of branches) {
+        if (isObject(branch) && check(branch, value, path).length === 0)
+            return [];
+    }
+    return [`${path} is ${describe(value)}, which satisfies none of the alternatives the schema allows.`];
+}
+function checkObject(schema, value, path) {
+    const problems = [];
+    const properties = isObject(schema.properties) ? schema.properties : {};
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    for (const name of required) {
+        if (typeof name === 'string' && !(name in value)) {
+            problems.push(`${path}.${name} is required and missing.`);
+        }
+    }
+    for (const [name, property] of Object.entries(properties)) {
+        if (!isObject(property) || !(name in value))
+            continue;
+        problems.push(...check(property, value[name], `${path}.${name}`));
+    }
+    // Only where the schema closed itself. An open object invites the extra key,
+    // so reporting it would be this package's opinion rather than the schema's.
+    if (schema.additionalProperties === false) {
+        for (const name of Object.keys(value)) {
+            if (!(name in properties)) {
+                problems.push(`${path}.${name} was returned, and the schema declares no such property.`);
+            }
+        }
+    }
+    return problems;
+}
+function checkArray(schema, value, path) {
+    if (!isObject(schema.items))
+        return [];
+    const items = schema.items;
+    return value.flatMap((item, index) => check(items, item, `${path}[${index}]`));
+}
+/** The declared types, as a list — a nullable schema declares two. */
+function declaredTypes(schema) {
+    if (typeof schema.type === 'string')
+        return [schema.type];
+    if (Array.isArray(schema.type))
+        return schema.type.filter((type) => typeof type === 'string');
+    return [];
+}
+function matches(type, value) {
+    switch (type) {
+        case 'string':
+            return typeof value === 'string';
+        // An integer satisfies `number`, as JSON Schema says it does. The other
+        // direction does not, and JavaScript is where that is easiest to get wrong:
+        // 2.0 parses as the same number as 2, so `Number.isInteger` is the test
+        // rather than the absence of a fractional part in the source text.
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value);
+        case 'integer':
+            return typeof value === 'number' && Number.isInteger(value);
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'null':
+            return value === null;
+        case 'array':
+            return Array.isArray(value);
+        case 'object':
+            return isObject(value);
+        default:
+            return true;
+    }
+}
+function describe(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'an array';
+    if (typeof value === 'object')
+        return 'an object';
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'string') {
+        return `the string "${value.length > 40 ? `${value.slice(0, 40)}…` : value}"`;
+    }
+    return `the number ${value}`;
+}
+function members(values) {
+    return values
+        .map((value) => (typeof value === 'string' ? `'${value}'` : JSON.stringify(value)))
+        .join(', ');
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * What to call the document in a problem message.
+ *
+ * A schema that names itself — Prism's `ObjectSchema` writes `name` — gets its
+ * own name in the path, so `plan.steps[1].do` reads the way the schema's author
+ * wrote it. Anything else is just "document".
+ */
+export function schemaName(schema) {
+    return typeof schema.name === 'string' && schema.name !== '' ? schema.name : 'document';
+}

package/dist/thread-rows.d.ts

@@ -0,0 +1,71 @@
+import type { JsonObject, JsonValue } from './json.js';
+/**
+ * The rows a run writes to a thread, in the shape the PHP reference stores.
+ *
+ * prism-harness stores Prism's own messages: an assistant turn carries its tool
+ * calls (arguments and provider ids included), its provider state and its
+ * approval requests; a tool result turn carries every result of a step and any
+ * approval decisions. These builders write exactly that, with the row's `type`
+ * beside it, so a thread written here reads the same as one written there.
+ * prism-parity's `harness-thread-rows` corpus pins it.
+ */
+export type ToolCallRow = {
+    id: string;
+    name: string;
+    arguments: JsonObject;
+    result_id: string | null;
+    reasoning_id: string | null;
+    reasoning_summary: JsonValue[] | null;
+};
+export type ToolResultEntry = {
+    tool_call_id: string;
+    tool_name: string;
+    args: JsonObject;
+    result: string;
+    tool_call_result_id: string | null;
+    artifacts: JsonValue[];
+};
+export type ApprovalRequestEntry = {
+    approval_id: string;
+    tool_call_id: string;
+};
+export type ApprovalDecisionEntry = {
+    approval_id: string;
+    approved: boolean;
+    reason: string | null;
+};
+export type AssistantRow = {
+    type: 'assistant';
+    content: string;
+    tool_calls: ToolCallRow[];
+    additional_content: JsonObject;
+    tool_approval_requests: ApprovalRequestEntry[];
+};
+export type ToolResultRow = {
+    type: 'tool_result';
+    tool_results: ToolResultEntry[];
+    tool_approval_responses: ApprovalDecisionEntry[];
+};
+export interface ToolCallInput {
+    id: string;
+    name: string;
+    arguments: JsonObject;
+    resultId?: string | null;
+    reasoningId?: string | null;
+    reasoningSummary?: readonly JsonValue[] | null;
+}
+export declare function assistantRow(content: string, toolCalls: readonly ToolCallInput[], additionalContent?: Readonly<JsonObject>, approvalRequests?: readonly ApprovalRequestEntry[]): AssistantRow;
+export declare function toolResultEntry(call: ToolCallInput, result: string): ToolResultEntry;
+export declare function toolResultRow(results: readonly ToolResultEntry[], decisions?: readonly ApprovalDecisionEntry[]): ToolResultRow;
+/**
+ * The thread as the model is shown it: rows written by 0.3.0 and earlier read
+ * in today's shape, and consecutive tool result rows folded into one.
+ *
+ * An approval leaves several tool result rows in a row: the results of the
+ * calls a stopped step did run, the decisions, and the results written when the
+ * run resumes. Rows are never rewritten, so all of them stay stored; shown to a
+ * provider separately, a tool output would go twice. Folded, a result is keyed
+ * by its tool call id and a decision by its approval id, and a later one
+ * replaces an earlier one in the earlier one's position.
+ */
+export declare function threadView(rows: readonly JsonObject[]): JsonObject[];

package/dist/thread-rows.js

@@ -0,0 +1,135 @@
+export function assistantRow(content, toolCalls, additionalContent = {}, approvalRequests = []) {
+    return {
+        type: 'assistant',
+        content,
+        tool_calls: toolCalls.map((call) => ({
+            id: call.id,
+            name: call.name,
+            arguments: { ...call.arguments },
+            result_id: call.resultId ?? null,
+            reasoning_id: call.reasoningId ?? null,
+            reasoning_summary: call.reasoningSummary ? [...call.reasoningSummary] : null,
+        })),
+        additional_content: { ...additionalContent },
+        tool_approval_requests: approvalRequests.map((request) => ({ ...request })),
+    };
+}
+export function toolResultEntry(call, result) {
+    return {
+        tool_call_id: call.id,
+        tool_name: call.name,
+        args: { ...call.arguments },
+        result,
+        tool_call_result_id: call.resultId ?? null,
+        artifacts: [],
+    };
+}
+export function toolResultRow(results, decisions = []) {
+    return {
+        type: 'tool_result',
+        tool_results: results.map((entry) => ({ ...entry })),
+        tool_approval_responses: decisions.map((decision) => ({ ...decision })),
+    };
+}
+/**
+ * The thread as the model is shown it: rows written by 0.3.0 and earlier read
+ * in today's shape, and consecutive tool result rows folded into one.
+ *
+ * An approval leaves several tool result rows in a row: the results of the
+ * calls a stopped step did run, the decisions, and the results written when the
+ * run resumes. Rows are never rewritten, so all of them stay stored; shown to a
+ * provider separately, a tool output would go twice. Folded, a result is keyed
+ * by its tool call id and a decision by its approval id, and a later one
+ * replaces an earlier one in the earlier one's position.
+ */
+export function threadView(rows) {
+    const view = [];
+    for (const row of rows) {
+        const normalised = normalise(row, view);
+        if (normalised === null)
+            continue;
+        const previous = view.at(-1);
+        if (normalised.type === 'tool_result' && previous?.type === 'tool_result') {
+            view[view.length - 1] = fold(previous, normalised);
+        }
+        else {
+            view.push(normalised);
+        }
+    }
+    return view;
+}
+function normalise(row, view) {
+    switch (row.type) {
+        case 'assistant':
+            return assistantRow(typeof row.content === 'string' ? row.content : '', list(row.tool_calls).map((call) => ({
+                id: text(call.id),
+                name: text(call.name),
+                arguments: isObject(call.arguments) ? call.arguments : {},
+                resultId: nullableText(call.result_id),
+                reasoningId: nullableText(call.reasoning_id),
+                reasoningSummary: Array.isArray(call.reasoning_summary) ? call.reasoning_summary : null,
+            })), isObject(row.additional_content) ? row.additional_content : {}, list(row.tool_approval_requests).map((request) => ({
+                approval_id: text(request.approval_id),
+                tool_call_id: text(request.tool_call_id),
+            })));
+        case 'tool_result':
+            if (Array.isArray(row.tool_results) || Array.isArray(row.tool_approval_responses)) {
+                return toolResultRow(list(row.tool_results).map((entry) => ({
+                    tool_call_id: text(entry.tool_call_id),
+                    tool_name: text(entry.tool_name),
+                    args: isObject(entry.args) ? entry.args : {},
+                    result: text(entry.result),
+                    tool_call_result_id: nullableText(entry.tool_call_result_id),
+                    artifacts: Array.isArray(entry.artifacts) ? entry.artifacts : [],
+                })), list(row.tool_approval_responses).map(decision));
+            }
+            // 0.3.0 and earlier: one row per call, with no arguments on it.
+            return toolResultRow([
+                {
+                    tool_call_id: text(row.tool_call_id),
+                    tool_name: text(row.name),
+                    args: {},
+                    result: text(row.result),
+                    tool_call_result_id: null,
+                    artifacts: [],
+                },
+            ]);
+        case 'tool_approval_request': {
+            // 0.3.0 and earlier kept the request in its own row, keyed by the CALL id.
+            // It belongs to the assistant turn before it.
+            const assistant = [...view].reverse().find((candidate) => candidate.type === 'assistant');
+            for (const approval of list(row.approvals)) {
+                assistant?.tool_approval_requests.push({ approval_id: text(approval.id), tool_call_id: text(approval.id) });
+            }
+            return null;
+        }
+        case 'tool_approval_response':
+            return toolResultRow([], [decision(row)]);
+        default:
+            return row;
+    }
+}
+function fold(earlier, later) {
+    const results = new Map();
+    const decisions = new Map();
+    for (const entry of [...earlier.tool_results, ...later.tool_results])
+        results.set(entry.tool_call_id, entry);
+    for (const entry of [...earlier.tool_approval_responses, ...later.tool_approval_responses])
+        decisions.set(entry.approval_id, entry);
+    return toolResultRow([...results.values()], [...decisions.values()]);
+}
+function decision(value) {
+    return { approval_id: text(value.approval_id), approved: value.approved === true, reason: nullableText(value.reason) };
+}
+function list(value) {
+    return Array.isArray(value) ? value.filter(isObject) : [];
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function text(value) {
+    return typeof value === 'string' ? value : value === undefined || value === null ? '' : JSON.stringify(value);
+}
+function nullableText(value) {
+    return typeof value === 'string' ? value : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/prism-harness",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Durable agent sessions for TypeScript — threads, session state and store drivers.",
   "type": "module",
   "sideEffects": false,