@kuralle-agents/core 0.3.9 → 0.3.11

package/dist/index.d.ts

@@ -71,7 +71,7 @@ export { buildToolSet, toolToAiSdk, ToolApprovalDeniedError } from './tools/effe
 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, ConfirmGate } from './types/flow.js';
+export type { Flow, FlowNode, Transition, CollectNode, DecideNode, ConfirmGate, NodeGrounding, } from './types/flow.js';
 export { parseConfirmation } from './flow/confirmParse.js';
 export type { ConfirmVerdict } from './flow/confirmParse.js';
 export type { Route } from './types/route.js';
@@ -80,7 +80,7 @@ export type { HarnessStreamPart } from './types/stream.js';
 export type { ChoiceOption, ResolvedSelection } from './types/selection.js';
 export type { RunState, StepRecord } from './runtime/durable/types.js';
 export type { RunStore } from './runtime/durable/RunStore.js';
-export type { ChannelDriver, TextDriver, VoiceDriver } from './runtime/channels/index.js';
+export type { ChannelDriver, TextDriver } from './runtime/channels/index.js';
 export type { TurnResult } from './types/channel.js';
 export type { RunContext } from './types/run-context.js';
 export { createRuntime, Runtime, type HarnessConfig, type RunOptions, } from './runtime/Runtime.js';

package/dist/runtime/channels/TextDriver.js

@@ -6,7 +6,7 @@ import { consumePendingUserInput } from './inputBuffer.js';
 import { runSilentExtraction } from './extractionTurn.js';
 import { applyPreTurnPolicies, applyPostTurnPolicies } from '../policies/agentTurn.js';
 import { resolveMaxSteps } from '../policies/limits.js';
-import { appendGatherBlocks, runGatherPhase } from '../grounding/index.js';
+import { appendGatherBlocks, resolveNodeGatherScope, runGatherPhase } from '../grounding/index.js';
 export class TextDriver {
     toolDefs;
     maxSteps;
@@ -26,7 +26,8 @@ export class TextDriver {
             ctx.emit({ type: 'turn-end' });
             return { text: blocked, toolResults: [] };
         }
-        const gather = await runGatherPhase(ctx);
+        const scope = resolveNodeGatherScope(replyNode, ctx.runState.state, ctx.runState.messages);
+        const gather = await runGatherPhase(ctx, scope);
         const out = { text: '', toolResults: [] };
         const model = replyNode.model ?? ctx.model;
         const nodeSystem = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);

package/dist/runtime/channels/VoiceDriver.js

@@ -4,7 +4,7 @@ import { buildNodePrompt, resolveInstructions, composeSystem } from '../../flow/
 import { executeModelToolCall } from './executeModelTool.js';
 import { applyPreTurnPolicies, applyPostTurnPolicies } from '../policies/agentTurn.js';
 import { resolveMaxSteps } from '../policies/limits.js';
-import { appendGatherBlocks, runGatherPhase } from '../grounding/index.js';
+import { appendGatherBlocks, resolveNodeGatherScope, runGatherPhase } from '../grounding/index.js';
 import { resolveVoiceGeminiTools } from './voiceTools.js';
 export class VoiceDriver {
     client;
@@ -29,7 +29,8 @@ export class VoiceDriver {
             ctx.emit({ type: 'turn-end' });
             return { text: blocked, toolResults: [] };
         }
-        const gather = await runGatherPhase(ctx);
+        const scope = resolveNodeGatherScope(replyNode, ctx.runState.state, ctx.runState.messages);
+        const gather = await runGatherPhase(ctx, scope);
         const out = { text: '', toolResults: [] };
         const nodeSystem = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);
         const baseSystem = composeSystem(ctx.baseInstructions, nodeSystem, ctx.runState.state);
@@ -64,8 +65,15 @@ export class VoiceDriver {
         return out;
     }
     async runStructured(node, ctx) {
-        const system = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state);
+        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.model,
             schema,

package/dist/runtime/channels/index.js

@@ -1,4 +1,8 @@
 export { TextDriver, buildNodePrompt } from './TextDriver.js';
+// PAUSED: the realtime VoiceDriver is not on the primary (text) path and is not
+// re-exported from the package's headline API. It stays here for the realtime
+// stack (`@kuralle-agents/realtime-audio`) via the `/runtime` subpath. Text is
+// the primary primitive; cascaded voice runs over text (see livekit-plugin).
 export { VoiceDriver } from './VoiceDriver.js';
 export { resolveVoiceGeminiTools, v2ToolsToGemini } from './voiceTools.js';
 export { setPendingUserInput, consumePendingUserInput, peekPendingUserInput } from './inputBuffer.js';

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

@@ -1,6 +1,7 @@
-import type { RunContext } from '../../types/run-context.js';
+import type { GatherScope, RunContext } from '../../types/run-context.js';
+export type { GatherScope } from '../../types/run-context.js';
 export interface GatherResult {
     retrievalBlock?: string;
     memoryBlock?: string;
 }
-export declare function runGatherPhase(ctx: RunContext): Promise<GatherResult>;
+export declare function runGatherPhase(ctx: RunContext, scope?: GatherScope): Promise<GatherResult>;

package/dist/runtime/grounding/gather.js

@@ -1,5 +1,9 @@
-export async function runGatherPhase(ctx) {
-    const retrievalBlock = ctx.autoRetrieve ? await ctx.autoRetrieve.retrieve(ctx) : undefined;
-    const memoryBlock = ctx.memoryService?.preload ? await ctx.memoryService.preload(ctx) : undefined;
+export async function runGatherPhase(ctx, scope) {
+    const retrievalBlock = ctx.autoRetrieve && scope?.knowledge?.autoRetrieve !== false
+        ? await ctx.autoRetrieve.retrieve(ctx, scope)
+        : undefined;
+    const memoryBlock = ctx.memoryService?.preload && scope?.memory?.preload !== false
+        ? await ctx.memoryService.preload(ctx, scope)
+        : undefined;
     return { retrievalBlock, memoryBlock };
 }

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

@@ -1,4 +1,5 @@
 export { appendGatherBlocks, buildAutoRetrieveProvider, buildKnowledgeProvider, } from './knowledge.js';
 export { buildMemoryService, resetMissingUserIdWarningsForTests, runMemoryIngest, warnMissingUserId, } from './memory.js';
-export { runGatherPhase, type GatherResult } from './gather.js';
+export { runGatherPhase, type GatherResult, type GatherScope } from './gather.js';
+export { resolveNodeGatherScope } from './nodeScope.js';
 export { createInMemoryKnowledgeConfig, createInMemoryKnowledgeRetriever, type InMemoryKnowledgeDocument, } from './inMemoryKnowledge.js';

package/dist/runtime/grounding/index.js

@@ -1,4 +1,5 @@
 export { appendGatherBlocks, buildAutoRetrieveProvider, buildKnowledgeProvider, } from './knowledge.js';
 export { buildMemoryService, resetMissingUserIdWarningsForTests, runMemoryIngest, warnMissingUserId, } from './memory.js';
 export { runGatherPhase } from './gather.js';
+export { resolveNodeGatherScope } from './nodeScope.js';
 export { createInMemoryKnowledgeConfig, createInMemoryKnowledgeRetriever, } from './inMemoryKnowledge.js';

package/dist/runtime/grounding/knowledge.js

@@ -35,22 +35,23 @@ export function buildAutoRetrieveProvider(provider, agent) {
         return undefined;
     }
     const overrides = agent.knowledge;
-    const maxOutputTokens = provider.resolveConfig(overrides).maxOutputTokens;
     return {
-        retrieve: async (ctx) => {
-            const query = latestUserMessage(ctx);
+        retrieve: async (ctx, scope) => {
+            const query = scope?.query ?? latestUserMessage(ctx);
+            const merged = scope?.knowledge ? { ...overrides, ...scope.knowledge } : overrides;
             const cache = undefined;
-            const { results, events } = await provider.retrieve(query || ' ', cache, overrides, false);
+            const { results, events } = await provider.retrieve(query || ' ', cache, merged, false);
             for (const event of events) {
                 ctx.emit(event);
             }
-            const compiled = provider.getCompiledKnowledge(overrides);
+            const compiled = provider.getCompiledKnowledge(merged);
             const retrievalResults = results.length > 0 ? results : [];
             const combined = [
                 ...(compiled ? [{ text: compiled }] : []),
                 ...retrievalResults.map((result) => ({ text: result.text })),
             ];
-            return formatRetrievalBlock(combined, maxOutputTokens * 4);
+            const maxChars = provider.resolveConfig(merged).maxOutputTokens * 4;
+            return formatRetrievalBlock(combined, maxChars);
         },
     };
 }

package/dist/runtime/grounding/memory.js

@@ -31,16 +31,16 @@ export function buildMemoryService(service, agent) {
     }
     return {
         preload: preloadEnabled
-            ? async (ctx) => {
+            ? async (ctx, scope) => {
                 if (!ctx.session.userId) {
                     warnMissingUserId(ctx.session.id);
                     return undefined;
                 }
-                const userInput = latestUserMessage(ctx);
+                const userInput = scope?.query ?? latestUserMessage(ctx);
                 if (!userInput.trim()) {
                     return undefined;
                 }
-                const budget = agent.memory?.preload?.tokenBudget ?? 500;
+                const budget = scope?.memory?.tokenBudget ?? agent.memory?.preload?.tokenBudget ?? 500;
                 const block = await preloadMemoryContext(service, ctx.session, userInput, budget);
                 return block ? `\n\n${block}` : undefined;
             }

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

@@ -0,0 +1,4 @@
+import type { ModelMessage } from 'ai';
+import type { FlowState, ReplyNode } from '../../types/flow.js';
+import type { GatherScope } from '../../types/run-context.js';
+export declare function resolveNodeGatherScope(node: ReplyNode, state: FlowState, history: ModelMessage[]): GatherScope | undefined;

package/dist/runtime/grounding/nodeScope.js

@@ -0,0 +1,11 @@
+export function resolveNodeGatherScope(node, state, history) {
+    const g = node.grounding;
+    if (!g) {
+        return undefined;
+    }
+    return {
+        query: typeof g.query === 'function' ? g.query(state, history) : g.query,
+        knowledge: g.knowledge,
+        memory: g.memory,
+    };
+}

package/dist/types/flow.d.ts

@@ -1,5 +1,6 @@
-import type { LanguageModel, ToolSet } from 'ai';
+import type { LanguageModel, ModelMessage, ToolSet } from 'ai';
 import type { Instructions } from './agentConfig.js';
+import type { AgentKnowledgeOverrides } from './voice.js';
 import type { StandardSchemaV1 } from './standard-schema.js';
 import type { ContextStrategy } from './context.js';
 import type { TurnResult } from './channel.js';
@@ -17,6 +18,25 @@ export interface Flow {
     maxOscillations?: number;
 }
 export type FlowNode = ReplyNode | CollectNode | ActionNode | DecideNode;
+/** Per-node retrieval/memory scoping (W3). All optional; omitting `grounding`
+ *  entirely leaves the node grounded exactly as the agent-wide default. */
+export interface NodeGrounding {
+    /** Retrieval/memory query for this node. A fixed topic string, or a function
+     *  over current flow state + message history. Defaults to the last user message. */
+    query?: string | ((state: FlowState, history: ModelMessage[]) => string);
+    /** Node-scoped knowledge overrides, merged OVER the agent's (node wins). Most
+     *  useful: `filter` (restrict to a node-specific doc subset) and `autoRetrieve:false`
+     *  to skip retrieval for this node. `topK`/`maxOutputTokens` also honored. */
+    knowledge?: AgentKnowledgeOverrides & {
+        autoRetrieve?: boolean;
+    };
+    /** Node-scoped memory: `preload:false` skips memory preload for this node;
+     *  `tokenBudget` overrides the agent default for this node only. */
+    memory?: {
+        preload?: boolean;
+        tokenBudget?: number;
+    };
+}
 export type Transition = FlowNode | (() => FlowNode) | {
     goto: FlowNode | (() => FlowNode);
     data?: Record<string, unknown>;
@@ -35,6 +55,7 @@ export interface ReplyNode {
     tools?: ToolSet | ((state: FlowState) => ToolSet);
     model?: LanguageModel;
     context?: ContextStrategy;
+    grounding?: NodeGrounding;
     next?: (turn: TurnResult, state: FlowState) => Transition | Promise<Transition>;
 }
 export interface CollectNode {

package/dist/types/run-context.d.ts

@@ -9,6 +9,17 @@ import type { ValidationCapability } from '../capabilities/ValidationCapability.
 import type { Limits } from './guardrails.js';
 import type { AnyTool } from './effectTool.js';
 import type { Instructions } from './agentConfig.js';
+import type { AgentKnowledgeOverrides } from './voice.js';
+export interface GatherScope {
+    query?: string;
+    knowledge?: AgentKnowledgeOverrides & {
+        autoRetrieve?: boolean;
+    };
+    memory?: {
+        preload?: boolean;
+        tokenBudget?: number;
+    };
+}
 export interface EffectToolExecutor {
     execute(args: {
         name: string;
@@ -23,10 +34,10 @@ export interface EffectToolExecutor {
     getTool?(name: string): AnyTool | undefined;
 }
 export interface AutoRetrieveProvider {
-    retrieve(ctx: RunContext): Promise<string | undefined>;
+    retrieve(ctx: RunContext, scope?: GatherScope): Promise<string | undefined>;
 }
 export interface MemoryService {
-    preload?(ctx: RunContext): Promise<string | undefined>;
+    preload?(ctx: RunContext, scope?: GatherScope): Promise<string | undefined>;
     ingest?(ctx: RunContext): Promise<void>;
 }
 export interface HookRunner {

package/package.json

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