@kuralle-agents/core 0.3.13 → 0.3.14

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/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/runtime/Runtime.js

@@ -109,6 +109,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/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/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/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.14",
   "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.14"
   },
   "dependencies": {
     "chrono-node": "^2.6.0",