@kuralle-agents/core 0.3.14 → 0.3.15

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/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.15",
   "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.15"
   },
   "dependencies": {
     "chrono-node": "^2.6.0",