@myagentroam/agent 0.9.142 → 0.9.144

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

@@ -3,12 +3,15 @@ import { MarAgentError, describeMarAgentError } from '../../error.js';
 import { truncateModelText } from '../../runtime/token-budget.js';
 import { TOOL_EXECUTION_LIMITS as limits } from '../execution-limits.js';
 import { BoundedTextOutput, renderCapturedText } from './text-output.js';
+import { boundObservations, selectObservationImages, newObservationId, visibleObservation } from './observations.js';
 /** Keeps a failed tool call observable without discarding earlier explicit output. */
 export class CodeCellExecutionError extends MarAgentError {
     result;
     constructor(error, result) {
         const diagnostic = describeMarAgentError(error, 'MAR_AGENT_CODE_FAILED');
-        super(diagnostic.code, diagnostic.message.replace(`${diagnostic.code}: `, ''), {
+        super(diagnostic.code, diagnostic.message.startsWith(`${diagnostic.code}: `)
+            ? diagnostic.message.slice(diagnostic.code.length + 2)
+            : diagnostic.message, {
             cause: error,
             ...(error instanceof MarAgentError ? { retryable: error.retryable } : {})
         });
@@ -88,6 +91,9 @@ export class CodeCells {
             status: 'running',
             text: new BoundedTextOutput(limits.codeMaxOutputBytes),
             images: [],
+            observations: [],
+            calls: new Map(),
+            imageOffset: 0,
             yielded: false,
             truncated: false,
             listeners: new Set(),
@@ -104,6 +110,8 @@ export class CodeCells {
             .then(async () => {
             releaseSession = await context.codeMode?.retainSession?.();
             return run(source, { ...context, signal: controller.signal }, {
+                call: (value) => cell.calls.set(value.callId, value),
+                observe: (value) => cell.observations.push(value),
                 text: (text, originalBytes) => cell.text.append(text, originalBytes),
                 image: (image) => cell.images.push(image),
                 yield: () => {
@@ -199,6 +207,31 @@ export class CodeCells {
         if (!supportsImages && (cell.images.length || cell.terminal?.images?.length))
             throw new MarAgentError('MAR_AGENT_INPUT_CAPABILITY_UNSUPPORTED', 'The current model cannot receive this cell image output.');
         if (cell.terminal) {
+            if (cell.terminal.observations) {
+                const bounded = boundObservations(cell.terminal.observations, input.maxOutputTokens);
+                const visible = selectObservationImages(bounded.observations, cell.terminal.images ?? []);
+                const original = cell.terminal.data;
+                const data = {
+                    ...original,
+                    output: truncateModelText(original.output ?? '', input.maxOutputTokens).content,
+                    observations: visible.observations,
+                    cached: true,
+                    truncated: cell.terminal.truncated === true || bounded.truncated
+                };
+                return {
+                    ...cell.terminal,
+                    observations: visible.observations,
+                    images: visible.images,
+                    content: JSON.stringify({
+                        ...data,
+                        output: undefined,
+                        calls: undefined,
+                        observations: visible.observations.map(visibleObservation)
+                    }),
+                    data,
+                    truncated: data.truncated
+                };
+            }
             const snapshot = cell.terminal.data;
             const bounded = truncateModelText(snapshot.output, input.maxOutputTokens);
             const data = {
@@ -219,7 +252,21 @@ export class CodeCells {
         const text = renderCapturedText(captured, images.length);
         cell.yielded = false;
         const bounded = truncateModelText(text, input.maxOutputTokens);
-        cell.truncated ||= captured.droppedBytes > 0 || bounded.truncated;
+        const pending = cell.observations.splice(0);
+        if (!pending.length && captured.text)
+            pending.push({
+                type: 'value',
+                id: newObservationId(),
+                format: 'text',
+                value: captured.text,
+                truncated: captured.droppedBytes > 0
+            });
+        const structured = boundObservations(pending, input.maxOutputTokens);
+        const visible = selectObservationImages(structured.observations, images, cell.imageOffset);
+        const remapped = visible.observations;
+        const visibleImages = visible.images;
+        cell.imageOffset += images.length;
+        cell.truncated ||= captured.droppedBytes > 0 || bounded.truncated || structured.truncated;
         const error = cell.error === undefined
             ? undefined
             : describeMarAgentError(cell.error, 'MAR_AGENT_CODE_FAILED');
@@ -227,6 +274,8 @@ export class CodeCells {
             cellId: cell.cellId,
             status: cell.status,
             output: bounded.content,
+            observations: remapped,
+            calls: [...cell.calls.values()],
             ...cell.result?.data,
             outputBytes: captured.originalBytes,
             outputDroppedBytes: captured.droppedBytes,
@@ -235,10 +284,17 @@ export class CodeCells {
             cached: false
         };
         const result = {
-            content: JSON.stringify(data),
+            content: JSON.stringify({
+                ...data,
+                output: undefined,
+                calls: undefined,
+                observations: remapped.map(visibleObservation)
+            }),
+            calls: [...cell.calls.values()],
+            observations: remapped,
             data,
-            truncated: cell.truncated,
-            ...(images.length ? { images } : {})
+            truncated: cell.truncated || structured.truncated,
+            ...(visibleImages.length ? { images: visibleImages } : {})
         };
         if (cell.status !== 'running')
             cell.terminal = result;
@@ -246,7 +302,7 @@ export class CodeCells {
         if (initial && cell.status !== 'running') {
             if (cell.error !== undefined)
                 throw new CodeCellExecutionError(cell.error, result);
-            return { ...result, content: bounded.content || 'Code Exec completed without emitted text.' };
+            return result;
         }
         return result;
     }

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

@@ -1,9 +1,8 @@
 import { randomUUID } from 'node:crypto';
 import { MarAgentError, describeMarAgentError } from '../../error.js';
 import { AGENT_EXECUTION_POLICY } from '../../runtime/execution-policy.js';
-import { truncateModelText } from '../../runtime/token-budget.js';
 import { allowsToolCaller } from '../callers.js';
-import { structuredToolEventData } from '../output-projection.js';
+import { boundedModelToolOutput, structuredToolEventData } from '../output-projection.js';
 import { executeRegisteredTool } from '../runtime.js';
 /** Capture only the cell's immutable dispatch identity, never the model loop or its AbortSignal. */
 export function createCodeToolDispatch(input) {
@@ -24,7 +23,7 @@ export function createCodeToolDispatch(input) {
                     signal,
                     ...(expected ? { expectedMcpTool: expected } : {})
                 });
-                const bounded = truncateModelText(result.content, AGENT_EXECUTION_POLICY.modelToolOutputTokens);
+                const bounded = boundedModelToolOutput(call.name, result.content, result.data);
                 const data = structuredToolEventData(call.name, result.data);
                 const summary = result.content.slice(0, AGENT_EXECUTION_POLICY.toolEventSummaryCharacters);
                 await input.emit({
@@ -37,7 +36,11 @@ export function createCodeToolDispatch(input) {
                         summary.length < result.content.length,
                     ...(result.artifacts ? { artifacts: result.artifacts } : {})
                 });
-                return { ...result, content: bounded.content };
+                return {
+                    ...result,
+                    content: bounded.content,
+                    truncated: result.truncated === true || bounded.truncated
+                };
             }
             catch (error) {
                 const diagnostic = describeMarAgentError(error, 'MAR_AGENT_HOST_OPERATION_FAILED');

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

@@ -32,6 +32,18 @@ export interface CodeModeEngine {
         onToolCall(call: ToolCall): Promise<ProgrammaticToolResult>;
         onText(value: string, originalBytes?: number): void;
         onImage(value: unknown): void;
+        onObserve(value: {
+            type: 'tool_result';
+            operationId: string;
+        } | {
+            type: 'value';
+            format: 'text' | 'json';
+            value: string;
+            originalBytes: number;
+        } | {
+            type: 'image';
+            value: unknown;
+        }): void;
         onYield(): void;
     }): Promise<{
         readonly stateMutations: readonly CodeModeStateMutation[];

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

@@ -8,6 +8,7 @@ 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';
@@ -20,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.
@@ -29,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. Prefer observe.result for inspecting tool results.
+- 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
@@ -55,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: {
@@ -267,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;
@@ -316,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)
@@ -332,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();
@@ -343,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))
@@ -350,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)
@@ -359,13 +505,34 @@ 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,
-                            error: { code: diagnostic.code, message: diagnostic.message }
+                            error: {
+                                code: diagnostic.code,
+                                // The guest carries the code separately; the outer error adds its own prefix.
+                                message: diagnostic.message.startsWith(`${diagnostic.code}: `)
+                                    ? diagnostic.message.slice(diagnostic.code.length + 2)
+                                    : diagnostic.message
+                            }
                         });
                     }
                 })().catch(fail);
@@ -470,8 +637,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;