@kuralle-agents/core 0.3.14 → 0.3.16

package/dist/flow/choiceMatch.d.ts

@@ -0,0 +1,17 @@
+import type { ModelMessage } from 'ai';
+import { z } from 'zod';
+import type { DecideNode } from '../types/flow.js';
+import type { ChoiceOption } from '../types/selection.js';
+import type { RunContext } from '../types/run-context.js';
+/** Reserved enum member: model declines to pick a listed choice (→ author stay/unmatched). */
+export declare const CHOICE_NONE = "__none";
+export declare function isConstrainedChoiceEnumSchema(schema: unknown): boolean;
+export declare function isChoiceFieldSchema(schema: unknown): schema is z.ZodObject<{
+    choice: z.ZodString;
+}>;
+export declare function buildChoiceEnumSchema(choices: ChoiceOption[]): z.ZodObject<{
+    choice: z.ZodEnum<[string, ...string[]]>;
+}>;
+export declare function latestUserMessageText(messages: ModelMessage[]): string | undefined;
+export declare function matchChoiceFromInput(input: string, choices: ChoiceOption[]): string | undefined;
+export declare function resolveStructuredDecide(node: DecideNode, ctx: RunContext, system: string): Promise<unknown>;

package/dist/flow/choiceMatch.js

@@ -0,0 +1,119 @@
+import { generateObject } from 'ai';
+import { z } from 'zod';
+/** Reserved enum member: model declines to pick a listed choice (→ author stay/unmatched). */
+export const CHOICE_NONE = '__none';
+function normalize(raw) {
+    return raw.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+function keywordTerms(text) {
+    return normalize(text)
+        .split(/[^a-z0-9]+/)
+        .filter((term) => term.length > 4);
+}
+export function isConstrainedChoiceEnumSchema(schema) {
+    if (!(schema instanceof z.ZodObject)) {
+        return false;
+    }
+    return schema.shape.choice instanceof z.ZodEnum;
+}
+export function isChoiceFieldSchema(schema) {
+    if (!(schema instanceof z.ZodObject)) {
+        return false;
+    }
+    const keys = Object.keys(schema.shape);
+    if (keys.length !== 1 || keys[0] !== 'choice') {
+        return false;
+    }
+    return schema.shape.choice instanceof z.ZodString;
+}
+export function buildChoiceEnumSchema(choices) {
+    const ids = choices.map((c) => c.id);
+    if (ids.length === 0) {
+        return z.object({ choice: z.enum([CHOICE_NONE]) });
+    }
+    const members = [ids[0], ...ids.slice(1), CHOICE_NONE];
+    return z.object({ choice: z.enum(members) });
+}
+export function latestUserMessageText(messages) {
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const message = messages[i];
+        if (message?.role === 'user') {
+            if (typeof message.content === 'string') {
+                return message.content;
+            }
+            if (Array.isArray(message.content)) {
+                const text = message.content
+                    .filter((part) => part.type === 'text')
+                    .map((part) => part.text)
+                    .join('');
+                if (text) {
+                    return text;
+                }
+            }
+        }
+    }
+    return undefined;
+}
+export function matchChoiceFromInput(input, choices) {
+    const normalized = normalize(input);
+    if (!normalized) {
+        return undefined;
+    }
+    const idMatches = choices.filter((c) => normalize(c.id) === normalized).map((c) => c.id);
+    if (idMatches.length === 1) {
+        return idMatches[0];
+    }
+    if (idMatches.length > 1) {
+        return undefined;
+    }
+    const labelMatches = choices.filter((c) => normalize(c.label) === normalized).map((c) => c.id);
+    if (labelMatches.length === 1) {
+        return labelMatches[0];
+    }
+    if (labelMatches.length > 1) {
+        return undefined;
+    }
+    const keywordMatches = [];
+    for (const choice of choices) {
+        const terms = keywordTerms(choice.label);
+        if (terms.length > 0 && terms.some((term) => normalized.includes(term))) {
+            keywordMatches.push(choice.id);
+        }
+    }
+    if (keywordMatches.length === 1) {
+        return keywordMatches[0];
+    }
+    return undefined;
+}
+export async function resolveStructuredDecide(node, ctx, system) {
+    const schema = node.schema;
+    const useConstrainedChoices = (node.choices?.length ?? 0) > 0 && isChoiceFieldSchema(schema);
+    if (!useConstrainedChoices) {
+        const { object } = await generateObject({
+            model: ctx.controlModel,
+            schema,
+            system,
+            messages: ctx.runState.messages,
+            temperature: 0,
+            abortSignal: ctx.abortSignal,
+        });
+        return object;
+    }
+    const input = latestUserMessageText(ctx.runState.messages);
+    if (input) {
+        const matched = matchChoiceFromInput(input, node.choices);
+        if (matched) {
+            return { choice: matched };
+        }
+    }
+    const choiceSchema = buildChoiceEnumSchema(node.choices);
+    const { object } = await generateObject({
+        model: ctx.controlModel,
+        schema: choiceSchema,
+        system,
+        messages: ctx.runState.messages,
+        temperature: 0,
+        abortSignal: ctx.abortSignal,
+    });
+    return object;
+}

package/dist/flow/collectUntilComplete.js

@@ -1,6 +1,6 @@
 import { hasPendingUserInput } from '../runtime/channels/inputBuffer.js';
 import { resolveCollectExtractionNode } from './nodeBuilders.js';
-import { computeMissingFields, createExtractionSubmitTool, getCollectData, incrementCollectTurns, mergeTurnExtraction, projectCollectData, schemaSatisfied, } from './extraction.js';
+import { computeMissingFields, createExtractionSubmitTool, getCollectData, incrementCollectTurns, emitExtractionTelemetry, mergeTurnExtraction, projectCollectData, schemaSatisfied, } from './extraction.js';
 import { normalizeTransition } from './normalizeTransition.js';
 function appendAssistantMessage(run, text) {
     if (!text.trim()) {
@@ -57,7 +57,7 @@ export async function collectUntilComplete(node, run, driver, ctx) {
         const turn = await (driver.runExtraction
             ? driver.runExtraction(resolved, ctx)
             : driver.runAgentTurn(resolved, ctx));
-        mergeExtractionFromTurn(node, run, turn);
+        mergeExtractionFromTurn(node, run, turn, ctx);
     }
 }
 function humanizeField(field) {
@@ -92,8 +92,11 @@ function emitCollectAsk(node, run, ctx) {
     ctx.emit({ type: 'turn-end' });
     appendAssistantMessage(run, text);
 }
-function mergeExtractionFromTurn(node, run, turn) {
-    mergeTurnExtraction(node, run.state, turn.toolResults.map((record) => ({ name: record.name, result: record.result })));
+function mergeExtractionFromTurn(node, run, turn, ctx) {
+    const { merged, incoming } = mergeTurnExtraction(node, run.state, turn.toolResults.map((record) => ({ name: record.name, result: record.result })));
+    if (merged && incoming) {
+        emitExtractionTelemetry(node, run.state, incoming, ctx.emit);
+    }
 }
 function peekLatestUserMessage(run) {
     for (let i = run.messages.length - 1; i >= 0; i -= 1) {

package/dist/flow/extraction.d.ts

@@ -1,5 +1,6 @@
 import type { CollectNode, FlowState } from '../types/flow.js';
 import type { Tool } from '../types/effectTool.js';
+import type { HarnessStreamPart } from '../types/stream.js';
 export declare function getCollectData(state: FlowState, nodeId: string): Record<string, unknown>;
 export declare function incrementCollectTurns(state: FlowState, nodeId: string): number;
 export declare function computeMissingFields(node: CollectNode, data: Record<string, unknown>): string[];
@@ -10,7 +11,12 @@ export declare function createExtractionSubmitTool(node: CollectNode, missingFie
     userMessage?: string;
     retryNudge?: boolean;
 }): Tool;
+export interface MergeTurnExtractionResult {
+    merged: boolean;
+    incoming?: Record<string, unknown>;
+}
 export declare function mergeTurnExtraction(node: CollectNode, state: FlowState, toolResults: Array<{
     name: string;
     result: unknown;
-}>): boolean;
+}>): MergeTurnExtractionResult;
+export declare function emitExtractionTelemetry(node: CollectNode, state: FlowState, incoming: Record<string, unknown>, emit: (part: HarnessStreamPart) => void): void;

package/dist/flow/extraction.js

@@ -95,6 +95,7 @@ function submitToolName(nodeId) {
 export function mergeTurnExtraction(node, state, toolResults) {
     const submitName = submitToolName(node.id);
     let merged = false;
+    let lastIncoming;
     const current = getCollectData(state, node.id);
     for (const record of toolResults) {
         if (record.name !== submitName) {
@@ -108,8 +109,33 @@ export function mergeTurnExtraction(node, state, toolResults) {
         setCollectData(state, node.id, next);
         Object.assign(current, next);
         merged = true;
+        lastIncoming = incoming;
     }
-    return merged;
+    return merged ? { merged: true, incoming: lastIncoming } : { merged: false };
+}
+export function emitExtractionTelemetry(node, state, incoming, emit) {
+    const fieldsAccepted = [];
+    const fieldsRejected = [];
+    for (const [key, value] of Object.entries(incoming)) {
+        if (fieldPopulated(value)) {
+            fieldsAccepted.push(key);
+        }
+        else {
+            fieldsRejected.push(key);
+        }
+    }
+    emit({
+        type: 'custom',
+        name: 'flow.extraction.submission',
+        data: { node: node.id, fieldsAccepted, fieldsRejected },
+    });
+    const collected = getCollectData(state, node.id);
+    const missing = computeMissingFields(node, collected);
+    emit({
+        type: 'custom',
+        name: 'flow.extraction.update',
+        data: { nodeId: node.id, collected, missing },
+    });
 }
 function fieldPopulated(value) {
     if (value === null || value === undefined) {

package/dist/index.d.ts

@@ -67,7 +67,7 @@ export type { Hooks } from './types/hooks.js';
 export type { HarnessHooks } from './types/runtime.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 { buildToolSet, toolToAiSdk, ToolApprovalDeniedError, ToolTimeoutError, } 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';

package/dist/index.js

@@ -38,6 +38,6 @@ export { CapabilityHost, TriageCapability, ExtractionCapability, HandoffCapabili
 export { filterAuditEntries } from './audit/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 { buildToolSet, toolToAiSdk, ToolApprovalDeniedError, ToolTimeoutError, } from './tools/effect/index.js';
 export { parseConfirmation } from './flow/confirmParse.js';
 export { createRuntime, Runtime, } from './runtime/Runtime.js';

package/dist/runtime/Runtime.js

@@ -74,6 +74,7 @@ export class Runtime {
                 tools: effectTools,
                 enforcer: policies.enforcer,
                 agentId: opened.agent.id,
+                onInterim: (message) => emit({ type: 'text-delta', text: message }),
             });
             const steps = await loadRecordedSteps(opened.runStore, opened.runState.runId);
             const freshRunState = (await opened.runStore.getRunState(opened.runState.runId)) ?? opened.runState;

package/dist/runtime/channels/TextDriver.js

@@ -1,4 +1,4 @@
-import { streamText, generateObject } from 'ai';
+import { streamText } from 'ai';
 import { buildNodePrompt, resolveInstructions, composeSystem } from '../../flow/nodeBuilders.js';
 import { buildToolSet } from '../../tools/effect/index.js';
 import { executeModelToolCall, toolResultMessage } from './executeModelTool.js';
@@ -8,6 +8,7 @@ import { applyPreTurnPolicies, applyPostTurnPolicies } from '../policies/agentTu
 import { resolveMaxSteps } from '../policies/limits.js';
 import { appendGatherBlocks, resolveNodeGatherScope, runGatherPhase } from '../grounding/index.js';
 import { isFlowTransitionControlTool } from '../../flow/flowControlTools.js';
+import { resolveStructuredDecide } from '../../flow/choiceMatch.js';
 export class TextDriver {
     toolDefs;
     maxSteps;
@@ -113,26 +114,8 @@ export class TextDriver {
         return runSilentExtraction(node, ctx, ctx.controlModel, resolveMaxSteps(ctx.limits, this.maxSteps));
     }
     async runStructured(node, ctx) {
-        const base = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state);
-        const schema = node.schema;
-        // When the node offers choices (e.g. via withChoices), constrain the model
-        // to return exactly one option id. Otherwise an unconstrained string schema
-        // lets the model reply with free-form prose that `decide()` can't match,
-        // stalling the flow at every interactive node.
-        const system = node.choices?.length
-            ? `${base}\n\nYou MUST pick exactly ONE option by its id. Valid ids: ${node.choices
-                .map((c) => c.id)
-                .join(', ')}. Respond with only the chosen id, nothing else.`
-            : base;
-        const { object } = await generateObject({
-            model: ctx.controlModel,
-            schema,
-            system,
-            messages: ctx.runState.messages,
-            temperature: 0,
-            abortSignal: ctx.abortSignal,
-        });
-        return object;
+        const system = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state);
+        return resolveStructuredDecide(node, ctx, system);
     }
     async awaitUser(ctx) {
         const input = consumePendingUserInput(ctx.session);

package/dist/runtime/channels/VoiceDriver.js

@@ -1,5 +1,5 @@
-import { generateObject } from 'ai';
 import { runSilentExtraction } from './extractionTurn.js';
+import { resolveStructuredDecide } from '../../flow/choiceMatch.js';
 import { buildNodePrompt, resolveInstructions, composeSystem } from '../../flow/nodeBuilders.js';
 import { executeModelToolCall } from './executeModelTool.js';
 import { applyPreTurnPolicies, applyPostTurnPolicies } from '../policies/agentTurn.js';
@@ -65,24 +65,8 @@ export class VoiceDriver {
         return out;
     }
     async runStructured(node, ctx) {
-        const base = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state);
-        const schema = node.schema;
-        // Parity with TextDriver: when the node offers choices, constrain the model
-        // to a single option id so an unconstrained string can't stall the decide.
-        const system = node.choices?.length
-            ? `${base}\n\nYou MUST pick exactly ONE option by its id. Valid ids: ${node.choices
-                .map((c) => c.id)
-                .join(', ')}. Respond with only the chosen id, nothing else.`
-            : base;
-        const { object } = await generateObject({
-            model: ctx.controlModel,
-            schema,
-            system,
-            messages: ctx.runState.messages,
-            temperature: 0,
-            abortSignal: ctx.abortSignal,
-        });
-        return object;
+        const system = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state);
+        return resolveStructuredDecide(node, ctx, system);
     }
     // Non-speaking collect extraction: uses the shared text-model extraction path
     // rather than the realtime audio provider, so the agent never SPEAKS during

package/dist/runtime/select.js

@@ -24,6 +24,10 @@ export async function selectHostTarget(options) {
     if (availableFlows.length === 1 && agentRoutes.length === 0) {
         return { kind: 'enterFlow', flow: availableFlows[0] };
     }
+    const deterministic = deterministicRouteMatch(latestUser, routes, availableFlows);
+    if (deterministic) {
+        return deterministic;
+    }
     const flowLines = availableFlows
         .map((flow) => `- flow "${flow.name}": ${flow.description}`)
         .join('\n');
@@ -72,6 +76,32 @@ export async function selectHostTarget(options) {
     }
     return keywordRouteFallback(latestUser, routes, availableFlows);
 }
+function deterministicRouteMatch(message, routes, availableFlows) {
+    const lower = message.toLowerCase();
+    const hits = [];
+    for (const route of routes) {
+        const terms = route.when
+            .toLowerCase()
+            .split(/[^a-z0-9]+/)
+            .filter((term) => term.length > 3);
+        if (!terms.some((term) => lower.includes(term))) {
+            continue;
+        }
+        if (route.flow) {
+            const flow = availableFlows.find((candidate) => candidate.name === route.flow);
+            if (flow) {
+                hits.push({ kind: 'enterFlow', flow });
+            }
+        }
+        else if (route.agent) {
+            hits.push({ kind: 'route', agentId: route.agent });
+        }
+    }
+    if (hits.length === 1) {
+        return hits[0];
+    }
+    return undefined;
+}
 function keywordRouteFallback(message, routes, availableFlows) {
     const lower = message.toLowerCase();
     for (const route of routes) {

package/dist/tools/Tool.d.ts

@@ -25,10 +25,12 @@ export interface ToolDefinition<TInput = unknown, TResult = unknown> {
     errorPolicy?: 'abort' | 'warn' | 'continue';
 }
 export interface ToolWithFiller<TInput = unknown, TResult = unknown> extends ToolDefinition<TInput, TResult> {
-    /** Optional filler message to display while tool is executing */
+    /** @deprecated Use `interim` on effect tools (`defineTool`). */
     filler?: string;
-    /** Optional estimated duration in ms for showing filler */
+    /** @deprecated Use `interimAfterMs` on effect tools (`defineTool`). */
     estimatedDurationMs?: number;
+    interim?: string;
+    interimAfterMs?: number;
 }
 type SchemaToolDefinition<TSchema extends ZodTypeAny, TResult = unknown> = {
     description: string;
@@ -38,8 +40,12 @@ type SchemaToolDefinition<TSchema extends ZodTypeAny, TResult = unknown> = {
     errorPolicy?: 'abort' | 'warn' | 'continue';
 };
 type SchemaToolWithFiller<TSchema extends ZodTypeAny, TResult = unknown> = SchemaToolDefinition<TSchema, TResult> & {
+    /** @deprecated Use `interim`. */
     filler?: string;
+    /** @deprecated Use `interimAfterMs`. */
     estimatedDurationMs?: number;
+    interim?: string;
+    interimAfterMs?: number;
 };
 export declare function createTool<TSchema extends ZodTypeAny, TResult = unknown>(definition: SchemaToolDefinition<TSchema, TResult>): Tool<z.infer<TSchema>, TResult> & ToolDefinition<z.infer<TSchema>, TResult>;
 export declare function createToolWithFiller<TSchema extends ZodTypeAny, TResult = unknown>(definition: SchemaToolWithFiller<TSchema, TResult>): Tool<z.infer<TSchema>, TResult> & ToolWithFiller<z.infer<TSchema>, TResult>;

package/dist/tools/Tool.js

@@ -11,9 +11,18 @@ export function createToolWithFiller(definition) {
     // @ts-expect-error — same deferred-generic limitation as createTool (see above).
     const t = aiTool({ description, inputSchema: zodSchema(inputSchema), execute });
     const extended = Object.assign(t, definition);
-    if (definition.filler)
-        extended.filler = definition.filler;
-    if (definition.estimatedDurationMs)
-        extended.estimatedDurationMs = definition.estimatedDurationMs;
+    const interim = definition.interim ?? definition.filler;
+    const interimAfterMs = definition.interimAfterMs ?? definition.estimatedDurationMs;
+    if (interim) {
+        extended.interim = interim;
+        if (definition.filler)
+            extended.filler = definition.filler;
+    }
+    if (interimAfterMs != null) {
+        extended.interimAfterMs = interimAfterMs;
+        if (definition.estimatedDurationMs != null) {
+            extended.estimatedDurationMs = definition.estimatedDurationMs;
+        }
+    }
     return extended;
 }

package/dist/tools/effect/ToolExecutor.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { debug } from '../../debug.js';
 import { cancelledPlaceholder, inProgressPlaceholder, PairingTracker, } from './pairing.js';
+import { ToolTimeoutError } from './errors.js';
 import { ToolValidationError, validateAndSanitize, validateOutput } from './schema.js';
 export class CoreToolExecutor {
     tools;
@@ -93,10 +94,13 @@ export class CoreToolExecutor {
             }
         }
         let interimTimer;
+        let timeoutTimer;
         let interimSent = false;
         const onAbort = () => {
             if (interimTimer)
                 clearTimeout(interimTimer);
+            if (timeoutTimer)
+                clearTimeout(timeoutTimer);
         };
         abortSignal?.addEventListener('abort', onAbort, { once: true });
         try {
@@ -129,11 +133,27 @@ export class CoreToolExecutor {
                     abortSignal.addEventListener('abort', () => reject(new DOMException('Aborted', 'AbortError')), { once: true });
                 })
                 : null;
-            const rawResult = abortPromise
-                ? await Promise.race([executePromise, abortPromise])
-                : await executePromise;
+            const timeoutMs = def.timeoutMs;
+            const timeoutPromise = timeoutMs != null && timeoutMs > 0
+                ? new Promise((_, reject) => {
+                    timeoutTimer = setTimeout(() => {
+                        reject(new ToolTimeoutError(name, timeoutMs));
+                    }, timeoutMs);
+                    if (typeof timeoutTimer === 'object' && 'unref' in timeoutTimer) {
+                        timeoutTimer.unref();
+                    }
+                })
+                : null;
+            const racers = [executePromise];
+            if (abortPromise)
+                racers.push(abortPromise);
+            if (timeoutPromise)
+                racers.push(timeoutPromise);
+            const rawResult = racers.length > 1 ? await Promise.race(racers) : await executePromise;
             if (interimTimer)
                 clearTimeout(interimTimer);
+            if (timeoutTimer)
+                clearTimeout(timeoutTimer);
             const validated = await validateOutput(def.output, rawResult, name);
             callRecord.result = validated;
             callRecord.durationMs = Date.now() - callRecord.timestamp;
@@ -149,6 +169,8 @@ export class CoreToolExecutor {
         catch (error) {
             if (interimTimer)
                 clearTimeout(interimTimer);
+            if (timeoutTimer)
+                clearTimeout(timeoutTimer);
             if (error instanceof DOMException && error.name === 'AbortError') {
                 const placeholder = cancelledPlaceholder(requestId, name);
                 callRecord.success = false;

package/dist/tools/effect/defineTool.d.ts

@@ -13,6 +13,11 @@ export declare function defineTool<S extends z.ZodTypeAny | StandardSchemaV1 | u
     interruptible?: boolean;
     interim?: string;
     interimAfterMs?: number;
+    /** @deprecated Use `interim`. */
+    filler?: string;
+    /** @deprecated Use `interimAfterMs`. */
+    estimatedDurationMs?: number;
+    timeoutMs?: number;
     execute: (args: InferToolInput<S>, ctx?: ToolContext) => Promise<R> | AsyncIterable<R>;
 }): Tool<InferToolInput<S>, R>;
 export declare function toolToAiSdk<TInput = unknown, TOutput = unknown>(def: Tool<TInput, TOutput>): AiTool<TInput, TOutput>;

package/dist/tools/effect/defineTool.js

@@ -7,8 +7,9 @@ export function defineTool(config) {
         output: config.output,
         needsApproval: config.needsApproval,
         interruptible: config.interruptible,
-        interim: config.interim,
-        interimAfterMs: config.interimAfterMs,
+        interim: config.interim ?? config.filler,
+        interimAfterMs: config.interimAfterMs ?? config.estimatedDurationMs,
+        timeoutMs: config.timeoutMs,
         execute: config.execute,
     };
 }

package/dist/tools/effect/errors.d.ts

@@ -3,6 +3,11 @@
  * by a human (the `__approval` signal resolves with `approved: false`). Catch it
  * inside the calling flow `action` node to route gracefully (e.g. escalate or end).
  */
+export declare class ToolTimeoutError extends Error {
+    readonly toolName: string;
+    readonly timeoutMs: number;
+    constructor(toolName: string, timeoutMs: number);
+}
 export declare class ToolApprovalDeniedError extends Error {
     readonly toolName: string;
     readonly by?: string;

package/dist/tools/effect/errors.js

@@ -3,6 +3,16 @@
  * by a human (the `__approval` signal resolves with `approved: false`). Catch it
  * inside the calling flow `action` node to route gracefully (e.g. escalate or end).
  */
+export class ToolTimeoutError extends Error {
+    toolName;
+    timeoutMs;
+    constructor(toolName, timeoutMs) {
+        super(`Tool "${toolName}" timeout after ${timeoutMs}ms`);
+        this.name = 'ToolTimeoutError';
+        this.toolName = toolName;
+        this.timeoutMs = timeoutMs;
+    }
+}
 export class ToolApprovalDeniedError extends Error {
     toolName;
     by;

package/dist/tools/effect/index.d.ts

@@ -4,4 +4,4 @@ export type { CoreToolExecutorConfig, CoreExecuteArgs } from './ToolExecutor.js'
 export { PairingTracker, cancelledPlaceholder, inProgressPlaceholder, } from './pairing.js';
 export type { ToolCallPair, ToolPairStatus, ToolRequestRecord, ToolResponseRecord, CancelledToolResult, InProgressToolResult, } from './pairing.js';
 export { validateAndSanitize, validateOutput, ToolValidationError } from './schema.js';
-export { ToolApprovalDeniedError } from './errors.js';
+export { ToolApprovalDeniedError, ToolTimeoutError } from './errors.js';

package/dist/tools/effect/index.js

@@ -2,4 +2,4 @@ export { defineTool, toolToAiSdk, buildToolSet } from './defineTool.js';
 export { CoreToolExecutor } from './ToolExecutor.js';
 export { PairingTracker, cancelledPlaceholder, inProgressPlaceholder, } from './pairing.js';
 export { validateAndSanitize, validateOutput, ToolValidationError } from './schema.js';
-export { ToolApprovalDeniedError } from './errors.js';
+export { ToolApprovalDeniedError, ToolTimeoutError } from './errors.js';

package/dist/types/effectTool.d.ts

@@ -9,6 +9,7 @@ export interface Tool<TInput = unknown, TOutput = unknown> {
     interruptible?: boolean;
     interim?: string;
     interimAfterMs?: number;
+    timeoutMs?: number;
     execute: (args: TInput, ctx?: ToolContext) => Promise<TOutput> | AsyncIterable<TOutput>;
 }
 export type AnyTool = Tool<any, any>;

package/dist/types/stream.d.ts

@@ -59,6 +59,10 @@ export type HarnessStreamPart = {
 } | {
     type: 'error';
     error: string;
+} | {
+    type: 'custom';
+    name: string;
+    data: unknown;
 } | {
     type: 'done';
     sessionId: string;

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/kuralle-core"
   },
-  "version": "0.3.14",
+  "version": "0.3.16",
   "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.14"
+    "@kuralle-agents/realtime-audio": "0.3.16"
   },
   "dependencies": {
     "chrono-node": "^2.6.0",