@kuralle-agents/core 0.7.0 → 0.7.1

package/dist/runtime/Runtime.js

@@ -5,8 +5,7 @@ import { TextDriver } from './channels/TextDriver.js';
 import { createRunContext } from './ctx.js';
 import { createEventBus, createTurnHandle } from '../events/TurnHandle.js';
 import { CoreToolExecutor } from '../tools/effect/index.js';
-import { createFsTool } from '../tools/fs/createFsTool.js';
-import { wireAgentSkills } from '../skills/wireAgentSkills.js';
+import { buildAgentToolSurface } from './buildAgentToolSurface.js';
 import { hostLoop } from './hostLoop.js';
 import { isDegradableRuntimeError } from '../flow/degradableErrors.js';
 import { SAFE_DEGRADED_MESSAGE } from '../flow/degrade.js';
@@ -17,8 +16,7 @@ import { SessionRunStore } from './durable/SessionRunStore.js';
 import { loadRecordedSteps } from './durable/replay.js';
 import { markSessionOutcome } from './outcomeMarking.js';
 import { resolveAgentPolicies } from './policies/resolvePolicies.js';
-import { buildAutoRetrieveProvider, buildKnowledgeProvider, buildMemoryService, runMemoryIngest, wireWorkingMemory, } from './grounding/index.js';
-import { resolveAgentWorkspace } from './resolveAgentWorkspace.js';
+import { buildAutoRetrieveProvider, buildKnowledgeProvider, buildMemoryService, runMemoryIngest, } from './grounding/index.js';
 import { SessionMutex } from './SessionMutex.js';
 export class Runtime {
     config;
@@ -66,38 +64,16 @@ export class Runtime {
                 sessionStore: this.sessionStore,
             });
             const policies = resolveAgentPolicies(opened.agent);
-            const agentTools = {
-                ...(this.config.tools ?? {}),
-                ...(opened.agent.tools ?? {}),
-                // 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 resolvedWorkspace = resolveAgentWorkspace(opened.agent.workspace);
-            if (resolvedWorkspace) {
-                agentTools.workspace = createFsTool({
-                    fs: resolvedWorkspace.fs,
-                    readOnly: resolvedWorkspace.readOnly,
-                });
-            }
-            const wiredWorkingMemory = await wireWorkingMemory(opened.agent, opened.session, this.config.defaultWorkingMemoryStore);
-            if (wiredWorkingMemory) {
-                agentTools.memory_block = wiredWorkingMemory.memoryBlockTool;
-            }
-            let skillPrompt;
-            let skillTools = {};
-            if (opened.agent.skills) {
-                const wired = await wireAgentSkills(opened.agent);
-                if (wired) {
-                    skillTools = wired.tools;
-                    Object.assign(agentTools, wired.tools);
-                    skillPrompt = wired.promptSections.map((s) => s.content).join('\n\n');
-                }
-            }
-            const workspaceTool = agentTools.workspace;
+            const knowledgeProvider = this.config.knowledge
+                ? buildKnowledgeProvider(this.config.knowledge)
+                : undefined;
+            const openingSurface = await buildAgentToolSurface(opened.agent, opened.session, {
+                configTools: this.config.tools,
+                knowledgeProvider,
+                defaultWorkingMemoryStore: this.config.defaultWorkingMemoryStore,
+            });
             const toolExecutor = new CoreToolExecutor({
-                tools: agentTools,
+                tools: openingSurface.executorTools,
                 enforcer: policies.enforcer,
                 agentId: opened.agent.id,
                 onInterim: (message) => {
@@ -113,9 +89,6 @@ export class Runtime {
             if (!model) {
                 throw new Error('Runtime requires agent.model or config.defaultModel');
             }
-            const knowledgeProvider = this.config.knowledge
-                ? buildKnowledgeProvider(this.config.knowledge)
-                : undefined;
             runCtx = await createRunContext({
                 session: opened.session,
                 runState: freshRunState,
@@ -137,23 +110,15 @@ export class Runtime {
                 memoryService: this.config.memoryService
                     ? buildMemoryService(this.config.memoryService, opened.agent)
                     : undefined,
-                fs: resolvedWorkspace?.fs,
+                fs: openingSurface.resolvedWorkspace?.fs,
             });
             // Agent base layer (ADR 0001): composed into every node turn by the drivers.
             runCtx.baseInstructions = opened.agent.instructions;
-            runCtx.globalTools = {
-                ...(opened.agent.globalTools ?? {}),
-                ...(workspaceTool && resolvedWorkspace?.readOnly !== false
-                    ? { workspace: workspaceTool }
-                    : {}),
-                ...skillTools,
-            };
+            runCtx.globalTools = openingSurface.globalTools;
             runCtx.outOfBandControl = opened.agent.experimental?.outOfBandControl ?? false;
-            runCtx.skillPrompt = skillPrompt;
-            runCtx.workingMemoryPrompt = wiredWorkingMemory?.promptSection;
-            runCtx.workingMemoryTools = wiredWorkingMemory
-                ? { memory_block: wiredWorkingMemory.memoryBlockTool }
-                : undefined;
+            runCtx.skillPrompt = openingSurface.skillPrompt;
+            runCtx.workingMemoryPrompt = openingSurface.workingMemoryPrompt;
+            runCtx.workingMemoryTools = openingSurface.workingMemoryTools;
             await this.hooks?.onStart?.(runCtx);
             const driver = opts.driver ?? new TextDriver();
             let activeAgent = opened.agent;
@@ -193,17 +158,22 @@ export class Runtime {
                         });
                         runCtx.runState.activeAgentId = loopResult.to;
                         activeAgent = target;
+                        const targetSurface = await buildAgentToolSurface(target, opened.session, {
+                            configTools: this.config.tools,
+                            knowledgeProvider,
+                            defaultWorkingMemoryStore: this.config.defaultWorkingMemoryStore,
+                        });
                         runCtx.autoRetrieve = knowledgeProvider
                             ? buildAutoRetrieveProvider(knowledgeProvider, target)
                             : undefined;
+                        runCtx.globalTools = targetSurface.globalTools;
+                        runCtx.skillPrompt = targetSurface.skillPrompt;
+                        runCtx.workingMemoryPrompt = targetSurface.workingMemoryPrompt;
+                        runCtx.workingMemoryTools = targetSurface.workingMemoryTools;
+                        runCtx.fs = targetSurface.resolvedWorkspace?.fs;
                         runCtx.memoryService = this.config.memoryService
                             ? buildMemoryService(this.config.memoryService, target)
                             : undefined;
-                        const targetWorkingMemory = await wireWorkingMemory(target, opened.session, this.config.defaultWorkingMemoryStore);
-                        runCtx.workingMemoryPrompt = targetWorkingMemory?.promptSection;
-                        runCtx.workingMemoryTools = targetWorkingMemory
-                            ? { memory_block: targetWorkingMemory.memoryBlockTool }
-                            : undefined;
                         await runCtx.runStore.putRunState(runCtx.runState);
                         continue;
                     }

package/dist/runtime/buildAgentToolSurface.d.ts

@@ -0,0 +1,20 @@
+import type { AgentConfig } from '../types/agentConfig.js';
+import type { Session } from '../types/session.js';
+import type { AnyTool } from '../types/effectTool.js';
+import type { PersistentMemoryStore } from '../memory/blocks/types.js';
+import type { KnowledgeProvider } from './KnowledgeProvider.js';
+import { type ResolvedAgentWorkspace } from './resolveAgentWorkspace.js';
+export interface AgentToolSurface {
+    executorTools: Record<string, AnyTool>;
+    globalTools: Record<string, AnyTool>;
+    workingMemoryTools?: Record<string, AnyTool>;
+    workingMemoryPrompt?: string;
+    skillPrompt?: string;
+    resolvedWorkspace?: ResolvedAgentWorkspace;
+}
+export interface BuildAgentToolSurfaceDeps {
+    configTools?: Record<string, AnyTool>;
+    knowledgeProvider?: KnowledgeProvider;
+    defaultWorkingMemoryStore?: PersistentMemoryStore;
+}
+export declare function buildAgentToolSurface(agent: AgentConfig, session: Session, deps: BuildAgentToolSurfaceDeps): Promise<AgentToolSurface>;

package/dist/runtime/buildAgentToolSurface.js

@@ -0,0 +1,56 @@
+import { createFsTool } from '../tools/fs/createFsTool.js';
+import { wireAgentSkills } from '../skills/wireAgentSkills.js';
+import { buildKnowledgeTool, wireWorkingMemory } from './grounding/index.js';
+import { resolveAgentWorkspace, } from './resolveAgentWorkspace.js';
+export async function buildAgentToolSurface(agent, session, deps) {
+    const executorTools = {
+        ...(deps.configTools ?? {}),
+        ...(agent.tools ?? {}),
+        ...(agent.globalTools ?? {}),
+    };
+    const resolvedWorkspace = resolveAgentWorkspace(agent.workspace);
+    let workspaceTool;
+    if (resolvedWorkspace) {
+        workspaceTool = createFsTool({
+            fs: resolvedWorkspace.fs,
+            readOnly: resolvedWorkspace.readOnly,
+        });
+        executorTools.workspace = workspaceTool;
+    }
+    const wiredWorkingMemory = await wireWorkingMemory(agent, session, deps.defaultWorkingMemoryStore);
+    if (wiredWorkingMemory) {
+        executorTools.memory_block = wiredWorkingMemory.memoryBlockTool;
+    }
+    let skillPrompt;
+    let skillTools = {};
+    if (agent.skills) {
+        const wired = await wireAgentSkills(agent);
+        if (wired) {
+            skillTools = wired.tools;
+            Object.assign(executorTools, wired.tools);
+            skillPrompt = wired.promptSections.map((s) => s.content).join('\n\n');
+        }
+    }
+    const knowledgeTool = deps.knowledgeProvider
+        ? buildKnowledgeTool(deps.knowledgeProvider, agent)
+        : undefined;
+    if (knowledgeTool) {
+        executorTools.knowledge_search = knowledgeTool;
+    }
+    const globalTools = {
+        ...(agent.globalTools ?? {}),
+        ...(workspaceTool && resolvedWorkspace?.readOnly !== false ? { workspace: workspaceTool } : {}),
+        ...skillTools,
+        ...(knowledgeTool ? { knowledge_search: knowledgeTool } : {}),
+    };
+    return {
+        executorTools,
+        globalTools,
+        workingMemoryPrompt: wiredWorkingMemory?.promptSection,
+        workingMemoryTools: wiredWorkingMemory
+            ? { memory_block: wiredWorkingMemory.memoryBlockTool }
+            : undefined,
+        skillPrompt,
+        resolvedWorkspace,
+    };
+}

package/dist/runtime/channels/TextDriver.js

@@ -82,7 +82,11 @@ export class TextDriver {
                             args: call.input,
                             toolCallId: call.toolCallId,
                         });
-                        const { result: toolResult, control, failed } = await executeModelToolCall(ctx, { toolName: call.toolName, input: call.input, toolCallId: call.toolCallId }, node.localTools);
+                        const { result: toolResult, control, failed } = await executeModelToolCall(ctx, { toolName: call.toolName, input: call.input, toolCallId: call.toolCallId }, {
+                            ...ctx.globalTools,
+                            ...(ctx.workingMemoryTools ?? {}),
+                            ...node.localTools,
+                        });
                         out.toolResults.push({
                             name: call.toolName,
                             args: call.input,

package/dist/runtime/channels/VoiceDriver.js

@@ -202,7 +202,11 @@ export class VoiceDriver {
             const onToolCall = (id, name, args) => {
                 void (async () => {
                     ctx.emit({ type: 'tool-call', toolName: name, args, toolCallId: id });
-                    const { result: toolResult, control, failed } = await executeModelToolCall(ctx, { toolName: name, input: args, toolCallId: id }, localTools);
+                    const { result: toolResult, control, failed } = await executeModelToolCall(ctx, { toolName: name, input: args, toolCallId: id }, {
+                        ...ctx.globalTools,
+                        ...(ctx.workingMemoryTools ?? {}),
+                        ...localTools,
+                    });
                     out.toolResults.push({ name, args, result: toolResult, toolCallId: id });
                     toolCallsMade.push({
                         toolCallId: id,

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/types/grounding.d.ts

@@ -1,5 +1,14 @@
 import type { MemoryBlockScope, PersistentMemoryConfig } from '../memory/blocks/types.js';
 export interface AgentKnowledge {
+    /** Whether the runtime retrieves automatically. Default: `true`.
+     *  - `true` (guaranteed): pre-inject retrieved knowledge before every
+     *    answering turn — always grounded; a fused routing turn pays the
+     *    retrieval cost (the price of a kept grounding promise).
+     *  - `false` (on-demand): the runtime does not auto-inject; instead the model
+     *    is given a `knowledge_search` tool and retrieves only when it answers, so
+     *    routing/dispatch turns pay zero retrieval tax (grounding becomes
+     *    model-discretion). `autoRetrieve` and the tool are mutually exclusive —
+     *    the boolean picks the invoker (runtime vs model), not a separate mode. */
     autoRetrieve?: boolean;
     sources?: string[];
 }

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/kuralle-core"
   },
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "A framework for structured conversational AI agents",
   "publishConfig": {
     "access": "public"
@@ -103,7 +103,7 @@
     "typescript": "^5.3.0",
     "vitest": "^3.2.4",
     "zod": "^4.0.0",
-    "@kuralle-agents/realtime-audio": "0.7.0"
+    "@kuralle-agents/realtime-audio": "0.7.1"
   },
   "dependencies": {
     "chrono-node": "^2.6.0"