@kuralle-agents/core 0.3.15 → 0.3.16

package/dist/flow/choiceMatch.d.ts

@@ -0,0 +1,17 @@
+import type { ModelMessage } from 'ai';
+import { z } from 'zod';
+import type { DecideNode } from '../types/flow.js';
+import type { ChoiceOption } from '../types/selection.js';
+import type { RunContext } from '../types/run-context.js';
+/** Reserved enum member: model declines to pick a listed choice (→ author stay/unmatched). */
+export declare const CHOICE_NONE = "__none";
+export declare function isConstrainedChoiceEnumSchema(schema: unknown): boolean;
+export declare function isChoiceFieldSchema(schema: unknown): schema is z.ZodObject<{
+    choice: z.ZodString;
+}>;
+export declare function buildChoiceEnumSchema(choices: ChoiceOption[]): z.ZodObject<{
+    choice: z.ZodEnum<[string, ...string[]]>;
+}>;
+export declare function latestUserMessageText(messages: ModelMessage[]): string | undefined;
+export declare function matchChoiceFromInput(input: string, choices: ChoiceOption[]): string | undefined;
+export declare function resolveStructuredDecide(node: DecideNode, ctx: RunContext, system: string): Promise<unknown>;

package/dist/flow/choiceMatch.js

@@ -0,0 +1,119 @@
+import { generateObject } from 'ai';
+import { z } from 'zod';
+/** Reserved enum member: model declines to pick a listed choice (→ author stay/unmatched). */
+export const CHOICE_NONE = '__none';
+function normalize(raw) {
+    return raw.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+function keywordTerms(text) {
+    return normalize(text)
+        .split(/[^a-z0-9]+/)
+        .filter((term) => term.length > 4);
+}
+export function isConstrainedChoiceEnumSchema(schema) {
+    if (!(schema instanceof z.ZodObject)) {
+        return false;
+    }
+    return schema.shape.choice instanceof z.ZodEnum;
+}
+export function isChoiceFieldSchema(schema) {
+    if (!(schema instanceof z.ZodObject)) {
+        return false;
+    }
+    const keys = Object.keys(schema.shape);
+    if (keys.length !== 1 || keys[0] !== 'choice') {
+        return false;
+    }
+    return schema.shape.choice instanceof z.ZodString;
+}
+export function buildChoiceEnumSchema(choices) {
+    const ids = choices.map((c) => c.id);
+    if (ids.length === 0) {
+        return z.object({ choice: z.enum([CHOICE_NONE]) });
+    }
+    const members = [ids[0], ...ids.slice(1), CHOICE_NONE];
+    return z.object({ choice: z.enum(members) });
+}
+export function latestUserMessageText(messages) {
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const message = messages[i];
+        if (message?.role === 'user') {
+            if (typeof message.content === 'string') {
+                return message.content;
+            }
+            if (Array.isArray(message.content)) {
+                const text = message.content
+                    .filter((part) => part.type === 'text')
+                    .map((part) => part.text)
+                    .join('');
+                if (text) {
+                    return text;
+                }
+            }
+        }
+    }
+    return undefined;
+}
+export function matchChoiceFromInput(input, choices) {
+    const normalized = normalize(input);
+    if (!normalized) {
+        return undefined;
+    }
+    const idMatches = choices.filter((c) => normalize(c.id) === normalized).map((c) => c.id);
+    if (idMatches.length === 1) {
+        return idMatches[0];
+    }
+    if (idMatches.length > 1) {
+        return undefined;
+    }
+    const labelMatches = choices.filter((c) => normalize(c.label) === normalized).map((c) => c.id);
+    if (labelMatches.length === 1) {
+        return labelMatches[0];
+    }
+    if (labelMatches.length > 1) {
+        return undefined;
+    }
+    const keywordMatches = [];
+    for (const choice of choices) {
+        const terms = keywordTerms(choice.label);
+        if (terms.length > 0 && terms.some((term) => normalized.includes(term))) {
+            keywordMatches.push(choice.id);
+        }
+    }
+    if (keywordMatches.length === 1) {
+        return keywordMatches[0];
+    }
+    return undefined;
+}
+export async function resolveStructuredDecide(node, ctx, system) {
+    const schema = node.schema;
+    const useConstrainedChoices = (node.choices?.length ?? 0) > 0 && isChoiceFieldSchema(schema);
+    if (!useConstrainedChoices) {
+        const { object } = await generateObject({
+            model: ctx.controlModel,
+            schema,
+            system,
+            messages: ctx.runState.messages,
+            temperature: 0,
+            abortSignal: ctx.abortSignal,
+        });
+        return object;
+    }
+    const input = latestUserMessageText(ctx.runState.messages);
+    if (input) {
+        const matched = matchChoiceFromInput(input, node.choices);
+        if (matched) {
+            return { choice: matched };
+        }
+    }
+    const choiceSchema = buildChoiceEnumSchema(node.choices);
+    const { object } = await generateObject({
+        model: ctx.controlModel,
+        schema: choiceSchema,
+        system,
+        messages: ctx.runState.messages,
+        temperature: 0,
+        abortSignal: ctx.abortSignal,
+    });
+    return object;
+}

package/dist/runtime/channels/TextDriver.js

@@ -1,4 +1,4 @@
-import { streamText, generateObject } from 'ai';
+import { streamText } from 'ai';
 import { buildNodePrompt, resolveInstructions, composeSystem } from '../../flow/nodeBuilders.js';
 import { buildToolSet } from '../../tools/effect/index.js';
 import { executeModelToolCall, toolResultMessage } from './executeModelTool.js';
@@ -8,6 +8,7 @@ import { applyPreTurnPolicies, applyPostTurnPolicies } from '../policies/agentTu
 import { resolveMaxSteps } from '../policies/limits.js';
 import { appendGatherBlocks, resolveNodeGatherScope, runGatherPhase } from '../grounding/index.js';
 import { isFlowTransitionControlTool } from '../../flow/flowControlTools.js';
+import { resolveStructuredDecide } from '../../flow/choiceMatch.js';
 export class TextDriver {
     toolDefs;
     maxSteps;
@@ -113,26 +114,8 @@ export class TextDriver {
         return runSilentExtraction(node, ctx, ctx.controlModel, resolveMaxSteps(ctx.limits, this.maxSteps));
     }
     async runStructured(node, ctx) {
-        const base = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state);
-        const schema = node.schema;
-        // When the node offers choices (e.g. via withChoices), constrain the model
-        // to return exactly one option id. Otherwise an unconstrained string schema
-        // lets the model reply with free-form prose that `decide()` can't match,
-        // stalling the flow at every interactive node.
-        const system = node.choices?.length
-            ? `${base}\n\nYou MUST pick exactly ONE option by its id. Valid ids: ${node.choices
-                .map((c) => c.id)
-                .join(', ')}. Respond with only the chosen id, nothing else.`
-            : base;
-        const { object } = await generateObject({
-            model: ctx.controlModel,
-            schema,
-            system,
-            messages: ctx.runState.messages,
-            temperature: 0,
-            abortSignal: ctx.abortSignal,
-        });
-        return object;
+        const system = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state);
+        return resolveStructuredDecide(node, ctx, system);
     }
     async awaitUser(ctx) {
         const input = consumePendingUserInput(ctx.session);

package/dist/runtime/channels/VoiceDriver.js

@@ -1,5 +1,5 @@
-import { generateObject } from 'ai';
 import { runSilentExtraction } from './extractionTurn.js';
+import { resolveStructuredDecide } from '../../flow/choiceMatch.js';
 import { buildNodePrompt, resolveInstructions, composeSystem } from '../../flow/nodeBuilders.js';
 import { executeModelToolCall } from './executeModelTool.js';
 import { applyPreTurnPolicies, applyPostTurnPolicies } from '../policies/agentTurn.js';
@@ -65,24 +65,8 @@ export class VoiceDriver {
         return out;
     }
     async runStructured(node, ctx) {
-        const base = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state);
-        const schema = node.schema;
-        // Parity with TextDriver: when the node offers choices, constrain the model
-        // to a single option id so an unconstrained string can't stall the decide.
-        const system = node.choices?.length
-            ? `${base}\n\nYou MUST pick exactly ONE option by its id. Valid ids: ${node.choices
-                .map((c) => c.id)
-                .join(', ')}. Respond with only the chosen id, nothing else.`
-            : base;
-        const { object } = await generateObject({
-            model: ctx.controlModel,
-            schema,
-            system,
-            messages: ctx.runState.messages,
-            temperature: 0,
-            abortSignal: ctx.abortSignal,
-        });
-        return object;
+        const system = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state);
+        return resolveStructuredDecide(node, ctx, system);
     }
     // Non-speaking collect extraction: uses the shared text-model extraction path
     // rather than the realtime audio provider, so the agent never SPEAKS during

package/dist/runtime/select.js

@@ -24,6 +24,10 @@ export async function selectHostTarget(options) {
     if (availableFlows.length === 1 && agentRoutes.length === 0) {
         return { kind: 'enterFlow', flow: availableFlows[0] };
     }
+    const deterministic = deterministicRouteMatch(latestUser, routes, availableFlows);
+    if (deterministic) {
+        return deterministic;
+    }
     const flowLines = availableFlows
         .map((flow) => `- flow "${flow.name}": ${flow.description}`)
         .join('\n');
@@ -72,6 +76,32 @@ export async function selectHostTarget(options) {
     }
     return keywordRouteFallback(latestUser, routes, availableFlows);
 }
+function deterministicRouteMatch(message, routes, availableFlows) {
+    const lower = message.toLowerCase();
+    const hits = [];
+    for (const route of routes) {
+        const terms = route.when
+            .toLowerCase()
+            .split(/[^a-z0-9]+/)
+            .filter((term) => term.length > 3);
+        if (!terms.some((term) => lower.includes(term))) {
+            continue;
+        }
+        if (route.flow) {
+            const flow = availableFlows.find((candidate) => candidate.name === route.flow);
+            if (flow) {
+                hits.push({ kind: 'enterFlow', flow });
+            }
+        }
+        else if (route.agent) {
+            hits.push({ kind: 'route', agentId: route.agent });
+        }
+    }
+    if (hits.length === 1) {
+        return hits[0];
+    }
+    return undefined;
+}
 function keywordRouteFallback(message, routes, availableFlows) {
     const lower = message.toLowerCase();
     for (const route of routes) {

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/kuralle-core"
   },
-  "version": "0.3.15",
+  "version": "0.3.16",
   "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.15"
+    "@kuralle-agents/realtime-audio": "0.3.16"
   },
   "dependencies": {
     "chrono-node": "^2.6.0",