@kuralle-agents/core 0.3.5 → 0.3.7

package/dist/flow/nodeBuilders.d.ts

@@ -4,5 +4,10 @@ import type { ResolvedNode } from '../types/channel.js';
 import type { Tool } from '../types/effectTool.js';
 export declare function resolveInstructions(instructions: Instructions, state: FlowState): string;
 export declare function buildNodePrompt(node: ReplyNode, state: FlowState): string;
+/** Compose the agent base layer (ADR 0001) into a node's system prompt: the
+ *  agent's base instructions (persona / safety / grounding) prefix the node's
+ *  own instructions. Node instructions layer ON TOP — they never replace the
+ *  base. Base resolves against the current state so dynamic base prompts work. */
+export declare function composeSystem(base: Instructions | undefined, nodeSystem: string, state: FlowState): string;
 export declare function resolveReplyNode(node: ReplyNode, state: FlowState): ResolvedNode;
 export declare function resolveCollectExtractionNode(collectNode: CollectNode, missing: string[], state: FlowState, submitTool: Tool): ResolvedNode;

package/dist/flow/nodeBuilders.js

@@ -15,6 +15,14 @@ export function resolveInstructions(instructions, state) {
 export function buildNodePrompt(node, state) {
     return resolveInstructions(node.instructions, state);
 }
+/** Compose the agent base layer (ADR 0001) into a node's system prompt: the
+ *  agent's base instructions (persona / safety / grounding) prefix the node's
+ *  own instructions. Node instructions layer ON TOP — they never replace the
+ *  base. Base resolves against the current state so dynamic base prompts work. */
+export function composeSystem(base, nodeSystem, state) {
+    const baseText = base ? resolveInstructions(base, state) : '';
+    return [baseText, nodeSystem].filter((s) => s && s.trim()).join('\n\n');
+}
 function buildNodeTools(node, state) {
     if (!node.tools) {
         return {};

package/dist/runtime/Runtime.js

@@ -61,6 +61,10 @@ export class Runtime {
             const effectTools = {
                 ...(this.config.tools ?? {}),
                 ...(opened.agent.effectTools ?? {}),
+                // Global tools (ADR 0001) are model-visible in speaking turns via the
+                // drivers; register their executors here too so a model call can actually
+                // run them. Visibility stays gated (not exposed during collect extraction).
+                ...(opened.agent.globalTools ?? {}),
             };
             const toolExecutor = new CoreToolExecutor({
                 tools: effectTools,
@@ -97,6 +101,9 @@ export class Runtime {
                     ? buildMemoryService(this.config.memoryService, opened.agent)
                     : undefined,
             });
+            // Agent base layer (ADR 0001): composed into every node turn by the drivers.
+            runCtx.baseInstructions = opened.agent.instructions;
+            runCtx.globalTools = opened.agent.globalTools;
             await this.hooks?.onStart?.(runCtx);
             const driver = opts.driver ?? new TextDriver();
             let activeAgent = opened.agent;

package/dist/runtime/channels/TextDriver.js

@@ -1,5 +1,5 @@
 import { streamText, generateObject } from 'ai';
-import { buildNodePrompt, resolveInstructions } from '../../flow/nodeBuilders.js';
+import { buildNodePrompt, resolveInstructions, composeSystem } from '../../flow/nodeBuilders.js';
 import { buildToolSet } from '../../tools/effect/index.js';
 import { classifyControl } from '../../flow/classifyControl.js';
 import { consumePendingUserInput } from './inputBuffer.js';
@@ -29,10 +29,11 @@ export class TextDriver {
         const gather = await runGatherPhase(ctx);
         const out = { text: '', toolResults: [] };
         const model = replyNode.model ?? ctx.model;
-        const baseSystem = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);
+        const nodeSystem = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);
+        const baseSystem = composeSystem(ctx.baseInstructions, nodeSystem, ctx.runState.state);
         const system = appendGatherBlocks(baseSystem, [gather.retrievalBlock, gather.memoryBlock]);
         const messages = [...ctx.runState.messages];
-        const aiTools = this.resolveTools(node);
+        const aiTools = this.resolveTools(node, ctx.globalTools);
         const maxSteps = resolveMaxSteps(ctx.limits, this.maxSteps);
         const toolCallsMade = [];
         let draftText = '';
@@ -135,7 +136,7 @@ export class TextDriver {
         return runSilentExtraction(node, ctx, model, resolveMaxSteps(ctx.limits, this.maxSteps));
     }
     async runStructured(node, ctx) {
-        const base = resolveInstructions(node.instructions, ctx.runState.state);
+        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
@@ -159,8 +160,8 @@ export class TextDriver {
         const input = consumePendingUserInput(ctx.session);
         return { type: 'message', input };
     }
-    resolveTools(resolved) {
-        const merged = { ...this.toolDefs, ...(resolved.localTools ?? {}) };
+    resolveTools(resolved, globalTools) {
+        const merged = { ...this.toolDefs, ...(globalTools ?? {}), ...(resolved.localTools ?? {}) };
         const aiTools = { ...resolved.tools };
         for (const [name, tool] of Object.entries(merged)) {
             if (tool && !aiTools[name]) {

package/dist/runtime/channels/VoiceDriver.js

@@ -1,6 +1,6 @@
 import { generateObject } from 'ai';
 import { runSilentExtraction } from './extractionTurn.js';
-import { buildNodePrompt, resolveInstructions } from '../../flow/nodeBuilders.js';
+import { buildNodePrompt, resolveInstructions, composeSystem } from '../../flow/nodeBuilders.js';
 import { classifyControl } from '../../flow/classifyControl.js';
 import { applyPreTurnPolicies, applyPostTurnPolicies } from '../policies/agentTurn.js';
 import { resolveMaxSteps } from '../policies/limits.js';
@@ -31,9 +31,10 @@ export class VoiceDriver {
         }
         const gather = await runGatherPhase(ctx);
         const out = { text: '', toolResults: [] };
-        const baseSystem = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);
+        const nodeSystem = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);
+        const baseSystem = composeSystem(ctx.baseInstructions, nodeSystem, ctx.runState.state);
         const system = appendGatherBlocks(baseSystem, [gather.retrievalBlock, gather.memoryBlock]);
-        const geminiTools = resolveVoiceGeminiTools(node, this.toolDefs);
+        const geminiTools = resolveVoiceGeminiTools(node, { ...this.toolDefs, ...(ctx.globalTools ?? {}) });
         const toolCallsMade = [];
         const maxSteps = resolveMaxSteps(ctx.limits, this.maxSteps);
         let draftText = '';
@@ -63,7 +64,7 @@ export class VoiceDriver {
         return out;
     }
     async runStructured(node, ctx) {
-        const system = resolveInstructions(node.instructions, ctx.runState.state);
+        const system = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state);
         const schema = node.schema;
         const { object } = await generateObject({
             model: ctx.model,

package/dist/runtime/channels/extractionTurn.js

@@ -1,6 +1,6 @@
 import { streamText } from 'ai';
 import { buildToolSet } from '../../tools/effect/index.js';
-import { buildNodePrompt } from '../../flow/nodeBuilders.js';
+import { buildNodePrompt, composeSystem } from '../../flow/nodeBuilders.js';
 /**
  * Shared, NON-SPEAKING field extraction for `collect` nodes, used by every
  * ChannelDriver so text and voice behave identically. It runs the model with the
@@ -13,7 +13,8 @@ import { buildNodePrompt } from '../../flow/nodeBuilders.js';
  */
 export async function runSilentExtraction(node, ctx, model, maxSteps) {
     const replyNode = node.node;
-    const system = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);
+    const nodeSystem = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);
+    const system = composeSystem(ctx.baseInstructions, nodeSystem, ctx.runState.state);
     const messages = [...ctx.runState.messages];
     const aiTools = resolveExtractionTools(node);
     const out = { text: '', toolResults: [] };

package/dist/types/agentConfig.d.ts

@@ -16,6 +16,12 @@ export interface AgentConfig {
     model?: LanguageModel;
     tools?: ToolSet;
     effectTools?: Record<string, AnyTool>;
+    /** Safe, always-available tools made model-visible in EVERY speaking node turn
+     *  (the agent "base layer", ADR 0001) — e.g. a returns/FAQ knowledge-base
+     *  lookup the user might ask for mid-flow. This is an explicit allow-list:
+     *  NEVER put consequential/mutating tools here (they must stay flow-gated), and
+     *  they are not exposed during non-speaking collect extraction. */
+    globalTools?: Record<string, AnyTool>;
     flows?: Flow[];
     routes?: Route[];
     routing?: RoutingPolicy;

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

@@ -8,6 +8,7 @@ import type { RefinementCapability } from '../capabilities/RefinementCapability.
 import type { ValidationCapability } from '../capabilities/ValidationCapability.js';
 import type { Limits } from './guardrails.js';
 import type { AnyTool } from './effectTool.js';
+import type { Instructions } from './agentConfig.js';
 export interface EffectToolExecutor {
     execute(args: {
         name: string;
@@ -57,6 +58,12 @@ export interface RunContext {
      * context. Reset to false on every `createRunContext` (i.e. every turn).
      */
     turnInputConsumed?: boolean;
+    /** Agent base layer (ADR 0001), set when entering a flow. `baseInstructions`
+     *  is composed as a prefix into every node turn's system prompt (persona /
+     *  safety / grounding floor); `globalTools` are safe tools made model-visible
+     *  in every speaking turn. */
+    baseInstructions?: Instructions;
+    globalTools?: Record<string, AnyTool>;
     tool(name: string, args: unknown, options?: {
         toolCallId?: string;
         def?: AnyTool;

package/package.json

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