@kuralle-agents/core 0.13.0 → 0.15.0

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,17 @@
 import { randomUUID } from 'node:crypto';
+import { isControlFlowSignal } from '../../controlFlowSignal.js';
 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();
@@ -31,8 +32,14 @@ export async function speakGated(args) {
             }
         }
         catch (err) {
+            // A suspend unwinds through here on its way to the host loop. It is not a failure and
+            // must not reach the user as one — the same rule executeModelToolCall and runFlow
+            // already apply. This third path was missed, so an approval pause still surfaced as
+            // "error: Run suspended waiting for __approval" mid-conversation.
+            if (isControlFlowSignal(err))
+                throw 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 +55,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 +80,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 +103,21 @@ 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) {
+        if (isControlFlowSignal(err))
+            throw 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;

package/dist/runtime/controlFlowSignal.js

@@ -0,0 +1,29 @@
+import { SuspendError } from './durable/RunStore.js';
+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 function isControlFlowSignal(error) {
+    return error instanceof SuspendError;
+}
+/**
+ * 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 function isApprovalDenial(error) {
+    return error instanceof ToolApprovalDeniedError;
+}

package/dist/runtime/ctx.d.ts

@@ -1,7 +1,7 @@
 import type { LanguageModel } from 'ai';
 import type { Session } from '../types/session.js';
-import type { EffectToolExecutor, HookRunner, MemoryService, AutoRetrieveProvider, RunContext } from '../types/run-context.js';
-import type { HarnessStreamPart } from '../types/stream.js';
+import type { EffectToolExecutor, MemoryService, AutoRetrieveProvider, RunContext } from '../types/run-context.js';
+import type { StreamPart } from '../types/stream.js';
 import type { RefinementCapability } from '../capabilities/RefinementCapability.js';
 import type { ValidationCapability } from '../capabilities/ValidationCapability.js';
 import type { InputProcessor, OutputProcessor } from '../types/processors.js';
@@ -19,7 +19,6 @@ export interface CtxDeps {
     runStore: RunStore;
     steps: StepRecord[];
     toolExecutor: EffectToolExecutor;
-    hookRunner?: HookRunner;
     model: LanguageModel;
     controlModel?: LanguageModel;
     outOfBandControl?: boolean;
@@ -34,7 +33,7 @@ export interface CtxDeps {
     bargeIn?: AbortSignal;
     abortSignal?: AbortSignal;
     clock?: EffectClock;
-    emit?: (part: HarnessStreamPart) => void;
+    emit?: (part: StreamPart) => void;
 }
 export declare function createRunContext(deps: CtxDeps): Promise<RunContext>;
 export {};

package/dist/runtime/ctx.js

@@ -14,6 +14,22 @@ function makeCtx(deps) {
     const emit = deps.emit ?? (() => { });
     // Mutable holder: handoff reassigns runCtx.toolExecutor; ctx.tool must see the swap.
     const toolExecutorHolder = { executor: deps.toolExecutor };
+    let pendingAppendTail = Promise.resolve();
+    const serializePendingAppend = (operation) => {
+        const previous = pendingAppendTail;
+        let release;
+        pendingAppendTail = new Promise((resolve) => {
+            release = resolve;
+        });
+        return previous.then(async () => {
+            try {
+                return await operation();
+            }
+            finally {
+                release();
+            }
+        });
+    };
     const consumeCallsite = () => {
         const site = String(effectOrdinal);
         effectOrdinal += 1;
@@ -85,9 +101,28 @@ function makeCtx(deps) {
             }
         }
         const isRetry = hit?.status === 'running';
-        const stepIndex = options?.index ?? hit?.index ?? steps.length;
+        const stepIndex = options?.index ?? hit?.index;
         if (!isRetry) {
-            await appendPendingStep(key, kind, name, stepIndex);
+            const append = async () => {
+                let index = stepIndex;
+                if (index === undefined) {
+                    if (deps.runStore.reserveSteps) {
+                        index = (await deps.runStore.reserveSteps(deps.runState.runId, 1))[0];
+                    }
+                    else {
+                        // ctx.tool owns ordinal assignment: use the store's atomic reservation when available,
+                        // and serialize legacy stores that do not expose reserveSteps within this context.
+                        index = steps.length;
+                    }
+                }
+                await appendPendingStep(key, kind, name, index);
+            };
+            if (stepIndex === undefined && !deps.runStore.reserveSteps) {
+                await serializePendingAppend(append);
+            }
+            else {
+                await append();
+            }
         }
         let result;
         try {
@@ -131,7 +166,7 @@ function makeCtx(deps) {
         deps.runState.status = 'paused';
         deps.runState.updatedAt = Date.now();
         await deps.runStore.putRunState(deps.runState);
-        emit({ type: 'paused', waitingFor: signalName });
+        emit({ channel: 'internal', type: 'paused', payload: { waitingFor: signalName } });
         throw new SuspendError(signalName);
     };
     const pauseEffect = async (signalName, meta) => {
@@ -160,7 +195,6 @@ function makeCtx(deps) {
         set toolExecutor(executor) {
             toolExecutorHolder.executor = executor;
         },
-        hookRunner: deps.hookRunner ?? {},
         model: deps.model,
         controlModel: deps.controlModel ?? deps.model,
         outOfBandControl: deps.outOfBandControl ?? false,
@@ -223,7 +257,7 @@ function makeCtx(deps) {
                 toolCtx: options?.toolCtx,
             });
             if (def?.replay === false) {
-                const auditKey = `${key}:${steps.length}`;
+                const auditKey = `${key}:${steps.length}:${options?.index ?? callsite}`;
                 return replayOrExecute(auditKey, 'tool', name, executeTool, { index: options?.index });
             }
             return replayOrExecute(key, 'tool', name, executeTool, { index: options?.index });

package/dist/runtime/durable/RunStore.js

@@ -3,7 +3,7 @@ export class LogConflictError extends Error {
     expectedIndex;
     actualIndex;
     constructor(runId, expectedIndex, actualIndex) {
-        super(`Log conflict for run ${runId}: expected append at index ${expectedIndex}, current length is ${actualIndex}`);
+        super(`Log conflict for run ${runId}: expected append at index ${expectedIndex}, current length is ${actualIndex}. For parallel durable effects, use ctx.tool directly or reserve callsites with ctx.reserveCallsites(count) before supplying explicit indices.`);
         this.name = 'LogConflictError';
         this.runId = runId;
         this.expectedIndex = expectedIndex;

package/dist/runtime/grounding/gather.d.ts

@@ -1,4 +1,4 @@
-import type { SourceRef } from '../../types/voice.js';
+import type { SourceRef } from '../../types/knowledge.js';
 import type { GatherScope, RunContext } from '../../types/run-context.js';
 export type { GatherScope } from '../../types/run-context.js';
 export interface GatherResult {

package/dist/runtime/grounding/inMemoryKnowledge.d.ts

@@ -1,4 +1,4 @@
-import type { KnowledgeProviderConfig, KnowledgeRetrieverAdapter } from '../../types/voice.js';
+import type { KnowledgeProviderConfig, KnowledgeRetrieverAdapter } from '../../types/knowledge.js';
 export interface InMemoryKnowledgeDocument {
     id?: string;
     text: string;

package/dist/runtime/grounding/knowledge.d.ts

@@ -1,7 +1,7 @@
 import type { AgentConfig } from '../../types/agentConfig.js';
 import type { AutoRetrieveProvider } from '../../types/run-context.js';
 import type { AnyTool } from '../../types/effectTool.js';
-import type { KnowledgeProviderConfig } from '../../types/voice.js';
+import type { KnowledgeProviderConfig } from '../../types/knowledge.js';
 import { KnowledgeProvider } from '../KnowledgeProvider.js';
 export declare function buildKnowledgeProvider(config: KnowledgeProviderConfig): KnowledgeProvider;
 export declare function buildAutoRetrieveProvider(provider: KnowledgeProvider, agent: AgentConfig): AutoRetrieveProvider | undefined;

package/dist/runtime/hostLoop.js

@@ -36,7 +36,7 @@ export async function hostLoop(options) {
             return { kind: 'paused' };
         }
         if (error instanceof LimitsExceededError) {
-            ctx.emit({ type: 'error', error: error.message });
+            ctx.emit({ channel: 'client', type: 'error', payload: { error: error.message } });
             return { kind: 'ended', reason: error.message };
         }
         throw error;
@@ -80,10 +80,19 @@ async function runActiveFlow(flow, run, driver, ctx, agent) {
         await ctx.runStore.putRunState(run);
         return { kind: 'turnComplete' };
     }
-    const completed = run.state.__completedFlows;
-    const completedFlows = Array.isArray(completed) ? completed : [];
-    if (!completedFlows.includes(flow.name)) {
-        run.state.__completedFlows = [...completedFlows, flow.name];
+    // A flow that ended because a node threw is NOT completed. Marking it so made the
+    // failure permanent for the turn: `select` and the host-control tools both exclude a
+    // completed flow from re-entry, so a failed intake could not be retried even though the
+    // error was recoverable (a mistyped unit id, a transient tool fault). Observed live —
+    // a session held __completedFlows: ["raise_work_order"] with an errored journal step
+    // and no work order to show for it.
+    const degraded = result.kind === 'ended' && result.reason === 'error_degraded';
+    if (!degraded) {
+        const completed = run.state.__completedFlows;
+        const completedFlows = Array.isArray(completed) ? completed : [];
+        if (!completedFlows.includes(flow.name)) {
+            run.state.__completedFlows = [...completedFlows, flow.name];
+        }
     }
     run.activeFlow = undefined;
     run.activeNode = undefined;
@@ -160,7 +169,11 @@ function guardVerdictToTelemetryVerdict(verdict) {
     return 'keep';
 }
 function emitHostGuardTelemetry(ctx, data) {
-    ctx.emit({ type: 'custom', name: 'host-guard', data });
+    ctx.emit({
+        channel: 'internal',
+        type: 'custom',
+        payload: { name: 'host-guard', data },
+    });
 }
 function guardVerdictToControl(verdict, agent) {
     const selection = verdictToSelection(verdict, agent);
@@ -174,7 +187,11 @@ function guardVerdictToControl(verdict, agent) {
 }
 async function executeHostControl(agent, run, driver, ctx, control) {
     if (!control) {
-        ctx.emit({ type: 'error', error: 'No valid host control target resolved' });
+        ctx.emit({
+            channel: 'client',
+            type: 'error',
+            payload: { error: 'No valid host control target resolved' },
+        });
         return { kind: 'ended', reason: 'dispatch_failed' };
     }
     if (control.type === 'enterFlow') {
@@ -182,18 +199,30 @@ async function executeHostControl(agent, run, driver, ctx, control) {
         if (flow) {
             return await runActiveFlow(flow, run, driver, ctx, agent);
         }
-        ctx.emit({ type: 'error', error: `Flow not found: ${control.flowName}` });
+        ctx.emit({
+            channel: 'client',
+            type: 'error',
+            payload: { error: `Flow not found: ${control.flowName}` },
+        });
         return { kind: 'ended', reason: 'flow_not_found' };
     }
     if (control.type === 'handoff') {
-        ctx.emit({ type: 'handoff', targetAgent: control.target, reason: control.reason });
+        ctx.emit({
+            channel: 'internal',
+            type: 'handoff',
+            payload: { targetAgent: control.target, reason: control.reason },
+        });
         return { kind: 'handoff', to: control.target, reason: control.reason };
     }
     if (control.type === 'end') {
         return { kind: 'ended', reason: control.reason };
     }
     if (control.type === 'escalate') {
-        ctx.emit({ type: 'handoff', targetAgent: 'human', reason: control.reason });
+        // No handoff part is emitted here. Runtime owns it: it emits one for any
+        // target in `terminalHandoffTargets` (default ['human']) on this exact
+        // return value. Emitting here too produced two handoff spans per escalation
+        // and a meaningless `human -> human` self-edge, which then mis-attributed
+        // every later span in the turn to `human`.
         return { kind: 'handoff', to: 'human', reason: control.reason, category: control.category };
     }
     if (control.type === 'recover') {

package/dist/runtime/index.d.ts

@@ -3,8 +3,7 @@ export type { RuntimeLike } from './RuntimeLike.js';
 export { TraceRecorder, runOnce, type TraceRecorderOptions } from './TraceRecorder.js';
 export type { AgentSpan, AgentTrace, SpanKind } from '../types/trace.js';
 export { SessionWorkingMemory } from './WorkingMemory.js';
-export { TextDriver, VoiceDriver } from './channels/index.js';
-export type { VoiceDriverConfig } from './channels/index.js';
+export { TextDriver } from './channels/index.js';
 export { setPendingUserInput, consumePendingUserInput, consumeAllPendingUserInput, peekPendingUserInput, hasPendingUserInput, } from './channels/index.js';
 export { userInputToText, mergeUserInputContents, hasMediaParts, transcribeAudioParts, type UserInputContent, } from './userInput.js';
 export { isAbortSignal, type InterruptionEvent, type AbortOptions, type CancellationReason, } from '../types/index.js';

package/dist/runtime/index.js

@@ -1,7 +1,7 @@
 export { createRuntime, Runtime, } from './Runtime.js';
 export { TraceRecorder, runOnce } from './TraceRecorder.js';
 export { SessionWorkingMemory } from './WorkingMemory.js';
-export { TextDriver, VoiceDriver } from './channels/index.js';
+export { TextDriver } from './channels/index.js';
 // Pending-input buffer helpers — required by custom ChannelDriver authors to
 // implement awaitUser the same FIFO-aware way the built-in drivers do (the
 // buffer is an ordered queue since 0.3.13/H3, not a single slot).

package/dist/runtime/outcomeMarking.d.ts

@@ -1,9 +1,9 @@
 import type { Session } from '../types/session.js';
 import type { SessionStore } from '../session/SessionStore.js';
 import type { ConversationOutcome, ConversationOutcomeMarkedBy, ConversationOutcomeRecord } from '../outcomes/types.js';
-import type { HarnessStreamPart } from '../types/stream.js';
+import type { StreamPart } from '../types/stream.js';
 export declare function isTerminalOutcome(outcome: ConversationOutcome): boolean;
 export declare function markSessionOutcome(sessionStore: SessionStore, session: Session, outcome: ConversationOutcome, opts?: {
     reason?: string;
     markedBy?: ConversationOutcomeMarkedBy;
-}, emit?: (part: HarnessStreamPart) => void): Promise<ConversationOutcomeRecord>;
+}, emit?: (part: StreamPart) => void): Promise<ConversationOutcomeRecord>;

package/dist/runtime/outcomeMarking.js

@@ -22,8 +22,9 @@ export async function markSessionOutcome(sessionStore, session, outcome, opts =
     await sessionStore.save(session);
     if (emit) {
         emit({
+            channel: 'client',
             type: 'conversation-outcome',
-            outcome: record.outcome,
+            payload: { outcome: record.outcome },
         });
     }
     return record;