@myagentroam/agent 0.9.141 → 0.9.143

package/dist/{tools/code-mode.d.ts → agent-core/tools/code-mode/index.d.ts}

@@ -1,9 +1,9 @@
-import { type LocalProcessExecutor } from '../host/local-process-executor.js';
-import type { ClientToolDefinition, ModelMessage } from '../model/contracts.js';
-import type { ToolExecutionContext, ToolExecutionResult } from '../sdk/types.js';
-import { WorkspacePathResolver } from './shared/path-resolver.js';
-import type { CodeModeEngineFactory } from './code-mode/engine.js';
-import { type CellOutput } from './code-mode/cells.js';
+import { type LocalProcessExecutor } from '../../host/local-process-executor.js';
+import type { ClientToolDefinition, ModelMessage } from '../../model/contracts.js';
+import { type CellOutput } from './cells.js';
+import type { CodeModeEngineFactory } from './engine.js';
+import type { ToolExecutionContext, ToolExecutionResult } from '../contracts.js';
+import { WorkspacePathResolver } from '../shared/path-resolver.js';
 export declare const codeModeToolDefinition: ClientToolDefinition;
 export declare const codeExecWaitToolDefinition: ClientToolDefinition;
 /** Deferred definitions travel in search results, not in the stable Code Mode description. */
@@ -20,7 +20,7 @@ export declare class CodeModeTool {
     wait(value: unknown, context: ToolExecutionContext): Promise<ToolExecutionResult>;
     listSessionResources(sessionId: string): {
         cellId: string;
-        status: "completed" | "cancelled" | "running" | "failed";
+        status: "completed" | "failed" | "cancelled" | "running";
         executionId: string;
     }[];
     constructor(paths: WorkspacePathResolver, environment?: NodeJS.ProcessEnv, executor?: LocalProcessExecutor, engineFactory?: CodeModeEngineFactory);

package/dist/{tools/code-mode.js → agent-core/tools/code-mode/index.js}

@@ -1,19 +1,19 @@
 import { randomUUID } from 'node:crypto';
-import { createRequire } from 'node:module';
-import { pathToFileURL } from 'node:url';
 import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import { dirname, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { StringDecoder } from 'node:string_decoder';
-import { MarAgentError, describeMarAgentError } from '../error.js';
-import { directLocalProcessExecutor, signalProcessTree } from '../host/local-process-executor.js';
-import { TOOL_EXECUTION_LIMITS as limits } from './execution-limits.js';
-import { createToolCallScheduler } from './scheduler.js';
-import { detectImageMime } from './view-image.js';
-import { allowsDirectTool, allowsToolCaller } from './callers.js';
-import { CodeCells } from './code-mode/cells.js';
-import { BoundedTextOutput, renderCapturedText } from './code-mode/text-output.js';
-import { parseCodeModeStateMutations } from './code-mode/state.js';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { MarAgentError, describeMarAgentError } from '../../error.js';
+import { directLocalProcessExecutor, signalProcessTree } from '../../host/local-process-executor.js';
+import { allowsDirectTool, allowsToolCaller } from '../callers.js';
+import { CodeCells } from './cells.js';
+import { newObservationId, renderObservations } from './observations.js';
+import { parseCodeModeStateMutations } from './state.js';
+import { BoundedTextOutput, renderCapturedText } from './text-output.js';
+import { TOOL_EXECUTION_LIMITS as limits } from '../execution-limits.js';
+import { createToolCallScheduler } from '../scheduler.js';
+import { detectImageMime } from '../local/view-image.js';
 export const codeModeToolDefinition = {
     name: 'code_exec',
     description: `Run JavaScript to orchestrate or compose tool calls.
@@ -21,7 +21,7 @@ export const codeModeToolDefinition = {
 - Use bounded combinations, parallel independent calls, and filtering of large intermediate results to reduce model round trips.
 - Evaluates source in a fresh restricted ECMAScript runtime with top-level await and Promise.all. It is not Node.js or a browser. JavaScript globals do not survive between cells; bounded JSON state is available through state.
 - Accepts raw JavaScript source text, not JSON, quoted strings, or markdown code fences. Responses uses the source directly; Anthropic uses the code field of its tool input object. In either case, do not quote or fence the source again.
-- Use only standard ECMAScript built-ins and the explicitly documented tools, out, state, catalog and cell namespaces. Do not use Node.js, browser or Web APIs. Module imports, filesystem and network APIs are unavailable. Obtain external capabilities only through available tools. Use tools.exec to start managed processes when permitted; use tools.exec_wait afterward to wait, write stdin or cancel.
+- Use only standard ECMAScript built-ins and the explicitly documented tools, observe, state, catalog and cell namespaces. Do not use Node.js, browser or Web APIs. Module imports, filesystem and network APIs are unavailable. Obtain external capabilities only through available tools. Use tools.exec to start managed processes when permitted; use tools.exec_wait afterward to wait, write stdin or cancel.
 
 Tool calls:
 - tools.NAME(input) returns a Promise. Use the existing tool input schema; freeform tools such as apply_patch accept a raw string, not a JSON wrapper.
@@ -30,25 +30,26 @@ Tool calls:
 - skill, tool_search, question, code_exec, code_exec_wait and direct-only tools cannot be called here. Load Skills directly and read their instructions before the next tool call. Use direct tool_search before a later code cell for deferred tools; the current cell's tools do not change.
 
 Built-in namespaces:
-- out.text(value): void emits text. Strings and scalar values are stringified; JSON-compatible objects/arrays are serialized as compact JSON. Structured image objects (image/* mimeType and string dataBase64, or native MCP type:image with string data) are recursively summarized without their Base64 payload; originals remain unchanged. Ordinary strings remain unchanged. This does not emit pixels: use out.image(result.images[0]) for images. Prefer result.data or result.content over the whole image result. Excess ordinary text is truncated with omission metadata, without stopping later code or tools. Cyclic or unsupported object values fail. Only explicitly emitted output reaches the model.
-- out.image(value: {mimeType:string,dataBase64:string}): void emits one returned image; for example out.image(result.images[0]) when that image exists and the model supports images. It does not accept a path, URL, or result.content.
+- observe.result(result): void registers an unmodified complete tools.NAME result or caught tool error as a trusted tool_result, using the original text and all images without repeating program data. Non-original, copied or modified values are rejected. This selects evidence for the next model response, not a log and not a new model call.
+- observe.text(value): void registers bounded text/JSON values. observe.image(value): void registers one image value using the existing capability, MIME, byte and count limits. Both accept original tool results for compatibility and use the same complete tool_result observation path; they do not select part of an original result. Extracted single images, copies and computed summaries are value observations, never trusted tool results. Observations are returned in registration order. Only explicitly observed evidence reaches the model; registration does not prove inspection. Sources and types are runtime-assigned. No out or callable observe(value) alias exists.
 - state.get(key), state.has(key), state.set(key, value), state.delete(key) access bounded session JSON state. Mutations commit atomically only when the cell succeeds; failed or cancelled cells discard them.
 - catalog.tools() returns a read-only snapshot of the tools callable in this cell, including name, description, inputSchema and inputMode. It does not discover or authorize additional tools.
 - await cell.sleep(ms) performs a cancellable Host-side delay up to 30000 ms and remains subject to the cell deadline.
 - await cell.yield_control() returns accumulated output to the model immediately while this cell continues running.
 - Optionally start source with // @options: {"yieldMs": ${limits.codeDefaultYieldMs}, "maxOutputTokens": 10000}. yieldMs defaults to ${limits.codeDefaultYieldMs} ms and is a wait window (0..${limits.codeMaxYieldMs}), not a cell timeout. Explicit values are preserved and do not change nested tools' wait windows. A running result includes cellId; use direct code_exec_wait for new output, completion or termination.
 - Registered cells are Session warm resources: ending or cancelling the model Execution cancels its wait, not the cell. Reuse retained cellId; do not start duplicate work. Host cleanup or explicit termination stops the cell.
-- tools, out, state, catalog and cell are frozen bindings. Do not shadow their names.
+- tools, observe, state, catalog and cell are frozen bindings. Do not shadow their names.
 - Input max 1 MiB; cumulative text capture max 1 MiB with truncation; 128 calls, 120 seconds. Tool-specific limits apply before explicit text capture. Protocol, image, memory and time limits remain hard failures. Failures do not roll back completed tool work; do not replay successful operations blindly.
 
 Examples (copy the JavaScript source, not the fences; use only tools available in the current directory):
-Independent reads, emitting only source text:
+Independent reads, observing the original tool results:
 \`\`\`js
 const [a, b] = await Promise.all([
   tools.read({ reads: [{ path: "a.txt" }] }),
   tools.read({ reads: [{ path: "b.txt" }] })
 ]);
-out.text({ a: a.data.results[0].text, b: b.data.results[0].text });
+observe.result(a);
+observe.result(b);
 \`\`\`
 Inspect before a dependent edit; successful await needs no invented success flag:
 \`\`\`js
@@ -56,7 +57,7 @@ const inspected = await tools.read({ reads: [{ path: "source.txt" }] });
 const sourceText = inspected.data.results[0].text;
 if (!sourceText?.includes("original=1")) throw new Error("Unexpected source");
 const patched = await tools.apply_patch("*** Begin Patch\\n*** Update File: source.txt\\n@@\\n original=1\\n+updated=2\\n*** End Patch");
-out.text({ files: patched.data.files.length });
+observe.result(patched);
 \`\`\``,
     inputMode: 'freeform',
     inputSchema: {
@@ -154,10 +155,10 @@ function defaultEngineFactory() {
         return root.includes(`${sep}.pnpm${sep}`) ? dirname(dirname(root)) : root;
     };
     return {
-        moduleUrl: new URL('./code-mode/quickjs-engine.js', import.meta.url).href,
+        moduleUrl: new URL('./quickjs-engine.js', import.meta.url).href,
         runtimeDirectories: [
             ...new Set([
-                fileURLToPath(new URL('./code-mode/', import.meta.url)),
+                fileURLToPath(new URL('.', import.meta.url)),
                 dependencyRoot(core),
                 dependencyRoot(variant),
                 dependencyRoot(ffi)
@@ -255,7 +256,7 @@ export class CodeModeTool {
                 `--max-old-space-size=${limits.codeHeapMegabytes}`,
                 '--input-type=module',
                 '--eval',
-                await readFile(new URL('./code-mode/worker.js', import.meta.url), 'utf8')
+                await readFile(new URL('./worker.js', import.meta.url), 'utf8')
             ],
             cwd,
             shell: false,
@@ -268,6 +269,34 @@ export class CodeModeTool {
         });
         const text = new BoundedTextOutput(limits.codeMaxOutputBytes);
         const images = [];
+        const observations = [];
+        let observationBytes = 0;
+        const appendObservation = (value, originalBytes) => {
+            const capture = new BoundedTextOutput(Math.max(0, limits.codeMaxOutputBytes - observationBytes), '');
+            const body = value.type === 'tool_result' ? value.result.content : value.value;
+            capture.append(body);
+            const bounded = capture.snapshot();
+            observationBytes += bounded.retainedBytes;
+            text.append(body, originalBytes ?? Buffer.byteLength(body));
+            output?.text(body, originalBytes ?? Buffer.byteLength(body));
+            const observation = value.type === 'tool_result'
+                ? {
+                    ...value,
+                    result: {
+                        ...value.result,
+                        content: bounded.text,
+                        truncated: value.result.truncated === true || bounded.droppedBytes > 0
+                    }
+                }
+                : {
+                    ...value,
+                    value: bounded.text,
+                    truncated: value.truncated === true || bounded.droppedBytes > 0
+                };
+            observations.push(observation);
+            output?.observe(observation);
+        };
+        const toolResults = new Map();
         let transportBytes = 0;
         let calls = 0;
         let complete = false;
@@ -317,13 +346,94 @@ export class CodeModeTool {
         const receive = (frame) => {
             if (complete)
                 throw new MarAgentError('MAR_AGENT_CODE_PROTOCOL_ERROR', 'Code Mode sent data after completion.');
-            if (frame.kind === 'text' && typeof frame.value === 'string') {
+            if (frame.kind === 'observe' && frame.observation && typeof frame.observation === 'object') {
+                const value = frame.observation;
+                if (observations.length >= 4096)
+                    throw new MarAgentError('MAR_AGENT_TOOL_OUTPUT_LIMIT', 'Too many Code Mode observations.');
+                const addImage = (raw) => {
+                    if (!context.codeMode?.supportsImages)
+                        throw new MarAgentError('MAR_AGENT_INPUT_CAPABILITY_UNSUPPORTED', 'The current model cannot receive image observations.');
+                    if (images.length >= 5)
+                        throw new MarAgentError('MAR_AGENT_TOOL_OUTPUT_LIMIT', 'Code Mode emitted too many images.');
+                    const image = parseImage(raw);
+                    const index = images.length;
+                    images.push(image);
+                    output?.image(image);
+                    return index;
+                };
+                let observation;
+                if (value.type === 'tool_result' && typeof value.operationId === 'string') {
+                    const original = toolResults.get(value.operationId);
+                    if (!original)
+                        throw new MarAgentError('MAR_AGENT_CODE_PROTOCOL_ERROR', 'Unknown observation source.');
+                    const bounded = {
+                        content: original.result.content,
+                        truncated: original.result.truncated === true
+                    };
+                    const indices = original.result.images?.map(addImage);
+                    const data = [
+                        'apply_patch',
+                        'todo_read',
+                        'todo_write',
+                        'agent_start',
+                        'agent_wait',
+                        'agent_message',
+                        'agent_cancel'
+                    ].includes(original.source.toolName)
+                        ? original.result.data
+                        : undefined;
+                    observation = {
+                        type: 'tool_result',
+                        id: newObservationId(),
+                        source: original.source,
+                        outcome: original.outcome,
+                        result: {
+                            content: bounded.content,
+                            truncated: original.result.truncated === true || bounded.truncated,
+                            ...(data === undefined ? {} : { data }),
+                            ...(indices?.length ? { imageIndices: indices } : {})
+                        }
+                    };
+                }
+                else if (value.type === 'image') {
+                    observation = {
+                        type: 'value',
+                        id: newObservationId(),
+                        format: 'image',
+                        value: '',
+                        imageIndices: [addImage(value.value)]
+                    };
+                }
+                else if (value.type === 'value' &&
+                    typeof value.value === 'string' &&
+                    ['text', 'json'].includes(String(value.format))) {
+                    observation = {
+                        type: 'value',
+                        id: newObservationId(),
+                        format: value.format,
+                        value: value.value,
+                        truncated: typeof value.originalBytes === 'number' &&
+                            value.originalBytes > Buffer.byteLength(value.value)
+                    };
+                }
+                else
+                    throw new MarAgentError('MAR_AGENT_CODE_PROTOCOL_ERROR', 'Invalid observation frame.');
+                appendObservation(observation, value.type === 'value' && typeof value.originalBytes === 'number'
+                    ? value.originalBytes
+                    : undefined);
+            }
+            else if (frame.kind === 'text' && typeof frame.value === 'string') {
                 const originalBytes = frame.originalBytes ?? Buffer.byteLength(frame.value);
                 if (!Number.isSafeInteger(originalBytes) ||
                     originalBytes < Buffer.byteLength(frame.value))
                     throw new MarAgentError('MAR_AGENT_CODE_PROTOCOL_ERROR', 'Code Mode sent invalid text byte counts.');
-                text.append(frame.value, originalBytes);
-                output?.text(frame.value, originalBytes);
+                appendObservation({
+                    type: 'value',
+                    id: newObservationId(),
+                    format: 'text',
+                    value: frame.value,
+                    truncated: originalBytes > Buffer.byteLength(frame.value)
+                }, originalBytes);
             }
             else if (frame.kind === 'image') {
                 if (!context.codeMode?.supportsImages)
@@ -333,6 +443,13 @@ export class CodeModeTool {
                     throw new MarAgentError('MAR_AGENT_TOOL_OUTPUT_LIMIT', 'Code Mode emitted too many images.');
                 images.push(image);
                 output?.image(image);
+                appendObservation({
+                    type: 'value',
+                    id: newObservationId(),
+                    format: 'image',
+                    value: '',
+                    imageIndices: [images.length - 1]
+                });
             }
             else if (frame.kind === 'yield') {
                 output?.yield();
@@ -344,6 +461,14 @@ export class CodeModeTool {
                 if (seen.has(id) || ++calls > limits.codeMaxCalls)
                     throw new MarAgentError('MAR_AGENT_CODE_PROTOCOL_ERROR', 'Code Mode call ID or call count is invalid.');
                 seen.add(id);
+                const source = {
+                    callId: randomUUID(),
+                    toolName: frame.name,
+                    input: frame.arguments
+                };
+                const operationId = typeof frame.operationId === 'string' ? frame.operationId : String(id);
+                const recordCall = (value) => output?.call(value);
+                recordCall({ ...source, status: 'running' });
                 const job = (async () => {
                     try {
                         if (frame.name === 'code_exec' || !available.has(frame.name))
@@ -351,7 +476,27 @@ export class CodeModeTool {
                         const output = await invoke({
                             name: frame.name,
                             arguments: frame.arguments,
-                            callId: randomUUID()
+                            callId: source.callId
+                        });
+                        toolResults.set(operationId, { source, outcome: 'completed', result: output });
+                        recordCall({
+                            ...source,
+                            status: 'completed',
+                            result: {
+                                content: '',
+                                truncated: output.truncated === true,
+                                data: [
+                                    'apply_patch',
+                                    'todo_read',
+                                    'todo_write',
+                                    'agent_start',
+                                    'agent_wait',
+                                    'agent_message',
+                                    'agent_cancel'
+                                ].includes(source.toolName)
+                                    ? output.data
+                                    : undefined
+                            }
                         });
                         const { content, ...structured } = output;
                         const projected = output.data !== undefined && content === JSON.stringify(output.data)
@@ -360,9 +505,24 @@ export class CodeModeTool {
                         await write({ id, ok: true, output: projected });
                     }
                     catch (error) {
+                        // Serialization/transport failures cannot undo an already completed tool call.
+                        if (toolResults.get(operationId)?.outcome === 'completed')
+                            throw error;
                         if (context.signal.aborted)
                             return;
                         const diagnostic = describeMarAgentError(error, 'MAR_AGENT_HOST_OPERATION_FAILED');
+                        recordCall({
+                            ...source,
+                            status: 'failed',
+                            error: { code: diagnostic.code, message: diagnostic.message }
+                        });
+                        toolResults.set(operationId, {
+                            source,
+                            outcome: 'failed',
+                            result: {
+                                content: JSON.stringify({ error: diagnostic.code, message: diagnostic.message })
+                            }
+                        });
                         await write({
                             id,
                             ok: false,
@@ -471,8 +631,10 @@ export class CodeModeTool {
                 await context.codeMode.commitState?.(stateMutations);
             const captured = text.snapshot();
             return {
-                content: renderCapturedText(captured, images.length) ||
-                    'Code Mode completed without emitted text.',
+                content: observations.length
+                    ? renderObservations(observations)
+                    : renderCapturedText(captured, images.length) || '[]',
+                observations,
                 data: {
                     toolCalls: calls,
                     outputBytes: captured.originalBytes,

package/dist/agent-core/tools/code-mode/observations.d.ts

@@ -0,0 +1,103 @@
+/** Execution metadata is independent of explicit model observations. */
+export interface CodeToolCallRecord {
+    callId: string;
+    toolName: string;
+    input: unknown;
+    status: 'running' | 'completed' | 'failed';
+    result?: {
+        content: string;
+        data?: unknown;
+        truncated?: boolean;
+    };
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export declare function parseCodeCalls(value: unknown): CodeToolCallRecord[] | undefined;
+export type CodeObservation = {
+    type: 'tool_result';
+    id: string;
+    source: {
+        callId: string;
+        toolName: string;
+        input: unknown;
+    };
+    outcome: 'completed' | 'failed';
+    result: {
+        content: string;
+        data?: unknown;
+        truncated?: boolean;
+        imageIndices?: number[];
+    };
+} | {
+    type: 'value';
+    id: string;
+    format: 'text' | 'json' | 'image';
+    value: string;
+    truncated?: boolean;
+    imageIndices?: number[];
+};
+export declare function observationContent(value: CodeObservation): string;
+export declare function observationImages(value: CodeObservation): readonly number[];
+export declare function selectObservationImages(values: readonly CodeObservation[], images: readonly {
+    mimeType: string;
+    dataBase64: string;
+}[], offset?: number): {
+    observations: ({
+        result: {
+            imageIndices: number[];
+            content: string;
+            data?: unknown;
+            truncated?: boolean;
+        };
+        type: "tool_result";
+        id: string;
+        source: {
+            callId: string;
+            toolName: string;
+            input: unknown;
+        };
+        outcome: "completed" | "failed";
+    } | {
+        imageIndices: number[];
+        type: "value";
+        id: string;
+        format: "text" | "json" | "image";
+        value: string;
+        truncated?: boolean;
+    })[];
+    images: {
+        mimeType: string;
+        dataBase64: string;
+    }[];
+};
+/** Only the visible projection crosses into model text; program data and inputs stay private. */
+export declare function visibleObservation(value: CodeObservation): Record<string, unknown>;
+export declare function renderObservations(values: readonly CodeObservation[]): string;
+export declare function renderObservationResult(values: readonly CodeObservation[], original: string): string;
+/** Truncate each body before encoding, never a JSON array or its trusted identity. */
+export declare function boundObservations(values: readonly CodeObservation[], maximumTokens: number): {
+    observations: CodeObservation[];
+    content: string;
+    truncated: boolean;
+};
+export declare function newObservationId(): string;
+export declare function observationModelParts(message: {
+    content?: string;
+    observations?: readonly CodeObservation[];
+    images?: readonly {
+        mimeType: string;
+        dataBase64: string;
+    }[];
+}): Array<{
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    image: {
+        mimeType: string;
+        dataBase64: string;
+    };
+}> | undefined;
+export declare function parseObservations(value: unknown): CodeObservation[] | undefined;

package/dist/agent-core/tools/code-mode/observations.js

@@ -0,0 +1,195 @@
+import { randomUUID } from 'node:crypto';
+import { truncateModelText, countModelTokens } from '../../runtime/token-budget.js';
+export function parseCodeCalls(value) {
+    if (!Array.isArray(value) || value.length > 128)
+        return undefined;
+    const ids = new Set();
+    for (const item of value) {
+        if (!item ||
+            typeof item !== 'object' ||
+            typeof item.callId !== 'string' ||
+            !item.callId ||
+            ids.has(item.callId) ||
+            typeof item.toolName !== 'string' ||
+            !['running', 'completed', 'failed'].includes(item.status))
+            return undefined;
+        if (item.result !== undefined && (!item.result || typeof item.result.content !== 'string'))
+            return undefined;
+        ids.add(item.callId);
+    }
+    return value;
+}
+export function observationContent(value) {
+    return value.type === 'tool_result' ? value.result.content : value.value;
+}
+export function observationImages(value) {
+    return value.type === 'tool_result'
+        ? (value.result.imageIndices ?? [])
+        : (value.imageIndices ?? []);
+}
+export function selectObservationImages(values, images, offset = 0) {
+    const selected = [];
+    const indices = new Map();
+    const observations = values.map((value) => {
+        const remap = observationImages(value).flatMap((index) => {
+            const image = images[index - offset];
+            if (!image)
+                return [];
+            let next = indices.get(index);
+            if (next === undefined) {
+                next = selected.length;
+                indices.set(index, next);
+                selected.push(image);
+            }
+            return [next];
+        });
+        return value.type === 'tool_result'
+            ? { ...value, result: { ...value.result, imageIndices: remap } }
+            : { ...value, imageIndices: remap };
+    });
+    return { observations, images: selected };
+}
+/** Only the visible projection crosses into model text; program data and inputs stay private. */
+export function visibleObservation(value) {
+    return value.type === 'tool_result'
+        ? {
+            type: value.type,
+            toolName: value.source.toolName,
+            outcome: value.outcome,
+            content: value.result.content,
+            ...(value.result.truncated ? { truncated: true } : {})
+        }
+        : {
+            type: value.type,
+            format: value.format,
+            value: value.value,
+            ...(value.truncated ? { truncated: true } : {})
+        };
+}
+export function renderObservations(values) {
+    return JSON.stringify(values.map(visibleObservation));
+}
+export function renderObservationResult(values, original) {
+    try {
+        const envelope = JSON.parse(original);
+        if (envelope && !Array.isArray(envelope) && typeof envelope === 'object')
+            return JSON.stringify({ ...envelope, observations: values.map(visibleObservation) });
+    }
+    catch { }
+    return renderObservations(values);
+}
+/** Truncate each body before encoding, never a JSON array or its trusted identity. */
+export function boundObservations(values, maximumTokens) {
+    let remaining = Math.max(0, maximumTokens - 2);
+    let truncated = false;
+    const observations = [];
+    const selected = [];
+    let overheadBudget = 0;
+    for (const original of values) {
+        const empty = original.type === 'tool_result'
+            ? { ...original, result: { ...original.result, content: '', truncated: true } }
+            : { ...original, value: '', truncated: true };
+        const overhead = countModelTokens(JSON.stringify(visibleObservation(empty))) + 8;
+        if (overheadBudget + overhead > remaining) {
+            truncated = true;
+            break;
+        }
+        selected.push({ original, overhead });
+        overheadBudget += overhead;
+    }
+    for (const { original, overhead } of selected) {
+        let bodyBudget = Math.max(0, remaining - overheadBudget - 12);
+        let value;
+        let bodyTruncated = false;
+        for (;;) {
+            const bounded = truncateModelText(observationContent(original), bodyBudget);
+            bodyTruncated ||= bounded.truncated;
+            value =
+                original.type === 'tool_result'
+                    ? {
+                        ...original,
+                        result: {
+                            ...original.result,
+                            content: bounded.content,
+                            truncated: original.result.truncated === true || bodyTruncated
+                        }
+                    }
+                    : {
+                        ...original,
+                        value: bounded.content,
+                        truncated: original.truncated === true || bodyTruncated
+                    };
+            if (countModelTokens(JSON.stringify(visibleObservation(value))) + 1 <=
+                remaining - (overheadBudget - overhead) ||
+                bodyBudget === 0)
+                break;
+            bodyBudget = Math.floor(bodyBudget / 2);
+        }
+        overheadBudget -= overhead;
+        observations.push(value);
+        remaining -= countModelTokens(JSON.stringify(visibleObservation(value))) + 1;
+        truncated ||=
+            bodyTruncated ||
+                (original.type === 'tool_result'
+                    ? original.result.truncated === true
+                    : original.truncated === true);
+    }
+    return { observations, content: renderObservations(observations), truncated };
+}
+export function newObservationId() {
+    return randomUUID();
+}
+export function observationModelParts(message) {
+    if (!message.observations || !message.images?.length)
+        return undefined;
+    const prefix = [];
+    try {
+        const parsed = JSON.parse(message.content ?? '');
+        if (parsed && !Array.isArray(parsed) && typeof parsed === 'object') {
+            const { observations: _observations, ...metadata } = parsed;
+            prefix.push({ type: 'text', text: JSON.stringify(metadata) });
+        }
+    }
+    catch { }
+    return [
+        ...prefix,
+        ...message.observations.flatMap((value) => {
+            const parts = [{ type: 'text', text: JSON.stringify(visibleObservation(value)) }];
+            for (const index of observationImages(value)) {
+                const image = message.images?.[index];
+                if (image)
+                    parts.push({ type: 'image', image });
+            }
+            return parts;
+        })
+    ];
+}
+export function parseObservations(value) {
+    if (!Array.isArray(value) || value.length > 4096)
+        return undefined;
+    const ids = new Set();
+    for (const item of value) {
+        if (!item || typeof item !== 'object' || typeof item.id !== 'string' || ids.has(item.id))
+            return undefined;
+        ids.add(item.id);
+        if (item.type === 'tool_result') {
+            if (!item.source ||
+                typeof item.source.callId !== 'string' ||
+                typeof item.source.toolName !== 'string' ||
+                !['completed', 'failed'].includes(item.outcome) ||
+                !item.result ||
+                typeof item.result.content !== 'string')
+                return undefined;
+        }
+        else if (item.type !== 'value' ||
+            !['text', 'json', 'image'].includes(item.format) ||
+            typeof item.value !== 'string')
+            return undefined;
+        const indices = item.type === 'tool_result' ? item.result.imageIndices : item.imageIndices;
+        if (indices !== undefined &&
+            (!Array.isArray(indices) ||
+                indices.some((i) => !Number.isSafeInteger(i) || Number(i) < 0 || Number(i) >= 5)))
+            return undefined;
+    }
+    return value;
+}