@kuralle-agents/core 0.6.1 → 0.7.1

package/dist/runtime/deriveAgent.d.ts

@@ -6,5 +6,14 @@ export interface DerivedAgentCapabilities {
     hasHandoffs: boolean;
     precedence: 'routes' | 'flows' | 'free';
 }
+export interface AgentShape {
+    hasDispatchTargets: boolean;
+    hasLocalProcedure: boolean;
+    hasLocalAnsweringSurface: boolean;
+    isAnsweringAgent: boolean;
+    isPureDispatcher: boolean;
+}
+export declare function hasLocalAnsweringSurface(agent: AgentConfig): boolean;
+export declare function hasDispatchTargets(agent: AgentConfig): boolean;
+export declare function deriveAgentShape(agent: AgentConfig): AgentShape;
 export declare function deriveAgentCapabilities(agent: AgentConfig): DerivedAgentCapabilities;
-export declare function shouldRunHostSelector(agent: AgentConfig, activeFlow?: string, alwaysRoute?: boolean): boolean;

package/dist/runtime/deriveAgent.js

@@ -1,8 +1,68 @@
+function hasPopulatedInstructions(instructions) {
+    if (instructions === undefined) {
+        return false;
+    }
+    if (typeof instructions === 'string') {
+        return instructions.trim().length > 0;
+    }
+    return true;
+}
+export function hasLocalAnsweringSurface(agent) {
+    if (hasPopulatedInstructions(agent.instructions)) {
+        return true;
+    }
+    if (agent.tools && Object.keys(agent.tools).length > 0) {
+        return true;
+    }
+    if (agent.globalTools && Object.keys(agent.globalTools).length > 0) {
+        return true;
+    }
+    if (agent.knowledge) {
+        return true;
+    }
+    if (agent.memory) {
+        return true;
+    }
+    if (agent.skills) {
+        return true;
+    }
+    if (agent.workspace) {
+        return true;
+    }
+    return false;
+}
+export function hasDispatchTargets(agent) {
+    const routes = agent.routes ?? [];
+    if (routes.some((route) => route.agent || route.flow)) {
+        return true;
+    }
+    if ((agent.agents?.length ?? 0) > 0) {
+        return true;
+    }
+    if ((agent.handoffs?.length ?? 0) > 0) {
+        return true;
+    }
+    return false;
+}
+export function deriveAgentShape(agent) {
+    const hasLocalProcedure = (agent.flows?.length ?? 0) > 0;
+    const answeringSurface = hasLocalAnsweringSurface(agent);
+    const dispatchTargets = hasDispatchTargets(agent);
+    const isAnsweringAgent = hasLocalProcedure || answeringSurface;
+    const isPureDispatcher = dispatchTargets && !isAnsweringAgent;
+    return {
+        hasDispatchTargets: dispatchTargets,
+        hasLocalProcedure,
+        hasLocalAnsweringSurface: answeringSurface,
+        isAnsweringAgent,
+        isPureDispatcher,
+    };
+}
 export function deriveAgentCapabilities(agent) {
+    const shape = deriveAgentShape(agent);
     const hasRoutes = (agent.routes?.length ?? 0) > 0;
-    const hasFlows = (agent.flows?.length ?? 0) > 0;
+    const hasFlows = shape.hasLocalProcedure;
     const hasHandoffs = (agent.agents?.length ?? 0) > 0 || (agent.handoffs?.length ?? 0) > 0;
-    const hasFreeConversation = true;
     const precedence = hasRoutes
         ? 'routes'
         : hasFlows
@@ -11,18 +71,8 @@ export function deriveAgentCapabilities(agent) {
     return {
         hasRoutes,
         hasFlows,
-        hasFreeConversation,
+        hasFreeConversation: shape.isAnsweringAgent,
         hasHandoffs,
         precedence,
     };
 }
-export function shouldRunHostSelector(agent, activeFlow, alwaysRoute) {
-    if (activeFlow) {
-        return false;
-    }
-    if (alwaysRoute) {
-        return true;
-    }
-    const { hasRoutes, hasFlows } = deriveAgentCapabilities(agent);
-    return hasRoutes || hasFlows;
-}

package/dist/runtime/dispatchMode.d.ts

@@ -0,0 +1,5 @@
+import type { AgentConfig } from '../types/agentConfig.js';
+import type { DriverOutputCapability } from '../types/channel.js';
+export type DispatchMode = 'strict' | 'relaxed';
+export declare function resolveDispatchMode(agent: AgentConfig, capability: DriverOutputCapability): DispatchMode;
+export declare function isAdvisoryDispatch(capability: DriverOutputCapability): boolean;

package/dist/runtime/dispatchMode.js

@@ -0,0 +1,18 @@
+export function resolveDispatchMode(agent, capability) {
+    if (agent.routing?.dispatch === 'strict') {
+        return 'strict';
+    }
+    switch (capability) {
+        case 'kuralle-controlled-text':
+            return 'relaxed';
+        case 'kuralle-controlled-tts':
+            return 'strict';
+        case 'native-realtime':
+            return 'strict';
+        default:
+            return 'relaxed';
+    }
+}
+export function isAdvisoryDispatch(capability) {
+    return capability === 'native-realtime';
+}

package/dist/runtime/grounding/index.d.ts

@@ -1,4 +1,4 @@
-export { appendGatherBlocks, buildAutoRetrieveProvider, buildKnowledgeProvider, } from './knowledge.js';
+export { appendGatherBlocks, buildAutoRetrieveProvider, buildKnowledgeProvider, buildKnowledgeTool, } from './knowledge.js';
 export { buildMemoryService, resetMissingUserIdWarningsForTests, runMemoryIngest, warnMissingUserId, } from './memory.js';
 export { wireWorkingMemory, loadWorkingMemoryBlocks, formatWorkingMemorySection, resolveWorkingMemoryStore, resolveWorkingMemoryOwner, type LoadedWorkingMemoryBlock, type WiredWorkingMemory, } from './workingMemory.js';
 export { runGatherPhase, type GatherResult, type GatherScope } from './gather.js';

package/dist/runtime/grounding/index.js

@@ -1,4 +1,4 @@
-export { appendGatherBlocks, buildAutoRetrieveProvider, buildKnowledgeProvider, } from './knowledge.js';
+export { appendGatherBlocks, buildAutoRetrieveProvider, buildKnowledgeProvider, buildKnowledgeTool, } from './knowledge.js';
 export { buildMemoryService, resetMissingUserIdWarningsForTests, runMemoryIngest, warnMissingUserId, } from './memory.js';
 export { wireWorkingMemory, loadWorkingMemoryBlocks, formatWorkingMemorySection, resolveWorkingMemoryStore, resolveWorkingMemoryOwner, } from './workingMemory.js';
 export { runGatherPhase } from './gather.js';

package/dist/runtime/grounding/knowledge.d.ts

@@ -1,7 +1,9 @@
 import type { AgentConfig } from '../../types/agentConfig.js';
 import type { AutoRetrieveProvider } from '../../types/run-context.js';
+import type { AnyTool } from '../../types/effectTool.js';
 import type { KnowledgeProviderConfig } from '../../types/voice.js';
 import { KnowledgeProvider } from '../KnowledgeProvider.js';
 export declare function buildKnowledgeProvider(config: KnowledgeProviderConfig): KnowledgeProvider;
 export declare function buildAutoRetrieveProvider(provider: KnowledgeProvider, agent: AgentConfig): AutoRetrieveProvider | undefined;
+export declare function buildKnowledgeTool(provider: KnowledgeProvider, agent: AgentConfig): AnyTool | undefined;
 export declare function appendGatherBlocks(system: string, blocks: Array<string | undefined>): string;

package/dist/runtime/grounding/knowledge.js

@@ -1,3 +1,5 @@
+import { z } from 'zod';
+import { defineTool } from '../../tools/effect/defineTool.js';
 import { normalizeCitations } from '../citations/index.js';
 import { KnowledgeProvider } from '../KnowledgeProvider.js';
 function latestUserMessage(ctx) {
@@ -61,6 +63,41 @@ export function buildAutoRetrieveProvider(provider, agent) {
         },
     };
 }
+export function buildKnowledgeTool(provider, agent) {
+    if (!agent.knowledge || agent.knowledge.autoRetrieve !== false) {
+        return undefined;
+    }
+    if (!provider.hasRetriever && !provider.hasCompiled) {
+        return undefined;
+    }
+    const overrides = agent.knowledge;
+    return defineTool({
+        name: 'knowledge_search',
+        description: 'Search the knowledge base for facts needed to answer the user. Call this whenever you need grounded information before answering. Returns relevant document snippets.',
+        input: z.object({
+            query: z
+                .string()
+                .trim()
+                .min(1, 'Query must not be empty.')
+                .describe("What to look up, in the user's language."),
+        }),
+        execute: async ({ query }, ctx) => {
+            const { results, events } = await provider.retrieve(query, undefined, overrides, false);
+            if (ctx?.emit) {
+                for (const event of events) {
+                    ctx.emit(event);
+                }
+            }
+            const compiled = provider.getCompiledKnowledge(overrides);
+            return {
+                documents: [
+                    ...(compiled ? [compiled] : []),
+                    ...results.map((result) => result.text),
+                ],
+            };
+        },
+    });
+}
 export function appendGatherBlocks(system, blocks) {
     const extras = blocks.filter((block) => Boolean(block?.trim()));
     if (extras.length === 0) {

package/dist/runtime/hostClassifyAdapter.d.ts

@@ -0,0 +1,2 @@
+import type { classifyHostTarget } from './select.js';
+export declare function adaptHostSelect(select: typeof import('./select.js').selectHostTarget): typeof classifyHostTarget;

package/dist/runtime/hostClassifyAdapter.js

@@ -0,0 +1,21 @@
+export function adaptHostSelect(select) {
+    return async (options) => {
+        const selection = await select({
+            agent: options.agent,
+            run: options.run,
+            model: options.model,
+            excludeFlowNames: options.excludeFlowNames,
+        });
+        if (selection.kind === 'keep') {
+            return { action: 'keep', confidence: 1 };
+        }
+        if (selection.kind === 'enterFlow') {
+            return { action: 'enterFlow', flowName: selection.flow.name };
+        }
+        return {
+            action: 'transfer',
+            targetAgentId: selection.agentId,
+            reason: selection.reason,
+        };
+    };
+}

package/dist/runtime/hostControlGuard.d.ts

@@ -0,0 +1,23 @@
+import type { LanguageModel } from 'ai';
+import type { AgentConfig } from '../types/agentConfig.js';
+import type { TurnControl } from '../types/channel.js';
+import type { RunState } from './durable/types.js';
+import { type HostGuardVerdict, type ClassifyHostOptions } from './select.js';
+export type { HostGuardVerdict };
+export declare function startHostControlGuard(options: {
+    agent: AgentConfig;
+    run: RunState;
+    model: LanguageModel;
+    classify?: (opts: ClassifyHostOptions) => Promise<HostGuardVerdict>;
+}): Promise<HostGuardVerdict>;
+export declare function isValidControl(control: TurnControl, agent: AgentConfig, run: RunState): boolean;
+export declare function isValidGuardVerdict(verdict: HostGuardVerdict, agent: AgentConfig, run: RunState): boolean;
+export declare function guardVerdictToControl(verdict: HostGuardVerdict): TurnControl | 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 declare function resolveHostControl(mainControl: TurnControl | undefined, guardVerdict: HostGuardVerdict | undefined, agent: AgentConfig, run: RunState, mainAnswered: boolean): TurnControl | undefined;

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' };
 }