@myagentroam/agent 0.11.42 → 0.11.44

package/dist/host/local-exec-tool.js

@@ -169,7 +169,8 @@ export class ExecTool {
                 ...(child.signalCode == null ? {} : { exitSignal: child.signalCode }),
                 finalized: false,
                 terminalResultReturned: false,
-                waiters: new Set()
+                waiters: new Set(),
+                outputListeners: new Set()
             };
             this.#processes.set(id, managed);
             if (native) {
@@ -188,6 +189,8 @@ export class ExecTool {
                         return;
                     const decoded = Buffer.from(managed[name].decoder.write(chunk));
                     appendDisplay(managed[name === 'stdout' ? 'stdoutDisplay' : 'stderrDisplay'], decoded);
+                    for (const listener of managed.outputListeners)
+                        listener(name, decoded);
                     appendOutput(managed[name], decoded, this.maxOutputBytes, chunk.length);
                     appendOutput(managed[name === 'stdout' ? 'stdoutHistory' : 'stderrHistory'], decoded, this.maxOutputBytes, chunk.length);
                     notifyProcessChange(managed);
@@ -226,6 +229,8 @@ export class ExecTool {
                 else {
                     const message = Buffer.from(error.message);
                     appendDisplay(managed.stderrDisplay, message);
+                    for (const listener of managed.outputListeners)
+                        listener('stderr', message);
                     appendOutput(managed.stderr, message, this.maxOutputBytes);
                     appendOutput(managed.stderrHistory, message, this.maxOutputBytes);
                     notifyProcessChange(managed);
@@ -421,7 +426,13 @@ export class ExecTool {
                 stderrBytes: process.stderr.totalBytes,
                 stdoutDroppedBytes: stdout.droppedBytes,
                 stderrDroppedBytes: stderr.droppedBytes,
-                displayOutput: displayOutput(process)
+                displayOutput: displayOutput(process),
+                executionSource: {
+                    kind: 'SHELL',
+                    text: process.command.slice(0, 10_000),
+                    cwd: process.cwd.slice(0, 10_000),
+                    truncated: process.command.length > 10_000 || process.cwd.length > 10_000
+                }
             }
         });
         while (this.#completed.size > TOOL_EXECUTION_LIMITS.execMaxCompletedResults)
@@ -484,7 +495,13 @@ export class ExecTool {
             stderrBytes: process.stderr.totalBytes,
             stdoutDroppedBytes: stdout.droppedBytes,
             stderrDroppedBytes: stderr.droppedBytes,
-            displayOutput: displayOutput(process)
+            displayOutput: displayOutput(process),
+            executionSource: {
+                kind: 'SHELL',
+                text: process.command.slice(0, 10_000),
+                cwd: process.cwd.slice(0, 10_000),
+                truncated: process.command.length > 10_000 || process.cwd.length > 10_000
+            }
         };
     }
     async dispose() {
@@ -529,6 +546,10 @@ function finalizeManagedProcess(managed, maximumOutputBytes, exitCode) {
     const stderrEnd = Buffer.from(managed.stderr.decoder.end());
     appendDisplay(managed.stdoutDisplay, stdoutEnd);
     appendDisplay(managed.stderrDisplay, stderrEnd);
+    for (const listener of managed.outputListeners) {
+        listener('stdout', stdoutEnd);
+        listener('stderr', stderrEnd);
+    }
     appendOutput(managed.stdout, stdoutEnd, maximumOutputBytes);
     appendOutput(managed.stderr, stderrEnd, maximumOutputBytes);
     appendOutput(managed.stdoutHistory, stdoutEnd, maximumOutputBytes);
@@ -642,34 +663,36 @@ async function waitForProcessCompletion(processId, managed, waitMs, signal, inte
         stopOutput?.();
     }
 }
-/** Coalesce display snapshots without consuming output or queueing behind a slow observer. */
+/** Coalesce decoded chunks into bounded per-call frames without blocking the process. */
 function watchProcessOutput(processId, managed, onOutput) {
     let stopped = false;
-    let dirty = false;
+    let stdout = { value: Buffer.alloc(0), droppedBytes: 0 };
+    let stderr = { value: Buffer.alloc(0), droppedBytes: 0 };
     let timer;
     let inFlight;
     let failed = false;
+    let initialSnapshot = managed.stdoutDisplay.value.length > 0 || managed.stderrDisplay.value.length > 0;
     const publish = () => {
-        dirty = false;
-        const preview = (output) => {
-            const bounded = createOutputBuffer();
-            for (const chunk of output.chunks)
-                appendOutput(bounded, chunk, TOOL_EXECUTION_LIMITS.execProgressMaxOutputBytes);
-            const result = consumeOutput(bounded);
-            return { ...result, droppedBytes: result.droppedBytes + output.droppedBytes };
-        };
-        const stdout = preview(managed.stdout);
-        const stderr = preview(managed.stderr);
+        const frameOut = stdout;
+        const frameErr = stderr;
+        stdout = { value: Buffer.alloc(0), droppedBytes: 0 };
+        stderr = { value: Buffer.alloc(0), droppedBytes: 0 };
+        const snapshot = displayOutput(managed);
+        const snapshotFrame = initialSnapshot || frameOut.droppedBytes > 0 || frameErr.droppedBytes > 0;
+        initialSnapshot = false;
         inFlight = Promise.resolve()
             .then(() => {
             if (stopped)
                 return;
             return onOutput({
                 processId,
-                stdout: stdout.value,
-                stderr: stderr.value,
-                truncated: stdout.droppedBytes > 0 || stderr.droppedBytes > 0,
-                displayOutput: displayOutput(managed)
+                mode: snapshotFrame ? 'snapshot' : 'delta',
+                stdout: snapshotFrame ? snapshot.stdout : frameOut.value.toString('utf8'),
+                stderr: snapshotFrame ? snapshot.stderr : frameErr.value.toString('utf8'),
+                truncated: snapshotFrame
+                    ? snapshot.stdoutDroppedBytes > 0 || snapshot.stderrDroppedBytes > 0
+                    : frameOut.droppedBytes > 0 || frameErr.droppedBytes > 0,
+                displayOutput: snapshot
             });
         })
             .catch(() => {
@@ -678,7 +701,7 @@ function watchProcessOutput(processId, managed, onOutput) {
         })
             .finally(() => {
             inFlight = undefined;
-            if (dirty)
+            if (stdout.value.length || stderr.value.length)
                 schedule();
         });
     };
@@ -691,17 +714,18 @@ function watchProcessOutput(processId, managed, onOutput) {
         }, TOOL_EXECUTION_LIMITS.execProgressIntervalMs);
         timer.unref();
     };
-    const changed = () => {
-        if (managed.stdout.bytes === 0 && managed.stderr.bytes === 0)
+    const changed = (channel, chunk) => {
+        if (chunk.length === 0)
             return;
-        dirty = true;
+        appendDisplay(channel === 'stdout' ? stdout : stderr, chunk);
         schedule();
     };
-    managed.waiters.add(changed);
-    changed();
+    managed.outputListeners.add(changed);
+    if (initialSnapshot)
+        schedule();
     return () => {
         stopped = true;
-        managed.waiters.delete(changed);
+        managed.outputListeners.delete(changed);
         if (timer)
             clearTimeout(timer);
     };

package/dist/runtime/async-queue.d.ts

@@ -1,7 +1,7 @@
 export declare class AsyncQueue<T> implements AsyncIterable<T> {
     #private;
     /** Best-effort live values are delivered only to an actively waiting consumer. */
-    pushIfWaiting(value: T): void;
+    pushIfWaiting(value: T): boolean;
     push(value: T): void;
     close(): void;
     discardIfUnobserved(): boolean;

package/dist/runtime/async-queue.js

@@ -8,8 +8,10 @@ export class AsyncQueue {
     #discarded = false;
     /** Best-effort live values are delivered only to an actively waiting consumer. */
     pushIfWaiting(value) {
-        if (this.#waiterOffset < this.#waiters.length)
-            this.push(value);
+        if (this.#waiterOffset >= this.#waiters.length || this.#closed || this.#discarded)
+            return false;
+        this.push(value);
+        return true;
     }
     push(value) {
         if (this.#closed || this.#discarded)

package/dist/runtime/events.d.ts

@@ -91,7 +91,7 @@ export type AgentEvent = AgentEventBase & ({
     truncated?: boolean;
 } | {
     type: 'tool.output';
-    toolName: 'exec' | 'exec_wait';
+    toolName: 'exec' | 'exec_wait' | 'code_exec_wait';
     callId: string;
     parentCallId?: string;
     output: import('../tools/contracts.js').ExecOutputSnapshot;

package/dist/runtime/wait.js

@@ -40,12 +40,19 @@ export function waitForToolCondition(input) {
                 reject(error);
         };
         const check = () => {
-            if (input.signal?.aborted)
-                abort();
-            else if (input.ready())
-                finish('ready');
-            else if (input.interrupt?.pending())
-                finish('interrupted');
+            if (settled)
+                return;
+            try {
+                if (input.signal?.aborted)
+                    abort();
+                else if (input.ready())
+                    finish('ready');
+                else if (input.interrupt?.pending())
+                    finish('interrupted');
+            }
+            catch (error) {
+                finish('interrupted', error);
+            }
         };
         const abort = () => finish('interrupted', input.signal?.reason ??
             new AgentError('MAR_AGENT_EXECUTION_CANCELLED', 'Execution cancelled.'));

package/dist/sdk/session-execution.d.ts

@@ -105,6 +105,7 @@ export declare class SessionExecution {
     private terminalAdmitted;
     private releaseLease;
     private eventSequence;
+    private readonly missedOutput;
     private persistedTerminal;
     private completionAdmitted;
     private appendedMessages;

package/dist/sdk/session-execution.js

@@ -65,6 +65,7 @@ export class SessionExecution {
     terminalAdmitted = false;
     releaseLease;
     eventSequence = 0;
+    missedOutput = new Set();
     persistedTerminal = false;
     completionAdmitted = false;
     appendedMessages = [];
@@ -235,10 +236,32 @@ export class SessionExecution {
                 full.type === 'execution.failed' ||
                 full.type === 'execution.cancelled')
                 this.#observedTerminal = structuredClone(full);
-            if (full.type === 'tool.output')
-                this.events.pushIfWaiting(full);
-            else
+            if (full.type === 'tool.output') {
+                const missed = this.missedOutput.has(full.callId);
+                const deliver = missed && full.output.displayOutput
+                    ? {
+                        ...full,
+                        output: {
+                            ...full.output,
+                            mode: 'snapshot',
+                            stdout: full.output.displayOutput.stdout,
+                            stderr: full.output.displayOutput.stderr,
+                            truncated: full.output.truncated ||
+                                full.output.displayOutput.stdoutDroppedBytes > 0 ||
+                                full.output.displayOutput.stderrDroppedBytes > 0
+                        }
+                    }
+                    : full;
+                if (this.events.pushIfWaiting(deliver))
+                    this.missedOutput.delete(full.callId);
+                else
+                    this.missedOutput.add(full.callId);
+            }
+            else {
+                if (full.type === 'tool.completed' || full.type === 'tool.failed')
+                    this.missedOutput.delete(full.callId);
                 this.events.push(full);
+            }
             ports.observe?.(full);
             this.compactRequests.publish(full);
             try {

package/dist/tools/code-mode/cells.d.ts

@@ -3,7 +3,7 @@ import type { ToolExecutionContext, ToolExecutionResult } from '../contracts.js'
 import type { CodeObservation, CodeToolCallRecord } from '../../session/code-observation-contract.js';
 export interface CellOutput {
     call(value: CodeToolCallRecord): void;
-    observe(value: CodeObservation): void;
+    observe(value: CodeObservation, display?: CodeObservation, displayHeadTruncated?: boolean): void;
     text(value: string, originalBytes?: number): void;
     image(value: NonNullable<ToolExecutionResult['images']>[number]): void;
     yield(): void;

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

@@ -6,6 +6,7 @@ import { TOOL_EXECUTION_LIMITS as limits } from '../execution-limits.js';
 import { waitForToolCondition, waitMetadata } from '../wait.js';
 import { BoundedTextOutput, renderCapturedText } from './text-output.js';
 import { boundObservations, newObservationId } from './observations.js';
+import { publicCodeObservations } from '../output-projection.js';
 import { selectObservationImages, visibleObservation } from '../../session/code-observation-projection.js';
 /** Keeps a failed tool call observable without discarding earlier explicit output. */
 export class CodeCellExecutionError extends AgentError {
@@ -20,6 +21,110 @@ export class CodeCellExecutionError extends AgentError {
         this.result = result;
     }
 }
+/** A waiting call owns its bounded display window; delivery never delays the cell. */
+function forwardCellOutput(publish) {
+    let stopped = false;
+    let failed = false;
+    let inFlight = false;
+    let pending = false;
+    let latest;
+    // Source metadata is bounded by the cell's tool-call budget; text shares one window.
+    const sources = new Map();
+    const trim = (channel) => {
+        let excess = [...sources.values()].reduce((bytes, source) => bytes + Buffer.byteLength(source[channel]), 0) - limits.execProgressMaxOutputBytes;
+        for (const source of sources.values()) {
+            if (excess <= 0)
+                break;
+            const bytes = Buffer.from(source[channel]);
+            let removed = Math.min(excess, bytes.length);
+            while (removed < bytes.length && (bytes[removed] & 0xc0) === 0x80)
+                removed++;
+            source[channel] = bytes.subarray(removed).toString('utf8');
+            excess -= removed;
+        }
+    };
+    const snapshot = () => {
+        const entries = [...sources.values()];
+        const stdout = entries.map((source) => source.stdout).join('');
+        const stderr = entries.map((source) => source.stderr).join('');
+        const stdoutDroppedBytes = entries.reduce((bytes, source) => bytes + source.stdoutBytes, 0) - Buffer.byteLength(stdout);
+        const stderrDroppedBytes = entries.reduce((bytes, source) => bytes + source.stderrBytes, 0) - Buffer.byteLength(stderr);
+        return {
+            ...latest,
+            mode: 'snapshot',
+            stdout,
+            stderr,
+            truncated: entries.some((source) => source.truncated) ||
+                stdoutDroppedBytes > 0 ||
+                stderrDroppedBytes > 0,
+            displayOutput: {
+                stdout,
+                stderr,
+                stdoutDroppedBytes,
+                stderrDroppedBytes
+            }
+        };
+    };
+    const send = (output) => {
+        inFlight = true;
+        void Promise.resolve()
+            .then(() => (stopped ? undefined : publish(output)))
+            .catch(() => {
+            failed = true;
+        })
+            .finally(() => {
+            inFlight = false;
+            if (!stopped && !failed && pending) {
+                pending = false;
+                send(snapshot());
+            }
+        });
+    };
+    return {
+        onOutput(output) {
+            if (stopped || failed)
+                return;
+            const isSnapshot = output.mode !== 'delta';
+            const source = sources.get(output.processId) ?? {
+                stdout: '',
+                stderr: '',
+                stdoutBytes: 0,
+                stderrBytes: 0,
+                truncated: false
+            };
+            if (isSnapshot) {
+                source.stdout = output.stdout;
+                source.stderr = output.stderr;
+                source.stdoutBytes =
+                    Buffer.byteLength(output.stdout) + (output.displayOutput?.stdoutDroppedBytes ?? 0);
+                source.stderrBytes =
+                    Buffer.byteLength(output.stderr) + (output.displayOutput?.stderrDroppedBytes ?? 0);
+                source.truncated = output.truncated;
+            }
+            else {
+                source.stdout += output.stdout;
+                source.stderr += output.stderr;
+                source.stdoutBytes += Buffer.byteLength(output.stdout);
+                source.stderrBytes += Buffer.byteLength(output.stderr);
+                source.truncated ||= output.truncated;
+            }
+            sources.set(output.processId, source);
+            trim('stdout');
+            trim('stderr');
+            latest = output;
+            if (inFlight)
+                pending = true;
+            else
+                send(isSnapshot ? snapshot() : { ...output, displayOutput: snapshot().displayOutput });
+        },
+        stop() {
+            stopped = true;
+            pending = false;
+            sources.clear();
+            latest = undefined;
+        }
+    };
+}
 function options(value, wait) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         throw new AgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Code Exec options must be an object.');
@@ -77,6 +182,7 @@ export class CodeCells {
             throw new AgentError('MAR_AGENT_PROCESS_LIMIT', `The Local Host shared running-cell limit (${limits.codeMaxConcurrentCells}) was reached.`);
         const controller = new AbortController();
         const cell = {
+            source: { kind: 'CODE', text: source.slice(0, 10_000), truncated: source.length > 10_000 },
             cellId: this.#handles.create(),
             sessionId: context.sessionId,
             executionId: context.executionId,
@@ -90,9 +196,14 @@ export class CodeCells {
             yielded: false,
             truncated: false,
             listeners: new Set(),
+            outputListeners: new Set(),
             done: Promise.resolve()
         };
         this.#cells.set(cell.cellId, cell);
+        const unsubscribeOutput = context.codeMode?.subscribeToolOutput?.((output) => {
+            for (const listener of cell.outputListeners)
+                listener(output);
+        });
         const notify = () => {
             for (const listener of cell.listeners)
                 listener();
@@ -104,7 +215,18 @@ export class CodeCells {
             releaseSession = await context.codeMode?.retainSession?.();
             return run(source, { ...context, signal: controller.signal, waitInterrupt: undefined }, {
                 call: (value) => cell.calls.set(value.callId, value),
-                observe: (value) => cell.observations.push(value),
+                observe: (value, display = value, displayHeadTruncated = false) => {
+                    cell.observations.push(value);
+                    const observations = [...(cell.display?.observations ?? []), display];
+                    cell.display = publicCodeObservations(observations, {
+                        cellId: cell.cellId,
+                        status: cell.status,
+                        observations,
+                        ...(cell.display?.outputHeadTruncated || displayHeadTruncated
+                            ? { outputHeadTruncated: true }
+                            : {})
+                    });
+                },
                 text: (text, originalBytes) => cell.text.append(text, originalBytes),
                 image: (image) => cell.images.push(image),
                 yield: () => {
@@ -124,6 +246,7 @@ export class CodeCells {
             outcome = controller.signal.aborted ? 'cancelled' : 'failed';
         })
             .then(async () => {
+            unsubscribeOutput?.();
             try {
                 await context.codeMode?.onSettled?.({
                     cellId: cell.cellId,
@@ -179,7 +302,23 @@ export class CodeCells {
                     abort();
             });
         }
-        return this.#wait(cell, input, context.signal, false, context.codeMode?.supportsImages === true, input.action === 'poll' ? context.waitInterrupt : undefined);
+        const forward = cell.executionId !== context.executionId &&
+            input.action === 'poll' &&
+            input.yieldMs > 0 &&
+            context.onOutput
+            ? forwardCellOutput(context.onOutput)
+            : undefined;
+        if (forward)
+            cell.outputListeners.add(forward.onOutput);
+        try {
+            return await this.#wait(cell, input, context.signal, false, context.codeMode?.supportsImages === true, input.action === 'poll' ? context.waitInterrupt : undefined);
+        }
+        finally {
+            if (forward) {
+                cell.outputListeners.delete(forward.onOutput);
+                forward.stop();
+            }
+        }
     }
     async #wait(cell, input, signal, initial, supportsImages, interrupt) {
         const outcome = input.yieldMs === 0
@@ -232,6 +371,14 @@ export class CodeCells {
                         observations: visible.observations.map(visibleObservation)
                     }),
                     data,
+                    eventData: {
+                        ...data,
+                        ...cell.display,
+                        status: cell.status,
+                        cached: true,
+                        ...wait,
+                        executionSource: cell.source
+                    },
                     truncated: data.truncated
                 };
             }
@@ -247,6 +394,7 @@ export class CodeCells {
             return {
                 ...cell.terminal,
                 data,
+                eventData: { ...data, executionSource: cell.source },
                 content: JSON.stringify(data),
                 truncated: cell.terminal.truncated || bounded.truncated
             };
@@ -301,6 +449,12 @@ export class CodeCells {
             calls: [...cell.calls.values()],
             observations: remapped,
             data,
+            eventData: {
+                ...data,
+                ...cell.display,
+                status: cell.status,
+                executionSource: cell.source
+            },
             truncated: cell.truncated || structured.truncated,
             ...(visibleImages.length ? { images: visibleImages } : {})
         };

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

@@ -49,6 +49,9 @@ export function createCodeToolDispatch(input) {
                 const { eventData: _eventData, ...guestResult } = result;
                 return {
                     ...guestResult,
+                    ...((call.name === 'exec' || call.name === 'exec_wait') && data !== undefined
+                        ? { eventData: { ...data } }
+                        : {}),
                     content: bounded.content,
                     truncated: result.truncated === true || bounded.truncated
                 };

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

@@ -41,6 +41,8 @@ export interface CodeModeEngine {
             format: 'text' | 'json';
             value: string;
             originalBytes: number;
+            /** Public display tail, independent of the model capture budget. */
+            displayValue?: string;
         } | {
             type: 'image';
             value: unknown;

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

@@ -300,7 +300,7 @@ export class CodeModeTool {
         const images = [];
         const observations = [];
         let observationBytes = 0;
-        const appendObservation = (value, originalBytes) => {
+        const appendObservation = (value, originalBytes, display) => {
             const capture = new BoundedTextOutput(Math.max(0, limits.codeMaxOutputBytes - observationBytes), '');
             const body = value.type === 'tool_result' ? value.result.content : value.value;
             capture.append(body);
@@ -323,7 +323,10 @@ export class CodeModeTool {
                     truncated: value.truncated === true || bounded.droppedBytes > 0
                 };
             observations.push(observation);
-            output?.observe(observation);
+            output?.observe(observation, display ?? value, display !== undefined &&
+                (display.type === 'tool_result'
+                    ? display.result.truncated === true
+                    : display.truncated === true));
         };
         const toolResults = new Map();
         let transportBytes = 0;
@@ -389,6 +392,7 @@ export class CodeModeTool {
                     return index;
                 };
                 let observation;
+                let displayObservation;
                 if (value.type === 'tool_result' && typeof value.operationId === 'string') {
                     const original = toolResults.get(value.operationId);
                     if (!original)
@@ -423,6 +427,23 @@ export class CodeModeTool {
                             ...(indices?.length ? { imageIndices: indices } : {})
                         }
                     };
+                    const display = original.result.eventData?.displayOutput;
+                    if ((original.source.toolName === 'exec' || original.source.toolName === 'exec_wait') &&
+                        display !== null &&
+                        typeof display === 'object' &&
+                        'stdout' in display &&
+                        'stderr' in display &&
+                        typeof display.stdout === 'string' &&
+                        typeof display.stderr === 'string')
+                        displayObservation = {
+                            ...observation,
+                            result: {
+                                content: '',
+                                data: { stdout: display.stdout, stderr: display.stderr },
+                                truncated: ('stdoutDroppedBytes' in display && Number(display.stdoutDroppedBytes) > 0) ||
+                                    ('stderrDroppedBytes' in display && Number(display.stderrDroppedBytes) > 0)
+                            }
+                        };
                 }
                 else if (value.type === 'image') {
                     observation = {
@@ -444,12 +465,22 @@ export class CodeModeTool {
                         truncated: typeof value.originalBytes === 'number' &&
                             value.originalBytes > Buffer.byteLength(value.value)
                     };
+                    if (typeof value.displayValue === 'string') {
+                        if (Buffer.byteLength(value.displayValue) > 10_000)
+                            throw new AgentError('MAR_AGENT_CODE_PROTOCOL_ERROR', 'Code Mode sent oversized display text.');
+                        displayObservation = {
+                            ...observation,
+                            value: value.displayValue,
+                            truncated: typeof value.originalBytes === 'number' &&
+                                value.originalBytes > Buffer.byteLength(value.displayValue)
+                        };
+                    }
                 }
                 else
                     throw new AgentError('MAR_AGENT_CODE_PROTOCOL_ERROR', 'Invalid observation frame.');
                 appendObservation(observation, value.type === 'value' && typeof value.originalBytes === 'number'
                     ? value.originalBytes
-                    : undefined);
+                    : undefined, displayObservation);
             }
             else if (frame.kind === 'text' && typeof frame.value === 'string') {
                 const originalBytes = frame.originalBytes ?? Buffer.byteLength(frame.value);
@@ -527,10 +558,11 @@ export class CodeModeTool {
                                     : undefined
                             }
                         });
-                        const { content, ...structured } = output;
+                        const { eventData: _eventData, ...guestOutput } = output;
+                        const { content, ...structured } = guestOutput;
                         const projected = output.data !== undefined && content === JSON.stringify(output.data)
                             ? structured
-                            : output;
+                            : guestOutput;
                         await write({ id, ok: true, output: projected });
                     }
                     catch (error) {

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

@@ -354,6 +354,7 @@ export async function createCodeModeEngine(options) {
                 }
                 const separatorBytes = textCalls ? 1 : 0;
                 const capture = new BoundedTextOutput(Math.max(0, input.limits.outputBytes - outputBytes - separatorBytes), '');
+                const display = new BoundedTextOutput(10_000, '', 'tail');
                 const emit = vm.newFunction('textChunk', (chunk) => {
                     if (!chunk || vm.typeof(chunk) !== 'string')
                         return {
@@ -366,7 +367,9 @@ export async function createCodeModeEngine(options) {
                         return {
                             error: guestError('MAR_AGENT_TOOL_OUTPUT_LIMIT', 'Text serialization chunk limit exceeded.')
                         };
-                    capture.append(vm.getString(chunk));
+                    const text = vm.getString(chunk);
+                    capture.append(text);
+                    display.append(text);
                     return vm.undefined;
                 });
                 const result = callGuest(formatText, vm.undefined, handle ?? vm.undefined, emit);
@@ -381,6 +384,7 @@ export async function createCodeModeEngine(options) {
                         type: 'value',
                         format: handle && vm.typeof(handle) === 'object' ? 'json' : 'text',
                         value: captured.text,
+                        displayValue: display.snapshot().text,
                         originalBytes: captured.originalBytes
                     });
                 }

package/dist/tools/code-mode/text-output.d.ts

@@ -1,9 +1,10 @@
 export function renderCapturedText(snapshot: any, imageCount?: number): string;
 /** Bounded UTF-8 capture shared by trusted engines, the bridge and retained cells. */
 export class BoundedTextOutput {
-    constructor(maximumBytes: any, separator?: string);
+    constructor(maximumBytes: any, separator?: string, retention?: string);
     maximumBytes: any;
     separator: string;
+    retention: string;
     append(value: any, originalBytes?: number): void;
     snapshot(): {
         text: string;

package/dist/tools/code-mode/text-output.js

@@ -6,9 +6,10 @@ export class BoundedTextOutput {
     #retained = 0;
     #hasValue = false;
     #sealed = false;
-    constructor(maximumBytes, separator = '\n') {
+    constructor(maximumBytes, separator = '\n', retention = 'head') {
         this.maximumBytes = maximumBytes;
         this.separator = separator;
+        this.retention = retention;
     }
     append(value, originalBytes = Buffer.byteLength(value)) {
         const separator = this.#hasValue ? this.separator : '';
@@ -16,10 +17,22 @@ export class BoundedTextOutput {
         this.#original += Buffer.byteLength(separator) + originalBytes;
         this.#capture(separator);
         this.#capture(value);
-        if (originalBytes > Buffer.byteLength(value))
+        if (this.retention === 'head' && originalBytes > Buffer.byteLength(value))
             this.#sealed = true;
     }
     #capture(value) {
+        if (this.retention === 'tail') {
+            let start = Math.max(0, value.length - this.maximumBytes);
+            if (start > 0 && /[\uDC00-\uDFFF]/u.test(value[start]))
+                start++;
+            const bytes = Buffer.from(this.#chunks.join('') + value.slice(start));
+            let offset = Math.max(0, bytes.length - this.maximumBytes);
+            while (offset < bytes.length && (bytes[offset] & 0xc0) === 0x80)
+                offset++;
+            this.#chunks = [bytes.subarray(offset).toString('utf8')];
+            this.#retained = bytes.length - offset;
+            return;
+        }
         const remaining = Math.max(0, this.maximumBytes - this.#used);
         if (this.#sealed || !value.length)
             return;

package/dist/tools/contracts.d.ts

@@ -41,6 +41,7 @@ export interface ToolExecutionContext {
         readonly data: Buffer;
     }[];
     codeMode?: {
+        subscribeToolOutput?(listener: (output: ExecOutputSnapshot) => void): () => void;
         retainSession?(): Promise<() => Promise<void>>;
         onSettled?(result: CodeCellEventData): Promise<void>;
         supportsImages?: boolean;
@@ -94,6 +95,8 @@ export interface AgentToolImageArtifact {
 export type AgentToolArtifact = AgentToolImageArtifact;
 export interface ExecOutputSnapshot {
     processId: string;
+    /** Omitted for legacy snapshot sources; delta is a real decoded process chunk. */
+    mode?: 'delta' | 'snapshot';
     stdout: string;
     stderr: string;
     truncated: boolean;
@@ -106,6 +109,13 @@ export interface ExecDisplayOutput {
     stdoutDroppedBytes: number;
     stderrDroppedBytes: number;
 }
+/** Bounded original input for public presentation, never added to model results. */
+export interface ExecutionSource {
+    kind: 'SHELL' | 'CODE';
+    text: string;
+    cwd?: string;
+    truncated: boolean;
+}
 export interface ToolExecutionResult {
     calls?: readonly import('../session/code-observation-contract.js').CodeToolCallRecord[];
     content: string;
@@ -124,6 +134,7 @@ export interface ToolExecutionResult {
     resultExtensions?: readonly import('./result-extension-contract.js').ToolResultExtension[];
 }
 export interface CodeCellEventData {
+    executionSource?: ExecutionSource;
     permissionStop?: import('./permission-contract.js').PermissionStop;
     calls?: readonly import('../session/code-observation-contract.js').CodeToolCallRecord[];
     cellId: string;
@@ -132,6 +143,8 @@ export interface CodeCellEventData {
     reason?: 'steer';
     cached?: boolean;
     truncated?: boolean;
+    /** Public output projection discarded older text; not inferred from source truncation. */
+    outputHeadTruncated?: boolean;
     observations?: readonly import('../session/code-observation-contract.js').CodeObservation[];
     error?: {
         code: string;
@@ -139,6 +152,7 @@ export interface CodeCellEventData {
     };
 }
 export interface ExecResult {
+    executionSource?: ExecutionSource;
     status: 'running' | 'completed' | 'cancelled';
     waitOutcome?: import('./wait.js').ToolWaitOutcome;
     reason?: 'steer';

package/dist/tools/execution.js

@@ -24,6 +24,7 @@ export async function createRoundToolRuntimeContext(scope, call, signal) {
     const assertSessionLive = scope.assertLive;
     const assertExecutionLive = scope.assertExecutionLive;
     const emitCodeEvent = scope.emit;
+    const outputListeners = new Set();
     const retainSession = codeMode.retainSession?.bind(codeMode);
     let retained = 0;
     const assertDispatchLive = () => {
@@ -40,6 +41,10 @@ export async function createRoundToolRuntimeContext(scope, call, signal) {
         signal,
         codeMode: {
             ...codeMode,
+            subscribeToolOutput: (listener) => {
+                outputListeners.add(listener);
+                return () => outputListeners.delete(listener);
+            },
             ...(retainSession === undefined
                 ? {}
                 : {
@@ -67,7 +72,12 @@ export async function createRoundToolRuntimeContext(scope, call, signal) {
                 parentCallId: call.callId,
                 schedule: scope.schedule,
                 assertLive: assertDispatchLive,
-                emit: (event) => emitCodeEvent(event, assertDispatchLive)
+                emit: (event) => {
+                    if (event.type === 'tool.output')
+                        for (const listener of outputListeners)
+                            listener(event.output);
+                    return emitCodeEvent(event, assertDispatchLive);
+                }
             })
         },
         ...(scope.extensionToolNames.has(call.name) && recentImages !== undefined
@@ -118,7 +128,10 @@ export async function executeRoundTools(calls, scope) {
                 : typeof output.eventSummary === 'string'
                     ? output.eventSummary
                     : '');
-            const structuredData = call.name === 'exec' || call.name === 'exec_wait'
+            const structuredData = call.name === 'exec' ||
+                call.name === 'exec_wait' ||
+                call.name === 'code_exec' ||
+                call.name === 'code_exec_wait'
                 ? structuredToolEventData(call.name, output.eventData ?? output.data)
                 : output.eventData === undefined
                     ? structuredToolEventData(call.name, output.data)
@@ -159,7 +172,7 @@ export async function executeRoundTools(calls, scope) {
             const eventData = failureData ??
                 (partial?.data === undefined
                     ? undefined
-                    : structuredToolEventData(call.name, partial.data));
+                    : structuredToolEventData(call.name, partial.eventData ?? partial.data));
             await scope.emit({
                 type: 'tool.failed',
                 ...(failedToolResultExtensions(error)

package/dist/tools/local/exec.js

@@ -2,7 +2,7 @@ import { AgentError } from '../../error.js';
 import { TOOL_EXECUTION_LIMITS } from '../execution-limits.js';
 /** Share the model-facing body across direct calls and original Code Mode observations. */
 export function formatExecResult(result) {
-    const { displayOutput, ...modelResult } = result;
+    const { displayOutput, executionSource, ...modelResult } = result;
     const visible = { ...modelResult };
     if (result.stderr === '')
         delete visible.stderr;
@@ -22,8 +22,10 @@ export function formatExecResult(result) {
         delete visible.cached;
     return {
         content: JSON.stringify(visible),
-        data: displayOutput === undefined ? result : modelResult,
-        ...(displayOutput === undefined ? {} : { eventData: { ...modelResult, displayOutput } }),
+        data: executionSource === undefined && displayOutput === undefined ? result : modelResult,
+        ...(displayOutput === undefined && executionSource === undefined
+            ? {}
+            : { eventData: { ...modelResult, displayOutput, executionSource } }),
         truncated: result.truncated
     };
 }

package/dist/tools/output-projection.d.ts

@@ -12,6 +12,8 @@ export declare function boundedModelToolOutput(toolName: string, value: string,
 };
 /** The opted-in allowlist fails closed and never mutates the invocation arguments. */
 export declare function publicToolEventInput(value: unknown, fields: readonly string[]): Readonly<Record<string, unknown>>;
+/** Explicit observations are public, but their event projection must remain bounded. */
+export declare function publicCodeObservations(values: unknown, data: CodeCellEventData): CodeCellEventData;
 /** Project only known, validated tool result shapes into public structured events. */
 export declare function structuredToolEventData(toolName: string, value: unknown): CodeCellEventData | ExecResult | ApplyPatchResult | ReadEventData | ViewImageResult | SleepResult | PublicToolMetadata | undefined;
 /** Partial patch facts are allowlisted; arbitrary error details never become public event data. */

package/dist/tools/output-projection.js

@@ -68,7 +68,7 @@ export function publicToolEventInput(value, fields) {
     }
 }
 /** Explicit observations are public, but their event projection must remain bounded. */
-function publicCodeObservations(values, data) {
+export function publicCodeObservations(values, data) {
     if (!Array.isArray(values))
         return data;
     const retained = new Set(data.observations ?? []);
@@ -76,6 +76,7 @@ function publicCodeObservations(values, data) {
     let displayedCount = 0;
     let remaining = 10_000;
     let truncated = false;
+    let headTruncated = data.outputHeadTruncated === true;
     const clip = (text) => {
         let start = Math.max(0, text.length - remaining);
         if (start > 0 && /[\uDC00-\uDFFF]/u.test(text[start]))
@@ -83,6 +84,7 @@ function publicCodeObservations(values, data) {
         const result = text.slice(start);
         remaining -= result.length;
         truncated ||= start > 0;
+        headTruncated ||= start > 0;
         return result;
     };
     for (let index = values.length - 1; index >= 0; index--) {
@@ -95,6 +97,7 @@ function publicCodeObservations(values, data) {
             (entry.format === 'text' || entry.format === 'json' || entry.format === 'image')) {
             if (displayedCount >= 32) {
                 truncated = true;
+                headTruncated = true;
                 continue;
             }
             displayedCount++;
@@ -122,6 +125,7 @@ function publicCodeObservations(values, data) {
                 (entry.outcome === 'completed' || entry.outcome === 'failed')) {
                 if (displayedCount >= 32) {
                     truncated = true;
+                    headTruncated = true;
                     continue;
                 }
                 displayedCount++;
@@ -146,7 +150,12 @@ function publicCodeObservations(values, data) {
             }
         }
     }
-    return { ...data, observations: selected, ...(truncated ? { truncated: true } : {}) };
+    return {
+        ...data,
+        observations: selected,
+        ...(truncated ? { truncated: true } : {}),
+        ...(headTruncated ? { outputHeadTruncated: true } : {})
+    };
 }
 /** Project only known, validated tool result shapes into public structured events. */
 export function structuredToolEventData(toolName, value) {
@@ -176,7 +185,20 @@ export function structuredToolEventData(toolName, value) {
         ['running', 'completed', 'failed', 'cancelled'].includes(String(value.status)))
         return publicCodeObservations(value.observations, {
             cellId: value.cellId,
+            ...(isRecord(value.executionSource) &&
+                value.executionSource.kind === 'CODE' &&
+                typeof value.executionSource.text === 'string'
+                ? {
+                    executionSource: {
+                        kind: 'CODE',
+                        text: value.executionSource.text.slice(0, 10_000),
+                        truncated: value.executionSource.truncated === true ||
+                            value.executionSource.text.length > 10_000
+                    }
+                }
+                : {}),
             status: value.status,
+            ...(value.outputHeadTruncated === true ? { outputHeadTruncated: true } : {}),
             cached: value.cached === true,
             ...(['snapshot', 'completion', 'timeout', 'yield', 'interrupted'].includes(String(value.waitOutcome))
                 ? { waitOutcome: value.waitOutcome }

package/dist/tools/runtime-context.d.ts

@@ -19,7 +19,7 @@ export interface ToolImageStore extends ResourceStore {
 }
 export type ToolRuntimeEvent = {
     type: 'tool.output';
-    toolName: 'exec' | 'exec_wait';
+    toolName: 'exec' | 'exec_wait' | 'code_exec_wait';
     callId: string;
     parentCallId?: string;
     output: import('./contracts.js').ExecOutputSnapshot;

package/dist/tools/runtime.js

@@ -50,7 +50,8 @@ export async function executeCapturedTool(kind, call, context) {
         mode: context.mode,
         signal: context.signal,
         waitInterrupt: context.waitInterrupt,
-        ...((name === 'exec' || name === 'exec_wait') && callId !== undefined
+        ...((name === 'exec' || name === 'exec_wait' || name === 'code_exec_wait') &&
+            callId !== undefined
             ? {
                 onOutput: (output) => context.emit({
                     type: 'tool.output',

package/package.json

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