@myagentroam/agent 0.11.28 → 0.11.30

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

@@ -1,5 +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;
     push(value: T): void;
     close(): void;
     discardIfUnobserved(): boolean;

package/dist/agent-core/runtime/async-queue.js

@@ -6,6 +6,11 @@ export class AsyncQueue {
     #closed = false;
     #observed = false;
     #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);
+    }
     push(value) {
         if (this.#closed || this.#discarded)
             return;

package/dist/agent-core/runtime/event-projection.js

@@ -12,6 +12,7 @@ export function toolEventSummary(text) {
 /** Keep streaming deltas live-only; exec output has one durable copy in model context records. */
 export function eventForPersistence(event) {
     if (event.type === 'message.delta' ||
+        event.type === 'tool.output' ||
         event.type === 'input.received' ||
         (event.type === 'context.compacting' && event.async !== true && event.stage === undefined) ||
         event.type === 'model.performance' ||

package/dist/agent-core/runtime/events.d.ts

@@ -91,6 +91,12 @@ export type MarAgentEvent = MarAgentEventBase & ({
     input?: unknown;
     data?: import('../tools/public-metadata.js').PublicToolMetadata;
     truncated?: boolean;
+} | {
+    type: 'tool.output';
+    toolName: 'exec' | 'exec_wait';
+    callId: string;
+    parentCallId?: string;
+    output: import('../tools/contracts.js').ExecOutputSnapshot;
 } | {
     type: 'tool.completed';
     resultExtensions?: readonly import('../tools/result-extensions.js').ToolResultExtension[];

package/dist/agent-core/sdk/session.js

@@ -319,7 +319,10 @@ export function createSessionOpener(services) {
                                 messageSources.set(message, stored);
                         }
                     }
-                    queue.push(full);
+                    if (full.type === 'tool.output')
+                        queue.pushIfWaiting(full);
+                    else
+                        queue.push(full);
                     compactRequests.publish(full);
                     if (internal.publishHostEvents !== false) {
                         try {
@@ -346,7 +349,9 @@ export function createSessionOpener(services) {
                         }
                     }
                 });
-                emitTail = operation.catch(() => undefined);
+                // Best-effort previews follow prior durable events without delaying later results.
+                if (full.type !== 'tool.output')
+                    emitTail = operation.catch(() => undefined);
                 return operation;
             };
             const recordModelAttempt = (purpose) => (diagnostic) => {
@@ -2006,6 +2011,7 @@ export function createSessionOpener(services) {
                     }
                     catch (error) {
                         // Preserve the first failure/cancellation; successful executions still report release errors.
+                        // eslint-disable-next-line no-unsafe-finally -- Successful results must not hide writer lease release failures.
                         if (!failedExecution)
                             throw error;
                     }

package/dist/agent-core/sdk/types.d.ts

@@ -14,7 +14,7 @@ export type { HostExecutionExtensions, HostSessionResourceSnapshot, HostSkill, M
 export type { AccessMode, ExecutionMode, ExecutionResult, MarAgentImageMetadata, RolloutBudgetOptions, RunInput, RunInputImage } from '../runtime/contracts.js';
 export type { MarAgentEvent, MarAgentEventBase } from '../runtime/events.js';
 export type { CompactInput, ExecutionHandle } from '../runtime/execution-handle.js';
-export type { CodeCellEventData, MarAgentToolArtifact, MarAgentToolImageArtifact, McpCatalogTool, McpToolCallContext, McpToolCatalog, McpToolCatalogContext, ToolCall, ToolExecutionContext, ToolExecutionResult } from '../tools/contracts.js';
+export type { CodeCellEventData, ExecOutputSnapshot, MarAgentToolArtifact, MarAgentToolImageArtifact, McpCatalogTool, McpToolCallContext, McpToolCatalog, McpToolCatalogContext, ToolCall, ToolExecutionContext, ToolExecutionResult } from '../tools/contracts.js';
 export interface SteerInput {
     readonly expectedExecutionId: string;
     readonly prompt: string;

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

@@ -1,5 +1,5 @@
-import { randomUUID } from 'node:crypto';
 import { permissionStopFromError } from '../permissions.js';
+import { RuntimeResourceHandles } from '../runtime-resource-handles.js';
 import { MarAgentError, describeMarAgentError } from '../../error.js';
 import { truncateModelText } from '../../runtime/token-budget.js';
 import { TOOL_EXECUTION_LIMITS as limits } from '../execution-limits.js';
@@ -39,6 +39,7 @@ function options(value, wait) {
 /** Session-owned execution, separate from the cancellable model-tool wait. */
 export class CodeCells {
     #cells = new Map();
+    #handles = new RuntimeResourceHandles('cell', (id) => this.#cells.has(id));
     #closed = false;
     #disposing = new Set();
     async start(value, context, run) {
@@ -75,7 +76,7 @@ export class CodeCells {
             throw new MarAgentError('MAR_AGENT_PROCESS_LIMIT', `The Local Host shared running-cell limit (${limits.codeMaxConcurrentCells}) was reached.`);
         const controller = new AbortController();
         const cell = {
-            cellId: randomUUID(),
+            cellId: this.#handles.create(),
             sessionId: context.sessionId,
             executionId: context.executionId,
             controller,
@@ -160,6 +161,7 @@ export class CodeCells {
     async wait(value, context) {
         const input = options(value, true);
         context.signal.throwIfAborted();
+        this.#handles.assertType(input.cellId);
         const cell = this.#cells.get(input.cellId);
         if (!cell || cell.sessionId !== context.sessionId)
             throw new MarAgentError('MAR_AGENT_CODE_CELL_NOT_FOUND', 'Code Exec cell is unavailable in this Session.');

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

@@ -4,7 +4,7 @@ import type { McpToolCallContext, ToolCall, ToolExecutionResult } from '../contr
 import type { ToolRuntimeContext } from '../runtime-context.js';
 import type { createSessionToolScheduler } from '../scheduler.js';
 type ToolEvent = Extract<MarAgentEvent, {
-    type: 'tool.started' | 'tool.completed' | 'tool.failed';
+    type: 'tool.started' | 'tool.output' | 'tool.completed' | 'tool.failed';
 }>;
 type Payload<T = ToolEvent> = T extends ToolEvent ? Omit<T, 'eventId' | 'sequence' | 'timestamp' | 'sessionId' | 'executionId' | 'turnId'> : never;
 /** Capture only the cell's immutable dispatch identity, never the model loop or its AbortSignal. */

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

@@ -26,6 +26,7 @@ export function createCodeToolDispatch(input) {
                 const expected = input.expectations.get(call.name);
                 const result = await executeRegisteredTool(call.name, call.arguments, callId, {
                     ...input.context,
+                    emit: (event) => event.type === 'tool.output' ? input.emit(event) : input.context.emit(event),
                     parentCallId: input.parentCallId,
                     signal,
                     ...(expected ? { expectedMcpTool: expected } : {})

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

@@ -45,7 +45,7 @@ Built-in namespaces:
 - catalog.tools() returns a read-only array of the tools callable in this cell, including name, description and inputSchema. It does not discover or authorize additional tools.
 - await cell.sleep(ms) performs a cancellable delay up to ${limits.codeSleepMaxMs} ms.
 - await cell.yield_control() returns accumulated output to the model immediately while this cell continues running.
-- Optionally start source with // @options: {"yieldMs": ${limits.codeDefaultYieldMs}}. yieldMs defaults to ${limits.codeDefaultYieldMs} ms and controls this call's wait window (0..${limits.codeMaxYieldMs}), not nested tool timeouts or wait windows. A running result includes cellId; use direct code_exec_wait for new output, completion or termination.
+- Optionally start source with // @options: {"yieldMs": ${limits.codeDefaultYieldMs}}. yieldMs defaults to ${limits.codeDefaultYieldMs} ms and controls this call's wait window (0..${limits.codeMaxYieldMs}), not nested tool timeouts or wait windows. A running result includes cellId (c_ plus 12 lowercase hex characters); use direct code_exec_wait for new output, completion or termination.
 - waitOutcome separates snapshot, completion, timeout, and yield from the cell status. A foreground steer returns interrupted with reason=steer without stopping the cell or its internal tool waits.
 - 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, observe, state, catalog and cell are frozen bindings. Do not shadow their names.
@@ -84,7 +84,10 @@ export const codeExecWaitToolDefinition = {
     inputSchema: {
         type: 'object',
         properties: {
-            cellId: { type: 'string' },
+            cellId: {
+                type: 'string',
+                description: 'Copy the complete cellId returned by code_exec (c_ followed by 12 lowercase hex characters). Never use a processId (p_); use exec_wait for processes.'
+            },
             yieldMs: {
                 type: 'integer',
                 minimum: 0,

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

@@ -30,6 +30,8 @@ export interface ToolExecutionContext {
     mode: ExecutionMode;
     signal: AbortSignal;
     waitInterrupt?: import('./wait.js').ToolWaitInterrupt | undefined;
+    /** Live-only process output; does not consume the eventual tool result. */
+    onOutput?: (output: ExecOutputSnapshot) => Promise<void>;
     sessionId: string;
     executionId: string;
     /** Current model identity for neutral Host-owned tool policies. */
@@ -90,6 +92,12 @@ export interface MarAgentToolImageArtifact {
     fileName: string;
 }
 export type MarAgentToolArtifact = MarAgentToolImageArtifact;
+export interface ExecOutputSnapshot {
+    processId: string;
+    stdout: string;
+    stderr: string;
+    truncated: boolean;
+}
 export interface ToolExecutionResult {
     calls?: readonly import('./code-mode/observations.js').CodeToolCallRecord[];
     content: string;

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

@@ -14,6 +14,8 @@ export declare const TOOL_EXECUTION_LIMITS: Readonly<{
     execMaxPollYieldMs: 300000;
     execTerminationGraceMs: 1000;
     execDefaultMaxOutputBytes: 1000000;
+    execProgressMaxOutputBytes: 8192;
+    execProgressIntervalMs: 100;
     maxProcesses: 64;
     execMaxCompletedResults: 16;
     execCompletedRetentionMs: 300000;

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

@@ -14,6 +14,8 @@ export const TOOL_EXECUTION_LIMITS = Object.freeze({
     execMaxPollYieldMs: 300_000,
     execTerminationGraceMs: 1_000,
     execDefaultMaxOutputBytes: 1_000_000,
+    execProgressMaxOutputBytes: 8_192,
+    execProgressIntervalMs: 100,
     maxProcesses: 64,
     execMaxCompletedResults: 16,
     execCompletedRetentionMs: 300_000,

package/dist/agent-core/tools/local/exec.d.ts

@@ -1,6 +1,6 @@
 import { type LocalProcessExecutor } from '../../host/local-process-executor.js';
 import type { ClientToolDefinition } from '../../model/contracts.js';
-import type { ExecResult, ToolExecutionResult } from '../contracts.js';
+import type { ExecOutputSnapshot, ExecResult, ToolExecutionResult } from '../contracts.js';
 import { type ToolWaitInterrupt } from '../wait.js';
 import { WorkspacePathResolver } from '../shared/path-resolver.js';
 import { type CoreProcessInput, type CoreProcessHandle } from '../../extensions/processes.js';
@@ -40,7 +40,7 @@ export declare class ExecTool {
     private readonly shell?;
     private readonly processExecutor;
     constructor(paths: WorkspacePathResolver, maxOutputBytes?: number, maxProcesses?: number, environment?: NodeJS.ProcessEnv, shell?: string | undefined, processExecutor?: LocalProcessExecutor);
-    execute(arguments_: unknown, signal?: AbortSignal, owner?: NonNullable<import('../../host/local-process-executor.js').LocalProcessSpawnRequest['owner']>, waitInterrupt?: ToolWaitInterrupt): Promise<ExecResult>;
+    execute(arguments_: unknown, signal?: AbortSignal, owner?: NonNullable<import('../../host/local-process-executor.js').LocalProcessSpawnRequest['owner']>, waitInterrupt?: ToolWaitInterrupt, onOutput?: (output: ExecOutputSnapshot) => Promise<void>): Promise<ExecResult>;
     spawn(input: CoreProcessInput, call: CoreOperationContext): Promise<CoreProcessHandle>;
     listSessionResources(sessionId: string): {
         processId: string;

package/dist/agent-core/tools/local/exec.js

@@ -1,4 +1,4 @@
-import { randomUUID } from 'node:crypto';
+import { RuntimeResourceHandles } from '../runtime-resource-handles.js';
 import { StringDecoder } from 'node:string_decoder';
 import { MarAgentError } from '../../error.js';
 import { directLocalProcessExecutor, signalProcessTree } from '../../host/local-process-executor.js';
@@ -30,7 +30,7 @@ export const execToolDefinition = {
     name: 'exec',
     allowedCallers: ['direct', 'programmatic'],
     parallelSafety: 'safe',
-    description: 'Start a platform-native command, script, or program in workspace/default cwd. Returns a stable processId, status, bounded stdout/stderr, cumulative byte counts, dropped-byte counts, exitCode and truncated. A completed status does not imply exitCode 0; inspect stderr/exitCode. For subsequent waiting, stdin writes or cancellation, call exec_wait directly with processId, not exec. Truncation does not stop the process. Cancelling the initial wait does not terminate the process. waitOutcome distinguishes snapshot, completion, timeout, and yield. A foreground wait may return interrupted with reason=steer; the process keeps running.',
+    description: 'Start a platform-native command, script, or program in workspace/default cwd. Returns a stable processId (p_ plus 12 lowercase hex characters), status, bounded stdout/stderr, cumulative byte counts, dropped-byte counts, exitCode and truncated. A completed status does not imply exitCode 0; inspect stderr/exitCode. For subsequent waiting, stdin writes or cancellation, call exec_wait directly with processId, not exec. Truncation does not stop the process. Cancelling the initial wait does not terminate the process. waitOutcome distinguishes snapshot, completion, and timeout. A foreground wait may return interrupted with reason=steer; the process keeps running.',
     outputSchema: {
         type: 'object',
         required: ['content', 'data'],
@@ -104,7 +104,7 @@ export const execWaitToolDefinition = {
     name: 'exec_wait',
     allowedCallers: ['direct', 'programmatic'],
     parallelSafety: 'safe',
-    description: 'Wait for or control a managed process by processId. action defaults to poll: wait for new output or termination and return incremental stdout/stderr. write sends data to stdin; cancel terminates the process or removes its cached result. Terminal polls return a bounded snapshot marked cached for up to five minutes. Cancelling a wait does not terminate the process. Uses the same Session-owned processes as exec; cannot start a process or extend its timeout. Inspect stderr/exitCode; completed does not imply success. Supports direct and programmatic calls; in Code Mode use tools.exec_wait. Poll results include waitOutcome; interrupted with reason=steer ends only a foreground wait, never the process.',
+    description: 'Wait for or control a managed process by processId. action defaults to poll: collect output until termination or the wait window ends, then return incremental stdout/stderr. New output does not end the wait. write sends data to stdin; cancel terminates the process or removes its cached result. Terminal polls return a bounded snapshot marked cached for up to five minutes. Cancelling a wait does not terminate the process. Uses the same Session-owned processes as exec; cannot start a process or extend its timeout. Inspect stderr/exitCode; completed does not imply success. Supports direct and programmatic calls; in Code Mode use tools.exec_wait. Poll results include waitOutcome; interrupted with reason=steer ends only a foreground wait, never the process.',
     outputSchema: execToolDefinition.outputSchema,
     inputSchema: {
         type: 'object',
@@ -112,7 +112,7 @@ export const execWaitToolDefinition = {
             processId: {
                 type: 'string',
                 minLength: 1,
-                description: 'Stable processId returned by exec.'
+                description: 'Copy the complete processId returned by exec (p_ followed by 12 lowercase hex characters). Never use a cellId (c_); use code_exec_wait for cells.'
             },
             action: { enum: ['poll', 'write', 'cancel'], default: 'poll' },
             yieldMs: {
@@ -154,6 +154,7 @@ export class ExecTool {
     processExecutor;
     #processes = new Map();
     #completed = new Map();
+    #handles = new RuntimeResourceHandles('process', (id) => this.#processes.has(id) || this.#completed.has(id));
     #startingProcesses = new Set();
     constructor(paths, maxOutputBytes = TOOL_EXECUTION_LIMITS.execDefaultMaxOutputBytes, maxProcesses = TOOL_EXECUTION_LIMITS.maxProcesses, environment = process.env, shell, processExecutor = directLocalProcessExecutor) {
         this.paths = paths;
@@ -163,11 +164,12 @@ export class ExecTool {
         this.shell = shell;
         this.processExecutor = processExecutor;
     }
-    async execute(arguments_, signal, owner, waitInterrupt) {
+    async execute(arguments_, signal, owner, waitInterrupt, onOutput) {
         if (signal?.aborted)
             throw executionAbortReason(signal);
         const input = parseExecInput(arguments_);
         if ('processId' in input) {
+            this.#handles.assertType(input.processId);
             const process = this.#processes.get(input.processId);
             const completed = this.#completed.get(input.processId);
             if (completed) {
@@ -191,7 +193,7 @@ export class ExecTool {
                 throw new MarAgentError('MAR_AGENT_PROCESS_NOT_FOUND', 'Managed process was not found.');
             let outcome;
             if (input.action === 'poll' && input.yieldMs)
-                outcome = await waitForProcessChange(process, Math.min(Math.max(input.yieldMs, 0), TOOL_EXECUTION_LIMITS.execMaxPollYieldMs), signal, waitInterrupt);
+                outcome = await waitForProcessCompletion(input.processId, process, Math.min(Math.max(input.yieldMs, 0), TOOL_EXECUTION_LIMITS.execMaxPollYieldMs), signal, waitInterrupt, onOutput);
             if (input.action === 'write') {
                 if (process.status !== 'running')
                     throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Completed process cannot accept input.');
@@ -214,9 +216,7 @@ export class ExecTool {
                             ? 'completion'
                             : outcome === 'interrupted'
                                 ? 'interrupted'
-                                : outcome === 'ready'
-                                    ? 'yield'
-                                    : 'timeout')
+                                : 'timeout')
                     : {})
             };
         }
@@ -243,18 +243,7 @@ export class ExecTool {
         const yieldMs = Math.min(input.yieldMs ?? TOOL_EXECUTION_LIMITS.execDefaultYieldMs, TOOL_EXECUTION_LIMITS.execMaxYieldMs);
         const outcome = yieldMs === 0
             ? undefined
-            : await waitForToolCondition({
-                ready: () => managed.finalized,
-                subscribe: (notify) => {
-                    managed.waiters.add(notify);
-                    return () => {
-                        managed.waiters.delete(notify);
-                    };
-                },
-                waitMs: yieldMs,
-                signal,
-                interrupt: waitInterrupt
-            });
+            : await waitForProcessCompletion(id, managed, yieldMs, signal, waitInterrupt, onOutput);
         const result = this.#result(id, managed);
         if (managed.status !== 'running')
             this.#retainCompleted(id, managed);
@@ -294,7 +283,7 @@ export class ExecTool {
                     details: { reasonCode: error?.code ?? 'UNKNOWN' }
                 });
             }
-            const id = randomUUID();
+            const id = this.#handles.create();
             let resolveExited;
             let resolveSettled;
             const managed = {
@@ -800,27 +789,88 @@ function notifyProcessChange(managed) {
     for (const resolve of managed.waiters)
         resolve();
 }
-async function waitForProcessChange(managed, waitMs, signal, interrupt) {
-    let changed = false;
-    return waitForToolCondition({
-        ready: () => managed.status !== 'running' ||
-            managed.stdout.bytes > 0 ||
-            managed.stderr.bytes > 0 ||
-            changed,
-        subscribe: (notify) => {
-            const listener = () => {
-                changed = true;
-                notify();
-            };
-            managed.waiters.add(listener);
-            return () => {
-                managed.waiters.delete(listener);
-            };
-        },
-        waitMs,
-        signal,
-        interrupt
-    });
+async function waitForProcessCompletion(processId, managed, waitMs, signal, interrupt, onOutput) {
+    const stopOutput = onOutput && watchProcessOutput(processId, managed, onOutput);
+    try {
+        return await waitForToolCondition({
+            ready: () => managed.finalized,
+            subscribe: (notify) => {
+                managed.waiters.add(notify);
+                return () => {
+                    managed.waiters.delete(notify);
+                };
+            },
+            waitMs,
+            signal,
+            interrupt
+        });
+    }
+    finally {
+        stopOutput?.();
+    }
+}
+/** Coalesce display snapshots without consuming output or queueing behind a slow observer. */
+function watchProcessOutput(processId, managed, onOutput) {
+    let stopped = false;
+    let dirty = false;
+    let timer;
+    let inFlight;
+    let failed = false;
+    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);
+        inFlight = Promise.resolve()
+            .then(() => {
+            if (stopped)
+                return;
+            return onOutput({
+                processId,
+                stdout: stdout.value,
+                stderr: stderr.value,
+                truncated: stdout.droppedBytes > 0 || stderr.droppedBytes > 0
+            });
+        })
+            .catch(() => {
+            // Display delivery must not change the process result or wait deadline.
+            failed = true;
+        })
+            .finally(() => {
+            inFlight = undefined;
+            if (dirty)
+                schedule();
+        });
+    };
+    const schedule = () => {
+        if (stopped || failed || timer || inFlight)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            publish();
+        }, TOOL_EXECUTION_LIMITS.execProgressIntervalMs);
+        timer.unref();
+    };
+    const changed = () => {
+        if (managed.stdout.bytes === 0 && managed.stderr.bytes === 0)
+            return;
+        dirty = true;
+        schedule();
+    };
+    managed.waiters.add(changed);
+    changed();
+    return () => {
+        stopped = true;
+        managed.waiters.delete(changed);
+        if (timer)
+            clearTimeout(timer);
+    };
 }
 function executionAbortReason(signal) {
     return (signal?.reason ?? new MarAgentError('MAR_AGENT_EXECUTION_CANCELLED', 'Execution cancelled.'));

package/dist/agent-core/tools/local/registry.js

@@ -90,7 +90,7 @@ export class LocalToolRegistry {
                                     ? {}
                                     : { ownerInstanceId: context.operation.ownerInstanceId })
                             })
-                    }, context.waitInterrupt);
+                    }, context.waitInterrupt, context.onOutput);
                     return formatExecResult(result);
                 }
             ])

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

@@ -4,6 +4,12 @@ import type { AgentSkill } from '../runtime/context/instructions.js';
 import type { SubagentController, SubagentLatestMessage } from '../subagent/scheduler.js';
 import type { TodoStore } from './agent/todo.js';
 export type ToolRuntimeEvent = {
+    type: 'tool.output';
+    toolName: 'exec' | 'exec_wait';
+    callId: string;
+    parentCallId?: string;
+    output: import('./contracts.js').ExecOutputSnapshot;
+} | {
     type: 'sleep.started';
     callId: string;
     durationMs: number;

package/dist/agent-core/tools/runtime-resource-handles.d.ts

@@ -0,0 +1,21 @@
+declare const types: {
+    readonly cell: {
+        readonly prefix: "c_";
+        readonly field: "cellId";
+        readonly tool: "code_exec_wait";
+    };
+    readonly process: {
+        readonly prefix: "p_";
+        readonly field: "processId";
+        readonly tool: "exec_wait";
+    };
+};
+/** Typed runtime handles; resource owners retain registration and lifecycle authority. */
+export declare class RuntimeResourceHandles {
+    private readonly kind;
+    private readonly isReserved;
+    constructor(kind: keyof typeof types, isReserved: (id: string) => boolean);
+    create(): string;
+    assertType(id: string): void;
+}
+export {};

package/dist/agent-core/tools/runtime-resource-handles.js

@@ -0,0 +1,28 @@
+import { randomBytes } from 'node:crypto';
+import { MarAgentError } from '../error.js';
+const types = {
+    cell: { prefix: 'c_', field: 'cellId', tool: 'code_exec_wait' },
+    process: { prefix: 'p_', field: 'processId', tool: 'exec_wait' }
+};
+/** Typed runtime handles; resource owners retain registration and lifecycle authority. */
+export class RuntimeResourceHandles {
+    kind;
+    isReserved;
+    constructor(kind, isReserved) {
+        this.kind = kind;
+        this.isReserved = isReserved;
+    }
+    create() {
+        let id;
+        do {
+            id = `${types[this.kind].prefix}${randomBytes(6).toString('hex')}`;
+        } while (this.isReserved(id));
+        return id;
+    }
+    assertType(id) {
+        const expected = types[this.kind];
+        const actual = Object.values(types).find((type) => id.startsWith(type.prefix));
+        if (actual && actual !== expected)
+            throw new MarAgentError('MAR_AGENT_RESOURCE_HANDLE_TYPE_MISMATCH', `Expected ${expected.field} (${expected.prefix}...). This looks like ${actual.field}; use ${actual.tool} for that resource.`, { details: { expected: expected.field, received: actual.field, tool: actual.tool } });
+    }
+}

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

@@ -45,10 +45,22 @@ export async function executeCapturedTool(kind, call, context) {
             ...(context.expectedMcpTool ? { expectedTool: context.expectedMcpTool } : {})
         });
     }
+    const { name, callId } = call;
     return context.host.executeTool(call, {
         mode: context.mode,
         signal: context.signal,
         waitInterrupt: context.waitInterrupt,
+        ...((name === 'exec' || name === 'exec_wait') && callId !== undefined
+            ? {
+                onOutput: (output) => context.emit({
+                    type: 'tool.output',
+                    toolName: name,
+                    callId,
+                    ...(context.parentCallId === undefined ? {} : { parentCallId: context.parentCallId }),
+                    output
+                })
+            }
+            : {}),
         sessionId: context.sessionId,
         executionId: context.executionId,
         ...(context.modelId === undefined ? {} : { modelId: context.modelId }),

package/dist/index.d.ts

@@ -44,7 +44,7 @@ export { openMarAgentSessionCatalog, type MarAgentContextUsage, type MarAgentHis
 export type { SessionListInput, SessionSource } from './agent-core/session/types.js';
 export type { SessionStore, SessionResource, SessionStoreMaintenance, SessionStoreSession, SessionRecordInput, SessionStoreCompactInput, SessionRecord, SessionExecutionState, CompactHistoryMessage, CompactUserInput, SessionInputImage, SessionInputImageMetadata, SessionInputImageData, RestoredSessionInputImage, CodeModeStateEntry, TodoSnapshot, TodoItem, CodeToolCallRecord, CodeObservation, ModelMessage, ModelUsage, ModelInputMetadata, ModelTextBlock, ModelContextualBlock, EnvironmentContextState, ContextGcCheckpointDraft, ContextGcBase, ContextGcPlatform, ContextGcEconomicsPolicy, ContextGcMetrics, ContextGcReplacement, ContextGcTarget, ContextGcReadItemReplacement, ContextGcWebToolName, ContextGcSubagentToolName, AvailableToolResultResource } from './agent-core/session/store/contracts.js';
 export type { OpenMarAgentSessionCatalogInput } from './agent-core/session/catalog.js';
-export type { ApplyPatchFileResult, ApplyPatchResult, ApplyPatchPartialResult, ClientToolDefinition, MarAgentToolArtifact, MarAgentToolImageArtifact, McpCatalogTool, McpToolCallContext, McpToolCatalog, McpToolCatalogContext, ToolCall, ToolCaller, ToolExecutionContext, ToolExecutionResult } from './agent-core/tools/contracts.js';
+export type { ApplyPatchFileResult, ApplyPatchResult, ApplyPatchPartialResult, ExecOutputSnapshot, ClientToolDefinition, MarAgentToolArtifact, MarAgentToolImageArtifact, McpCatalogTool, McpToolCallContext, McpToolCatalog, McpToolCatalogContext, ToolCall, ToolCaller, ToolExecutionContext, ToolExecutionResult } from './agent-core/tools/contracts.js';
 export { MCP_DEFINITION_LIMITS, assertMcpToolCatalog, assertMcpToolDefinition } from './agent-core/tools/mcp/catalog.js';
 export type { WorkspacePathMount } from './agent-core/tools/shared/path-resolver.js';
 export type { CodeModeEngine, CodeModeEngineFactory, CreateCodeModeEngine } from './agent-core/tools/code-mode/engine.js';

package/package.json

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