@kuralle-agents/core 0.3.7 → 0.3.9

package/dist/authoring/index.d.ts

@@ -1,2 +1,2 @@
-export { reply, collect, action, decide, defineFlow } from './nodes.js';
+export { reply, collect, action, decide, confirmGate, defineFlow } from './nodes.js';
 export { defineAgent, type AgentConfig, type Instructions } from './defineAgent.js';

package/dist/authoring/index.js

@@ -1,2 +1,2 @@
-export { reply, collect, action, decide, defineFlow } from './nodes.js';
+export { reply, collect, action, decide, confirmGate, defineFlow } from './nodes.js';
 export { defineAgent } from './defineAgent.js';

package/dist/authoring/nodes.d.ts

@@ -1 +1 @@
-export { reply, collect, action, decide, defineFlow } from '../types/flow.js';
+export { reply, collect, action, decide, confirmGate, defineFlow } from '../types/flow.js';

package/dist/authoring/nodes.js

@@ -1 +1 @@
-export { reply, collect, action, decide, defineFlow } from '../types/flow.js';
+export { reply, collect, action, decide, confirmGate, defineFlow } from '../types/flow.js';

package/dist/flow/classifyControl.js

@@ -1,5 +1,6 @@
 import { isHandoffResult } from '../tools/handoff.js';
 import { isFinalResult } from '../tools/final.js';
+import { isEscalateResult, isRecoverResult } from '../tools/controlResults.js';
 export function classifyControl(result) {
     if (isHandoffResult(result)) {
         return {
@@ -11,5 +12,11 @@ export function classifyControl(result) {
     if (isFinalResult(result)) {
         return { type: 'end', reason: result.text };
     }
+    if (isEscalateResult(result)) {
+        return { type: 'escalate', reason: result.reason };
+    }
+    if (isRecoverResult(result)) {
+        return { type: 'recover', reason: result.reason };
+    }
     return undefined;
 }

package/dist/flow/confirmParse.d.ts

@@ -0,0 +1,2 @@
+export type ConfirmVerdict = 'affirm' | 'decline' | 'ambiguous';
+export declare function parseConfirmation(raw: string): ConfirmVerdict;

package/dist/flow/confirmParse.js

@@ -0,0 +1,170 @@
+const AFFIRM_TOKENS = new Set([
+    'yes',
+    'yeah',
+    'yep',
+    'yup',
+    'ya',
+    'sure',
+    'ok',
+    'okay',
+    'okey',
+    'k',
+    'confirm',
+    'confirmed',
+    'correct',
+    'right',
+    'proceed',
+    'do',
+    'done',
+    'yessir',
+    'affirmative',
+    'ow',
+    'ova',
+    'hari',
+    'hariyata',
+    'ehenam',
+    'aam',
+    'aama',
+    'sari',
+    'seri',
+]);
+const AFFIRM_PHRASES = [
+    'go ahead',
+    'do it',
+    'book it',
+    'place it',
+    'place the order',
+    'place my order',
+    'sounds good',
+    "that's right",
+    'thats right',
+    'that is correct',
+    'please do',
+    "let's do it",
+    'lets do it',
+    'go for it',
+    'confirm the order',
+    'yes please',
+];
+const AFFIRM_SCRIPT = ['ඔව්', 'හරි', 'හා', 'හරියට', 'ஆம்', 'சரி', 'ஆமா'];
+const DECLINE_TOKENS = new Set([
+    'no',
+    'nope',
+    'nah',
+    'na',
+    'not',
+    'dont',
+    "don't",
+    'stop',
+    'cancel',
+    'wait',
+    'hold',
+    'change',
+    'edit',
+    'incorrect',
+    'wrong',
+    'nevermind',
+    'never',
+    'naha',
+    'nae',
+    'epa',
+    'epaa',
+    'wenas',
+    'illa',
+    'illai',
+    'vendam',
+    'vendaam',
+    'vena',
+]);
+const DECLINE_PHRASES = [
+    'not yet',
+    'hold on',
+    'no thanks',
+    'no thank you',
+    "don't",
+    'do not',
+    'change it',
+    'change the',
+    'let me change',
+    'something else',
+    'go back',
+];
+const DECLINE_SCRIPT = ['නැහැ', 'නෑ', 'එපා', 'වෙනස්', 'இல்லை', 'வேண்டாம்', 'வேற'];
+const INTERROGATIVE_WORDS = [
+    'what',
+    'how',
+    'when',
+    'where',
+    'why',
+    'which',
+    'who',
+    'do you',
+    'can you',
+    'could you',
+    'is there',
+    'tell me',
+    'show me',
+];
+function normalize(raw) {
+    return raw.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+function stripTokenPunctuation(token) {
+    return token.replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, '');
+}
+function tokenize(normalized) {
+    return normalized
+        .split(/\s+/)
+        .map(stripTokenPunctuation)
+        .filter((token) => token.length > 0);
+}
+function hasDeclineToken(tokens) {
+    return tokens.some((token) => DECLINE_TOKENS.has(token));
+}
+function hasDeclinePhrase(normalized) {
+    return DECLINE_PHRASES.some((phrase) => normalized.includes(phrase));
+}
+function hasDeclineScript(normalized, raw) {
+    return DECLINE_SCRIPT.some((fragment) => normalized.includes(fragment) || raw.includes(fragment));
+}
+function hasDecline(normalized, tokens, raw) {
+    return hasDeclineToken(tokens) || hasDeclinePhrase(normalized) || hasDeclineScript(normalized, raw);
+}
+function hasInterrogative(normalized) {
+    if (normalized.includes('?')) {
+        return true;
+    }
+    return INTERROGATIVE_WORDS.some((word) => {
+        const pattern = new RegExp(`(?:^|\\s)${word.replace(/\s+/g, '\\s+')}(?:\\s|$|[?.!,])`, 'i');
+        return pattern.test(normalized);
+    });
+}
+function hasAffirmScript(normalized, raw) {
+    return AFFIRM_SCRIPT.some((fragment) => normalized.includes(fragment) || raw.includes(fragment));
+}
+function hasAffirmPhrase(normalized) {
+    return AFFIRM_PHRASES.some((phrase) => normalized.startsWith(phrase));
+}
+function hasAffirmToken(tokens) {
+    const head = tokens.slice(0, 3);
+    if (head.some((token) => AFFIRM_TOKENS.has(token))) {
+        return true;
+    }
+    return tokens.length === 1 && tokens[0] === 'y';
+}
+function hasAffirm(normalized, tokens, raw) {
+    return hasAffirmScript(normalized, raw) || hasAffirmPhrase(normalized) || hasAffirmToken(tokens);
+}
+export function parseConfirmation(raw) {
+    const normalized = normalize(raw);
+    const tokens = tokenize(normalized);
+    if (hasDecline(normalized, tokens, raw)) {
+        return 'decline';
+    }
+    if (hasInterrogative(normalized)) {
+        return 'ambiguous';
+    }
+    if (hasAffirm(normalized, tokens, raw)) {
+        return 'affirm';
+    }
+    return 'ambiguous';
+}

package/dist/flow/degradableErrors.d.ts

@@ -0,0 +1 @@
+export declare function isDegradableRuntimeError(error: unknown): boolean;

package/dist/flow/degradableErrors.js

@@ -0,0 +1,5 @@
+import { ToolValidationError } from '../tools/effect/schema.js';
+import { FlowOscillationError } from './runFlow.js';
+export function isDegradableRuntimeError(error) {
+    return error instanceof ToolValidationError || error instanceof FlowOscillationError;
+}

package/dist/flow/degrade.d.ts

@@ -0,0 +1,17 @@
+import type { ChannelDriver } from '../types/channel.js';
+import type { Flow, FlowNode } from '../types/flow.js';
+import type { RunContext } from '../types/run-context.js';
+import type { RunState } from '../runtime/durable/types.js';
+type DegradedFlowResult = {
+    kind: 'ended';
+    reason: string;
+} | {
+    kind: 'handoff';
+    to: string;
+    reason?: string;
+};
+export declare const SAFE_DEGRADED_MESSAGE = "I'm sorry \u2014 something went wrong on my side. Let me try to help you another way.";
+export declare function findEscalateNode(registry: Map<string, FlowNode>): FlowNode | undefined;
+export declare function appendSafeAssistantMessage(run: RunState, ctx: RunContext, text?: string): void;
+export declare function degradeFlowError(flow: Flow, registry: Map<string, FlowNode>, run: RunState, driver: ChannelDriver, ctx: RunContext, dispatchNode: (node: FlowNode, run: RunState, driver: ChannelDriver, ctx: RunContext) => Promise<import('./normalizeTransition.js').NormalizedTransition>): Promise<DegradedFlowResult>;
+export {};

package/dist/flow/degrade.js

@@ -0,0 +1,31 @@
+import { SuspendError } from '../runtime/durable/RunStore.js';
+export const SAFE_DEGRADED_MESSAGE = "I'm sorry — something went wrong on my side. Let me try to help you another way.";
+export function findEscalateNode(registry) {
+    return registry.get('escalate');
+}
+export function appendSafeAssistantMessage(run, ctx, text = SAFE_DEGRADED_MESSAGE) {
+    const message = { role: 'assistant', content: text };
+    run.messages = [...run.messages, message];
+    ctx.emit({ type: 'text-delta', text });
+}
+export async function degradeFlowError(flow, registry, run, driver, ctx, dispatchNode) {
+    appendSafeAssistantMessage(run, ctx);
+    const escalateNode = findEscalateNode(registry);
+    if (escalateNode) {
+        try {
+            const transition = await dispatchNode(escalateNode, run, driver, ctx);
+            if (transition.kind === 'escalate') {
+                await ctx.signal('__escalate', { meta: { reason: transition.reason } });
+                return { kind: 'handoff', to: 'human', reason: transition.reason };
+            }
+        }
+        catch (error) {
+            if (error instanceof SuspendError) {
+                throw error;
+            }
+            // Fall through to graceful end if the escalate node also fails.
+        }
+    }
+    ctx.emit({ type: 'flow-end', flow: flow.name, reason: 'error_degraded' });
+    return { kind: 'ended', reason: 'error_degraded' };
+}

package/dist/flow/runFlow.js

@@ -1,3 +1,4 @@
+import { parseConfirmation } from './confirmParse.js';
 import { hasPendingUserInput } from '../runtime/channels/inputBuffer.js';
 import { collectUntilComplete } from './collectUntilComplete.js';
 import { isActionNode, isCollectNode, isDecideNode, isReplyNode, } from './nodeKinds.js';
@@ -6,7 +7,10 @@ import { reduceTransition } from './reduceTransition.js';
 import { resolveReplyNode } from './nodeBuilders.js';
 import { runNodeVerify, VerifyBlockedError } from './verify.js';
 import { loadRecordedSteps } from '../runtime/durable/replay.js';
+import { SuspendError } from '../runtime/durable/RunStore.js';
+import { ToolApprovalDeniedError } from '../tools/effect/errors.js';
 import { emitInteractiveOnNodeEnter } from './emitInteractive.js';
+import { appendSafeAssistantMessage, degradeFlowError, findEscalateNode, } from './degrade.js';
 export class FlowOscillationError extends Error {
     constructor(from, to) {
         super(`Flow oscillation blocked: ${from} -> ${to}`);
@@ -43,6 +47,38 @@ function appendUserMessage(run, input) {
     const message = { role: 'user', content: input };
     run.messages = [...run.messages, message];
 }
+function latestUserText(run) {
+    for (let i = run.messages.length - 1; i >= 0; i -= 1) {
+        const message = run.messages[i];
+        if (message?.role === 'user' && typeof message.content === 'string') {
+            return message.content;
+        }
+    }
+    return '';
+}
+async function dispatchConfirmGate(node, run, driver, ctx) {
+    const gate = node.confirmGate;
+    if (!hasPendingUserInput(ctx.session) && ctx.turnInputConsumed) {
+        return { kind: 'stay' };
+    }
+    let input = '';
+    if (hasPendingUserInput(ctx.session)) {
+        const signal = await driver.awaitUser(ctx);
+        input = signal.input;
+        appendUserMessage(run, signal.input);
+    }
+    else {
+        input = latestUserText(run);
+    }
+    ctx.turnInputConsumed = true;
+    const verdict = parseConfirmation(input);
+    const branch = verdict === 'affirm'
+        ? gate.onConfirm
+        : verdict === 'decline'
+            ? gate.onDecline
+            : (gate.onAmbiguous ?? 'stay');
+    return normalizeTransition(branch);
+}
 function appendAssistantMessage(run, text) {
     if (!text.trim()) {
         return;
@@ -58,9 +94,15 @@ async function dispatchNode(node, run, driver, ctx) {
         return collectUntilComplete(node, run, driver, ctx);
     }
     if (isDecideNode(node)) {
+        if (node.confirmGate) {
+            return dispatchConfirmGate(node, run, driver, ctx);
+        }
         if (!driver.runStructured) {
             throw new Error('ChannelDriver.runStructured is required for decide nodes');
         }
+        if (!node.schema || !node.decide) {
+            throw new Error(`decide node "${node.id}" requires schema and decide`);
+        }
         // An interactive choice node (withChoices) reached when the turn's input was
         // already consumed by a prior node: its choices were presented on node-enter,
         // so wait for the user to actually pick rather than auto-deciding on stale
@@ -98,6 +140,12 @@ async function dispatchNode(node, run, driver, ctx) {
         if (turn.control?.type === 'end') {
             return { kind: 'end', reason: turn.control.reason };
         }
+        if (turn.control?.type === 'escalate') {
+            return { kind: 'escalate', reason: turn.control.reason };
+        }
+        if (turn.control?.type === 'recover') {
+            return { kind: 'end', reason: turn.control.reason ?? 'error_degraded' };
+        }
         if (node.next) {
             return normalizeTransition(await node.next(turn, run.state));
         }
@@ -123,7 +171,18 @@ export async function runFlow(flow, run, driver, ctx) {
     const edgeCounts = new Map();
     const maxOscillations = flow.maxOscillations ?? 2;
     for (;;) {
-        const transition = await dispatchNode(node, run, driver, ctx);
+        let transition;
+        try {
+            transition = await dispatchNode(node, run, driver, ctx);
+        }
+        catch (error) {
+            if (error instanceof SuspendError || error instanceof ToolApprovalDeniedError) {
+                throw error;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            ctx.emit({ type: 'error', error: message });
+            return degradeFlowError(flow, registry, run, driver, ctx, dispatchNode);
+        }
         if (transition.kind === 'end') {
             ctx.emit({ type: 'flow-end', flow: flow.name, reason: transition.reason });
             return { kind: 'ended', reason: transition.reason };
@@ -168,7 +227,26 @@ export async function runFlow(flow, run, driver, ctx) {
         const oscillation = bumpOscillation(edgeCounts, node.id, target.id);
         if (oscillation > maxOscillations) {
             ctx.emit({ type: 'error', error: `Flow oscillation blocked: ${node.id} -> ${target.id}` });
-            throw new FlowOscillationError(node.id, target.id);
+            const escalateNode = findEscalateNode(registry);
+            if (escalateNode) {
+                appendSafeAssistantMessage(run, ctx);
+                await reduceTransition({
+                    fromNodeId: node.id,
+                    toNode: escalateNode,
+                    run,
+                    flow,
+                    model: ctx.model,
+                    data: transition.data,
+                    emit: ctx.emit,
+                    abortSignal: ctx.abortSignal,
+                });
+                await ctx.runStore.putRunState(run);
+                node = escalateNode;
+                continue;
+            }
+            appendSafeAssistantMessage(run, ctx);
+            ctx.emit({ type: 'flow-end', flow: flow.name, reason: 'error_degraded' });
+            return { kind: 'ended', reason: 'error_degraded' };
         }
         await reduceTransition({
             fromNodeId: node.id,

package/dist/index.d.ts

@@ -65,13 +65,15 @@ export type { AuditConfig, AuditEntryBase, AuditEntryType, AuditListOptions, Aud
 export type { RealtimeAudioClient, RealtimeSessionConfig, RealtimeAudioConfig, RealtimeToolResponse, RealtimeEventMap, RealtimeSessionHandle, } from './realtime/index.js';
 export type { Hooks } from './types/hooks.js';
 export type { HarnessHooks } from './types/runtime.js';
-export { defineAgent, defineFlow, reply, collect, action, decide, } from './authoring/index.js';
+export { defineAgent, defineFlow, reply, collect, action, decide, confirmGate, } from './authoring/index.js';
 export { defineTool } from './types/effectTool.js';
 export { buildToolSet, toolToAiSdk, ToolApprovalDeniedError } from './tools/effect/index.js';
 export type { Tool as EffectTool } from './types/effectTool.js';
 export type { AgentRoute } from './types/processors.js';
 export type { AgentConfig, Instructions } from './types/agentConfig.js';
-export type { Flow, FlowNode, Transition, CollectNode, DecideNode } from './types/flow.js';
+export type { Flow, FlowNode, Transition, CollectNode, DecideNode, ConfirmGate } from './types/flow.js';
+export { parseConfirmation } from './flow/confirmParse.js';
+export type { ConfirmVerdict } from './flow/confirmParse.js';
 export type { Route } from './types/route.js';
 export type { TurnHandle } from './types/stream.js';
 export type { HarnessStreamPart } from './types/stream.js';

package/dist/index.js

@@ -36,7 +36,8 @@ export { handoffFilters, removeToolHistory, keepRecentMessages, removeKeys, comp
 export { DefaultToolExecutor, DefaultConversationState, DefaultConversationEventLog, DefaultAgentStateController, createFoundation, } from './foundation/index.js';
 export { CapabilityHost, TriageCapability, ExtractionCapability, HandoffCapability, GuardrailCapability, AutoRetrieveCapability, PassThroughRefinement, PassThroughValidation, toGeminiDeclarations, toAISDKTools, } from './capabilities/index.js';
 export { filterAuditEntries } from './audit/index.js';
-export { defineAgent, defineFlow, reply, collect, action, decide, } from './authoring/index.js';
+export { defineAgent, defineFlow, reply, collect, action, decide, confirmGate, } from './authoring/index.js';
 export { defineTool } from './types/effectTool.js';
 export { buildToolSet, toolToAiSdk, ToolApprovalDeniedError } from './tools/effect/index.js';
+export { parseConfirmation } from './flow/confirmParse.js';
 export { createRuntime, Runtime, } from './runtime/Runtime.js';

package/dist/runtime/Runtime.js

@@ -6,6 +6,8 @@ import { createRunContext } from './ctx.js';
 import { createEventBus, createTurnHandle } from '../events/TurnHandle.js';
 import { CoreToolExecutor } from '../tools/effect/index.js';
 import { hostLoop } from './hostLoop.js';
+import { isDegradableRuntimeError } from '../flow/degradableErrors.js';
+import { SAFE_DEGRADED_MESSAGE } from '../flow/degrade.js';
 import { openRun } from './openRun.js';
 import { closeRun } from './closeRun.js';
 import { SessionRunStore } from './durable/SessionRunStore.js';
@@ -163,7 +165,21 @@ export class Runtime {
             }
             catch (error) {
                 await this.hooks?.onError?.(runCtx, error);
-                throw error;
+                if (isDegradableRuntimeError(error)) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    emit({ type: 'error', error: message });
+                    emit({ type: 'text-delta', text: SAFE_DEGRADED_MESSAGE });
+                    runCtx.runState.messages = [
+                        ...runCtx.runState.messages,
+                        { role: 'assistant', content: SAFE_DEGRADED_MESSAGE },
+                    ];
+                    await runCtx.runStore.putRunState(runCtx.runState);
+                    terminalOutcome = 'unresolved';
+                    loopResult = { kind: 'ended', reason: 'error_degraded' };
+                }
+                else {
+                    throw error;
+                }
             }
             finally {
                 this.activeTurnAborts.delete(sessionId);

package/dist/runtime/channels/TextDriver.js

@@ -1,7 +1,7 @@
 import { streamText, generateObject } from 'ai';
 import { buildNodePrompt, resolveInstructions, composeSystem } from '../../flow/nodeBuilders.js';
 import { buildToolSet } from '../../tools/effect/index.js';
-import { classifyControl } from '../../flow/classifyControl.js';
+import { executeModelToolCall, toolResultMessage } from './executeModelTool.js';
 import { consumePendingUserInput } from './inputBuffer.js';
 import { runSilentExtraction } from './extractionTurn.js';
 import { applyPreTurnPolicies, applyPostTurnPolicies } from '../policies/agentTurn.js';
@@ -70,21 +70,7 @@ export class TextDriver {
                     args: call.input,
                     toolCallId: call.toolCallId,
                 });
-                const localTool = node.localTools?.[call.toolName];
-                const toolResult = await ctx.tool(call.toolName, call.input, {
-                    toolCallId: call.toolCallId,
-                    ...(localTool && {
-                        def: localTool,
-                        toolCtx: {
-                            session: ctx.session,
-                            runState: ctx.runState,
-                            tool: ctx.tool.bind(ctx),
-                            now: ctx.now.bind(ctx),
-                            uuid: ctx.uuid.bind(ctx),
-                            emit: ctx.emit.bind(ctx),
-                        },
-                    }),
-                });
+                const { result: toolResult, control, failed } = await executeModelToolCall(ctx, { toolName: call.toolName, input: call.input, toolCallId: call.toolCallId }, node.localTools);
                 out.toolResults.push({
                     name: call.toolName,
                     args: call.input,
@@ -96,27 +82,17 @@ export class TextDriver {
                     toolName: call.toolName,
                     args: call.input,
                     result: toolResult,
-                    success: true,
+                    success: !failed,
                     timestamp: Date.now(),
                 });
-                out.control ??= classifyControl(toolResult);
+                out.control ??= control;
                 ctx.emit({
                     type: 'tool-result',
                     toolName: call.toolName,
                     result: toolResult,
                     toolCallId: call.toolCallId,
                 });
-                messages.push({
-                    role: 'tool',
-                    content: [
-                        {
-                            type: 'tool-result',
-                            toolCallId: call.toolCallId,
-                            toolName: call.toolName,
-                            output: { type: 'json', value: toolResult },
-                        },
-                    ],
-                });
+                messages.push(toolResultMessage({ toolName: call.toolName, input: call.input, toolCallId: call.toolCallId }, toolResult));
             }
         }
         const postTurn = await applyPostTurnPolicies(ctx, draftText, toolCallsMade);

package/dist/runtime/channels/VoiceDriver.js

@@ -1,7 +1,7 @@
 import { generateObject } from 'ai';
 import { runSilentExtraction } from './extractionTurn.js';
 import { buildNodePrompt, resolveInstructions, composeSystem } from '../../flow/nodeBuilders.js';
-import { classifyControl } from '../../flow/classifyControl.js';
+import { executeModelToolCall } from './executeModelTool.js';
 import { applyPreTurnPolicies, applyPostTurnPolicies } from '../policies/agentTurn.js';
 import { resolveMaxSteps } from '../policies/limits.js';
 import { appendGatherBlocks, runGatherPhase } from '../grounding/index.js';
@@ -128,39 +128,20 @@ export class VoiceDriver {
             };
             const onToolCall = (id, name, args) => {
                 void (async () => {
-                    try {
-                        ctx.emit({ type: 'tool-call', toolName: name, args, toolCallId: id });
-                        const localTool = localTools?.[name];
-                        const toolResult = await ctx.tool(name, args, {
-                            toolCallId: id,
-                            ...(localTool && {
-                                def: localTool,
-                                toolCtx: {
-                                    session: ctx.session,
-                                    runState: ctx.runState,
-                                    tool: ctx.tool.bind(ctx),
-                                    now: ctx.now.bind(ctx),
-                                    uuid: ctx.uuid.bind(ctx),
-                                    emit: ctx.emit.bind(ctx),
-                                },
-                            }),
-                        });
-                        out.toolResults.push({ name, args, result: toolResult, toolCallId: id });
-                        toolCallsMade.push({
-                            toolCallId: id,
-                            toolName: name,
-                            args,
-                            result: toolResult,
-                            success: true,
-                            timestamp: Date.now(),
-                        });
-                        out.control ??= classifyControl(toolResult);
-                        ctx.emit({ type: 'tool-result', toolName: name, result: toolResult, toolCallId: id });
-                        this.client.sendToolResponse([{ id, name, output: toolResult }]);
-                    }
-                    catch (error) {
-                        fail(error);
-                    }
+                    ctx.emit({ type: 'tool-call', toolName: name, args, toolCallId: id });
+                    const { result: toolResult, control, failed } = await executeModelToolCall(ctx, { toolName: name, input: args, toolCallId: id }, localTools);
+                    out.toolResults.push({ name, args, result: toolResult, toolCallId: id });
+                    toolCallsMade.push({
+                        toolCallId: id,
+                        toolName: name,
+                        args,
+                        result: toolResult,
+                        success: !failed,
+                        timestamp: Date.now(),
+                    });
+                    out.control ??= control;
+                    ctx.emit({ type: 'tool-result', toolName: name, result: toolResult, toolCallId: id });
+                    this.client.sendToolResponse([{ id, name, output: toolResult }]);
                 })();
             };
             const onTurnComplete = () => {

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

@@ -0,0 +1,29 @@
+import type { JSONValue } from 'ai';
+import type { TurnControl } from '../../types/channel.js';
+import type { RunContext } from '../../types/run-context.js';
+import type { AnyTool } from '../../types/effectTool.js';
+export interface ModelToolCall {
+    toolName: string;
+    input: unknown;
+    toolCallId: string;
+}
+export interface ModelToolCallOutcome {
+    result: unknown;
+    control?: TurnControl;
+    failed: boolean;
+}
+export declare function executeModelToolCall(ctx: RunContext, call: ModelToolCall, localTools?: Record<string, AnyTool>): Promise<ModelToolCallOutcome>;
+export declare function toolResultMessage(call: ModelToolCall, result: unknown): {
+    role: 'tool';
+    content: [
+        {
+            type: 'tool-result';
+            toolCallId: string;
+            toolName: string;
+            output: {
+                type: 'json';
+                value: JSONValue;
+            };
+        }
+    ];
+};

package/dist/runtime/channels/executeModelTool.js

@@ -0,0 +1,40 @@
+import { classifyControl } from '../../flow/classifyControl.js';
+import { toolErrorResult } from '../../tools/controlResults.js';
+export async function executeModelToolCall(ctx, call, localTools) {
+    try {
+        const localTool = localTools?.[call.toolName];
+        const toolResult = await ctx.tool(call.toolName, call.input, {
+            toolCallId: call.toolCallId,
+            ...(localTool && {
+                def: localTool,
+                toolCtx: {
+                    session: ctx.session,
+                    runState: ctx.runState,
+                    tool: ctx.tool.bind(ctx),
+                    now: ctx.now.bind(ctx),
+                    uuid: ctx.uuid.bind(ctx),
+                    emit: ctx.emit.bind(ctx),
+                },
+            }),
+        });
+        return { result: toolResult, control: classifyControl(toolResult), failed: false };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.emit({ type: 'error', error: message });
+        return { result: toolErrorResult(error), failed: true };
+    }
+}
+export function toolResultMessage(call, result) {
+    return {
+        role: 'tool',
+        content: [
+            {
+                type: 'tool-result',
+                toolCallId: call.toolCallId,
+                toolName: call.toolName,
+                output: { type: 'json', value: result },
+            },
+        ],
+    };
+}

package/dist/runtime/channels/extractionTurn.js

@@ -1,4 +1,5 @@
 import { streamText } from 'ai';
+import { executeModelToolCall, toolResultMessage } from './executeModelTool.js';
 import { buildToolSet } from '../../tools/effect/index.js';
 import { buildNodePrompt, composeSystem } from '../../flow/nodeBuilders.js';
 /**
@@ -37,38 +38,14 @@ export async function runSilentExtraction(node, ctx, model, maxSteps) {
         }
         const toolCalls = await result.toolCalls;
         for (const call of toolCalls) {
-            const localTool = node.localTools?.[call.toolName];
-            const toolResult = await ctx.tool(call.toolName, call.input, {
-                toolCallId: call.toolCallId,
-                ...(localTool && {
-                    def: localTool,
-                    toolCtx: {
-                        session: ctx.session,
-                        runState: ctx.runState,
-                        tool: ctx.tool.bind(ctx),
-                        now: ctx.now.bind(ctx),
-                        uuid: ctx.uuid.bind(ctx),
-                        emit: ctx.emit.bind(ctx),
-                    },
-                }),
-            });
+            const { result: toolResult } = await executeModelToolCall(ctx, { toolName: call.toolName, input: call.input, toolCallId: call.toolCallId }, node.localTools);
             out.toolResults.push({
                 name: call.toolName,
                 args: call.input,
                 result: toolResult,
                 toolCallId: call.toolCallId,
             });
-            messages.push({
-                role: 'tool',
-                content: [
-                    {
-                        type: 'tool-result',
-                        toolCallId: call.toolCallId,
-                        toolName: call.toolName,
-                        output: { type: 'json', value: toolResult },
-                    },
-                ],
-            });
+            messages.push(toolResultMessage({ toolName: call.toolName, input: call.input, toolCallId: call.toolCallId }, toolResult));
         }
     }
     return out;

package/dist/runtime/hostLoop.js

@@ -87,6 +87,13 @@ async function runFreeConversation(agent, run, driver, ctx) {
     if (turn.control?.type === 'end') {
         return { kind: 'ended', reason: turn.control.reason };
     }
+    if (turn.control?.type === 'escalate') {
+        ctx.emit({ type: 'handoff', targetAgent: 'human', reason: turn.control.reason });
+        return { kind: 'handoff', to: 'human', reason: turn.control.reason };
+    }
+    if (turn.control?.type === 'recover') {
+        return { kind: 'ended', reason: turn.control.reason ?? 'error_degraded' };
+    }
     return { kind: 'turnComplete' };
 }
 function findFlowByName(agent, flowName) {

package/dist/tools/controlResults.d.ts

@@ -0,0 +1,15 @@
+export interface EscalateResult {
+    __escalate: true;
+    reason: string;
+}
+export declare function isEscalateResult(result: unknown): result is EscalateResult;
+export interface RecoverResult {
+    __recover: true;
+    reason?: string;
+}
+export declare function isRecoverResult(result: unknown): result is RecoverResult;
+/** Standard tool-result shape when `ctx.tool` fails in a model-initiated call. */
+export declare function toolErrorResult(error: unknown): {
+    error: true;
+    message: string;
+};

package/dist/tools/controlResults.js

@@ -0,0 +1,18 @@
+export function isEscalateResult(result) {
+    return (typeof result === 'object' &&
+        result !== null &&
+        '__escalate' in result &&
+        result.__escalate === true &&
+        typeof result.reason === 'string');
+}
+export function isRecoverResult(result) {
+    return (typeof result === 'object' &&
+        result !== null &&
+        '__recover' in result &&
+        result.__recover === true);
+}
+/** Standard tool-result shape when `ctx.tool` fails in a model-initiated call. */
+export function toolErrorResult(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { error: true, message };
+}

package/dist/types/channel.d.ts

@@ -47,5 +47,11 @@ export type TurnControl = {
 } | {
     type: 'end';
     reason: string;
+} | {
+    type: 'escalate';
+    reason: string;
+} | {
+    type: 'recover';
+    reason?: string;
 };
 export {};

package/dist/types/flow.d.ts

@@ -61,16 +61,30 @@ export interface ActionNode {
     outputSchema?: StandardSchemaV1;
     run: (state: FlowState, ctx: ActionContext) => Transition | Promise<Transition>;
 }
+export interface ConfirmGate {
+    onConfirm: Transition;
+    onDecline: Transition;
+    onAmbiguous?: Transition;
+}
 export interface DecideNode {
     kind: 'decide';
     id: string;
     instructions: Instructions;
-    schema: StandardSchemaV1;
+    schema?: StandardSchemaV1;
     choices?: ChoiceOption[];
-    decide: (data: unknown, state: FlowState) => Transition | Promise<Transition>;
+    confirmGate?: ConfirmGate;
+    decide?: (data: unknown, state: FlowState) => Transition | Promise<Transition>;
 }
 export declare function reply(node: Omit<ReplyNode, 'kind'>): ReplyNode;
 export declare function collect(node: Omit<CollectNode, 'kind'>): CollectNode;
 export declare function action(node: Omit<ActionNode, 'kind'>): ActionNode;
-export declare function decide(node: Omit<DecideNode, 'kind'>): DecideNode;
+export declare function decide(node: Omit<DecideNode, 'kind' | 'confirmGate'> & Required<Pick<DecideNode, 'schema' | 'decide'>>): DecideNode;
+export declare function confirmGate(node: {
+    id: string;
+    instructions: Instructions;
+    onConfirm: Transition;
+    onDecline: Transition;
+    onAmbiguous?: Transition;
+    choices?: ChoiceOption[];
+}): DecideNode;
 export declare function defineFlow(flow: Flow): Flow;

package/dist/types/flow.js

@@ -10,6 +10,19 @@ export function action(node) {
 export function decide(node) {
     return { kind: 'decide', ...node };
 }
+export function confirmGate(node) {
+    return {
+        kind: 'decide',
+        id: node.id,
+        instructions: node.instructions,
+        choices: node.choices,
+        confirmGate: {
+            onConfirm: node.onConfirm,
+            onDecline: node.onDecline,
+            onAmbiguous: node.onAmbiguous,
+        },
+    };
+}
 export function defineFlow(flow) {
     return flow;
 }

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/kuralle-core"
   },
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "A framework for structured conversational AI agents",
   "publishConfig": {
     "access": "public"
@@ -97,7 +97,7 @@
     "dotenv": "^16.4.0",
     "typescript": "^5.3.0",
     "zod": "^3.23.0",
-    "@kuralle-agents/realtime-audio": "0.3.7"
+    "@kuralle-agents/realtime-audio": "0.3.9"
   },
   "dependencies": {
     "chrono-node": "^2.6.0",