@kuralle-agents/core 0.3.8 → 0.3.9

package/dist/authoring/index.d.ts

@@ -1,2 +1,2 @@
-export { reply, collect, action, decide, defineFlow } from './nodes.js';
+export { reply, collect, action, decide, confirmGate, defineFlow } from './nodes.js';
 export { defineAgent, type AgentConfig, type Instructions } from './defineAgent.js';

package/dist/authoring/index.js

@@ -1,2 +1,2 @@
-export { reply, collect, action, decide, defineFlow } from './nodes.js';
+export { reply, collect, action, decide, confirmGate, defineFlow } from './nodes.js';
 export { defineAgent } from './defineAgent.js';

package/dist/authoring/nodes.d.ts

@@ -1 +1 @@
-export { reply, collect, action, decide, defineFlow } from '../types/flow.js';
+export { reply, collect, action, decide, confirmGate, defineFlow } from '../types/flow.js';

package/dist/authoring/nodes.js

@@ -1 +1 @@
-export { reply, collect, action, decide, defineFlow } from '../types/flow.js';
+export { reply, collect, action, decide, confirmGate, defineFlow } from '../types/flow.js';

package/dist/flow/confirmParse.d.ts

@@ -0,0 +1,2 @@
+export type ConfirmVerdict = 'affirm' | 'decline' | 'ambiguous';
+export declare function parseConfirmation(raw: string): ConfirmVerdict;

package/dist/flow/confirmParse.js

@@ -0,0 +1,170 @@
+const AFFIRM_TOKENS = new Set([
+    'yes',
+    'yeah',
+    'yep',
+    'yup',
+    'ya',
+    'sure',
+    'ok',
+    'okay',
+    'okey',
+    'k',
+    'confirm',
+    'confirmed',
+    'correct',
+    'right',
+    'proceed',
+    'do',
+    'done',
+    'yessir',
+    'affirmative',
+    'ow',
+    'ova',
+    'hari',
+    'hariyata',
+    'ehenam',
+    'aam',
+    'aama',
+    'sari',
+    'seri',
+]);
+const AFFIRM_PHRASES = [
+    'go ahead',
+    'do it',
+    'book it',
+    'place it',
+    'place the order',
+    'place my order',
+    'sounds good',
+    "that's right",
+    'thats right',
+    'that is correct',
+    'please do',
+    "let's do it",
+    'lets do it',
+    'go for it',
+    'confirm the order',
+    'yes please',
+];
+const AFFIRM_SCRIPT = ['ඔව්', 'හරි', 'හා', 'හරියට', 'ஆம்', 'சரி', 'ஆமா'];
+const DECLINE_TOKENS = new Set([
+    'no',
+    'nope',
+    'nah',
+    'na',
+    'not',
+    'dont',
+    "don't",
+    'stop',
+    'cancel',
+    'wait',
+    'hold',
+    'change',
+    'edit',
+    'incorrect',
+    'wrong',
+    'nevermind',
+    'never',
+    'naha',
+    'nae',
+    'epa',
+    'epaa',
+    'wenas',
+    'illa',
+    'illai',
+    'vendam',
+    'vendaam',
+    'vena',
+]);
+const DECLINE_PHRASES = [
+    'not yet',
+    'hold on',
+    'no thanks',
+    'no thank you',
+    "don't",
+    'do not',
+    'change it',
+    'change the',
+    'let me change',
+    'something else',
+    'go back',
+];
+const DECLINE_SCRIPT = ['නැහැ', 'නෑ', 'එපා', 'වෙනස්', 'இல்லை', 'வேண்டாம்', 'வேற'];
+const INTERROGATIVE_WORDS = [
+    'what',
+    'how',
+    'when',
+    'where',
+    'why',
+    'which',
+    'who',
+    'do you',
+    'can you',
+    'could you',
+    'is there',
+    'tell me',
+    'show me',
+];
+function normalize(raw) {
+    return raw.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+function stripTokenPunctuation(token) {
+    return token.replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, '');
+}
+function tokenize(normalized) {
+    return normalized
+        .split(/\s+/)
+        .map(stripTokenPunctuation)
+        .filter((token) => token.length > 0);
+}
+function hasDeclineToken(tokens) {
+    return tokens.some((token) => DECLINE_TOKENS.has(token));
+}
+function hasDeclinePhrase(normalized) {
+    return DECLINE_PHRASES.some((phrase) => normalized.includes(phrase));
+}
+function hasDeclineScript(normalized, raw) {
+    return DECLINE_SCRIPT.some((fragment) => normalized.includes(fragment) || raw.includes(fragment));
+}
+function hasDecline(normalized, tokens, raw) {
+    return hasDeclineToken(tokens) || hasDeclinePhrase(normalized) || hasDeclineScript(normalized, raw);
+}
+function hasInterrogative(normalized) {
+    if (normalized.includes('?')) {
+        return true;
+    }
+    return INTERROGATIVE_WORDS.some((word) => {
+        const pattern = new RegExp(`(?:^|\\s)${word.replace(/\s+/g, '\\s+')}(?:\\s|$|[?.!,])`, 'i');
+        return pattern.test(normalized);
+    });
+}
+function hasAffirmScript(normalized, raw) {
+    return AFFIRM_SCRIPT.some((fragment) => normalized.includes(fragment) || raw.includes(fragment));
+}
+function hasAffirmPhrase(normalized) {
+    return AFFIRM_PHRASES.some((phrase) => normalized.startsWith(phrase));
+}
+function hasAffirmToken(tokens) {
+    const head = tokens.slice(0, 3);
+    if (head.some((token) => AFFIRM_TOKENS.has(token))) {
+        return true;
+    }
+    return tokens.length === 1 && tokens[0] === 'y';
+}
+function hasAffirm(normalized, tokens, raw) {
+    return hasAffirmScript(normalized, raw) || hasAffirmPhrase(normalized) || hasAffirmToken(tokens);
+}
+export function parseConfirmation(raw) {
+    const normalized = normalize(raw);
+    const tokens = tokenize(normalized);
+    if (hasDecline(normalized, tokens, raw)) {
+        return 'decline';
+    }
+    if (hasInterrogative(normalized)) {
+        return 'ambiguous';
+    }
+    if (hasAffirm(normalized, tokens, raw)) {
+        return 'affirm';
+    }
+    return 'ambiguous';
+}

package/dist/flow/runFlow.js

@@ -1,3 +1,4 @@
+import { parseConfirmation } from './confirmParse.js';
 import { hasPendingUserInput } from '../runtime/channels/inputBuffer.js';
 import { collectUntilComplete } from './collectUntilComplete.js';
 import { isActionNode, isCollectNode, isDecideNode, isReplyNode, } from './nodeKinds.js';
@@ -46,6 +47,38 @@ function appendUserMessage(run, input) {
     const message = { role: 'user', content: input };
     run.messages = [...run.messages, message];
 }
+function latestUserText(run) {
+    for (let i = run.messages.length - 1; i >= 0; i -= 1) {
+        const message = run.messages[i];
+        if (message?.role === 'user' && typeof message.content === 'string') {
+            return message.content;
+        }
+    }
+    return '';
+}
+async function dispatchConfirmGate(node, run, driver, ctx) {
+    const gate = node.confirmGate;
+    if (!hasPendingUserInput(ctx.session) && ctx.turnInputConsumed) {
+        return { kind: 'stay' };
+    }
+    let input = '';
+    if (hasPendingUserInput(ctx.session)) {
+        const signal = await driver.awaitUser(ctx);
+        input = signal.input;
+        appendUserMessage(run, signal.input);
+    }
+    else {
+        input = latestUserText(run);
+    }
+    ctx.turnInputConsumed = true;
+    const verdict = parseConfirmation(input);
+    const branch = verdict === 'affirm'
+        ? gate.onConfirm
+        : verdict === 'decline'
+            ? gate.onDecline
+            : (gate.onAmbiguous ?? 'stay');
+    return normalizeTransition(branch);
+}
 function appendAssistantMessage(run, text) {
     if (!text.trim()) {
         return;
@@ -61,9 +94,15 @@ async function dispatchNode(node, run, driver, ctx) {
         return collectUntilComplete(node, run, driver, ctx);
     }
     if (isDecideNode(node)) {
+        if (node.confirmGate) {
+            return dispatchConfirmGate(node, run, driver, ctx);
+        }
         if (!driver.runStructured) {
             throw new Error('ChannelDriver.runStructured is required for decide nodes');
         }
+        if (!node.schema || !node.decide) {
+            throw new Error(`decide node "${node.id}" requires schema and decide`);
+        }
         // An interactive choice node (withChoices) reached when the turn's input was
         // already consumed by a prior node: its choices were presented on node-enter,
         // so wait for the user to actually pick rather than auto-deciding on stale

package/dist/index.d.ts

@@ -65,13 +65,15 @@ export type { AuditConfig, AuditEntryBase, AuditEntryType, AuditListOptions, Aud
 export type { RealtimeAudioClient, RealtimeSessionConfig, RealtimeAudioConfig, RealtimeToolResponse, RealtimeEventMap, RealtimeSessionHandle, } from './realtime/index.js';
 export type { Hooks } from './types/hooks.js';
 export type { HarnessHooks } from './types/runtime.js';
-export { defineAgent, defineFlow, reply, collect, action, decide, } from './authoring/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 type { Tool as EffectTool } from './types/effectTool.js';
 export type { AgentRoute } from './types/processors.js';
 export type { AgentConfig, Instructions } from './types/agentConfig.js';
-export type { Flow, FlowNode, Transition, CollectNode, DecideNode } from './types/flow.js';
+export type { Flow, FlowNode, Transition, CollectNode, DecideNode, ConfirmGate } from './types/flow.js';
+export { parseConfirmation } from './flow/confirmParse.js';
+export type { ConfirmVerdict } from './flow/confirmParse.js';
 export type { Route } from './types/route.js';
 export type { TurnHandle } from './types/stream.js';
 export type { HarnessStreamPart } from './types/stream.js';

package/dist/index.js

@@ -36,7 +36,8 @@ export { handoffFilters, removeToolHistory, keepRecentMessages, removeKeys, comp
 export { DefaultToolExecutor, DefaultConversationState, DefaultConversationEventLog, DefaultAgentStateController, createFoundation, } from './foundation/index.js';
 export { CapabilityHost, TriageCapability, ExtractionCapability, HandoffCapability, GuardrailCapability, AutoRetrieveCapability, PassThroughRefinement, PassThroughValidation, toGeminiDeclarations, toAISDKTools, } from './capabilities/index.js';
 export { filterAuditEntries } from './audit/index.js';
-export { defineAgent, defineFlow, reply, collect, action, decide, } from './authoring/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 { parseConfirmation } from './flow/confirmParse.js';
 export { createRuntime, Runtime, } from './runtime/Runtime.js';

package/dist/types/flow.d.ts

@@ -61,16 +61,30 @@ export interface ActionNode {
     outputSchema?: StandardSchemaV1;
     run: (state: FlowState, ctx: ActionContext) => Transition | Promise<Transition>;
 }
+export interface ConfirmGate {
+    onConfirm: Transition;
+    onDecline: Transition;
+    onAmbiguous?: Transition;
+}
 export interface DecideNode {
     kind: 'decide';
     id: string;
     instructions: Instructions;
-    schema: StandardSchemaV1;
+    schema?: StandardSchemaV1;
     choices?: ChoiceOption[];
-    decide: (data: unknown, state: FlowState) => Transition | Promise<Transition>;
+    confirmGate?: ConfirmGate;
+    decide?: (data: unknown, state: FlowState) => Transition | Promise<Transition>;
 }
 export declare function reply(node: Omit<ReplyNode, 'kind'>): ReplyNode;
 export declare function collect(node: Omit<CollectNode, 'kind'>): CollectNode;
 export declare function action(node: Omit<ActionNode, 'kind'>): ActionNode;
-export declare function decide(node: Omit<DecideNode, 'kind'>): DecideNode;
+export declare function decide(node: Omit<DecideNode, 'kind' | 'confirmGate'> & Required<Pick<DecideNode, 'schema' | 'decide'>>): DecideNode;
+export declare function confirmGate(node: {
+    id: string;
+    instructions: Instructions;
+    onConfirm: Transition;
+    onDecline: Transition;
+    onAmbiguous?: Transition;
+    choices?: ChoiceOption[];
+}): DecideNode;
 export declare function defineFlow(flow: Flow): Flow;

package/dist/types/flow.js

@@ -10,6 +10,19 @@ export function action(node) {
 export function decide(node) {
     return { kind: 'decide', ...node };
 }
+export function confirmGate(node) {
+    return {
+        kind: 'decide',
+        id: node.id,
+        instructions: node.instructions,
+        choices: node.choices,
+        confirmGate: {
+            onConfirm: node.onConfirm,
+            onDecline: node.onDecline,
+            onAmbiguous: node.onAmbiguous,
+        },
+    };
+}
 export function defineFlow(flow) {
     return flow;
 }

package/package.json

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