@myagentroam/agent 0.10.52 → 0.10.53

package/dist/agent-core/extensions/agents.js

@@ -51,17 +51,18 @@ function resolveAgentSpawn(input) {
     };
 }
 export function bindAgentController(controller, action) {
-    const wait = (input) => action('agent.wait', input, (target, call) => {
+    const wait = (input, waitInterrupt) => action('agent.wait', input, (target, call) => {
         const selection = parseAgentWaitTargets(target);
         return selection.agentIds !== undefined
             ? controller.outputMany(selection.agentIds, {
                 ...target,
+                waitInterrupt,
                 mode: selection.mode ?? 'any',
                 signal: call.signal
             })
             : target.agentId === undefined
-                ? controller.outputAny({ ...target, signal: call.signal })
-                : controller.output(target.agentId, { ...target, signal: call.signal });
+                ? controller.outputAny({ ...target, waitInterrupt, signal: call.signal })
+                : controller.output(target.agentId, { ...target, waitInterrupt, signal: call.signal });
     });
     return {
         run: (input, options) => {
@@ -95,9 +96,18 @@ export function bindAgentController(controller, action) {
                 });
             });
         },
-        output: (id, options) => wait({ ...options, agentId: id }),
-        outputAny: (options) => wait({ ...options }),
-        outputMany: (ids, options) => wait({ ...options, agentIds: ids }),
+        output: (id, options) => {
+            const { waitInterrupt, ...input } = options ?? {};
+            return wait({ ...input, agentId: id }, waitInterrupt);
+        },
+        outputAny: (options) => {
+            const { waitInterrupt, ...input } = options ?? {};
+            return wait(input, waitInterrupt);
+        },
+        outputMany: (ids, options) => {
+            const { waitInterrupt, ...input } = options ?? {};
+            return wait({ ...input, agentIds: ids }, waitInterrupt);
+        },
         message: (id, message, options) => action('agent.message', { ...options, agentId: id, message }, (target, call) => controller.message(target.agentId, target.message, {
             ...(target.delivery === undefined ? {} : { delivery: target.delivery }),
             signal: call.signal

package/dist/agent-core/sdk/native-steer.d.ts

@@ -16,4 +16,5 @@ export declare function createNativeSteer(input: {
         status: 'accepted';
     }>['entry']): Promise<unknown>;
     diagnose(): void;
+    wake(): void;
 }): (request: SteerInput) => Promise<SteerResult>;

package/dist/agent-core/sdk/native-steer.js

@@ -60,6 +60,7 @@ export function createNativeSteer(input) {
             void input.notify(historyEntry).catch(() => input.diagnose());
             ready.resolve();
             result.resolve({ status: 'accepted', entry: historyEntry });
+            input.wake();
             return {};
         })));
         void admission

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

@@ -10,6 +10,7 @@ import { ExecutionLoop } from '../runtime/execution.js';
 import { closeModelAdapters, createModelTurnSession } from './model-runtime.js';
 import { createSubagentBackend } from './subagent-backend.js';
 import { ExecutionToolPermissions, projectPermissionTool, resolvePermissionMode, withToolPermissions } from '../tools/permissions.js';
+import { createToolWaitInterrupt } from '../tools/wait.js';
 import { discoveredMcpToolNames, rebindMcpToolSearchOutputs } from '../tools/mcp/history.js';
 import { currentExecutionImages } from '../tools/output-projection.js';
 import { createHash, randomUUID } from 'node:crypto';
@@ -414,6 +415,7 @@ export function createSessionOpener(services) {
                     });
                     const messages = restored.messages;
                     const pendingInputs = restored.pendingInputs;
+                    const waitInterrupt = createToolWaitInterrupt(() => pendingInputs.size > 0);
                     liveModelMessages = messages;
                     const restoredRecordIds = new Set(contextRecords.map((record) => record.recordId));
                     for (const pending of pendingAppends)
@@ -1009,6 +1011,7 @@ export function createSessionOpener(services) {
                             executionId,
                             modelId: selectedModel.id,
                             signal: controller.signal,
+                            waitInterrupt,
                             emit,
                             skills: instructionContext?.skills ?? new Map(),
                             invokeTool: (call, context, caller) => {
@@ -1051,6 +1054,7 @@ export function createSessionOpener(services) {
                             recentImages,
                             captureCodeContext: () => ({
                                 ...toolContext,
+                                waitInterrupt: undefined,
                                 recentImages: recentImages()
                             }),
                             codeModeContext: async (call) => {
@@ -1223,6 +1227,7 @@ export function createSessionOpener(services) {
                                 return record;
                             }),
                             notify: (entry) => emit({ type: 'input.received', entry }),
+                            wake: () => waitInterrupt.notify(),
                             diagnose: () => coreExtensions.diagnose({ code: 'MAR_AGENT_STEER_POST_COMMIT_FAILED', sessionId })
                         });
                     }

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

@@ -62,9 +62,10 @@ export interface SubagentTaskSnapshot extends Record<string, unknown> {
     turnId?: string;
     deliveryStatus?: 'accepted' | 'applied' | 'cancelled' | 'failed';
     waitOutcome?: SubagentWaitOutcome;
+    reason?: 'steer';
 }
 export type SubagentWaitFor = 'completion' | 'message';
-export type SubagentWaitOutcome = 'snapshot' | 'message' | 'completion' | 'timeout';
+export type SubagentWaitOutcome = Exclude<import('../tools/wait.js').ToolWaitOutcome, 'yield'>;
 export interface SubagentMessageOptions {
     delivery?: 'append' | 'replace';
     signal?: AbortSignal;
@@ -76,6 +77,7 @@ export interface SubagentRunOptions {
     onCreated?: (task: SubagentTaskSnapshot) => Promise<void> | void;
 }
 export interface SubagentOutputOptions {
+    waitInterrupt?: import('../tools/wait.js').ToolWaitInterrupt | undefined;
     untilSettled?: true;
     waitMs?: number;
     waitFor?: SubagentWaitFor;
@@ -89,6 +91,7 @@ export interface SubagentManyOutput {
     mode: SubagentWaitMode;
     waitFor: SubagentWaitFor;
     waitOutcome: SubagentWaitOutcome;
+    reason?: 'steer';
     agents: SubagentTaskSnapshot[];
     pendingAgentIds: string[];
 }

package/dist/agent-core/subagent/scheduler.d.ts

@@ -39,6 +39,7 @@ export declare class SubagentScheduler implements SubagentController {
         messageId?: string;
         turnId?: string;
         deliveryStatus?: "accepted" | "applied" | "cancelled" | "failed";
+        reason?: "steer";
     } | {
         waitOutcome: "completion" | "timeout";
         permissionStop?: import("../tools/permissions.js").PermissionStop;
@@ -65,6 +66,7 @@ export declare class SubagentScheduler implements SubagentController {
         messageId?: string;
         turnId?: string;
         deliveryStatus?: "accepted" | "applied" | "cancelled" | "failed";
+        reason?: "steer";
     }>;
     outputAny(options?: SubagentOutputOptions): Promise<{
         waitOutcome: "snapshot";
@@ -92,6 +94,7 @@ export declare class SubagentScheduler implements SubagentController {
         messageId?: string;
         turnId?: string;
         deliveryStatus?: "accepted" | "applied" | "cancelled" | "failed";
+        reason?: "steer";
     } | {
         waitOutcome: "completion" | "timeout";
         permissionStop?: import("../tools/permissions.js").PermissionStop;
@@ -118,6 +121,7 @@ export declare class SubagentScheduler implements SubagentController {
         messageId?: string;
         turnId?: string;
         deliveryStatus?: "accepted" | "applied" | "cancelled" | "failed";
+        reason?: "steer";
     }>;
     outputMany(agentIds: readonly string[], options?: SubagentManyOutputOptions): Promise<SubagentManyOutput>;
     cancel(agentId: string): Promise<SubagentTaskSnapshot>;

package/dist/agent-core/subagent/session-controller.d.ts

@@ -123,7 +123,7 @@ export declare class SubagentSessionController implements SubagentController {
     cancel(agentId: string): Promise<SubagentTaskSnapshot>;
     listSessionResources(): {
         agentId: string;
-        status: "completed" | "failed" | "cancelled" | "running" | "interrupted" | "queued";
+        status: "completed" | "failed" | "cancelled" | "interrupted" | "running" | "queued";
         description: string;
     }[];
     dispose(): Promise<void>;

package/dist/agent-core/subagent/session-controller.js

@@ -1,8 +1,9 @@
+import { waitForToolCondition, waitMetadata } from '../tools/wait.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomUUID } from 'node:crypto';
 import { MarAgentError, describeMarAgentError } from '../error.js';
 import { TOOL_EXECUTION_LIMITS } from '../tools/execution-limits.js';
-import { parseAgentWaitTargets, waitForAgentCondition, waitDeadline } from './wait.js';
+import { parseAgentWaitTargets, waitForAgentCondition } from './wait.js';
 export class SubagentSessionController {
     parentSessionId;
     rootSessionId;
@@ -290,7 +291,7 @@ export class SubagentSessionController {
             ? options.waitMs
             : Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
         if (waitFor === 'completion') {
-            const completed = await this.#waitForCompletion(state, waitMs, options.signal);
+            const completed = await this.#waitForCompletion(state, waitMs, options.signal, options.waitInterrupt);
             options.signal?.throwIfAborted();
             const includeLatestMessage = this.#hasUnreadMessage(state);
             const includeTerminalDetails = completed ? this.#observeTerminal(state) : false;
@@ -298,10 +299,10 @@ export class SubagentSessionController {
                 this.#observeLatestMessage(state);
             return {
                 ...this.#snapshot(state, { includeLatestMessage, includeTerminalDetails }),
-                waitOutcome: completed ? 'completion' : 'timeout'
+                ...waitMetadata(completed ? 'completion' : options.waitInterrupt?.pending() ? 'interrupted' : 'timeout')
             };
         }
-        const activity = await this.#waitForMessageOrCompletion([state], waitMs, options.signal);
+        const activity = await this.#waitForMessageOrCompletion([state], waitMs, options.signal, options.waitInterrupt);
         options.signal?.throwIfAborted();
         const includeLatestMessage = activity?.kind === 'message' ||
             (activity?.kind === 'completion' && this.#hasUnreadMessage(activity.state));
@@ -313,11 +314,7 @@ export class SubagentSessionController {
                 includeLatestMessage,
                 includeTerminalDetails
             }),
-            waitOutcome: activity?.kind === 'message'
-                ? 'message'
-                : activity?.kind === 'completion'
-                    ? 'completion'
-                    : 'timeout'
+            ...waitMetadata(activity?.kind ?? (options.waitInterrupt?.pending() ? 'interrupted' : 'timeout'))
         };
     }
     async outputAny(options = {}) {
@@ -359,7 +356,7 @@ export class SubagentSessionController {
             ? options.waitMs
             : Math.max(options.waitMs, TOOL_EXECUTION_LIMITS.agentWaitWaitFloorMs);
         if (waitFor === 'message') {
-            const activity = await this.#waitForMessageOrCompletion(live, waitMs, options.signal);
+            const activity = await this.#waitForMessageOrCompletion(live, waitMs, options.signal, options.waitInterrupt);
             options.signal?.throwIfAborted();
             const includeLatestMessage = activity?.kind === 'message' ||
                 (activity?.kind === 'completion' && this.#hasUnreadMessage(activity.state));
@@ -371,14 +368,10 @@ export class SubagentSessionController {
                     includeLatestMessage,
                     includeTerminalDetails
                 }),
-                waitOutcome: activity?.kind === 'message'
-                    ? 'message'
-                    : activity?.kind === 'completion'
-                        ? 'completion'
-                        : 'timeout'
+                ...waitMetadata(activity?.kind ?? (options.waitInterrupt?.pending() ? 'interrupted' : 'timeout'))
             };
         }
-        const completed = await this.#waitForAnyCompletion(live, waitMs, options.signal);
+        const completed = await this.#waitForAnyCompletion(live, waitMs, options.signal, options.waitInterrupt);
         options.signal?.throwIfAborted();
         const state = completed ?? this.#oldestUnreadMessage(live) ?? live.at(-1);
         const includeLatestMessage = this.#hasUnreadMessage(state);
@@ -390,7 +383,7 @@ export class SubagentSessionController {
                 includeLatestMessage,
                 includeTerminalDetails
             }),
-            waitOutcome: completed ? 'completion' : 'timeout'
+            ...waitMetadata(completed ? 'completion' : options.waitInterrupt?.pending() ? 'interrupted' : 'timeout')
         };
     }
     async outputMany(agentIds, options = {}) {
@@ -430,6 +423,7 @@ export class SubagentSessionController {
             satisfied = await waitForAgentCondition({
                 waitMs,
                 signal: options.signal,
+                interrupt: options.waitInterrupt,
                 ready: () => {
                     refresh();
                     return mode === 'all' ? targets.every(ready) : targets.some(ready);
@@ -443,6 +437,8 @@ export class SubagentSessionController {
             options.signal?.throwIfAborted();
         }
         refresh();
+        if (!snapshot)
+            satisfied = mode === 'all' ? targets.every(ready) : targets.some(ready);
         const pendingAgentIds = targets
             .filter((target) => !ready(target))
             .map((target) => target.state.agentId);
@@ -457,7 +453,9 @@ export class SubagentSessionController {
                         ? 'message'
                         : satisfied
                             ? 'snapshot'
-                            : 'timeout';
+                            : options.waitInterrupt?.pending()
+                                ? 'interrupted'
+                                : 'timeout';
             const includeLatestMessage = outcome !== 'snapshot' && unread(target);
             const includeTerminalDetails = outcome === 'completion' &&
                 (observation
@@ -466,7 +464,7 @@ export class SubagentSessionController {
             const result = {
                 ...this.#snapshot(view, { includeLatestMessage, includeTerminalDetails }),
                 ...(target.turn === undefined ? {} : { turnId: target.turn.turnId }),
-                waitOutcome: outcome
+                ...waitMetadata(outcome)
             };
             if (includeLatestMessage) {
                 if (observation)
@@ -487,13 +485,15 @@ export class SubagentSessionController {
             waitFor,
             agents,
             pendingAgentIds,
-            waitOutcome: snapshot
+            ...waitMetadata(snapshot
                 ? 'snapshot'
                 : !satisfied
-                    ? 'timeout'
+                    ? options.waitInterrupt?.pending()
+                        ? 'interrupted'
+                        : 'timeout'
                     : agents.some((agent) => agent.waitOutcome === 'message')
                         ? 'message'
-                        : 'completion'
+                        : 'completion')
         };
     }
     async message(agentId, message, options = {}) {
@@ -809,25 +809,25 @@ export class SubagentSessionController {
         if (terminal)
             state.terminalRevision = state.resourceRevision;
     }
-    #waitForAnyCompletion(candidates, waitMs, signal) {
-        return waitForCompletionNotification(this.#completionWaiters, (state) => candidates.includes(state), waitMs, signal);
+    #waitForAnyCompletion(candidates, waitMs, signal, interrupt) {
+        return waitForNotification(this.#completionWaiters, (state) => candidates.includes(state), () => candidates.find(isTerminalState), waitMs, signal, interrupt);
     }
-    #waitForCompletion(state, waitMs, signal) {
-        return waitForCompletionNotification(this.#completionWaiters, (completed) => completed === state, waitMs, signal);
+    #waitForCompletion(state, waitMs, signal, interrupt) {
+        return waitForNotification(this.#completionWaiters, (completed) => completed === state, () => (isTerminalState(state) ? state : undefined), waitMs, signal, interrupt);
     }
     #notifyCompletion(state) {
         for (const waiter of this.#completionWaiters)
             waiter(state);
         this.#notifyActivity({ state, kind: 'completion' });
     }
-    #waitForMessageOrCompletion(candidates, waitMs, signal) {
+    #waitForMessageOrCompletion(candidates, waitMs, signal, interrupt) {
         return waitForNotification(this.#activityWaiters, (activity) => candidates.includes(activity.state), () => {
             const pending = this.#oldestUnreadMessage(candidates);
             if (pending)
                 return { state: pending, kind: 'message' };
             const terminal = candidates.find(isTerminalState);
             return terminal ? { state: terminal, kind: 'completion' } : undefined;
-        }, waitMs, signal);
+        }, waitMs, signal, interrupt);
     }
     #notifyActivity(activity) {
         for (const waiter of this.#activityWaiters)
@@ -1301,69 +1301,30 @@ function truncateCharacters(value, maximumCharacters) {
         ? value
         : characters.slice(0, maximumCharacters).join('');
 }
-function waitForCompletionNotification(waiters, accepts, waitMs, signal) {
-    return new Promise((resolve, reject) => {
-        let settled = false;
-        const finish = (error) => {
-            if (settled)
-                return;
-            settled = true;
-            cancelTimer();
-            signal?.removeEventListener('abort', abort);
-            waiters.delete(notify);
-            if (error === undefined)
-                resolve(undefined);
-            else
-                reject(error);
-        };
-        const notify = (value) => {
-            if (!accepts(value) || settled)
-                return;
-            settled = true;
-            cancelTimer();
-            signal?.removeEventListener('abort', abort);
-            waiters.delete(notify);
-            resolve(value);
-        };
-        const abort = () => finish(signal?.reason ?? new MarAgentError('MAR_AGENT_EXECUTION_CANCELLED', 'Execution cancelled.'));
-        const cancelTimer = waitDeadline(waitMs, () => finish());
-        waiters.add(notify);
-        signal?.addEventListener('abort', abort, { once: true });
-        if (signal?.aborted)
-            abort();
-    });
-}
-function waitForNotification(waiters, accepts, current, waitMs, signal) {
-    return new Promise((resolve, reject) => {
-        let settled = false;
-        const finish = (value, error) => {
-            if (settled)
-                return;
-            settled = true;
-            cancelTimer();
-            signal?.removeEventListener('abort', abort);
-            waiters.delete(notify);
-            if (error === undefined)
-                resolve(value);
-            else
-                reject(error);
-        };
-        const notify = (value) => {
-            if (accepts(value))
-                finish(value);
-        };
-        const abort = () => finish(undefined, signal?.reason ?? new MarAgentError('MAR_AGENT_EXECUTION_CANCELLED', 'Execution cancelled.'));
-        const cancelTimer = waitDeadline(waitMs, () => finish());
-        waiters.add(notify);
-        signal?.addEventListener('abort', abort, { once: true });
-        if (signal?.aborted)
-            abort();
-        else {
-            const pending = current();
-            if (pending !== undefined)
-                finish(pending);
-        }
+async function waitForNotification(waiters, accepts, current, waitMs, signal, interrupt) {
+    let value;
+    await waitForToolCondition({
+        ready: () => {
+            value ??= current();
+            return value !== undefined;
+        },
+        subscribe: (notify) => {
+            const listener = (next) => {
+                if (accepts(next)) {
+                    value = next;
+                    notify();
+                }
+            };
+            waiters.add(listener);
+            return () => {
+                waiters.delete(listener);
+            };
+        },
+        waitMs,
+        signal,
+        interrupt
     });
+    return value;
 }
 function validateOutputOptions(options, native = false) {
     if ((options.untilSettled !== undefined && options.untilSettled !== true) ||

package/dist/agent-core/subagent/wait.d.ts

@@ -1,3 +1,4 @@
+import { waitForToolCondition } from '../tools/wait.js';
 import type { SubagentWaitMode } from './contracts.js';
 /** Validate the entire target set before any observation can be consumed. */
 export declare function parseAgentWaitTargets(input: {
@@ -8,12 +9,6 @@ export declare function parseAgentWaitTargets(input: {
     agentIds?: string[];
     mode?: SubagentWaitMode;
 };
+export { waitDeadline } from '../tools/wait.js';
 /** A group owns one listener and one deadline; readiness never consumes observations. */
-export declare function waitForAgentCondition(input: {
-    ready(): boolean;
-    subscribe(notify: () => void): () => void;
-    waitMs: number;
-    signal?: AbortSignal | undefined;
-}): Promise<boolean>;
-/** Explicit waits retain their deadline without overflowing the platform timer. */
-export declare function waitDeadline(waitMs: number, finish: () => void): () => void;
+export declare function waitForAgentCondition(input: Parameters<typeof waitForToolCondition>[0]): Promise<boolean>;

package/dist/agent-core/subagent/wait.js

@@ -1,3 +1,4 @@
+import { waitForToolCondition } from '../tools/wait.js';
 import { MarAgentError } from '../error.js';
 /** Validate the entire target set before any observation can be consumed. */
 export function parseAgentWaitTargets(input, maxAgents = Infinity) {
@@ -24,54 +25,8 @@ export function parseAgentWaitTargets(input, maxAgents = Infinity) {
 function invalid() {
     throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Agent wait targets are invalid.');
 }
+export { waitDeadline } from '../tools/wait.js';
 /** A group owns one listener and one deadline; readiness never consumes observations. */
-export function waitForAgentCondition(input) {
-    input.signal?.throwIfAborted();
-    return new Promise((resolve, reject) => {
-        let settled = false;
-        let unsubscribe = () => { };
-        let cancelTimer = () => { };
-        const finish = (ready, error) => {
-            if (settled)
-                return;
-            settled = true;
-            unsubscribe();
-            cancelTimer();
-            input.signal?.removeEventListener('abort', abort);
-            if (error === undefined)
-                resolve(ready);
-            else
-                reject(error);
-        };
-        const notify = () => {
-            if (input.ready())
-                finish(true);
-        };
-        const abort = () => finish(false, input.signal?.reason ??
-            new MarAgentError('MAR_AGENT_EXECUTION_CANCELLED', 'Execution cancelled.'));
-        unsubscribe = input.subscribe(notify);
-        cancelTimer = waitDeadline(input.waitMs, () => finish(input.ready()));
-        input.signal?.addEventListener('abort', abort, { once: true });
-        if (input.signal?.aborted)
-            abort();
-        else
-            notify();
-    });
-}
-/** Explicit waits retain their deadline without overflowing the platform timer. */
-export function waitDeadline(waitMs, finish) {
-    const deadline = performance.now() + waitMs;
-    let timer;
-    const tick = () => {
-        const remaining = deadline - performance.now();
-        if (remaining <= 0)
-            finish();
-        else
-            arm(remaining);
-    };
-    const arm = (remaining) => {
-        timer = setTimeout(tick, Math.min(remaining, 2_147_483_647));
-    };
-    arm(waitMs);
-    return () => clearTimeout(timer);
+export async function waitForAgentCondition(input) {
+    return (await waitForToolCondition(input)) === 'ready';
 }

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

@@ -5,7 +5,7 @@ export const agentWaitToolDefinition = {
     name: 'agent_wait',
     allowedCallers: ['direct'],
     parallelSafety: 'serial',
-    description: 'Read or wait a bounded time for a child agent result. Unread child messages and terminal results are supplied automatically before the next model request. Wait only when the next local step depends on the child result; otherwise continue useful non-overlapping work. waitFor defaults to "completion"; use "message" only when a fresh public commentary/final message would change the next decision. Omit agentId to wait for whichever live child returns first, matching Codex-style untargeted waiting and avoiding UUID transcription; provide the exact agentId returned by agent_start only when observing a specific child. If no child is live, untargeted waiting reads the most recently created child. For an exec processId, use exec_wait instead (tools.exec_wait in Code Mode). Omitting waitMs waits up to 30 seconds by default; waitMs=0 returns the current snapshot immediately. Positive waits range up to 5 minutes, and positive values below 10 seconds are raised to 10 seconds. When blocked on a live child result, prefer one 300000 ms completion wait rather than repeated short waits. Use agentIds with mode any (default) or all to wait for an explicit non-empty set of up to 8 distinct child IDs; never combine agentId and agentIds or use mode without agentIds. mode and waitFor are independent. A group uses one deadline and returns mode, waitFor, waitOutcome, agents in input order, and pendingAgentIds. Failed, cancelled and interrupted turns also satisfy completion; terminal state satisfies message waits too. Group waitMs=0 returns only snapshots without consuming messages. Single-target and untargeted results include waitOutcome as snapshot, message, completion, or timeout plus the real agentId and description. A message, timeout with unread progress, or first terminal completion result includes the newly observed latest public commentary/final message; snapshots and repeated observations omit previously observed message text. latestActivity can still identify a public message or bounded tool started/completed/failed status. A queued or running result is not completion. A message wait consumes only the latest unread public message in the current Session runtime; tool activity does not wake it, and parent cancellation preserves unread progress for a later Execution. Do not use message waits as heartbeat checks or request progress merely to confirm that a child is still running. First terminal results include bounded summary, changedFiles, verification, and read evidence with path/line ranges; use that evidence to avoid repeating the full exploration, while independently checking consequential edits and claims.',
+    description: 'Read or wait a bounded time for a child agent result. Unread child messages and terminal results are supplied automatically before the next model request. Wait only when the next local step depends on the child result; otherwise continue useful non-overlapping work. waitFor defaults to "completion"; use "message" only when a fresh public commentary/final message would change the next decision. Omit agentId to wait for whichever live child returns first, matching Codex-style untargeted waiting and avoiding UUID transcription; provide the exact agentId returned by agent_start only when observing a specific child. If no child is live, untargeted waiting reads the most recently created child. For an exec processId, use exec_wait instead (tools.exec_wait in Code Mode). Omitting waitMs waits up to 30 seconds by default; waitMs=0 returns the current snapshot immediately. Positive waits range up to 5 minutes, and positive values below 10 seconds are raised to 10 seconds. When blocked on a live child result, prefer one 300000 ms completion wait rather than repeated short waits. Use agentIds with mode any (default) or all to wait for an explicit non-empty set of up to 8 distinct child IDs; never combine agentId and agentIds or use mode without agentIds. mode and waitFor are independent. A group uses one deadline and returns mode, waitFor, waitOutcome, agents in input order, and pendingAgentIds. Failed, cancelled and interrupted turns also satisfy completion; terminal state satisfies message waits too. Group waitMs=0 returns only snapshots without consuming messages. Single-target and untargeted results include waitOutcome as snapshot, message, completion, or timeout plus the real agentId and description. A message, timeout with unread progress, or first terminal completion result includes the newly observed latest public commentary/final message; snapshots and repeated observations omit previously observed message text. latestActivity can still identify a public message or bounded tool started/completed/failed status. A queued or running result is not completion. A message wait consumes only the latest unread public message in the current Session runtime; tool activity does not wake it, and parent cancellation preserves unread progress for a later Execution. waitOutcome distinguishes snapshot, message, completion, and timeout. A foreground steer may return interrupted with reason=steer without cancelling any child. Do not use message waits as heartbeat checks or request progress merely to confirm that a child is still running. First terminal results include bounded summary, changedFiles, verification, and read evidence with path/line ranges; use that evidence to avoid repeating the full exploration, while independently checking consequential edits and claims.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -49,7 +49,8 @@ export async function executeAgentWait(arguments_, context) {
     const options = {
         waitMs: value.waitMs ?? TOOL_EXECUTION_LIMITS.agentWaitDefaultWaitMs,
         waitFor: value.waitFor ?? 'completion',
-        signal: context.signal
+        signal: context.signal,
+        waitInterrupt: context.waitInterrupt
     };
     const task = value.agentIds !== undefined
         ? await subagents.outputMany(value.agentIds, { ...options, mode: value.mode ?? 'any' })

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

@@ -3,6 +3,7 @@ import { permissionStopFromError } from '../permissions.js';
 import { MarAgentError, describeMarAgentError } from '../../error.js';
 import { truncateModelText } from '../../runtime/token-budget.js';
 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, selectObservationImages, newObservationId, visibleObservation } from './observations.js';
 /** Keeps a failed tool call observable without discarding earlier explicit output. */
@@ -100,7 +101,7 @@ export class CodeCells {
         cell.done = Promise.resolve()
             .then(async () => {
             releaseSession = await context.codeMode?.retainSession?.();
-            return run(source, { ...context, signal: controller.signal }, {
+            return run(source, { ...context, signal: controller.signal, waitInterrupt: undefined }, {
                 call: (value) => cell.calls.set(value.callId, value),
                 observe: (value) => cell.observations.push(value),
                 text: (text, originalBytes) => cell.text.append(text, originalBytes),
@@ -155,7 +156,7 @@ export class CodeCells {
             }
             notify();
         });
-        return this.#wait(cell, settings, context.signal, true, context.codeMode?.supportsImages === true);
+        return this.#wait(cell, settings, context.signal, true, context.codeMode?.supportsImages === true, context.waitInterrupt);
     }
     async wait(value, context) {
         const input = options(value, true);
@@ -176,30 +177,32 @@ export class CodeCells {
                     abort();
             });
         }
-        return this.#wait(cell, input, context.signal, false, context.codeMode?.supportsImages === true);
+        return this.#wait(cell, input, context.signal, false, context.codeMode?.supportsImages === true, input.action === 'poll' ? context.waitInterrupt : undefined);
     }
-    async #wait(cell, input, signal, initial, supportsImages) {
-        if (cell.status === 'running' && !cell.yielded) {
-            await new Promise((resolve, reject) => {
-                const finish = () => {
-                    clearTimeout(timer);
-                    cell.listeners.delete(finish);
-                    signal.removeEventListener('abort', abort);
-                    resolve();
-                };
-                const abort = () => {
-                    clearTimeout(timer);
-                    cell.listeners.delete(finish);
-                    signal.removeEventListener('abort', abort);
-                    reject(signal.reason);
-                };
-                const timer = setTimeout(finish, input.yieldMs);
-                cell.listeners.add(finish);
-                signal.addEventListener('abort', abort, { once: true });
-                if (signal.aborted)
-                    abort();
+    async #wait(cell, input, signal, initial, supportsImages, interrupt) {
+        const outcome = input.yieldMs === 0
+            ? undefined
+            : await waitForToolCondition({
+                ready: () => cell.status !== 'running' || cell.yielded,
+                subscribe: (notify) => {
+                    cell.listeners.add(notify);
+                    return () => {
+                        cell.listeners.delete(notify);
+                    };
+                },
+                waitMs: input.yieldMs,
+                signal,
+                interrupt
             });
-        }
+        const wait = waitMetadata(input.yieldMs === 0
+            ? 'snapshot'
+            : cell.status !== 'running'
+                ? 'completion'
+                : cell.yielded
+                    ? 'yield'
+                    : outcome === 'interrupted'
+                        ? 'interrupted'
+                        : 'timeout');
         signal.throwIfAborted();
         if (!supportsImages && (cell.images.length || cell.terminal?.images?.length))
             throw new MarAgentError('MAR_AGENT_INPUT_CAPABILITY_UNSUPPORTED', 'The current model cannot receive this cell image output.');
@@ -213,6 +216,7 @@ export class CodeCells {
                     output: truncateModelText(original.output ?? '', limits.codeMaxOutputTokens).content,
                     observations: visible.observations,
                     cached: true,
+                    ...wait,
                     truncated: cell.terminal.truncated === true || bounded.truncated
                 };
                 return {
@@ -235,7 +239,8 @@ export class CodeCells {
                 ...snapshot,
                 output: bounded.content,
                 truncated: cell.terminal.truncated || bounded.truncated,
-                cached: true
+                cached: true,
+                ...wait
             };
             return {
                 ...cell.terminal,
@@ -270,6 +275,7 @@ export class CodeCells {
         const data = {
             cellId: cell.cellId,
             status: cell.status,
+            ...wait,
             ...(permissionStopFromError(cell.error)
                 ? { permissionStop: permissionStopFromError(cell.error) }
                 : {}),

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

@@ -45,6 +45,7 @@ Built-in namespaces:
 - 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.
+- 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.
 
@@ -78,7 +79,7 @@ observe.result(patched);
 };
 export const codeExecWaitToolDefinition = {
     name: 'code_exec_wait',
-    description: 'Wait for a retained Code Exec cell by cellId. It cannot start new work; use code_exec for that. A missing cellId does not mean code_exec is unavailable. Returns only new output, or a bounded terminal snapshot marked cached on repeat reads. yieldMs is a wait window, not a timeout. action defaults to poll (wait); action cancel stops the cell and waits for cleanup. Cancelling this wait does not cancel the cell. Cells belong to the current Session and cannot survive Host restart. Call directly, never inside code_exec.',
+    description: 'Wait for a retained Code Exec cell by cellId. It cannot start new work; use code_exec for that. A missing cellId does not mean code_exec is unavailable. Returns only new output, or a bounded terminal snapshot marked cached on repeat reads. yieldMs is a wait window, not a timeout. action defaults to poll (wait); action cancel stops the cell and waits for cleanup. Cancelling this wait does not cancel the cell. Cells belong to the current Session and cannot survive Host restart. Call directly, never inside code_exec. Poll results include waitOutcome; interrupted with reason=steer ends only the foreground wait and preserves the cell.',
     inputSchema: {
         type: 'object',
         properties: {

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

@@ -27,6 +27,7 @@ export interface ToolCall {
 export interface ToolExecutionContext {
     mode: ExecutionMode;
     signal: AbortSignal;
+    waitInterrupt?: import('./wait.js').ToolWaitInterrupt | undefined;
     sessionId: string;
     executionId: string;
     /** Current model identity for neutral Host-owned tool policies. */
@@ -108,11 +109,15 @@ export interface CodeCellEventData {
     calls?: readonly import('./code-mode/observations.js').CodeToolCallRecord[];
     cellId: string;
     status: 'running' | 'completed' | 'failed' | 'cancelled';
+    waitOutcome?: import('./wait.js').ToolWaitOutcome;
+    reason?: 'steer';
     cached?: boolean;
     observations?: readonly import('./code-mode/observations.js').CodeObservation[];
 }
 export interface ExecResult {
     status: 'running' | 'completed' | 'cancelled';
+    waitOutcome?: import('./wait.js').ToolWaitOutcome;
+    reason?: 'steer';
     processId?: string;
     stdout: string;
     stderr: string;

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

@@ -1,6 +1,7 @@
 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 ToolWaitInterrupt } from '../wait.js';
 import { WorkspacePathResolver } from '../shared/path-resolver.js';
 import { type CoreProcessInput, type CoreProcessHandle } from '../../extensions/processes.js';
 import type { CoreOperationContext } from '../../extensions/operation.js';
@@ -39,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']>): Promise<ExecResult>;
+    execute(arguments_: unknown, signal?: AbortSignal, owner?: NonNullable<import('../../host/local-process-executor.js').LocalProcessSpawnRequest['owner']>, waitInterrupt?: ToolWaitInterrupt): Promise<ExecResult>;
     spawn(input: CoreProcessInput, call: CoreOperationContext): Promise<CoreProcessHandle>;
     listSessionResources(sessionId: string): {
         processId: string;

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

@@ -3,6 +3,7 @@ import { StringDecoder } from 'node:string_decoder';
 import { MarAgentError } from '../../error.js';
 import { directLocalProcessExecutor, signalProcessTree } from '../../host/local-process-executor.js';
 import { TOOL_EXECUTION_LIMITS } from '../execution-limits.js';
+import { waitForToolCondition, waitMetadata } from '../wait.js';
 import { validateCoreProcessInput } from '../../extensions/processes.js';
 /** Share the model-facing body across direct calls and original Code Mode observations. */
 export function formatExecResult(result) {
@@ -29,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.',
+    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.',
     outputSchema: {
         type: 'object',
         required: ['content', 'data'],
@@ -49,6 +50,8 @@ export const execToolDefinition = {
                 ],
                 properties: {
                     status: { enum: ['running', 'completed', 'cancelled'] },
+                    waitOutcome: { enum: ['snapshot', 'completion', 'timeout', 'yield', 'interrupted'] },
+                    reason: { enum: ['steer'] },
                     processId: { type: 'string' },
                     stdout: { type: 'string' },
                     stderr: { type: 'string' },
@@ -101,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.',
+    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.',
     outputSchema: execToolDefinition.outputSchema,
     inputSchema: {
         type: 'object',
@@ -160,7 +163,7 @@ export class ExecTool {
         this.shell = shell;
         this.processExecutor = processExecutor;
     }
-    async execute(arguments_, signal, owner) {
+    async execute(arguments_, signal, owner, waitInterrupt) {
         if (signal?.aborted)
             throw executionAbortReason(signal);
         const input = parseExecInput(arguments_);
@@ -174,14 +177,21 @@ export class ExecTool {
                     throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Completed process cannot accept input.');
                 if (input.action === 'cancel')
                     this.#removeCompleted(input.processId);
-                return { ...completed.result, cached: true };
+                return {
+                    ...completed.result,
+                    cached: true,
+                    ...(input.action === 'poll'
+                        ? waitMetadata(input.yieldMs === 0 ? 'snapshot' : 'completion')
+                        : {})
+                };
             }
             if (!process ||
                 process.native ||
                 (owner !== undefined && process.ownerSessionId !== owner.sessionId))
                 throw new MarAgentError('MAR_AGENT_PROCESS_NOT_FOUND', 'Managed process was not found.');
+            let outcome;
             if (input.action === 'poll' && input.yieldMs)
-                await waitForProcessChange(process, Math.min(Math.max(input.yieldMs, 0), TOOL_EXECUTION_LIMITS.execMaxPollYieldMs), signal);
+                outcome = await waitForProcessChange(process, Math.min(Math.max(input.yieldMs, 0), TOOL_EXECUTION_LIMITS.execMaxPollYieldMs), signal, waitInterrupt);
             if (input.action === 'write') {
                 if (process.status !== 'running')
                     throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Completed process cannot accept input.');
@@ -195,7 +205,20 @@ export class ExecTool {
                 if (input.action === 'cancel')
                     this.#removeCompleted(input.processId);
             }
-            return result;
+            return {
+                ...result,
+                ...(input.action === 'poll'
+                    ? waitMetadata(input.yieldMs === 0
+                        ? 'snapshot'
+                        : result.status !== 'running'
+                            ? 'completion'
+                            : outcome === 'interrupted'
+                                ? 'interrupted'
+                                : outcome === 'ready'
+                                    ? 'yield'
+                                    : 'timeout')
+                    : {})
+            };
         }
         const { id, managed } = await this.#startManaged(async () => {
             const cwd = await this.paths.resolveWithDisplay(input.cwd ?? '.');
@@ -217,11 +240,34 @@ export class ExecTool {
             }, Math.min(input.timeoutMs, TOOL_EXECUTION_LIMITS.execMaxTimeoutMs));
             managed.timer.unref();
         }
-        await waitForExitOrDelay(managed.settled, Math.min(input.yieldMs ?? TOOL_EXECUTION_LIMITS.execDefaultYieldMs, TOOL_EXECUTION_LIMITS.execMaxYieldMs), signal);
+        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
+            });
         const result = this.#result(id, managed);
         if (managed.status !== 'running')
             this.#retainCompleted(id, managed);
-        return result;
+        return {
+            ...result,
+            ...waitMetadata(yieldMs === 0
+                ? 'snapshot'
+                : result.status !== 'running'
+                    ? 'completion'
+                    : outcome === 'interrupted'
+                        ? 'interrupted'
+                        : 'timeout')
+        };
     }
     async #startManaged(request, ownerSessionId, native) {
         if (this.#processes.size + this.#startingProcesses.size >= this.maxProcesses)
@@ -734,30 +780,6 @@ function optionalBoundedInteger(value, minimum, maximum) {
 function invalidExecInput() {
     throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Exec input is invalid.');
 }
-async function waitForExitOrDelay(exited, delayMs, signal) {
-    if (signal?.aborted)
-        throw executionAbortReason(signal);
-    let timer;
-    let rejectAbort;
-    const aborted = new Promise((_resolve, reject) => (rejectAbort = reject));
-    const abort = () => rejectAbort(executionAbortReason(signal));
-    signal?.addEventListener('abort', abort, { once: true });
-    try {
-        await Promise.race([
-            exited,
-            aborted,
-            new Promise((resolve) => {
-                timer = setTimeout(resolve, delayMs);
-                timer.unref();
-            })
-        ]);
-    }
-    finally {
-        signal?.removeEventListener('abort', abort);
-        if (timer)
-            clearTimeout(timer);
-    }
-}
 async function waitForExit(exited, delayMs) {
     let timer;
     try {
@@ -777,37 +799,28 @@ async function waitForExit(exited, delayMs) {
 function notifyProcessChange(managed) {
     for (const resolve of managed.waiters)
         resolve();
-    managed.waiters.clear();
 }
-async function waitForProcessChange(managed, waitMs, signal) {
-    if (managed.status !== 'running' || waitMs === 0)
-        return;
-    if (signal?.aborted)
-        throw executionAbortReason(signal);
-    let timer;
-    let resolveChange;
-    const changed = new Promise((resolve) => (resolveChange = resolve));
-    let rejectAbort;
-    const aborted = new Promise((_resolve, reject) => (rejectAbort = reject));
-    const abort = () => rejectAbort(executionAbortReason(signal));
-    managed.waiters.add(resolveChange);
-    signal?.addEventListener('abort', abort, { once: true });
-    try {
-        await Promise.race([
+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,
-            aborted,
-            new Promise((resolve) => {
-                timer = setTimeout(resolve, waitMs);
-                timer.unref();
-            })
-        ]);
-    }
-    finally {
-        managed.waiters.delete(resolveChange);
-        signal?.removeEventListener('abort', abort);
-        if (timer)
-            clearTimeout(timer);
-    }
+        subscribe: (notify) => {
+            const listener = () => {
+                changed = true;
+                notify();
+            };
+            managed.waiters.add(listener);
+            return () => {
+                managed.waiters.delete(listener);
+            };
+        },
+        waitMs,
+        signal,
+        interrupt
+    });
 }
 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);
                     return formatExecResult(result);
                 }
             ])

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

@@ -38,7 +38,7 @@ export function structuredToolEventData(toolName, value) {
     if (toolName === 'agent_wait' &&
         (value.mode === 'any' || value.mode === 'all') &&
         (value.waitFor === 'completion' || value.waitFor === 'message') &&
-        ['snapshot', 'message', 'completion', 'timeout'].includes(String(value.waitOutcome)) &&
+        ['snapshot', 'message', 'completion', 'timeout', 'interrupted'].includes(String(value.waitOutcome)) &&
         Array.isArray(value.agents) &&
         value.agents.length > 0 &&
         value.agents.length <= TOOL_EXECUTION_LIMITS.agentWaitMaxAgents &&
@@ -54,6 +54,12 @@ export function structuredToolEventData(toolName, value) {
             cellId: value.cellId,
             status: value.status,
             cached: value.cached === true,
+            ...(['snapshot', 'completion', 'timeout', 'yield', 'interrupted'].includes(String(value.waitOutcome))
+                ? { waitOutcome: value.waitOutcome }
+                : {}),
+            ...(value.waitOutcome === 'interrupted' && value.reason === 'steer'
+                ? { reason: 'steer' }
+                : {}),
             ...(isRecord(value.permissionStop)
                 ? {
                     permissionStop: value.permissionStop
@@ -207,7 +213,8 @@ function isSubagentTaskSnapshot(value) {
             value.waitOutcome === 'snapshot' ||
             value.waitOutcome === 'message' ||
             value.waitOutcome === 'completion' ||
-            value.waitOutcome === 'timeout') &&
+            value.waitOutcome === 'timeout' ||
+            value.waitOutcome === 'interrupted') &&
         (value.latestMessage === undefined ||
             (isRecord(value.latestMessage) &&
                 typeof value.latestMessage.itemId === 'string' &&

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

@@ -47,6 +47,7 @@ export interface ToolRuntimeContext {
     executionId: string;
     modelId?: string;
     signal: AbortSignal;
+    waitInterrupt?: import('./wait.js').ToolWaitInterrupt | undefined;
     permissionPolicy?: import('./permissions.js').ExecutionToolPermissions;
     parentCallId?: string;
     writeToolResultResource?: import('./result-extensions.js').ToolResultResourceWriter;

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

@@ -36,6 +36,7 @@ export async function executeCapturedTool(kind, call, context) {
     return context.host.executeTool(call, {
         mode: context.mode,
         signal: context.signal,
+        waitInterrupt: context.waitInterrupt,
         sessionId: context.sessionId,
         executionId: context.executionId,
         ...(context.modelId === undefined ? {} : { modelId: context.modelId }),

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

@@ -0,0 +1,25 @@
+export type ToolWaitOutcome = 'snapshot' | 'message' | 'completion' | 'timeout' | 'yield' | 'interrupted';
+/** A wake-up source, deliberately independent of resource cancellation. */
+export interface ToolWaitInterrupt {
+    pending(): boolean;
+    subscribe(listener: () => void): () => void;
+}
+export declare function createToolWaitInterrupt(pending: () => boolean): {
+    pending: () => boolean;
+    subscribe(listener: () => void): () => void;
+    notify(): void;
+};
+export declare function waitMetadata<T extends ToolWaitOutcome>(waitOutcome: T): {
+    waitOutcome: T;
+    reason?: 'steer';
+};
+/** All exits release listeners; a ready result wins over steer and the deadline. */
+export declare function waitForToolCondition(input: {
+    ready(): boolean;
+    subscribe(listener: () => void): () => void;
+    waitMs: number;
+    signal?: AbortSignal | undefined;
+    interrupt?: ToolWaitInterrupt | undefined;
+}): Promise<'ready' | 'timeout' | 'interrupted'>;
+/** Explicit waits retain their deadline without overflowing the platform timer. */
+export declare function waitDeadline(waitMs: number, finish: () => void): () => void;

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

@@ -0,0 +1,82 @@
+import { MarAgentError } from '../error.js';
+export function createToolWaitInterrupt(pending) {
+    const listeners = new Set();
+    return {
+        pending,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        notify() {
+            for (const listener of listeners)
+                listener();
+        }
+    };
+}
+export function waitMetadata(waitOutcome) {
+    return { waitOutcome, ...(waitOutcome === 'interrupted' ? { reason: 'steer' } : {}) };
+}
+/** All exits release listeners; a ready result wins over steer and the deadline. */
+export function waitForToolCondition(input) {
+    input.signal?.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let unsubscribe = () => { };
+        let unsubscribeInterrupt = () => { };
+        let cancelTimer = () => { };
+        const finish = (outcome, error) => {
+            if (settled)
+                return;
+            settled = true;
+            unsubscribe();
+            unsubscribeInterrupt();
+            cancelTimer();
+            input.signal?.removeEventListener('abort', abort);
+            if (error === undefined)
+                resolve(outcome);
+            else
+                reject(error);
+        };
+        const check = () => {
+            if (input.signal?.aborted)
+                abort();
+            else if (input.ready())
+                finish('ready');
+            else if (input.interrupt?.pending())
+                finish('interrupted');
+        };
+        const abort = () => finish('interrupted', input.signal?.reason ??
+            new MarAgentError('MAR_AGENT_EXECUTION_CANCELLED', 'Execution cancelled.'));
+        unsubscribe = input.subscribe(check);
+        unsubscribeInterrupt = input.interrupt?.subscribe(check) ?? (() => { });
+        cancelTimer = waitDeadline(input.waitMs, () => {
+            check();
+            finish('timeout');
+        });
+        input.signal?.addEventListener('abort', abort, { once: true });
+        check();
+    });
+}
+/** Explicit waits retain their deadline without overflowing the platform timer. */
+export function waitDeadline(waitMs, finish) {
+    if (waitMs <= 2_147_483_647) {
+        const timer = setTimeout(finish, waitMs);
+        return () => clearTimeout(timer);
+    }
+    const deadline = performance.now() + waitMs;
+    let timer;
+    const tick = () => {
+        const remaining = deadline - performance.now();
+        if (remaining <= 0)
+            finish();
+        else
+            arm(remaining);
+    };
+    const arm = (remaining) => {
+        timer = setTimeout(tick, Math.min(remaining, 2_147_483_647));
+    };
+    arm(waitMs);
+    return () => clearTimeout(timer);
+}

package/package.json

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