@kuralle-agents/core 0.3.13 → 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/controlEvaluator.d.ts

@@ -0,0 +1,18 @@
+import type { FlowState, ReplyNode } from '../types/flow.js';
+import type { TurnResult } from '../types/channel.js';
+import { type NormalizedTransition } from './normalizeTransition.js';
+export interface ControlSignal {
+    node: ReplyNode;
+    turn: TurnResult;
+    state: FlowState;
+    interrupted: boolean;
+}
+export type ControlDecision = {
+    kind: 'transition';
+    transition: NormalizedTransition;
+} | {
+    kind: 'redispatch';
+} | {
+    kind: 'stay';
+};
+export declare function evaluateReplyControl(signal: ControlSignal): Promise<ControlDecision>;

package/dist/flow/controlEvaluator.js

@@ -0,0 +1,26 @@
+import { normalizeTransition } from './normalizeTransition.js';
+function controlToTransition(control) {
+    switch (control.type) {
+        case 'handoff':
+            return { kind: 'handoff', to: control.target, reason: control.reason };
+        case 'end':
+            return { kind: 'end', reason: control.reason };
+        case 'escalate':
+            return { kind: 'escalate', reason: control.reason };
+        case 'recover':
+            return { kind: 'end', reason: control.reason ?? 'error_degraded' };
+    }
+}
+export async function evaluateReplyControl(signal) {
+    const { node, turn, state, interrupted } = signal;
+    if (interrupted) {
+        return { kind: 'redispatch' };
+    }
+    if (turn.control) {
+        return { kind: 'transition', transition: controlToTransition(turn.control) };
+    }
+    if (node.next) {
+        return { kind: 'transition', transition: normalizeTransition(await node.next(turn, state)) };
+    }
+    return { kind: 'stay' };
+}

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/flow/flowControlTools.d.ts

@@ -0,0 +1,3 @@
+/** Model-initiated flow-transition tools siloed from flow reply speaking dicts (H1). */
+export declare const FLOW_TRANSITION_CONTROL_TOOL_NAMES: Set<string>;
+export declare function isFlowTransitionControlTool(name: string): boolean;

package/dist/flow/flowControlTools.js

@@ -0,0 +1,11 @@
+/** Model-initiated flow-transition tools siloed from flow reply speaking dicts (H1). */
+export const FLOW_TRANSITION_CONTROL_TOOL_NAMES = new Set([
+    'handoff',
+    'transfer_to_agent',
+    'final',
+    'escalate',
+    'recover',
+]);
+export function isFlowTransitionControlTool(name) {
+    return FLOW_TRANSITION_CONTROL_TOOL_NAMES.has(name);
+}

package/dist/flow/nodeBuilders.d.ts

@@ -9,5 +9,7 @@ export declare function buildNodePrompt(node: ReplyNode, state: FlowState): stri
  *  own instructions. Node instructions layer ON TOP — they never replace the
  *  base. Base resolves against the current state so dynamic base prompts work. */
 export declare function composeSystem(base: Instructions | undefined, nodeSystem: string, state: FlowState): string;
-export declare function resolveReplyNode(node: ReplyNode, state: FlowState): ResolvedNode;
+export declare function resolveReplyNode(node: ReplyNode, state: FlowState, options?: {
+    freeConversation?: boolean;
+}): ResolvedNode;
 export declare function resolveCollectExtractionNode(collectNode: CollectNode, missing: string[], state: FlowState, submitTool: Tool): ResolvedNode;

package/dist/flow/nodeBuilders.js

@@ -32,7 +32,7 @@ function buildNodeTools(node, state) {
     }
     return node.tools;
 }
-export function resolveReplyNode(node, state) {
+export function resolveReplyNode(node, state, options) {
     const tools = buildNodeTools(node, state);
     return {
         node,
@@ -41,6 +41,7 @@ export function resolveReplyNode(node, state) {
         // Recover the raw executors from the node's `buildToolSet` tools so they run
         // in-flow (with run context) — without also needing `agent.effectTools`.
         localTools: rawToolsFromSet(tools),
+        ...(options?.freeConversation && { freeConversation: true }),
     };
 }
 export function resolveCollectExtractionNode(collectNode, missing, state, submitTool) {

package/dist/flow/runFlow.js

@@ -5,6 +5,7 @@ import { isActionNode, isCollectNode, isDecideNode, isReplyNode, } from './nodeK
 import { normalizeTransition, resolveNodeRef } from './normalizeTransition.js';
 import { reduceTransition } from './reduceTransition.js';
 import { resolveReplyNode } from './nodeBuilders.js';
+import { evaluateReplyControl } from './controlEvaluator.js';
 import { runNodeVerify, VerifyBlockedError } from './verify.js';
 import { loadRecordedSteps } from '../runtime/durable/replay.js';
 import { SuspendError } from '../runtime/durable/RunStore.js';
@@ -128,6 +129,24 @@ async function dispatchNode(node, run, driver, ctx) {
     }
     if (isReplyNode(node)) {
         const turn = await driver.runAgentTurn(resolveReplyNode(node, run.state), ctx);
+        if (ctx.outOfBandControl) {
+            const decision = await evaluateReplyControl({
+                node,
+                turn,
+                state: run.state,
+                interrupted: !!turn.interrupted,
+            });
+            if (decision.kind === 'redispatch') {
+                const signal = await driver.awaitUser(ctx);
+                appendUserMessage(run, signal.input);
+                return dispatchNode(node, run, driver, ctx);
+            }
+            appendAssistantMessage(run, turn.text);
+            if (decision.kind === 'transition') {
+                return decision.transition;
+            }
+            return { kind: 'stay' };
+        }
         appendAssistantMessage(run, turn.text);
         if (turn.interrupted) {
             const signal = await driver.awaitUser(ctx);

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;
@@ -109,6 +110,7 @@ export class Runtime {
             // Agent base layer (ADR 0001): composed into every node turn by the drivers.
             runCtx.baseInstructions = opened.agent.instructions;
             runCtx.globalTools = opened.agent.globalTools;
+            runCtx.outOfBandControl = opened.agent.experimental?.outOfBandControl ?? false;
             await this.hooks?.onStart?.(runCtx);
             const driver = opts.driver ?? new TextDriver();
             let activeAgent = opened.agent;

package/dist/runtime/channels/TextDriver.js

@@ -7,6 +7,7 @@ import { runSilentExtraction } from './extractionTurn.js';
 import { applyPreTurnPolicies, applyPostTurnPolicies } from '../policies/agentTurn.js';
 import { resolveMaxSteps } from '../policies/limits.js';
 import { appendGatherBlocks, resolveNodeGatherScope, runGatherPhase } from '../grounding/index.js';
+import { isFlowTransitionControlTool } from '../../flow/flowControlTools.js';
 export class TextDriver {
     toolDefs;
     maxSteps;
@@ -34,7 +35,7 @@ export class TextDriver {
         const baseSystem = composeSystem(ctx.baseInstructions, nodeSystem, ctx.runState.state);
         const system = appendGatherBlocks(baseSystem, [gather.retrievalBlock, gather.memoryBlock]);
         const messages = [...ctx.runState.messages];
-        const aiTools = this.resolveTools(node, ctx.globalTools);
+        const aiTools = this.resolveTools(node, ctx);
         const maxSteps = resolveMaxSteps(ctx.limits, this.maxSteps);
         const toolCallsMade = [];
         let draftText = '';
@@ -137,20 +138,41 @@ export class TextDriver {
         const input = consumePendingUserInput(ctx.session);
         return { type: 'message', input };
     }
-    resolveTools(resolved, globalTools) {
-        const merged = { ...this.toolDefs, ...(globalTools ?? {}), ...(resolved.localTools ?? {}) };
+    resolveTools(resolved, ctx) {
+        const siloFlowControl = ctx.outOfBandControl && !resolved.freeConversation;
+        const merged = {
+            ...this.toolDefs,
+            ...(ctx.globalTools ?? {}),
+            ...(resolved.localTools ?? {}),
+        };
         const aiTools = { ...resolved.tools };
         for (const [name, tool] of Object.entries(merged)) {
+            if (siloFlowControl && isFlowTransitionControlTool(name)) {
+                continue;
+            }
             if (tool && !aiTools[name]) {
                 const built = buildToolSet({ [name]: tool });
                 Object.assign(aiTools, built);
             }
         }
+        if (siloFlowControl) {
+            for (const name of Object.keys(aiTools)) {
+                if (isFlowTransitionControlTool(name)) {
+                    delete aiTools[name];
+                }
+            }
+        }
         if (Object.keys(aiTools).length === 0 && Object.keys(merged).length === 0) {
             return undefined;
         }
         if (Object.keys(aiTools).length === 0) {
-            return buildToolSet(merged);
+            const filteredMerged = siloFlowControl
+                ? Object.fromEntries(Object.entries(merged).filter(([name]) => !isFlowTransitionControlTool(name)))
+                : merged;
+            if (Object.keys(filteredMerged).length === 0) {
+                return undefined;
+            }
+            return buildToolSet(filteredMerged);
         }
         return aiTools;
     }

package/dist/runtime/channels/VoiceDriver.js

@@ -35,7 +35,7 @@ export class VoiceDriver {
         const nodeSystem = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);
         const baseSystem = composeSystem(ctx.baseInstructions, nodeSystem, ctx.runState.state);
         const system = appendGatherBlocks(baseSystem, [gather.retrievalBlock, gather.memoryBlock]);
-        const geminiTools = resolveVoiceGeminiTools(node, { ...this.toolDefs, ...(ctx.globalTools ?? {}) });
+        const geminiTools = resolveVoiceGeminiTools(node, { ...this.toolDefs, ...(ctx.globalTools ?? {}) }, { siloFlowControl: ctx.outOfBandControl && !node.freeConversation });
         const toolCallsMade = [];
         const maxSteps = resolveMaxSteps(ctx.limits, this.maxSteps);
         let draftText = '';

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

@@ -3,5 +3,7 @@ import type { ResolvedNode } from '../../types/channel.js';
 import type { AnyTool } from '../../types/effectTool.js';
 import { buildToolSet } from '../../tools/effect/defineTool.js';
 export declare function v2ToolsToGemini(tools: Record<string, AnyTool>): GeminiFunctionDeclaration[];
-export declare function resolveVoiceGeminiTools(resolved: ResolvedNode, toolDefs: Record<string, AnyTool>): GeminiFunctionDeclaration[];
+export declare function resolveVoiceGeminiTools(resolved: ResolvedNode, toolDefs: Record<string, AnyTool>, options?: {
+    siloFlowControl?: boolean;
+}): GeminiFunctionDeclaration[];
 export { buildToolSet };

package/dist/runtime/channels/voiceTools.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { toGeminiDeclarations } from '../../capabilities/adapters/gemini.js';
 import { buildToolSet } from '../../tools/effect/defineTool.js';
+import { isFlowTransitionControlTool } from '../../flow/flowControlTools.js';
 function toolToDeclaration(name, tool) {
     return {
         name: tool.name || name,
@@ -13,14 +14,25 @@ export function v2ToolsToGemini(tools) {
     const declarations = Object.entries(tools).map(([name, tool]) => toolToDeclaration(name, tool));
     return toGeminiDeclarations(declarations);
 }
-export function resolveVoiceGeminiTools(resolved, toolDefs) {
+export function resolveVoiceGeminiTools(resolved, toolDefs, options) {
+    const siloFlowControl = options?.siloFlowControl === true;
     const merged = { ...toolDefs, ...(resolved.localTools ?? {}) };
     const fromNode = toolSetToEffectTools(resolved.tools);
     for (const [name, tool] of Object.entries(fromNode)) {
+        if (siloFlowControl && isFlowTransitionControlTool(name)) {
+            continue;
+        }
         if (!merged[name]) {
             merged[name] = tool;
         }
     }
+    if (siloFlowControl) {
+        for (const name of Object.keys(merged)) {
+            if (isFlowTransitionControlTool(name)) {
+                delete merged[name];
+            }
+        }
+    }
     return v2ToolsToGemini(merged);
 }
 function toolSetToEffectTools(tools) {

package/dist/runtime/ctx.d.ts

@@ -21,6 +21,7 @@ export interface CtxDeps {
     hookRunner?: HookRunner;
     model: LanguageModel;
     controlModel?: LanguageModel;
+    outOfBandControl?: boolean;
     refinementPolicies?: RefinementCapability[];
     validationPolicies?: ValidationCapability[];
     inputProcessors?: InputProcessor[];

package/dist/runtime/ctx.js

@@ -100,6 +100,7 @@ function makeCtx(deps) {
         hookRunner: deps.hookRunner ?? {},
         model: deps.model,
         controlModel: deps.controlModel ?? deps.model,
+        outOfBandControl: deps.outOfBandControl ?? false,
         refinementPolicies: deps.refinementPolicies ?? [],
         validationPolicies: deps.validationPolicies ?? [],
         inputProcessors: deps.inputProcessors ?? [],

package/dist/runtime/hostLoop.js

@@ -74,7 +74,7 @@ async function runFreeConversation(agent, run, driver, ctx) {
     incrementTurnCount(run);
     assertWithinTurnLimit(run, ctx.limits);
     const replyNode = buildAgentReplyNode(agent);
-    const turn = await driver.runAgentTurn(resolveReplyNode(replyNode, run.state), ctx);
+    const turn = await driver.runAgentTurn(resolveReplyNode(replyNode, run.state, { freeConversation: true }), ctx);
     if (turn.text.trim()) {
         const message = { role: 'assistant', content: turn.text };
         run.messages = [...run.messages, message];

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/agentConfig.d.ts

@@ -35,5 +35,9 @@ export interface AgentConfig {
     memory?: AgentMemory;
     guardrails?: Guardrails;
     limits?: Limits;
+    experimental?: {
+        /** Flow reply nodes: silo flow-transition control tools + deterministic evaluator (ADR 0003 H1). Default OFF. */
+        outOfBandControl?: boolean;
+    };
 }
 export declare function defineAgent(config: AgentConfig): AgentConfig;

package/dist/types/channel.d.ts

@@ -7,6 +7,8 @@ export interface ResolvedNode {
     prompt: string;
     tools: ToolSet;
     localTools?: Record<string, AnyTool>;
+    /** Free-conversation reply (host loop): keeps model control tools even when outOfBandControl is on. */
+    freeConversation?: boolean;
 }
 export interface ChannelDriver {
     runAgentTurn(node: ResolvedNode, ctx: RunContext): Promise<TurnResult>;

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/run-context.d.ts

@@ -53,6 +53,8 @@ export interface RunContext {
     model: LanguageModel;
     /** Control-path model (routing, decide, extraction) at temperature 0. */
     controlModel: LanguageModel;
+    /** When true, flow reply nodes use the out-of-band control evaluator (ADR 0003 H1). */
+    outOfBandControl: boolean;
     refinementPolicies: RefinementCapability[];
     validationPolicies: ValidationCapability[];
     inputProcessors: InputProcessor[];

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.13",
+  "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.13"
+    "@kuralle-agents/realtime-audio": "0.3.15"
   },
   "dependencies": {
     "chrono-node": "^2.6.0",