@myagentroam/agent 0.9.142 → 0.9.144

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;
+}

package/dist/agent-core/tools/code-mode/quickjs-engine.js

@@ -29,18 +29,22 @@ export async function createCodeModeEngine(options) {
             const stateMutations = [];
             let outputBytes = 0;
             let textCalls = 0;
+            const origins = [];
             const notify = () => {
                 wake?.();
                 wake = undefined;
             };
-            const fail = (handle) => {
+            const fail = (handle, locateSource = false) => {
                 const error = vm.dump(handle);
                 handle.dispose();
                 if (input.signal.aborted)
                     throw input.signal.reason;
                 if (Date.now() >= deadline)
                     throw diagnostic('MAR_AGENT_CODE_TIMEOUT', 'JavaScript execution exceeded its deadline.');
-                const message = String(error?.message ?? error).slice(0, 4096);
+                let message = String(error?.message ?? error).slice(0, 4096);
+                const location = locateSource ? compilerSourceLocation(error, input.code) : '';
+                if (location)
+                    message = message.slice(0, 4096 - location.length) + location;
                 const code = message.includes('out of memory')
                     ? 'MAR_AGENT_CODE_MEMORY_LIMIT'
                     : typeof error?.code === 'string'
@@ -72,6 +76,28 @@ export async function createCodeModeEngine(options) {
           });
         };
         globalThis.__text = ${streamText.toString()};
+        globalThis.__snapshot = (() => {
+          const keys = Reflect.ownKeys, descriptor = Object.getOwnPropertyDescriptor;
+          const create = Object.create, stringify = JSON.stringify;
+          return (value, errorSnapshot) => {
+            const seen = create(null); let depth = 0;
+            function walk(item) {
+              if (item === null || typeof item === 'string' || typeof item === 'number' || typeof item === 'boolean') return stringify(item);
+              if (typeof item !== 'object') throw new Error('Not an original JSON object.');
+              for (let i = 0; i < depth; i++) if (seen[i] === item) throw new Error('Cyclic object.');
+              seen[depth++] = item;
+              const names = keys(item); let text = '{';
+              for (let i = 0; i < names.length; i++) {
+                const name = names[i], field = descriptor(item, name);
+                if (errorSnapshot && depth === 1 && name !== 'code' && name !== 'message' && name !== 'name') continue;
+                if (typeof name !== 'string' || !field || !('value' in field)) throw new Error('Accessor object.');
+                text += stringify(name) + ':' + Number(field.enumerable) + Number(field.writable) + Number(field.configurable) + walk(field.value) + ';';
+              }
+              depth--; return text + '}';
+            }
+            try { return walk(value); } catch { return ''; }
+          };
+        })();
         globalThis.__deepFreeze = function deepFreeze(value) {
           if (value && typeof value === 'object' && !Object.isFrozen(value)) {
             for (const item of Object.values(value)) deepFreeze(item);
@@ -86,6 +112,20 @@ export async function createCodeModeEngine(options) {
             const parseJson = vm.getProp(vm.global, '__parseJson');
             const serialize = vm.getProp(vm.global, '__serialize');
             const formatText = vm.getProp(vm.global, '__text');
+            const snapshotFunction = vm.getProp(vm.global, '__snapshot');
+            const snapshot = (handle, errorSnapshot = false) => {
+                const value = vm.callFunction(snapshotFunction, vm.undefined, handle, errorSnapshot ? vm.true : vm.false);
+                if (value.error) {
+                    value.error.dispose();
+                    return '';
+                }
+                try {
+                    return vm.getString(value.value);
+                }
+                finally {
+                    value.value.dispose();
+                }
+            };
             const deepFreeze = vm.getProp(vm.global, '__deepFreeze');
             const parse = (value) => {
                 const handle = vm.newString(JSON.stringify(value));
@@ -142,11 +182,17 @@ export async function createCodeModeEngine(options) {
                     const deferred = vm.newPromise();
                     deferreds.add(deferred);
                     const job = Promise.resolve()
-                        .then(() => input.onToolCall({ name, arguments: parsed.value }))
+                        .then(() => input.onToolCall({ name, arguments: parsed.value, callId: String(operationId) }))
                         .then((output) => {
                         if (disposed || input.signal.aborted)
                             return;
                         const handle = parse(output);
+                        origins.push({
+                            handle: handle.dup(),
+                            snapshot: snapshot(handle),
+                            errorSnapshot: false,
+                            operationId: String(operationId)
+                        });
                         try {
                             deferred.resolve(handle);
                         }
@@ -163,6 +209,12 @@ export async function createCodeModeEngine(options) {
                         const code = vm.newString(String(error?.code ?? 'MAR_AGENT_HOST_OPERATION_FAILED'));
                         vm.setProp(handle, 'code', code);
                         code.dispose();
+                        origins.push({
+                            handle: handle.dup(),
+                            snapshot: snapshot(handle, true),
+                            errorSnapshot: true,
+                            operationId: String(operationId)
+                        });
                         try {
                             deferred.reject(handle);
                         }
@@ -198,8 +250,28 @@ export async function createCodeModeEngine(options) {
             });
             vm.setProp(vm.global, '__consumeToolCall', consumeToolCall);
             consumeToolCall.dispose();
-            const out = vm.newObject();
-            method(out, 'text', (handle) => {
+            const observeValue = (handle, kind) => {
+                for (const origin of origins) {
+                    if (handle &&
+                        vm.eq(handle, origin.handle) &&
+                        origin.snapshot &&
+                        snapshot(handle, origin.errorSnapshot) === origin.snapshot) {
+                        input.onObserve({ type: 'tool_result', operationId: origin.operationId });
+                        return vm.undefined;
+                    }
+                }
+                if (kind === 'result')
+                    return {
+                        error: guestError('MAR_AGENT_TOOL_INPUT_INVALID', 'observe.result requires an unmodified original tool result or error.')
+                    };
+                // A standalone image is a value, never an original tool-result observation.
+                if (kind === 'image') {
+                    const parsed = jsonValue(handle);
+                    if (parsed.error)
+                        return parsed;
+                    input.onObserve({ type: 'image', value: parsed.value });
+                    return vm.undefined;
+                }
                 const separatorBytes = textCalls ? 1 : 0;
                 const capture = new BoundedTextOutput(Math.max(0, input.limits.outputBytes - outputBytes - separatorBytes), '');
                 const emit = vm.newFunction('textChunk', (chunk) => {
@@ -225,22 +297,23 @@ export async function createCodeModeEngine(options) {
                     const captured = capture.snapshot();
                     outputBytes += captured.retainedBytes + separatorBytes;
                     textCalls++;
-                    input.onText(captured.text, captured.originalBytes);
+                    input.onObserve({
+                        type: 'value',
+                        format: handle && vm.typeof(handle) === 'object' ? 'json' : 'text',
+                        value: captured.text,
+                        originalBytes: captured.originalBytes
+                    });
                 }
                 finally {
                     result.value.dispose();
                 }
                 return vm.undefined;
-            });
-            method(out, 'image', (handle) => {
-                const parsed = jsonValue(handle ?? vm.undefined);
-                if (parsed.error)
-                    return parsed;
-                input.onImage(parsed.value);
-                return vm.undefined;
-            });
-            vm.setProp(vm.global, 'out', out);
-            out.dispose();
+            };
+            const observe = vm.newObject();
+            for (const kind of ['result', 'text', 'image'])
+                method(observe, kind, (handle) => observeValue(handle, kind));
+            vm.setProp(vm.global, 'observe', observe);
+            observe.dispose();
             const stateObject = vm.newObject();
             method(stateObject, 'get', (keyHandle) => {
                 const parsed = key(keyHandle);
@@ -384,7 +457,7 @@ export async function createCodeModeEngine(options) {
               { code: 'MAR_AGENT_TOOL_NOT_AVAILABLE' }); };
           return target[name];
         }});
-        for (const name of ['tools', 'out', 'state', 'catalog', 'cell']) {
+        for (const name of ['tools', 'observe', 'state', 'catalog', 'cell']) {
           const value = globalThis[name];
           Object.freeze(value);
           Object.defineProperty(globalThis, name, {
@@ -394,6 +467,7 @@ export async function createCodeModeEngine(options) {
         delete globalThis.__parseJson;
         delete globalThis.__serialize;
         delete globalThis.__text;
+        delete globalThis.__snapshot;
         delete globalThis.__deepFreeze;
         delete globalThis.__consumeToolCall;
       `);
@@ -405,7 +479,7 @@ export async function createCodeModeEngine(options) {
             try {
                 const evaluated = vm.evalCode(`(async () => {\n${input.code}\n})()`, 'code-mode.js');
                 if (evaluated.error)
-                    fail(evaluated.error);
+                    fail(evaluated.error, true);
                 main = evaluated.value;
                 for (;;) {
                     input.signal.throwIfAborted();
@@ -449,6 +523,9 @@ export async function createCodeModeEngine(options) {
                 parseJson.dispose();
                 serialize.dispose();
                 formatText.dispose();
+                snapshotFunction.dispose();
+                for (const origin of origins)
+                    origin.handle.dispose();
                 deepFreeze.dispose();
             }
         },
@@ -528,7 +605,7 @@ function streamText(value, emit) {
             emit('{');
             let first = true;
             const names = Object.keys(item);
-            // Special-case view_image and native MCP image objects: text omits Base64; out.image keeps pixels.
+            // Special-case view_image and native MCP image objects: text omits Base64; observe.image keeps pixels.
             const imagePayload = names.includes('mimeType') &&
                 typeof item.mimeType === 'string' &&
                 item.mimeType.startsWith('image/');
@@ -542,7 +619,7 @@ function streamText(value, emit) {
                 write(imagePayload &&
                     (name === 'dataBase64' || (name === 'data' && item.type === 'image')) &&
                     typeof field === 'string'
-                    ? '[image payload omitted; use out.image]'
+                    ? '[image payload omitted; use observe.image]'
                     : field, name);
             }
             emit('}');
@@ -551,6 +628,30 @@ function streamText(value, emit) {
     };
     write(value, '');
 }
+function compilerSourceLocation(error, source) {
+    if (error?.name !== 'SyntaxError' ||
+        error.fileName !== 'code-mode.js' ||
+        !Number.isSafeInteger(error.lineNumber) ||
+        error.lineNumber <= 1)
+        return '';
+    // QuickJS counts LF lines and Unicode code-point columns; the wrapper adds one LF line.
+    const lines = source.split('\n');
+    const line = error.lineNumber - 1;
+    if (line > lines.length)
+        return ` (code-mode.js:${source.split(/\r\n|[\r\n\u2028\u2029]/u).length}, end of input)`;
+    const column = Number(typeof error.stack === 'string'
+        ? error.stack.match(/^\s*at code-mode\.js:\d+:(\d+)(?:\n|$)/u)?.[1]
+        : undefined);
+    if (!Number.isSafeInteger(column) || column < 1)
+        return '';
+    const prefix = [
+        ...lines.slice(0, line - 1),
+        Array.from(lines[line - 1])
+            .slice(0, column - 1)
+            .join('')
+    ].join('\n');
+    return ` (code-mode.js:${prefix.split(/\r\n|[\r\n\u2028\u2029]/u).length})`;
+}
 function diagnostic(code, message) {
     return Object.assign(new Error(message), { code });
 }

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

@@ -34,10 +34,17 @@ lines.on('line', async (line) => {
             onText: (value, originalBytes) => send({ kind: 'text', value, originalBytes }),
             onImage: (value) => send({ kind: 'image', value }),
             onYield: () => send({ kind: 'yield' }),
+            onObserve: (value) => send({ kind: 'observe', observation: value }),
             onToolCall: (call) => new Promise((resolve, reject) => {
                 const id = ++sequence;
                 pending.set(id, { resolve, reject });
-                send({ kind: 'call', id, name: call.name, arguments: call.arguments });
+                send({
+                    kind: 'call',
+                    id,
+                    operationId: call.callId,
+                    name: call.name,
+                    arguments: call.arguments
+                });
             })
         });
         if (pending.size)

package/dist/agent-core/tools/contracts.d.ts

@@ -81,7 +81,9 @@ export interface MarAgentToolImageArtifact {
 }
 export type MarAgentToolArtifact = MarAgentToolImageArtifact;
 export interface ToolExecutionResult {
+    calls?: readonly import('./code-mode/observations.js').CodeToolCallRecord[];
     content: string;
+    observations?: readonly import('./code-mode/observations.js').CodeObservation[];
     data?: unknown;
     /** Runtime-only definitions used to encode a Tool Search output. */
     toolSearchTools?: readonly ClientToolDefinition[];
@@ -93,9 +95,11 @@ export interface ToolExecutionResult {
     artifacts?: readonly MarAgentToolArtifact[];
 }
 export interface CodeCellEventData {
+    calls?: readonly import('./code-mode/observations.js').CodeToolCallRecord[];
     cellId: string;
     status: 'running' | 'completed' | 'failed' | 'cancelled';
     cached?: boolean;
+    observations?: readonly import('./code-mode/observations.js').CodeObservation[];
 }
 export interface ExecResult {
     status: 'running' | 'completed' | 'cancelled';

package/dist/agent-core/tools/execution.d.ts

@@ -10,6 +10,8 @@ export type ExecutedToolCall = {
     call: ClientToolCall;
     content: string;
     images?: ToolExecutionResult['images'];
+    observations?: ToolExecutionResult['observations'];
+    calls?: ToolExecutionResult['calls'];
 } & ({
     failed: false;
     output: ToolExecutionResult;

package/dist/agent-core/tools/execution.js

@@ -68,6 +68,8 @@ export async function executeRoundTools(calls, scope) {
                 call,
                 output,
                 content: modelOutput.content,
+                ...(output.calls ? { calls: output.calls } : {}),
+                ...(output.observations ? { observations: output.observations } : {}),
                 ...(output.images?.length ? { images: output.images } : {}),
                 failed: false
             };
@@ -81,7 +83,12 @@ export async function executeRoundTools(calls, scope) {
                 callId: call.callId,
                 ...(parentCallId === undefined ? {} : { parentCallId }),
                 code: diagnostic.code,
-                message: diagnostic.message
+                message: diagnostic.message,
+                ...(partial?.data === undefined
+                    ? {}
+                    : {
+                        data: structuredToolEventData(call.name, partial.data)
+                    })
             });
             return {
                 call,
@@ -94,6 +101,8 @@ export async function executeRoundTools(calls, scope) {
                     : boundedModelToolOutput(call.name, partial.content, partial.data).content,
                 ...(partial?.images?.length ? { images: partial.images } : {}),
                 failed: true,
+                ...(partial?.calls ? { calls: partial.calls } : {}),
+                ...(partial?.observations ? { observations: partial.observations } : {}),
                 error
             };
         }

package/dist/agent-core/tools/output-projection.js

@@ -14,6 +14,10 @@ export function currentExecutionImages(modelInputImages, toolImages) {
         .map((image) => ({ mimeType: image.mimeType, data: Buffer.from(image.data) }));
 }
 export function boundedModelToolOutput(toolName, value, data) {
+    if ((toolName === 'code_exec' || toolName === 'code_exec_wait') &&
+        isRecord(data) &&
+        Array.isArray(data.observations))
+        return { content: value, truncated: data.truncated === true };
     const execDiagnostics = (toolName === 'exec' || toolName === 'exec_wait') &&
         isRecord(data) &&
         typeof data.stdout === 'string' &&
@@ -36,7 +40,37 @@ export function structuredToolEventData(toolName, value) {
         return {
             cellId: value.cellId,
             status: value.status,
-            cached: value.cached === true
+            cached: value.cached === true,
+            ...(Array.isArray(value.calls)
+                ? {
+                    calls: value.calls.filter((entry) => isRecord(entry) &&
+                        [
+                            'apply_patch',
+                            'todo_read',
+                            'todo_write',
+                            'agent_start',
+                            'agent_wait',
+                            'agent_message',
+                            'agent_cancel'
+                        ].includes(String(entry.toolName)))
+                }
+                : {}),
+            ...(Array.isArray(value.observations)
+                ? {
+                    observations: value.observations.filter((entry) => isRecord(entry) &&
+                        entry.type === 'tool_result' &&
+                        isRecord(entry.source) &&
+                        [
+                            'apply_patch',
+                            'todo_read',
+                            'todo_write',
+                            'agent_start',
+                            'agent_wait',
+                            'agent_message',
+                            'agent_cancel'
+                        ].includes(String(entry.source.toolName)))
+                }
+                : {})
         };
     if ((toolName === 'agent_start' ||
         toolName === 'agent_wait' ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/agent",
-  "version": "0.9.142",
+  "version": "0.9.144",
   "description": "Embeddable MAR coding agent SDK and CLI.",
   "license": "Apache-2.0",
   "type": "module",