@kuralle-agents/core 0.6.1 → 0.7.0

package/dist/runtime/hostControlGuard.js

@@ -0,0 +1,67 @@
+import { classifyHostTarget, } from './select.js';
+import { availableHostFlows, collectTransferTargets } from './hostControlTools.js';
+export function startHostControlGuard(options) {
+    const classify = options.classify ?? classifyHostTarget;
+    return classify({
+        agent: options.agent,
+        run: options.run,
+        model: options.model,
+        allowKeep: true,
+    });
+}
+export function isValidControl(control, agent, run) {
+    switch (control.type) {
+        case 'enterFlow': {
+            const flows = availableHostFlows(agent, run);
+            return flows.some((f) => f.name === control.flowName);
+        }
+        case 'handoff':
+            return collectTransferTargets(agent).some((t) => t.id === control.target);
+        case 'end':
+        case 'escalate':
+        case 'recover':
+            return true;
+        default:
+            return false;
+    }
+}
+export function isValidGuardVerdict(verdict, agent, run) {
+    if (verdict.action === 'keep') {
+        return true;
+    }
+    if (verdict.action === 'enterFlow' && verdict.flowName) {
+        return availableHostFlows(agent, run).some((f) => f.name === verdict.flowName);
+    }
+    if (verdict.action === 'transfer' && verdict.targetAgentId) {
+        return collectTransferTargets(agent).some((t) => t.id === verdict.targetAgentId);
+    }
+    return false;
+}
+export function guardVerdictToControl(verdict) {
+    if (verdict.action === 'enterFlow' && verdict.flowName) {
+        return { type: 'enterFlow', flowName: verdict.flowName, reason: verdict.reason };
+    }
+    if (verdict.action === 'transfer' && verdict.targetAgentId) {
+        return { type: 'handoff', target: verdict.targetAgentId, reason: verdict.reason };
+    }
+    return undefined;
+}
+/**
+ * Main model control wins when valid. The guard is a forgot-to-route net, NOT a
+ * second-guesser: it only overrides when the answering model produced neither a
+ * control tool NOR a substantive answer (`mainAnswered`). If the model answered,
+ * the answer stands — a guard verdict must not hijack a correct keep answer
+ * (which caused observed mis-routes of Q&A turns into flows).
+ */
+export function resolveHostControl(mainControl, guardVerdict, agent, run, mainAnswered) {
+    if (mainControl && isValidControl(mainControl, agent, run)) {
+        return mainControl;
+    }
+    if (!mainAnswered &&
+        guardVerdict &&
+        guardVerdict.action !== 'keep' &&
+        isValidGuardVerdict(guardVerdict, agent, run)) {
+        return guardVerdictToControl(guardVerdict);
+    }
+    return undefined;
+}

package/dist/runtime/hostControlTools.d.ts

@@ -0,0 +1,12 @@
+import type { AgentConfig } from '../types/agentConfig.js';
+import type { RunState } from './durable/types.js';
+import type { AnyTool } from '../types/effectTool.js';
+import type { Flow } from '../types/flow.js';
+export interface TransferTarget {
+    id: string;
+    descriptions: string[];
+}
+export declare function availableHostFlows(agent: AgentConfig, run: RunState): Flow[];
+export declare function collectTransferTargets(agent: AgentConfig): TransferTarget[];
+export declare function buildHostControlTools(agent: AgentConfig, run: RunState): Record<string, AnyTool>;
+export declare function hasHostControlTargets(agent: AgentConfig, run: RunState): boolean;

package/dist/runtime/hostControlTools.js

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+import { defineTool } from '../tools/effect/defineTool.js';
+import { createEnterFlowTool } from '../tools/enterFlow.js';
+export function availableHostFlows(agent, run) {
+    const flows = agent.flows ?? [];
+    const completedRaw = run.state.__completedFlows;
+    const completed = Array.isArray(completedRaw) ? completedRaw : [];
+    return flows.filter((flow) => !completed.includes(flow.name) && flow.name !== run.activeFlow);
+}
+export function collectTransferTargets(agent) {
+    const byId = new Map();
+    for (const route of agent.routes ?? []) {
+        if (!route.agent) {
+            continue;
+        }
+        const desc = `When: ${route.when}`;
+        const existing = byId.get(route.agent);
+        if (existing) {
+            existing.descriptions.push(desc);
+        }
+        else {
+            byId.set(route.agent, { id: route.agent, descriptions: [desc] });
+        }
+    }
+    for (const child of agent.agents ?? []) {
+        const desc = child.description ?? child.name ?? child.id;
+        const existing = byId.get(child.id);
+        if (existing) {
+            if (!existing.descriptions.includes(desc)) {
+                existing.descriptions.push(desc);
+            }
+        }
+        else {
+            byId.set(child.id, { id: child.id, descriptions: [desc] });
+        }
+    }
+    for (const handoffId of agent.handoffs ?? []) {
+        const child = agent.agents?.find((a) => a.id === handoffId);
+        const desc = child?.description ?? child?.name ?? handoffId;
+        const existing = byId.get(handoffId);
+        if (existing) {
+            if (!existing.descriptions.includes(desc)) {
+                existing.descriptions.push(desc);
+            }
+        }
+        else {
+            byId.set(handoffId, { id: handoffId, descriptions: [desc] });
+        }
+    }
+    return [...byId.values()];
+}
+function createTransferToAgentTool(targets) {
+    const ids = targets.map((t) => t.id);
+    const lines = targets.map((t) => `- ${t.id}: ${t.descriptions.join('; ')}`).join('\n');
+    return defineTool({
+        name: 'transfer_to_agent',
+        description: 'Transfer the conversation to a specialized agent when the user needs a specialist. ' +
+            'Call this INSTEAD of answering in prose or saying a filler/acknowledgement like "Sure" or "One moment"; ' +
+            'do not announce the transfer to the user.\n\n' +
+            `Available targets:\n${lines}`,
+        input: z.object({
+            targetAgentId: z.enum(ids).describe('Target agent id'),
+            reason: z.string().describe('Why this transfer — include relevant context'),
+            summary: z.string().optional().describe('Optional summary of progress so far'),
+        }),
+        execute: async ({ targetAgentId, reason, summary }) => ({
+            __handoff: true,
+            targetAgentId,
+            targetAgent: targetAgentId,
+            reason,
+            summary,
+        }),
+    });
+}
+export function buildHostControlTools(agent, run) {
+    const tools = {};
+    const flows = availableHostFlows(agent, run);
+    if (flows.length > 0) {
+        tools.enter_flow = createEnterFlowTool(flows);
+    }
+    const targets = collectTransferTargets(agent);
+    if (targets.length > 0) {
+        tools.transfer_to_agent = createTransferToAgentTool(targets);
+    }
+    return tools;
+}
+export function hasHostControlTargets(agent, run) {
+    return (availableHostFlows(agent, run).length > 0 || collectTransferTargets(agent).length > 0);
+}

package/dist/runtime/hostLoop.d.ts

@@ -2,7 +2,8 @@ import type { AgentConfig } from '../types/agentConfig.js';
 import type { ChannelDriver } from '../types/channel.js';
 import type { RunContext } from '../types/run-context.js';
 import type { RunState } from './durable/types.js';
-import { selectHostTarget } from './select.js';
+import { type ClassifyHostOptions, type HostGuardVerdict } from './select.js';
+import type { selectHostTarget } from './select.js';
 export type HostLoopResult = {
     kind: 'handoff';
     to: string;
@@ -20,6 +21,8 @@ export interface HostLoopOptions {
     run: RunState;
     driver: ChannelDriver;
     ctx: RunContext;
+    classify?: (opts: ClassifyHostOptions) => Promise<HostGuardVerdict>;
+    /** @deprecated Test injection — use classify. */
     select?: typeof selectHostTarget;
 }
 export declare function hostLoop(options: HostLoopOptions): Promise<HostLoopResult>;

package/dist/runtime/hostLoop.js

@@ -2,12 +2,17 @@ import { runFlow } from '../flow/runFlow.js';
 import { resolveReplyNode } from '../flow/nodeBuilders.js';
 import { SuspendError } from './durable/RunStore.js';
 import { buildAgentReplyNode } from './agentReply.js';
-import { deriveAgentCapabilities, shouldRunHostSelector } from './deriveAgent.js';
-import { selectHostTarget } from './select.js';
+import { deriveAgentShape } from './deriveAgent.js';
 import { assertWithinTurnLimit, incrementTurnCount, LimitsExceededError, } from './policies/limits.js';
+import { classifyHostTarget, verdictToSelection, } from './select.js';
+import { hasHostControlTargets } from './hostControlTools.js';
+import { isValidControl, resolveHostControl, startHostControlGuard, } from './hostControlGuard.js';
+import { resolveDispatchMode, isAdvisoryDispatch } from './dispatchMode.js';
+import { adaptHostSelect } from './hostClassifyAdapter.js';
 export async function hostLoop(options) {
     const { agent, run, driver, ctx } = options;
-    const select = options.select ?? selectHostTarget;
+    const classify = options.classify ??
+        (options.select ? adaptHostSelect(options.select) : classifyHostTarget);
     try {
         if (run.activeFlow) {
             const flow = findFlowByName(agent, run.activeFlow);
@@ -16,23 +21,14 @@ export async function hostLoop(options) {
             }
             return await runActiveFlow(flow, run, driver, ctx, agent);
         }
-        const alwaysRoute = agent.routing?.always === true;
-        if (shouldRunHostSelector(agent, run.activeFlow, alwaysRoute)) {
-            const selection = await select({
-                agent,
-                run,
-                model: agent.routing?.model ?? ctx.controlModel,
-                alwaysRoute,
-            });
-            if (selection.kind === 'enterFlow') {
-                return await runActiveFlow(selection.flow, run, driver, ctx, agent);
-            }
-            if (selection.kind === 'route') {
-                ctx.emit({ type: 'handoff', targetAgent: selection.agentId, reason: selection.reason });
-                return { kind: 'handoff', to: selection.agentId, reason: selection.reason };
-            }
+        const shape = deriveAgentShape(agent);
+        if (shape.isPureDispatcher) {
+            return await runPureDispatcher(agent, run, driver, ctx, classify);
+        }
+        if (shape.isAnsweringAgent) {
+            return await runAnsweringAgent(agent, run, driver, ctx, classify);
         }
-        return await runFreeConversation(agent, run, driver, ctx);
+        return await runFreeConversation(agent, run, driver, ctx, classify);
     }
     catch (error) {
         if (error instanceof SuspendError) {
@@ -45,6 +41,21 @@ export async function hostLoop(options) {
         throw error;
     }
 }
+async function runPureDispatcher(agent, run, driver, ctx, classify) {
+    incrementTurnCount(run);
+    assertWithinTurnLimit(run, ctx.limits);
+    const model = agent.routing?.model ?? ctx.controlModel;
+    const verdict = await classify({
+        agent,
+        run,
+        model,
+        allowKeep: false,
+    });
+    return await executeHostControl(agent, run, driver, ctx, guardVerdictToControl(verdict, agent));
+}
+async function runAnsweringAgent(agent, run, driver, ctx, classify) {
+    return await runFreeConversation(agent, run, driver, ctx, classify);
+}
 async function runActiveFlow(flow, run, driver, ctx, agent) {
     incrementTurnCount(run);
     assertWithinTurnLimit(run, ctx.limits);
@@ -66,33 +77,110 @@ async function runActiveFlow(flow, run, driver, ctx, agent) {
     await ctx.runStore.putRunState(run);
     return { kind: 'turnComplete' };
 }
-async function runFreeConversation(agent, run, driver, ctx) {
-    const caps = deriveAgentCapabilities(agent);
-    if (!caps.hasFreeConversation && !agent.tools) {
+async function runFreeConversation(agent, run, driver, ctx, classify) {
+    const shape = deriveAgentShape(agent);
+    if (!shape.isAnsweringAgent) {
         return { kind: 'turnComplete' };
     }
     incrementTurnCount(run);
     assertWithinTurnLimit(run, ctx.limits);
-    const replyNode = buildAgentReplyNode(agent);
-    const turn = await driver.runAgentTurn(resolveReplyNode(replyNode, run.state, { freeConversation: true }), ctx);
+    const capability = driver.outputCapability ?? 'kuralle-controlled-text';
+    const dispatchMode = resolveDispatchMode(agent, capability);
+    const advisoryDispatch = isAdvisoryDispatch(capability);
+    const needsGuard = hasHostControlTargets(agent, run);
+    const controlModel = agent.routing?.model ?? ctx.controlModel;
+    const startGuard = needsGuard
+        ? () => startHostControlGuard({
+            agent,
+            run,
+            model: controlModel,
+            classify,
+        })
+        : undefined;
+    const replyNode = buildAgentReplyNode(agent, run);
+    const resolved = resolveReplyNode(replyNode, run.state, { freeConversation: true });
+    if (needsGuard) {
+        // The driver only buffers/streams per dispatch mode; the guard has a single
+        // owner (this loop, on the empty-turn branch below) so it runs at most once.
+        resolved.hostControl = { dispatchMode, advisoryDispatch };
+    }
+    const turn = await driver.runAgentTurn(resolved, ctx);
+    if (turn.control && isValidControl(turn.control, agent, run)) {
+        emitHostGuardTelemetry(ctx, { invoked: false, reason: 'main-control' });
+        return await executeHostControl(agent, run, driver, ctx, turn.control);
+    }
     if (turn.text.trim()) {
+        emitHostGuardTelemetry(ctx, { invoked: false, reason: 'answered' });
         const message = { role: 'assistant', content: turn.text };
         run.messages = [...run.messages, message];
         await ctx.runStore.putRunState(run);
+        return { kind: 'turnComplete' };
+    }
+    if (startGuard) {
+        const guardVerdict = await startGuard();
+        const control = resolveHostControl(undefined, guardVerdict, agent, run, false);
+        if (control) {
+            emitHostGuardTelemetry(ctx, {
+                invoked: true,
+                reason: 'empty-routed',
+                verdict: guardVerdictToTelemetryVerdict(guardVerdict),
+            });
+            return await executeHostControl(agent, run, driver, ctx, control);
+        }
+        emitHostGuardTelemetry(ctx, {
+            invoked: true,
+            reason: 'empty-kept',
+            verdict: guardVerdictToTelemetryVerdict(guardVerdict),
+        });
+    }
+    return { kind: 'turnComplete' };
+}
+function guardVerdictToTelemetryVerdict(verdict) {
+    if (verdict.action === 'enterFlow')
+        return 'enterFlow';
+    if (verdict.action === 'transfer')
+        return 'transfer';
+    return 'keep';
+}
+function emitHostGuardTelemetry(ctx, data) {
+    ctx.emit({ type: 'custom', name: 'host-guard', data });
+}
+function guardVerdictToControl(verdict, agent) {
+    const selection = verdictToSelection(verdict, agent);
+    if (!selection || selection.kind === 'keep') {
+        return undefined;
+    }
+    if (selection.kind === 'enterFlow') {
+        return { type: 'enterFlow', flowName: selection.flow.name };
+    }
+    return { type: 'handoff', target: selection.agentId, reason: selection.reason };
+}
+async function executeHostControl(agent, run, driver, ctx, control) {
+    if (!control) {
+        ctx.emit({ type: 'error', error: 'No valid host control target resolved' });
+        return { kind: 'ended', reason: 'dispatch_failed' };
+    }
+    if (control.type === 'enterFlow') {
+        const flow = findFlowByName(agent, control.flowName);
+        if (flow) {
+            return await runActiveFlow(flow, run, driver, ctx, agent);
+        }
+        ctx.emit({ type: 'error', error: `Flow not found: ${control.flowName}` });
+        return { kind: 'ended', reason: 'flow_not_found' };
     }
-    if (turn.control?.type === 'handoff') {
-        ctx.emit({ type: 'handoff', targetAgent: turn.control.target, reason: turn.control.reason });
-        return { kind: 'handoff', to: turn.control.target, reason: turn.control.reason };
+    if (control.type === 'handoff') {
+        ctx.emit({ type: 'handoff', targetAgent: control.target, reason: control.reason });
+        return { kind: 'handoff', to: control.target, reason: control.reason };
     }
-    if (turn.control?.type === 'end') {
-        return { kind: 'ended', reason: turn.control.reason };
+    if (control.type === 'end') {
+        return { kind: 'ended', reason: 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 (control.type === 'escalate') {
+        ctx.emit({ type: 'handoff', targetAgent: 'human', reason: control.reason });
+        return { kind: 'handoff', to: 'human', reason: control.reason };
     }
-    if (turn.control?.type === 'recover') {
-        return { kind: 'ended', reason: turn.control.reason ?? 'error_degraded' };
+    if (control.type === 'recover') {
+        return { kind: 'ended', reason: control.reason ?? 'error_degraded' };
     }
     return { kind: 'turnComplete' };
 }

package/dist/runtime/select.d.ts

@@ -2,6 +2,7 @@ import type { LanguageModel } from 'ai';
 import type { AgentConfig } from '../types/agentConfig.js';
 import type { Flow } from '../types/flow.js';
 import type { RunState } from './durable/types.js';
+import { availableHostFlows } from './hostControlTools.js';
 export type HostSelection = {
     kind: 'enterFlow';
     flow: Flow;
@@ -12,12 +13,24 @@ export type HostSelection = {
 } | {
     kind: 'keep';
 };
-export interface SelectHostOptions {
+export interface HostGuardVerdict {
+    action: 'keep' | 'enterFlow' | 'transfer';
+    flowName?: string;
+    targetAgentId?: string;
+    reason?: string;
+    confidence?: number;
+}
+export interface ClassifyHostOptions {
     agent: AgentConfig;
     run: RunState;
     model: LanguageModel;
-    alwaysRoute?: boolean;
-    /** Flow names to exclude from enterFlow (e.g. the active flow during in-flow digression). */
+    allowKeep: boolean;
     excludeFlowNames?: string[];
 }
-export declare function selectHostTarget(options: SelectHostOptions): Promise<HostSelection>;
+export declare function classifyHostTarget(options: ClassifyHostOptions): Promise<HostGuardVerdict>;
+/** @deprecated Use classifyHostTarget — kept as alias for test injection. */
+export declare function selectHostTarget(options: Omit<ClassifyHostOptions, 'allowKeep'> & {
+    alwaysRoute?: boolean;
+}): Promise<HostSelection>;
+export declare function verdictToSelection(verdict: HostGuardVerdict, agent: AgentConfig): HostSelection | undefined;
+export { availableHostFlows };