@kuralle-agents/core 0.13.0 → 0.15.0

package/dist/runtime/Runtime.js

@@ -34,6 +34,13 @@ import { TraceRecorder } from './TraceRecorder.js';
 import { MemoryTraceStore } from '../tracing/MemoryTraceStore.js';
 import { mutateSessionWithRetry } from '../session/utils.js';
 import { isTraceStore } from '../tracing/TraceStore.js';
+import { runHookSafely } from './runHookSafely.js';
+/**
+ * What the user is told when the run hands off to a human and the app has not configured an
+ * escalation handler to say something better. Silence is the wrong default: an escalation
+ * that emits no text is indistinguishable from the agent having crashed.
+ */
+export const HANDOFF_TO_HUMAN_MESSAGE = "I'm bringing a colleague into this — they'll pick it up from here.";
 export class Runtime {
     config;
     agentsById;
@@ -72,6 +79,7 @@ export class Runtime {
         const recorder = this.shouldTrace(sessionId, opts.input)
             ? new TraceRecorder({
                 sessionId,
+                agentId: opts.agentId ?? this.config.defaultAgentId,
                 input: opts.input,
                 onSpan: (span) => this.writeSpan(span),
             })
@@ -84,12 +92,19 @@ export class Runtime {
         }
         const execute = async () => {
             let runCtx;
+            // Whether the user has been told anything at all this turn. A terminal handoff with
+            // no escalation handler configured used to emit zero text — seven consecutive turns
+            // were observed producing empty output while silently firing transfer_to_agent, which
+            // is indistinguishable from an outage.
+            let sawUserText = false;
             const emit = (part) => {
+                if (part.type === 'text-delta' && part.payload.delta)
+                    sawUserText = true;
                 recorder?.record(part);
                 if (part.type === 'done')
                     this.flushTraceSinks();
                 bus.emit(part);
-                void this.hooks?.onStreamPart?.(runCtx, part);
+                void runHookSafely('onStreamPart', () => this.hooks?.onStreamPart?.(runCtx, part));
             };
             const opened = await openRun(this.agentsById, {
                 sessionId,
@@ -106,6 +121,7 @@ export class Runtime {
                 defaultAgentId: this.config.defaultAgentId,
                 sessionStore: this.sessionStore,
             });
+            recorder?.setInitiatingAgent(opened.agent.id);
             const policies = resolveAgentPolicies(opened.agent);
             const knowledgeProvider = this.config.knowledge
                 ? buildKnowledgeProvider(this.config.knowledge)
@@ -121,9 +137,16 @@ export class Runtime {
                 agentId: opened.agent.id,
                 onInterim: (message) => {
                     const id = crypto.randomUUID();
-                    emit({ type: 'text-start', id });
-                    emit({ type: 'text-delta', id, delta: message });
-                    emit({ type: 'text-end', id });
+                    emit({ channel: 'client', type: 'text-start', payload: { id } });
+                    emit({ channel: 'client', type: 'text-delta', payload: { id, delta: message } });
+                    emit({ channel: 'client', type: 'text-end', payload: { id } });
+                },
+                onChunk: (chunk, toolName, toolCallId) => {
+                    emit({
+                        channel: 'internal',
+                        type: 'tool-result',
+                        payload: { toolName, result: chunk, toolCallId, preliminary: true },
+                    });
                 },
             });
             const steps = await loadRecordedSteps(opened.runStore, opened.runState.runId);
@@ -170,9 +193,9 @@ export class Runtime {
             runCtx.skillPrompt = openingSurface.skillPrompt;
             runCtx.workingMemoryPrompt = appendGoalsPrompt(openingSurface.workingMemoryPrompt, opened.session.workingMemory);
             runCtx.workingMemoryTools = openingSurface.workingMemoryTools;
-            await this.hooks?.onStart?.(runCtx);
+            await runHookSafely('onStart', () => this.hooks?.onStart?.(runCtx));
             if (opts.wake) {
-                emit({ type: 'wake', reason: opts.wake.reason });
+                emit({ channel: 'internal', type: 'wake', payload: { reason: opts.wake.reason } });
             }
             const driver = opts.driver ?? new TextDriver();
             let activeAgent = opened.agent;
@@ -202,8 +225,38 @@ export class Runtime {
                     }
                     if (loopResult.kind === 'handoff') {
                         if (this.terminalHandoffTargets.has(loopResult.to)) {
-                            emit({ type: 'handoff', targetAgent: loopResult.to, reason: loopResult.reason });
+                            // This emit is load-bearing for TERMINAL targets specifically. A terminal
+                            // handoff breaks out of the loop here, before hostLoop's own emit and before
+                            // handoffHistory is appended — so this is the only handoff part a client ever
+                            // sees for an escalation. Removing it as "redundant" silently produced zero
+                            // handoff parts for every escalation; escalation.test.ts catches it.
+                            //
+                            // The self-edge seen live (handoff human->human, two spans on one turn) is a
+                            // real but SEPARATE defect on the non-terminal path — fix it there, not by
+                            // deleting this.
+                            emit({
+                                channel: 'internal',
+                                type: 'handoff',
+                                payload: { targetAgent: loopResult.to, reason: loopResult.reason },
+                            });
                             runCtx.runState.status = 'paused';
+                            // Never hand off in silence. dispatchEscalation returns immediately when no
+                            // escalation handler is configured, so without this the turn ends with no
+                            // assistant text at all and the user cannot tell an escalation from a crash.
+                            if (!sawUserText) {
+                                const handoffId = crypto.randomUUID();
+                                emit({ channel: 'client', type: 'text-start', payload: { id: handoffId } });
+                                emit({
+                                    channel: 'client',
+                                    type: 'text-delta',
+                                    payload: { id: handoffId, delta: HANDOFF_TO_HUMAN_MESSAGE },
+                                });
+                                emit({ channel: 'client', type: 'text-end', payload: { id: handoffId } });
+                                runCtx.runState.messages = [
+                                    ...runCtx.runState.messages,
+                                    { role: 'assistant', content: HANDOFF_TO_HUMAN_MESSAGE },
+                                ];
+                            }
                             await runCtx.runStore.putRunState(runCtx.runState);
                             await this.dispatchEscalation(runCtx, activeAgent, { reason: loopResult.reason ?? 'handoff_to_human', category: loopResult.category }, emit, { setLatch: false });
                             break;
@@ -285,9 +338,20 @@ export class Runtime {
                             agentId: target.id,
                             onInterim: (message) => {
                                 const id = crypto.randomUUID();
-                                emit({ type: 'text-start', id });
-                                emit({ type: 'text-delta', id, delta: message });
-                                emit({ type: 'text-end', id });
+                                emit({ channel: 'client', type: 'text-start', payload: { id } });
+                                emit({
+                                    channel: 'client',
+                                    type: 'text-delta',
+                                    payload: { id, delta: message },
+                                });
+                                emit({ channel: 'client', type: 'text-end', payload: { id } });
+                            },
+                            onChunk: (chunk, toolName, toolCallId) => {
+                                emit({
+                                    channel: 'internal',
+                                    type: 'tool-result',
+                                    payload: { toolName, result: chunk, toolCallId, preliminary: true },
+                                });
                             },
                         });
                         await runCtx.runStore.putRunState(runCtx.runState);
@@ -314,14 +378,18 @@ export class Runtime {
                 await this.applyCompaction(runCtx, activeAgent, emit, false);
             }
             catch (error) {
-                await this.hooks?.onError?.(runCtx, error);
+                await runHookSafely('onError', () => this.hooks?.onError?.(runCtx, error));
                 if (isDegradableRuntimeError(error)) {
                     const message = error instanceof Error ? error.message : String(error);
-                    emit({ type: 'error', error: message });
+                    emit({ channel: 'client', type: 'error', payload: { error: message } });
                     const degradedId = crypto.randomUUID();
-                    emit({ type: 'text-start', id: degradedId });
-                    emit({ type: 'text-delta', id: degradedId, delta: SAFE_DEGRADED_MESSAGE });
-                    emit({ type: 'text-end', id: degradedId });
+                    emit({ channel: 'client', type: 'text-start', payload: { id: degradedId } });
+                    emit({
+                        channel: 'client',
+                        type: 'text-delta',
+                        payload: { id: degradedId, delta: SAFE_DEGRADED_MESSAGE },
+                    });
+                    emit({ channel: 'client', type: 'text-end', payload: { id: degradedId } });
                     runCtx.runState.messages = [
                         ...runCtx.runState.messages,
                         { role: 'assistant', content: SAFE_DEGRADED_MESSAGE },
@@ -354,11 +422,14 @@ export class Runtime {
                         }
                     },
                 });
-                await this.hooks?.onEnd?.(runCtx);
+                await runHookSafely('onEnd', () => this.hooks?.onEnd?.(runCtx));
                 emit({
+                    channel: 'client',
                     type: 'done',
-                    sessionId: opened.session.id,
-                    usage: computeTurnTraceUsage(usageBaseline, runCtx.runState.state),
+                    payload: {
+                        sessionId: opened.session.id,
+                        usage: computeTurnTraceUsage(usageBaseline, runCtx.runState.state),
+                    },
                 });
             }
             return { text: collectAssistantText(runCtx.runState.messages), toolResults: [] };
@@ -378,8 +449,13 @@ export class Runtime {
             run: gated,
         });
     }
-    runOnce(opts) {
-        return recordRunOnce(this, opts);
+    async runOnce(opts) {
+        const existing = opts.sessionId ? await this.sessionStore.get(opts.sessionId) : null;
+        // Caller's explicit agentId wins, matching run() (`opts.agentId ?? defaultAgentId`).
+        // Persisted state is the fallback, not an override — otherwise the two public
+        // entry points disagree about which agent handles the same turn.
+        const agentId = opts.agentId ?? existing?.activeAgentId ?? existing?.currentAgent ?? this.config.defaultAgentId;
+        return recordRunOnce(this, { ...opts, agentId });
     }
     stream(opts) {
         return this.run(opts);
@@ -398,6 +474,10 @@ export class Runtime {
     getTraceStore() {
         return this.traceStore;
     }
+    /** The agent used when neither the caller nor persisted state names one. */
+    getDefaultAgentId() {
+        return this.config.defaultAgentId;
+    }
     getSessionStore() {
         return this.sessionStore;
     }
@@ -506,7 +586,11 @@ export class Runtime {
         });
         if (!result.compacted) {
             if (force) {
-                emit({ type: 'compaction-skipped', reason: result.reason });
+                emit({
+                    channel: 'internal',
+                    type: 'compaction-skipped',
+                    payload: { reason: result.reason },
+                });
             }
             return false;
         }
@@ -518,10 +602,13 @@ export class Runtime {
         });
         runCtx.session.messages = [...result.messages];
         emit({
+            channel: 'internal',
             type: 'context-compacted',
-            beforeTokens: result.beforeTokens,
-            afterTokens: result.afterTokens,
-            summarizedCount: result.summarizedCount,
+            payload: {
+                beforeTokens: result.beforeTokens,
+                afterTokens: result.afterTokens,
+                summarizedCount: result.summarizedCount,
+            },
         });
         return true;
     }
@@ -536,9 +623,12 @@ export class Runtime {
         runCtx.runState.messages = runCtx.session.messages;
         const compacted = await this.applyCompaction(runCtx, agent, emit, true);
         emit({
+            channel: 'internal',
             type: 'context-overflow-recovered',
-            strippedCount: recovery.strippedCount,
-            compacted,
+            payload: {
+                strippedCount: recovery.strippedCount,
+                compacted,
+            },
         });
     }
     async getConversationLength(sessionId) {
@@ -592,11 +682,14 @@ export class Runtime {
         });
         runCtx.session.metadata = latestSession.metadata;
         emit({
+            channel: 'internal',
             type: 'escalation',
-            reason: info.reason,
-            category: info.category,
-            outcome: outcome.status,
-            summary: request.summary,
+            payload: {
+                reason: info.reason,
+                category: info.category,
+                outcome: outcome.status,
+                summary: request.summary,
+            },
         });
     }
     /**

package/dist/runtime/TraceRecorder.d.ts

@@ -1,9 +1,10 @@
 import type { TurnResult } from '../types/channel.js';
-import type { HarnessStreamPart, TurnHandle } from '../types/stream.js';
+import type { StreamPart, TurnHandle } from '../types/stream.js';
 import type { AgentSpan, AgentTrace } from '../types/trace.js';
 import type { RunOptions } from './Runtime.js';
 export interface TraceRecorderOptions {
     sessionId?: string;
+    agentId?: string;
     input?: unknown;
     onSpan?: (span: AgentSpan) => void;
 }
@@ -16,8 +17,10 @@ export declare class TraceRecorder {
     private readonly toolCallIds;
     private readonly emitted;
     private readonly onSpan?;
+    private currentAgentId?;
     constructor(options?: TraceRecorderOptions);
-    record(part: HarnessStreamPart): void;
+    setInitiatingAgent(agentId: string): void;
+    record(part: StreamPart): void;
     finish(result: TurnResult): AgentTrace;
     private openSpan;
     private takeToolSpan;
@@ -28,6 +31,21 @@ export declare class TraceRecorder {
     private close;
     private emitSpan;
 }
-export declare function runOnce(runtime: {
+/**
+ * What the standalone {@link runOnce} needs from a runtime. `run` is required;
+ * the optional accessors let it resolve the same agent `Runtime.runOnce` would.
+ *
+ * It must NOT call `runtime.runOnce` — that method delegates here, so delegating
+ * back is infinite recursion.
+ */
+export interface RunOnceRuntime {
     run(opts: RunOptions): TurnHandle;
-}, opts: RunOptions): Promise<AgentTrace>;
+    getSessionStore?(): {
+        get(id: string): Promise<{
+            activeAgentId?: string;
+            currentAgent?: string;
+        } | null>;
+    };
+    getDefaultAgentId?(): string;
+}
+export declare function runOnce(runtime: RunOnceRuntime, opts: RunOptions): Promise<AgentTrace>;

package/dist/runtime/TraceRecorder.js

@@ -7,11 +7,13 @@ export class TraceRecorder {
     toolCallIds = new Map();
     emitted = new Set();
     onSpan;
+    currentAgentId;
     constructor(options = {}) {
         const startedAt = Date.now();
         const sessionId = options.sessionId ?? '';
         const traceId = crypto.randomUUID().replaceAll('-', '');
         this.onSpan = options.onSpan;
+        this.currentAgentId = options.agentId;
         this.root = {
             traceId,
             spanId: newSpanId(),
@@ -21,6 +23,7 @@ export class TraceRecorder {
             status: 'ok',
             attributes: {
                 sessionId,
+                ...(options.agentId ? { agentId: options.agentId } : {}),
                 ...(options.input !== undefined ? { input: toJsonValue(options.input) } : {}),
             },
         };
@@ -35,22 +38,26 @@ export class TraceRecorder {
             startedAt,
         };
     }
+    setInitiatingAgent(agentId) {
+        this.currentAgentId = agentId;
+        this.root.attributes.agentId = agentId;
+    }
     record(part) {
         try {
             const at = Date.now();
             switch (part.type) {
                 case 'text-delta':
-                    this.trace.answer += part.delta;
+                    this.trace.answer += part.payload.delta;
                     break;
                 case 'flow-enter':
                     this.closeNode(at);
                     this.closeFlow(at);
                     this.currentFlow = this.openSpan({
-                        name: `flow:${part.flow}`,
+                        name: `flow:${part.payload.flow}`,
                         kind: 'flow',
                         parentSpanId: this.root.spanId,
                         at,
-                        attributes: { activeFlow: part.flow },
+                        attributes: { activeFlow: part.payload.flow },
                     });
                     break;
                 case 'flow-end':
@@ -60,13 +67,13 @@ export class TraceRecorder {
                 case 'node-enter':
                     this.closeNode(at);
                     this.currentNode = this.openSpan({
-                        name: `node:${part.nodeName}`,
+                        name: `node:${part.payload.nodeName}`,
                         kind: 'node',
                         parentSpanId: this.currentFlow?.spanId ?? this.root.spanId,
                         at,
                         attributes: {
                             ...(this.currentFlow ? { activeFlow: activeFlowName(this.currentFlow) } : {}),
-                            nodeId: part.nodeName,
+                            nodeId: part.payload.nodeName,
                         },
                     });
                     break;
@@ -75,37 +82,40 @@ export class TraceRecorder {
                     break;
                 case 'tool-call': {
                     const span = this.openSpan({
-                        name: `tool:${part.toolName}`,
+                        name: `tool:${part.payload.toolName}`,
                         kind: 'tool',
                         parentSpanId: this.currentNode?.spanId ?? this.root.spanId,
                         at,
                         attributes: {
                             ...(this.currentFlow ? { activeFlow: activeFlowName(this.currentFlow) } : {}),
                             ...(this.currentNode ? { nodeId: nodeName(this.currentNode) } : {}),
-                            toolName: part.toolName,
-                            input: toJsonValue(part.args),
+                            toolName: part.payload.toolName,
+                            input: toJsonValue(part.payload.args),
                         },
                     });
-                    this.toolCallIds.set(span, part.toolCallId);
+                    this.toolCallIds.set(span, part.payload.toolCallId);
                     this.openTools.push(span);
                     this.trace.usedTool = true;
-                    this.trace.toolCalls.push({ name: part.toolName, args: toJsonValue(part.args) });
+                    this.trace.toolCalls.push({
+                        name: part.payload.toolName,
+                        args: toJsonValue(part.payload.args),
+                    });
                     break;
                 }
                 case 'tool-result': {
                     this.trace.usedTool = true;
-                    const result = toJsonValue(part.result);
-                    this.trace.toolResults.push({ name: part.toolName, result });
-                    const span = this.takeToolSpan(part.toolName, part.toolCallId) ??
+                    const result = toJsonValue(part.payload.result);
+                    this.trace.toolResults.push({ name: part.payload.toolName, result });
+                    const span = this.takeToolSpan(part.payload.toolName, part.payload.toolCallId) ??
                         this.openSpan({
-                            name: `tool:${part.toolName}`,
+                            name: `tool:${part.payload.toolName}`,
                             kind: 'tool',
                             parentSpanId: this.currentNode?.spanId ?? this.root.spanId,
                             at,
                             attributes: {
                                 ...(this.currentFlow ? { activeFlow: activeFlowName(this.currentFlow) } : {}),
                                 ...(this.currentNode ? { nodeId: nodeName(this.currentNode) } : {}),
-                                toolName: part.toolName,
+                                toolName: part.payload.toolName,
                             },
                         });
                     span.attributes.output = result;
@@ -114,35 +124,43 @@ export class TraceRecorder {
                     break;
                 }
                 case 'handoff': {
+                    const handoffFrom = this.currentAgentId;
                     const span = this.openSpan({
-                        name: `handoff:${part.targetAgent}`,
+                        name: `handoff:${part.payload.targetAgent}`,
                         kind: 'handoff',
                         parentSpanId: this.root.spanId,
                         at,
-                        attributes: { handoffTo: part.targetAgent },
+                        attributes: {
+                            ...(handoffFrom ? { handoffFrom } : {}),
+                            handoffTo: part.payload.targetAgent,
+                        },
                     });
                     span.endTime = at;
                     this.emitSpan(span);
+                    this.currentAgentId = part.payload.targetAgent;
                     break;
                 }
                 case 'error': {
                     const span = this.openTools.at(-1) ?? this.currentNode ?? this.currentFlow ?? this.root;
                     span.status = 'error';
-                    span.attributes.error = part.error;
+                    span.attributes.error = part.payload.error;
                     this.root.status = 'error';
-                    this.root.attributes.error = part.error;
+                    this.root.attributes.error = part.payload.error;
                     break;
                 }
                 case 'done':
-                    this.setSessionId(part.sessionId);
+                    this.setSessionId(part.payload.sessionId);
                     this.root.attributes.output = this.trace.answer;
-                    if (part.usage) {
-                        if (typeof part.usage.inputTokens === 'number')
-                            this.root.attributes.tokensIn = part.usage.inputTokens;
-                        if (typeof part.usage.outputTokens === 'number')
-                            this.root.attributes.tokensOut = part.usage.outputTokens;
-                        if (typeof part.usage.contextTokens === 'number')
-                            this.root.attributes.contextTokens = part.usage.contextTokens;
+                    if (part.payload.usage) {
+                        if (typeof part.payload.usage.inputTokens === 'number') {
+                            this.root.attributes.tokensIn = part.payload.usage.inputTokens;
+                        }
+                        if (typeof part.payload.usage.outputTokens === 'number') {
+                            this.root.attributes.tokensOut = part.payload.usage.outputTokens;
+                        }
+                        if (typeof part.payload.usage.contextTokens === 'number') {
+                            this.root.attributes.contextTokens = part.payload.usage.contextTokens;
+                        }
                     }
                     this.close(at);
                     break;
@@ -174,7 +192,11 @@ export class TraceRecorder {
             kind: args.kind,
             startTime: args.at,
             status: 'ok',
-            attributes: { sessionId: this.trace.sessionId, ...args.attributes },
+            attributes: {
+                sessionId: this.trace.sessionId,
+                ...(this.currentAgentId ? { agentId: this.currentAgentId } : {}),
+                ...args.attributes,
+            },
         };
         this.trace.spans.push(span);
         return span;
@@ -239,8 +261,22 @@ export class TraceRecorder {
     }
 }
 export async function runOnce(runtime, opts) {
+    // Resolve attribution the same way Runtime.runOnce does: caller's agentId
+    // first, then persisted state, then the runtime default. Without this the
+    // standalone helper produced spans with no `agentId` and handoff spans with
+    // no `handoffFrom` — the exact feature it is documented to provide.
+    let agentId = opts.agentId;
+    if (!agentId && opts.sessionId && runtime.getSessionStore) {
+        const existing = await runtime.getSessionStore().get(opts.sessionId);
+        agentId = existing?.activeAgentId ?? existing?.currentAgent;
+    }
+    agentId ??= runtime.getDefaultAgentId?.();
     const handle = runtime.run(opts);
-    const recorder = new TraceRecorder({ sessionId: opts.sessionId, input: opts.input });
+    const recorder = new TraceRecorder({
+        sessionId: opts.sessionId,
+        agentId,
+        input: opts.input,
+    });
     for await (const part of handle.events) {
         recorder.record(part);
     }

package/dist/runtime/buildAgentToolSurface.js

@@ -28,7 +28,7 @@ export async function buildAgentToolSurface(agent, session, deps) {
     let skillPrompt;
     let skillTools = {};
     if (agent.skills) {
-        const wired = await wireAgentSkills(agent);
+        const wired = await wireAgentSkills(agent, resolvedWorkspace?.fs);
         if (wired) {
             skillTools = wired.tools;
             Object.assign(executorTools, wired.tools);

package/dist/runtime/channels/TextDriver.js

@@ -29,16 +29,19 @@ export class TextDriver {
         if (!preTurn.proceed) {
             const blocked = preTurn.blockedMessage ?? 'Input blocked by guardrails';
             ctx.emit({
+                channel: 'internal',
                 type: 'safety-blocked',
-                moderator: preTurn.blockedBy ?? 'input-guardrails',
-                rationale: preTurn.blockedReason ?? 'input blocked',
-                userFacingMessage: blocked,
+                payload: {
+                    moderator: preTurn.blockedBy ?? 'input-guardrails',
+                    rationale: preTurn.blockedReason ?? 'input blocked',
+                    userFacingMessage: blocked,
+                },
             });
             const id = crypto.randomUUID();
-            ctx.emit({ type: 'text-start', id });
-            ctx.emit({ type: 'text-delta', id, delta: blocked });
-            ctx.emit({ type: 'text-end', id });
-            ctx.emit({ type: 'turn-end' });
+            ctx.emit({ channel: 'client', type: 'text-start', payload: { id } });
+            ctx.emit({ channel: 'client', type: 'text-delta', payload: { id, delta: blocked } });
+            ctx.emit({ channel: 'client', type: 'text-end', payload: { id } });
+            ctx.emit({ channel: 'internal', type: 'turn-end', payload: {} });
             return { text: blocked, toolResults: [] };
         }
         const scope = resolveNodeGatherScope(replyNode, ctx.runState.state, ctx.runState.messages);
@@ -75,7 +78,7 @@ export class TextDriver {
                         if (part.type === 'error') {
                             const err = part.error;
                             const message = err instanceof Error ? err.message : String(err);
-                            ctx.emit({ type: 'error', error: message });
+                            ctx.emit({ channel: 'client', type: 'error', payload: { error: message } });
                             throw err instanceof Error ? err : new Error(message);
                         }
                     }
@@ -160,7 +163,7 @@ export class TextDriver {
         if (turnUsage && turnUsage.totalTokens > 0) {
             out.usage = turnUsage;
         }
-        ctx.emit({ type: 'turn-end' });
+        ctx.emit({ channel: 'internal', type: 'turn-end', payload: {} });
         return out;
     }
     // Non-speaking field extraction for collect nodes (shared helper so text and

package/dist/runtime/channels/executeModelTool.d.ts

@@ -11,6 +11,12 @@ export interface ModelToolCallOutcome {
     result: unknown;
     control?: TurnControl;
     failed: boolean;
+    /**
+     * Set when the call unwound with a control-flow signal rather than a failure. Held as a
+     * value so a parallel batch can still finalize its siblings; the dispatcher rethrows it
+     * once the batch has settled. Never surfaced to the model.
+     */
+    signal?: unknown;
 }
 export declare function executeModelToolCall(ctx: RunContext, call: ModelToolCall, localTools?: Record<string, AnyTool>, durableOpts?: {
     callsite?: string;