@kuralle-agents/core 0.3.7 → 0.3.8

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/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

@@ -6,7 +6,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}`);
@@ -98,6 +101,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 +132,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 +188,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/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/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.8",
   "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.8"
   },
   "dependencies": {
     "chrono-node": "^2.6.0",