@particle-academy/prism-harness 0.3.0 → 0.4.0

package/README.md

@@ -115,6 +115,52 @@ 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`.
+
+## 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/index.d.ts

@@ -24,6 +24,8 @@ 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 { 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, } from './runtime.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';

package/dist/index.js

@@ -13,6 +13,7 @@ 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 { 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';
@@ -33,6 +33,15 @@ 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;
@@ -64,7 +73,9 @@ export interface AgentResponse {
     stoppedBecause: string | null;
 }
 export interface PendingApproval {
+    /** The APPROVAL id: what `recordApproval()` answers. Not the tool call id. */
     id: string;
+    toolCallId: string;
     tool: string;
     arguments: JsonObject;
 }
@@ -75,24 +86,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);
@@ -114,5 +107,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,4 +1,5 @@
 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 { RunBudget, RunContext } from './subagents.js';
@@ -20,6 +21,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;
@@ -67,17 +72,24 @@ 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);
         }
         catch (error) {
             const failure = error instanceof Error ? error.message : String(error);
@@ -93,13 +105,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) {
         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,7 +118,7 @@ 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,
@@ -122,68 +129,138 @@ export class AgentRuntime {
             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).
+            await thread.record([assistantRow(response.text, toolCalls, response.additionalContent, requests)], runId);
             if (toolCalls.length === 0) {
                 return await this.#finish(session, runId, called, finishReason, text, run, null);
             }
-            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.
+     *
+     * 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:
      *
-     * 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.
+     * - 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 +269,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 +277,7 @@ 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)}`);
         }
     }
     async #finish(session, runId, called, finishReason, text, run, stoppedBecause) {
@@ -245,15 +311,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/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.4.0",
   "description": "Durable agent sessions for TypeScript — threads, session state and store drivers.",
   "type": "module",
   "sideEffects": false,