@kuralle-agents/core 0.13.0 → 0.14.0

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;

package/dist/runtime/channels/executeModelTool.js

@@ -1,7 +1,8 @@
 import { classifyControl } from '../../flow/classifyControl.js';
-import { toolErrorResult } from '../../tools/controlResults.js';
+import { toolDeniedResult, toolErrorResult } from '../../tools/controlResults.js';
 import { idempotencyKey, logicalRunId } from '../durable/idempotency.js';
 import { findStepByKey } from '../durable/replay.js';
+import { isApprovalDenial, isControlFlowSignal } from '../controlFlowSignal.js';
 export async function executeModelToolCall(ctx, call, localTools, durableOpts) {
     try {
         const localTool = localTools?.[call.toolName];
@@ -24,30 +25,79 @@ export async function executeModelToolCall(ctx, call, localTools, durableOpts) {
         return { result: toolResult, control: classifyControl(toolResult), failed: false };
     }
     catch (error) {
+        if (isControlFlowSignal(error)) {
+            // A suspend. Not a failure, so no client-facing error and no tool result: returning it
+            // as a value keeps this function's never-rejects contract (which `Promise.all` below
+            // depends on) while letting the dispatcher rethrow it once the batch has settled.
+            return { result: undefined, failed: true, signal: error };
+        }
+        if (isApprovalDenial(error)) {
+            // A human declined. The model asked for this call, so the model is told — otherwise
+            // the turn dies and the user never hears why. No client error part: nothing broke.
+            return { result: toolDeniedResult(error.toolName, error.by), failed: true };
+        }
         const message = error instanceof Error ? error.message : String(error);
-        ctx.emit({ type: 'error', error: message });
+        ctx.emit({ channel: 'client', type: 'error', payload: { error: message } });
         return { result: toolErrorResult(error), failed: true };
     }
 }
 function isParallelSafeTool(def) {
     return def?.parallelSafe === true || def?.replay === false;
 }
+/**
+ * Runs `task` over every item, at most `limit` at a time, preserving result order.
+ *
+ * Unbounded `Promise.all` over a model-emitted batch lets the model decide how many
+ * sockets, subprocesses, or rate-limited API calls open at once. `limit` is a ceiling on
+ * that; omitting it keeps the previous unbounded behaviour.
+ *
+ * `task` is expected not to reject (see the caller's contract). If one does, the rejection
+ * propagates and in-flight siblings still run to completion — they are not cancelled, so
+ * their journal writes complete rather than being abandoned half-done.
+ */
+async function runWithConcurrency(items, task, limit) {
+    if (limit === undefined || limit <= 0 || limit >= items.length) {
+        return Promise.all(items.map((item) => task(item)));
+    }
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const index = next++;
+            results[index] = await task(items[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: limit }, () => worker()));
+    return results;
+}
 export async function dispatchModelToolCalls(ctx, toolCalls, localTools, onEach) {
+    /** Resolves to a control-flow signal when the call suspended, otherwise `undefined`. */
     const runOne = async (call, durableOpts) => {
         ctx.emit({
+            channel: 'internal',
             type: 'tool-call',
-            toolName: call.toolName,
-            args: call.input,
-            toolCallId: call.toolCallId,
+            payload: {
+                toolName: call.toolName,
+                args: call.input,
+                toolCallId: call.toolCallId,
+            },
         });
         const outcome = await executeModelToolCall(ctx, call, localTools, durableOpts);
+        if (outcome.signal !== undefined) {
+            // Suspended: no result exists, so nothing may reach the model or the transcript.
+            return outcome.signal;
+        }
         onEach({ call, outcome });
         ctx.emit({
+            channel: 'internal',
             type: 'tool-result',
-            toolName: call.toolName,
-            result: outcome.result,
-            toolCallId: call.toolCallId,
+            payload: {
+                toolName: call.toolName,
+                result: outcome.result,
+                toolCallId: call.toolCallId,
+            },
         });
+        return undefined;
     };
     const runParallel = async (parallel) => {
         const callsites = ctx.reserveCallsites(parallel.length);
@@ -76,12 +126,22 @@ export async function dispatchModelToolCalls(ctx, toolCalls, localTools, onEach)
             const index = needsIndex ? indices?.[unresolvedCursor++] : hit?.index;
             return { call, callsite: callsites[i], index };
         });
-        await Promise.all(assignments.map(({ call, callsite, index }) => runOne(call, { callsite, index })));
+        // executeModelToolCall never rejects — tool errors resolve with failed: true and control-flow
+        // signals resolve as outcome.signal — so no sibling can be abandoned mid-flight with its
+        // finalizeStep unawaited. A suspend is rethrown only after every sibling has settled: you
+        // cannot cancel an in-flight promise, so failing fast here would let the work happen anyway
+        // while the journal recorded it as still running.
+        const signals = await runWithConcurrency(assignments, ({ call, callsite, index }) => runOne(call, { callsite, index }), ctx.limits?.maxToolConcurrency);
+        const suspended = signals.find((signal) => signal !== undefined);
+        if (suspended !== undefined)
+            throw suspended;
     };
     for (let cursor = 0; cursor < toolCalls.length;) {
         const call = toolCalls[cursor];
         if (!isParallelSafeTool(localTools[call.toolName])) {
-            await runOne(call);
+            const signal = await runOne(call);
+            if (signal !== undefined)
+                throw signal;
             cursor += 1;
             continue;
         }

package/dist/runtime/channels/extractionTurn.js

@@ -36,7 +36,7 @@ export async function runSilentExtraction(node, ctx, model, maxSteps) {
             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);
             }
         }

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

@@ -1,7 +1,4 @@
 export type { ChannelDriver } from '../../types/channel.js';
 export { TextDriver, buildNodePrompt } from './TextDriver.js';
 export type { TextDriverConfig } from './TextDriver.js';
-export { VoiceDriver } from './VoiceDriver.js';
-export type { VoiceDriverConfig } from './VoiceDriver.js';
-export { resolveVoiceGeminiTools, v2ToolsToGemini } from './voiceTools.js';
 export { setPendingUserInput, consumePendingUserInput, consumeAllPendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './inputBuffer.js';

package/dist/runtime/channels/index.js

@@ -1,8 +1,2 @@
 export { TextDriver, buildNodePrompt } from './TextDriver.js';
-// PAUSED: the realtime VoiceDriver is not on the primary (text) path and is not
-// re-exported from the package's headline API. It stays here for the realtime
-// stack (`@kuralle-agents/realtime-audio`) via the `/runtime` subpath. Text is
-// the primary primitive; cascaded voice runs over text (see livekit-plugin).
-export { VoiceDriver } from './VoiceDriver.js';
-export { resolveVoiceGeminiTools, v2ToolsToGemini } from './voiceTools.js';
 export { setPendingUserInput, consumePendingUserInput, consumeAllPendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './inputBuffer.js';

package/dist/runtime/channels/streaming/hostControlSpeak.js

@@ -72,7 +72,11 @@ export async function speakWithHostControl(args) {
     toolControl = getToolControl();
     if (toolControl) {
         if (spoken.text) {
-            ctx.emit({ type: 'text-cancel', id: turnId, reason: 'host-control' });
+            ctx.emit({
+                channel: 'client',
+                type: 'text-cancel',
+                payload: { id: turnId, reason: 'host-control' },
+            });
         }
         return { text: '', control: toolControl };
     }

package/dist/runtime/channels/streaming/speakGated.js

@@ -1,16 +1,16 @@
 import { randomUUID } from 'node:crypto';
 import { SentenceAggregator } from './SentenceAggregator.js';
 function emitMessage(ctx, id, text) {
-    ctx.emit({ type: 'text-start', id });
-    ctx.emit({ type: 'text-delta', id, delta: text });
-    ctx.emit({ type: 'text-end', id });
+    ctx.emit({ channel: 'client', type: 'text-start', payload: { id } });
+    ctx.emit({ channel: 'client', type: 'text-delta', payload: { id, delta: text } });
+    ctx.emit({ channel: 'client', type: 'text-end', payload: { id } });
 }
 async function emitBlockedSafeMessage(ctx, turnId, started, outcome) {
     if (started) {
         ctx.emit({
+            channel: 'client',
             type: 'text-cancel',
-            id: turnId,
-            reason: outcome.reason ?? 'blocked',
+            payload: { id: turnId, reason: outcome.reason ?? 'blocked' },
         });
     }
     const safeId = randomUUID();
@@ -32,7 +32,7 @@ export async function speakGated(args) {
         }
         catch (err) {
             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);
         }
         const decision = await runGate(full, true);
@@ -48,13 +48,17 @@ export async function speakGated(args) {
     let emitted = '';
     const openOnce = () => {
         if (!started) {
-            ctx.emit({ type: 'text-start', id: turnId });
+            ctx.emit({ channel: 'client', type: 'text-start', payload: { id: turnId } });
             started = true;
         }
     };
     const emitCleared = (chunk) => {
         openOnce();
-        ctx.emit({ type: 'text-delta', id: turnId, delta: chunk });
+        ctx.emit({
+            channel: 'client',
+            type: 'text-delta',
+            payload: { id: turnId, delta: chunk },
+        });
         emitted += chunk;
     };
     const gateSentence = async (sentence, final) => {
@@ -69,7 +73,11 @@ export async function speakGated(args) {
         for await (const { delta } of source) {
             if (mode === 'token') {
                 openOnce();
-                ctx.emit({ type: 'text-delta', id: turnId, delta });
+                ctx.emit({
+                    channel: 'client',
+                    type: 'text-delta',
+                    payload: { id: turnId, delta },
+                });
                 emitted += delta;
                 continue;
             }
@@ -88,15 +96,19 @@ export async function speakGated(args) {
             }
         }
         if (started) {
-            ctx.emit({ type: 'text-end', id: turnId });
+            ctx.emit({ channel: 'client', type: 'text-end', payload: { id: turnId } });
         }
         return { text: emitted };
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        ctx.emit({ type: 'error', error: message });
+        ctx.emit({ channel: 'client', type: 'error', payload: { error: message } });
         if (started) {
-            ctx.emit({ type: 'text-cancel', id: turnId, reason: message });
+            ctx.emit({
+                channel: 'client',
+                type: 'text-cancel',
+                payload: { id: turnId, reason: message },
+            });
         }
         throw err instanceof Error ? err : new Error(message);
     }

package/dist/runtime/citations/index.d.ts

@@ -1,15 +1,15 @@
-import type { AgentKnowledgeOverrides, HarnessStreamPart, KnowledgeRetrievalResult, RetrievalCacheAdapter, SourceRef } from '../../types/index.js';
+import type { AgentKnowledgeOverrides, StreamPart, KnowledgeRetrievalResult, RetrievalCacheAdapter, SourceRef } from '../../types/index.js';
 export interface CitationRetrievalProvider {
     retrieve(query: string, cache: RetrievalCacheAdapter | undefined, agentOverrides?: AgentKnowledgeOverrides, isVoice?: boolean): Promise<{
         results: KnowledgeRetrievalResult[];
         citations?: SourceRef[];
-        events: HarnessStreamPart[];
+        events: StreamPart[];
     }>;
 }
 export interface CitationRetrievalResult {
     results: KnowledgeRetrievalResult[];
     citations: SourceRef[];
-    events: HarnessStreamPart[];
+    events: StreamPart[];
 }
 export declare function retrieveWithCitations(provider: CitationRetrievalProvider, query: string, cache: RetrievalCacheAdapter | undefined, agentOverrides?: AgentKnowledgeOverrides, isVoice?: boolean): Promise<CitationRetrievalResult>;
 export declare function normalizeCitations(results: KnowledgeRetrievalResult[], nativeCitations?: readonly SourceRef[]): SourceRef[];

package/dist/runtime/closeRun.js

@@ -1,6 +1,7 @@
 import { isTerminalOutcome, markSessionOutcome } from './outcomeMarking.js';
 import { mutateSessionWithRetry } from '../session/utils.js';
 import { syncPendingUserInput } from './channels/inputBuffer.js';
+import { runHookSafely } from './runHookSafely.js';
 export async function closeRun(options) {
     const { session, runState, runStore, sessionStore, hooks, ctx } = options;
     runState.updatedAt = Date.now();
@@ -16,10 +17,10 @@ export async function closeRun(options) {
         outcomeRecord = await markSessionOutcome(sessionStore, session, options.terminalOutcome, { reason: options.outcomeReason, markedBy: 'hook' }, ctx.emit);
     }
     if (outcomeRecord && isTerminalOutcome(outcomeRecord.outcome)) {
-        await hooks?.onConversationEnd?.({
+        await runHookSafely('onConversationEnd', () => hooks?.onConversationEnd?.({
             session,
             outcome: outcomeRecord,
-        });
+        }));
     }
     await mutateSessionWithRetry(sessionStore, session.id, (latest) => {
         latest.currentAgent = runState.activeAgentId;

package/dist/runtime/controlFlowSignal.d.ts

@@ -0,0 +1,24 @@
+import { ToolApprovalDeniedError } from '../tools/effect/errors.js';
+/**
+ * The run is not finished: stop the turn, keep the journal, resume when a signal arrives.
+ * It unwinds the stack like an error but is not a failure, so it must never be reported to
+ * the model as a tool error, shown to the user as an error, or journaled as one.
+ *
+ * Only `SuspendError` qualifies. An approval *denial* is deliberately not a signal — see
+ * `isApprovalDenial`.
+ */
+export declare function isControlFlowSignal(error: unknown): boolean;
+/**
+ * A human answered "no". Neither a failure nor a suspend — the opposite of a suspend, in
+ * fact: a suspend defers the decision, a denial resolves it.
+ *
+ * Two rules follow, and they differ by who is driving the call:
+ *
+ * - It must never be degraded into "something went wrong on my side". Nothing went wrong;
+ *   saying so would be a lie to the user.
+ * - On the **model** path it becomes a tool result, because there is no author code to
+ *   catch it and the agent needs to be able to tell the user the request was declined.
+ *   On the **flow** path it keeps propagating, because an `action` node's author chose to
+ *   call the tool and can catch it or branch on `ctx.approve()` instead.
+ */
+export declare function isApprovalDenial(error: unknown): error is ToolApprovalDeniedError;