@kuralle-agents/core 0.4.1 → 0.6.0

package/dist/memory/index.d.ts

@@ -4,7 +4,11 @@ export { InMemoryMemoryService } from './stores/InMemoryMemoryService.js';
 export { preloadMemoryContext } from './preloadMemory.js';
 export { extractMemories } from './utils.js';
 export type { PersistentMemoryStore, PersistentMemoryBlock, PersistentMemoryConfig, MemoryBlockScope, } from './blocks/types.js';
+export type { WorkingMemoryBlockSpec, WorkingMemoryConfig } from '../types/grounding.js';
 export { DEFAULT_BLOCK_CHAR_LIMIT, DEFAULT_AUTO_LOAD_BLOCKS, } from './blocks/types.js';
+export { InMemoryPersistentMemoryStore } from './blocks/InMemoryPersistentMemoryStore.js';
 export { FilePersistentMemoryStore, type FilePersistentMemoryStoreOptions, } from './blocks/FilePersistentMemoryStore.js';
+export { RoutedPersistentMemoryStore, type RoutedPersistentMemoryStoreConfig, type MemoryRouteFn, } from './blocks/RoutedPersistentMemoryStore.js';
+export { TieredPersistentMemoryStore } from './blocks/TieredPersistentMemoryStore.js';
 export { scanMemoryWrite, type SafetyScanResult } from './blocks/safetyScanner.js';
 export { buildMemoryBlockTool, type MemoryBlockToolOptions } from './blocks/memoryBlockTool.js';

package/dist/memory/index.js

@@ -2,6 +2,9 @@ export { InMemoryMemoryService } from './stores/InMemoryMemoryService.js';
 export { preloadMemoryContext } from './preloadMemory.js';
 export { extractMemories } from './utils.js';
 export { DEFAULT_BLOCK_CHAR_LIMIT, DEFAULT_AUTO_LOAD_BLOCKS, } from './blocks/types.js';
+export { InMemoryPersistentMemoryStore } from './blocks/InMemoryPersistentMemoryStore.js';
 export { FilePersistentMemoryStore, } from './blocks/FilePersistentMemoryStore.js';
+export { RoutedPersistentMemoryStore, } from './blocks/RoutedPersistentMemoryStore.js';
+export { TieredPersistentMemoryStore } from './blocks/TieredPersistentMemoryStore.js';
 export { scanMemoryWrite } from './blocks/safetyScanner.js';
 export { buildMemoryBlockTool } from './blocks/memoryBlockTool.js';

package/dist/runtime/Runtime.d.ts

@@ -13,6 +13,7 @@ import type { ConversationOutcome, ConversationOutcomeMarkedBy } from '../outcom
 import type { selectHostTarget } from './select.js';
 import type { KnowledgeProviderConfig } from '../types/voice.js';
 import type { MemoryService as V1MemoryService } from '../memory/MemoryService.js';
+import type { PersistentMemoryStore } from '../memory/blocks/types.js';
 export interface HarnessConfig {
     agents: AgentConfig[];
     defaultAgentId: string;
@@ -26,6 +27,8 @@ export interface HarnessConfig {
     tools?: Record<string, AnyTool>;
     knowledge?: KnowledgeProviderConfig;
     memoryService?: V1MemoryService;
+    /** Default store for `agent.memory.workingMemory` when `workingMemory.store` is omitted. */
+    defaultWorkingMemoryStore?: PersistentMemoryStore;
 }
 export interface RunOptions {
     sessionId?: string;

package/dist/runtime/Runtime.js

@@ -5,6 +5,8 @@ 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 { hostLoop } from './hostLoop.js';
 import { isDegradableRuntimeError } from '../flow/degradableErrors.js';
 import { SAFE_DEGRADED_MESSAGE } from '../flow/degrade.js';
@@ -14,7 +16,8 @@ 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, } from './grounding/index.js';
+import { buildAutoRetrieveProvider, buildKnowledgeProvider, buildMemoryService, runMemoryIngest, wireWorkingMemory, } from './grounding/index.js';
+import { resolveAgentWorkspace } from './resolveAgentWorkspace.js';
 import { SessionMutex } from './SessionMutex.js';
 export class Runtime {
     config;
@@ -62,16 +65,38 @@ export class Runtime {
                 sessionStore: this.sessionStore,
             });
             const policies = resolveAgentPolicies(opened.agent);
-            const effectTools = {
+            const agentTools = {
                 ...(this.config.tools ?? {}),
-                ...(opened.agent.effectTools ?? {}),
+                ...(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 toolExecutor = new CoreToolExecutor({
-                tools: effectTools,
+                tools: agentTools,
                 enforcer: policies.enforcer,
                 agentId: opened.agent.id,
                 onInterim: (message) => {
@@ -111,11 +136,23 @@ export class Runtime {
                 memoryService: this.config.memoryService
                     ? buildMemoryService(this.config.memoryService, opened.agent)
                     : undefined,
+                fs: 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;
+            runCtx.globalTools = {
+                ...(opened.agent.globalTools ?? {}),
+                ...(workspaceTool && resolvedWorkspace?.readOnly !== false
+                    ? { workspace: workspaceTool }
+                    : {}),
+                ...skillTools,
+            };
             runCtx.outOfBandControl = opened.agent.experimental?.outOfBandControl ?? false;
+            runCtx.skillPrompt = skillPrompt;
+            runCtx.workingMemoryPrompt = wiredWorkingMemory?.promptSection;
+            runCtx.workingMemoryTools = wiredWorkingMemory
+                ? { memory_block: wiredWorkingMemory.memoryBlockTool }
+                : undefined;
             await this.hooks?.onStart?.(runCtx);
             const driver = opts.driver ?? new TextDriver();
             let activeAgent = opened.agent;
@@ -160,6 +197,11 @@ export class Runtime {
                         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/agentReply.js

@@ -1,3 +1,4 @@
+import { buildToolSet } from '../tools/effect/defineTool.js';
 export function buildAgentReplyNode(agent) {
     const label = agent.name ?? agent.id;
     const instructions = agent.instructions ??
@@ -6,7 +7,7 @@ export function buildAgentReplyNode(agent) {
         kind: 'reply',
         id: `${agent.id}__host`,
         instructions,
-        tools: agent.tools,
+        tools: agent.tools ? buildToolSet(agent.tools) : undefined,
         model: agent.model,
     };
 }

package/dist/runtime/channels/TextDriver.js

@@ -38,7 +38,7 @@ export class TextDriver {
         const out = { text: '', toolResults: [] };
         const model = replyNode.model ?? ctx.model;
         const nodeSystem = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);
-        const baseSystem = composeSystem(ctx.baseInstructions, nodeSystem, ctx.runState.state);
+        const baseSystem = composeSystem(ctx.baseInstructions, nodeSystem, ctx.runState.state, ctx.skillPrompt, ctx.workingMemoryPrompt);
         const system = appendGatherBlocks(baseSystem, [gather.retrievalBlock, gather.memoryBlock]);
         const messages = [...ctx.runState.messages];
         const aiTools = this.resolveTools(node, ctx);
@@ -137,7 +137,7 @@ export class TextDriver {
         return runSilentExtraction(node, ctx, ctx.controlModel, resolveMaxSteps(ctx.limits, this.maxSteps));
     }
     async runStructured(node, ctx) {
-        const system = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state);
+        const system = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state, ctx.skillPrompt, ctx.workingMemoryPrompt);
         return resolveStructuredDecide(node, ctx, system);
     }
     async awaitUser(ctx) {
@@ -149,6 +149,7 @@ export class TextDriver {
         const merged = {
             ...this.toolDefs,
             ...(ctx.globalTools ?? {}),
+            ...(ctx.workingMemoryTools ?? {}),
             ...(resolved.localTools ?? {}),
         };
         const aiTools = { ...resolved.tools };

package/dist/runtime/channels/VoiceDriver.js

@@ -63,9 +63,9 @@ export class VoiceDriver {
         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);
+        const baseSystem = composeSystem(ctx.baseInstructions, nodeSystem, ctx.runState.state, ctx.skillPrompt, ctx.workingMemoryPrompt);
         const system = appendGatherBlocks(baseSystem, [gather.retrievalBlock, gather.memoryBlock]);
-        const geminiTools = resolveVoiceGeminiTools(node, { ...this.toolDefs, ...(ctx.globalTools ?? {}) }, { siloFlowControl: ctx.outOfBandControl && !node.freeConversation });
+        const geminiTools = resolveVoiceGeminiTools(node, { ...this.toolDefs, ...(ctx.globalTools ?? {}), ...(ctx.workingMemoryTools ?? {}) }, { siloFlowControl: ctx.outOfBandControl && !node.freeConversation });
         const toolCallsMade = [];
         const maxSteps = resolveMaxSteps(ctx.limits, this.maxSteps);
         const mode = resolveStreamMode(ctx, node);
@@ -139,7 +139,7 @@ export class VoiceDriver {
         return out;
     }
     async runStructured(node, ctx) {
-        const system = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state);
+        const system = composeSystem(ctx.baseInstructions, resolveInstructions(node.instructions, ctx.runState.state), ctx.runState.state, ctx.skillPrompt, ctx.workingMemoryPrompt);
         return resolveStructuredDecide(node, ctx, system);
     }
     // Non-speaking collect extraction: uses the shared text-model extraction path

package/dist/runtime/channels/extractionTurn.js

@@ -15,7 +15,7 @@ import { buildNodePrompt, composeSystem } from '../../flow/nodeBuilders.js';
 export async function runSilentExtraction(node, ctx, model, maxSteps) {
     const replyNode = node.node;
     const nodeSystem = node.prompt || buildNodePrompt(replyNode, ctx.runState.state);
-    const system = composeSystem(ctx.baseInstructions, nodeSystem, ctx.runState.state);
+    const system = composeSystem(ctx.baseInstructions, nodeSystem, ctx.runState.state, ctx.skillPrompt, ctx.workingMemoryPrompt);
     const messages = [...ctx.runState.messages];
     const aiTools = resolveExtractionTools(node);
     const out = { text: '', toolResults: [] };

package/dist/runtime/ctx.d.ts

@@ -6,6 +6,7 @@ import type { RefinementCapability } from '../capabilities/RefinementCapability.
 import type { ValidationCapability } from '../capabilities/ValidationCapability.js';
 import type { InputProcessor, OutputProcessor } from '../types/processors.js';
 import type { Limits } from '../types/guardrails.js';
+import type { FileSystem } from '../types/filesystem.js';
 import type { RunState, StepRecord } from './durable/types.js';
 import type { RunStore } from './durable/RunStore.js';
 interface EffectClock {
@@ -29,6 +30,7 @@ export interface CtxDeps {
     limits?: Limits;
     autoRetrieve?: AutoRetrieveProvider;
     memoryService?: MemoryService;
+    fs?: FileSystem;
     bargeIn?: AbortSignal;
     abortSignal?: AbortSignal;
     clock?: EffectClock;

package/dist/runtime/ctx.js

@@ -108,6 +108,7 @@ function makeCtx(deps) {
         limits: deps.limits,
         autoRetrieve: deps.autoRetrieve,
         memoryService: deps.memoryService,
+        fs: deps.fs,
         bargeIn: deps.bargeIn,
         abortSignal: deps.abortSignal,
         turnInputConsumed: false,

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

@@ -0,0 +1,3 @@
+import type { PersistentMemoryStore } from '../../memory/blocks/types.js';
+export declare function registerNodeDefaultWorkingMemoryStore(factory: () => PersistentMemoryStore): void;
+export declare function getNodeDefaultWorkingMemoryStore(): (() => PersistentMemoryStore) | undefined;

package/dist/runtime/grounding/defaultStoreRegistry.js

@@ -0,0 +1,10 @@
+let nodeDefaultStoreFactory;
+export function registerNodeDefaultWorkingMemoryStore(factory) {
+    nodeDefaultStoreFactory = factory;
+}
+export function getNodeDefaultWorkingMemoryStore() {
+    if (typeof process === 'undefined' || !process.versions?.node) {
+        return undefined;
+    }
+    return nodeDefaultStoreFactory;
+}

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

@@ -1,5 +1,6 @@
 export { appendGatherBlocks, buildAutoRetrieveProvider, buildKnowledgeProvider, } 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';
 export { resolveNodeGatherScope } from './nodeScope.js';
 export { createInMemoryKnowledgeConfig, createInMemoryKnowledgeRetriever, type InMemoryKnowledgeDocument, } from './inMemoryKnowledge.js';

package/dist/runtime/grounding/index.js

@@ -1,5 +1,6 @@
 export { appendGatherBlocks, buildAutoRetrieveProvider, buildKnowledgeProvider, } 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';
 export { resolveNodeGatherScope } from './nodeScope.js';
 export { createInMemoryKnowledgeConfig, createInMemoryKnowledgeRetriever, } from './inMemoryKnowledge.js';

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

@@ -0,0 +1,19 @@
+import type { AgentConfig } from '../../types/agentConfig.js';
+import type { WorkingMemoryBlockSpec, WorkingMemoryConfig } from '../../types/grounding.js';
+import type { Session } from '../../types/session.js';
+import type { AnyTool } from '../../types/effectTool.js';
+import { type MemoryBlockScope, type PersistentMemoryStore } from '../../memory/blocks/types.js';
+export interface LoadedWorkingMemoryBlock {
+    scope: MemoryBlockScope;
+    key: string;
+    content: string;
+}
+export interface WiredWorkingMemory {
+    promptSection: string | undefined;
+    memoryBlockTool: AnyTool;
+}
+export declare function resolveWorkingMemoryStore(config: WorkingMemoryConfig, harnessDefault?: PersistentMemoryStore): PersistentMemoryStore;
+export declare function resolveWorkingMemoryOwner(scope: MemoryBlockScope, agentId: string, userId: string | undefined): string;
+export declare function loadWorkingMemoryBlocks(store: PersistentMemoryStore, autoLoad: WorkingMemoryBlockSpec[], resolveOwner: (scope: MemoryBlockScope) => string): Promise<LoadedWorkingMemoryBlock[]>;
+export declare function formatWorkingMemorySection(blocks: LoadedWorkingMemoryBlock[], autoLoad: WorkingMemoryBlockSpec[]): string | undefined;
+export declare function wireWorkingMemory(agent: AgentConfig, session: Session, harnessDefaultStore?: PersistentMemoryStore): Promise<WiredWorkingMemory | undefined>;

package/dist/runtime/grounding/workingMemory.js

@@ -0,0 +1,80 @@
+import { buildMemoryBlockTool } from '../../memory/blocks/memoryBlockTool.js';
+import { DEFAULT_AUTO_LOAD_BLOCKS, DEFAULT_BLOCK_CHAR_LIMIT, } from '../../memory/blocks/types.js';
+import { wrapAiSdkTool } from '../../tools/effect/wrapAiSdkTool.js';
+import { getNodeDefaultWorkingMemoryStore } from './defaultStoreRegistry.js';
+export function resolveWorkingMemoryStore(config, harnessDefault) {
+    if (config.store) {
+        return config.store;
+    }
+    if (harnessDefault) {
+        return harnessDefault;
+    }
+    const factory = getNodeDefaultWorkingMemoryStore();
+    if (factory) {
+        return factory();
+    }
+    throw new Error('[Kuralle] agent.memory.workingMemory requires a store. Pass workingMemory.store, ' +
+        'HarnessConfig.defaultWorkingMemoryStore, or import FilePersistentMemoryStore on Node.');
+}
+export function resolveWorkingMemoryOwner(scope, agentId, userId) {
+    return scope === 'agent' ? agentId : (userId ?? 'anonymous');
+}
+export async function loadWorkingMemoryBlocks(store, autoLoad, resolveOwner) {
+    const loaded = [];
+    for (const spec of autoLoad) {
+        const owner = resolveOwner(spec.scope);
+        const block = await store.loadBlock(spec.scope, owner, spec.key);
+        let content = block?.content?.trim() ?? '';
+        if (!content && spec.template) {
+            content = spec.template.trim();
+        }
+        if (content) {
+            loaded.push({ scope: spec.scope, key: spec.key, content });
+        }
+    }
+    return loaded;
+}
+export function formatWorkingMemorySection(blocks, autoLoad) {
+    if (autoLoad.length === 0) {
+        return undefined;
+    }
+    const byKey = new Map(blocks.map((b) => [`${b.scope}/${b.key}`, b]));
+    // Directive (Mastra-informed): the model must proactively maintain these blocks
+    // via the `memory_block` tool, not just read them. Rendered even when blocks are
+    // empty so a first-time conversation knows the capability exists.
+    const lines = [
+        '## Working memory',
+        '',
+        'You keep durable notes about the user and conversation in the blocks below, persisted across sessions. Use the `memory_block` tool to keep them current:',
+        '- When the user shares a durable fact or preference (name, account details, preferences, anything that may be referenced again), call `memory_block` with action `add`, the relevant block, and a short factual entry. Store proactively — if unsure whether it will matter later, store it.',
+        '- Answer questions about stored information from these blocks first; you do NOT need to call the tool to read them.',
+        '- Do not announce that you are saving, and do not call the tool when nothing relevant changed.',
+        '',
+    ];
+    for (const spec of autoLoad) {
+        const block = byKey.get(`${spec.scope}/${spec.key}`);
+        lines.push(`### ${spec.key} (${spec.scope})`);
+        lines.push(block?.content?.trim() || '(empty — add entries here as you learn them)');
+        lines.push('');
+    }
+    return lines.join('\n').trim();
+}
+export async function wireWorkingMemory(agent, session, harnessDefaultStore) {
+    const config = agent.memory?.workingMemory;
+    if (!config) {
+        return undefined;
+    }
+    const store = resolveWorkingMemoryStore(config, harnessDefaultStore);
+    const autoLoad = config.autoLoad ?? DEFAULT_AUTO_LOAD_BLOCKS;
+    const charLimit = config.defaultCharLimit ?? DEFAULT_BLOCK_CHAR_LIMIT;
+    const resolveOwner = (scope) => resolveWorkingMemoryOwner(scope, agent.id, session.userId);
+    const loaded = await loadWorkingMemoryBlocks(store, autoLoad, resolveOwner);
+    const promptSection = formatWorkingMemorySection(loaded, autoLoad);
+    const memoryBlockTool = wrapAiSdkTool('memory_block', buildMemoryBlockTool({
+        store,
+        resolveOwner,
+        charLimit,
+        scanForInjection: config.scanForInjection,
+    }));
+    return { promptSection, memoryBlockTool };
+}

package/dist/runtime/resolveAgentWorkspace.d.ts

@@ -0,0 +1,10 @@
+import type { FileSystem } from '../types/filesystem.js';
+export type AgentWorkspaceConfig = FileSystem | {
+    fs: FileSystem;
+    readOnly?: boolean;
+};
+export interface ResolvedAgentWorkspace {
+    fs: FileSystem;
+    readOnly: boolean;
+}
+export declare function resolveAgentWorkspace(workspace: AgentWorkspaceConfig | undefined): ResolvedAgentWorkspace | undefined;

package/dist/runtime/resolveAgentWorkspace.js

@@ -0,0 +1,9 @@
+export function resolveAgentWorkspace(workspace) {
+    if (!workspace) {
+        return undefined;
+    }
+    if (typeof workspace === 'object' && workspace !== null && 'fs' in workspace) {
+        return { fs: workspace.fs, readOnly: workspace.readOnly !== false };
+    }
+    return { fs: workspace, readOnly: true };
+}

package/dist/skills/SkillsCapability.d.ts

@@ -0,0 +1,10 @@
+import type { Capability, CapabilityAction, PromptSection, ToolDeclaration } from '../capabilities/index.js';
+import type { SkillMeta, SkillStoreLike } from '../types/skills.js';
+export declare class SkillsCapability implements Capability {
+    private readonly store;
+    private readonly metas;
+    constructor(store: SkillStoreLike, metas: SkillMeta[]);
+    getTools(): ToolDeclaration[];
+    getPromptSections(): PromptSection[];
+    processToolResult(_toolName: string, _args: unknown, _result: unknown): CapabilityAction | null;
+}

package/dist/skills/SkillsCapability.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+export class SkillsCapability {
+    store;
+    metas;
+    constructor(store, metas) {
+        this.store = store;
+        this.metas = metas;
+    }
+    getTools() {
+        return [
+            {
+                name: 'load_skill',
+                description: "Load a skill's full instructions by name when the task matches its description.",
+                parameters: z.object({
+                    name: z.string().describe('Skill name from the available skills list'),
+                }),
+                execute: async (args) => ({
+                    body: await this.store.loadBody(args.name),
+                }),
+            },
+            {
+                name: 'read_skill_resource',
+                description: 'Read a bundled resource file from a skill (reference docs, checklists, etc.).',
+                parameters: z.object({
+                    name: z.string().describe('Skill name'),
+                    path: z.string().describe('Relative resource path within the skill folder'),
+                }),
+                execute: async (args) => ({
+                    content: await this.store.loadResource(args.name, args.path),
+                }),
+            },
+        ];
+    }
+    getPromptSections() {
+        if (!this.metas.length)
+            return [];
+        const lines = this.metas.map((m) => `- ${m.name}: ${m.description}`).join('\n');
+        return [
+            {
+                role: 'context',
+                content: [
+                    '## Available skills',
+                    'Load a skill with load_skill when its description matches the task:',
+                    lines,
+                ].join('\n'),
+            },
+        ];
+    }
+    processToolResult(_toolName, _args, _result) {
+        return null;
+    }
+}

package/dist/skills/collectSkills.d.ts

@@ -0,0 +1,17 @@
+import type { AnyTool } from '../types/effectTool.js';
+import type { SkillLike, SkillSource, SkillStoreLike } from '../types/skills.js';
+export interface SkillWireAgent {
+    skills?: SkillSource;
+    tools?: Record<string, AnyTool>;
+    globalTools?: Record<string, AnyTool>;
+    flows?: Array<{
+        name: string;
+    }>;
+}
+export declare function isSkillStore(value: SkillSource): value is SkillStoreLike;
+export declare function collectRegisteredNames(agent: SkillWireAgent): Set<string>;
+export declare function validateSkillAllowedTools(skills: SkillLike[], registered: Set<string>): void;
+export declare function prepareSkillStore(source: SkillSource): Promise<{
+    store: SkillStoreLike;
+    skills: SkillLike[];
+}>;

package/dist/skills/collectSkills.js

@@ -0,0 +1,56 @@
+import { InlineSkillStore } from './inlineSkillStore.js';
+export function isSkillStore(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        'list' in value &&
+        typeof value.list === 'function');
+}
+async function collectSkillsFromSource(source) {
+    if (!isSkillStore(source)) {
+        return Array.isArray(source) ? source : [source];
+    }
+    if (typeof source.getAllSkills === 'function') {
+        const all = source.getAllSkills();
+        return Array.isArray(all) ? all : await all;
+    }
+    if (typeof source.loadAllSkills === 'function') {
+        return source.loadAllSkills();
+    }
+    const metas = await source.list();
+    const skills = [];
+    for (const meta of metas) {
+        const body = await source.loadBody(meta.name);
+        skills.push({ name: meta.name, description: meta.description, body });
+    }
+    return skills;
+}
+export function collectRegisteredNames(agent) {
+    const names = new Set();
+    for (const [key, tool] of Object.entries(agent.tools ?? {})) {
+        names.add(tool.name ?? key);
+    }
+    for (const [key, tool] of Object.entries(agent.globalTools ?? {})) {
+        names.add(tool.name ?? key);
+    }
+    for (const flow of agent.flows ?? []) {
+        names.add(flow.name);
+    }
+    return names;
+}
+export function validateSkillAllowedTools(skills, registered) {
+    for (const skill of skills) {
+        for (const toolName of skill.allowedTools ?? []) {
+            if (!registered.has(toolName)) {
+                throw new Error(`skill ${skill.name}: unknown tool ${toolName}`);
+            }
+        }
+    }
+}
+export async function prepareSkillStore(source) {
+    if (isSkillStore(source)) {
+        return { store: source, skills: await collectSkillsFromSource(source) };
+    }
+    const skills = Array.isArray(source) ? source : [source];
+    return { store: new InlineSkillStore(skills), skills };
+}

package/dist/skills/index.d.ts

@@ -0,0 +1,5 @@
+export { SkillsCapability } from './SkillsCapability.js';
+export { wireAgentSkills } from './wireAgentSkills.js';
+export type { WiredAgentSkills } from './wireAgentSkills.js';
+export { collectRegisteredNames, validateSkillAllowedTools, prepareSkillStore, isSkillStore, type SkillWireAgent, } from './collectSkills.js';
+export { InlineSkillStore } from './inlineSkillStore.js';

package/dist/skills/index.js

@@ -0,0 +1,4 @@
+export { SkillsCapability } from './SkillsCapability.js';
+export { wireAgentSkills } from './wireAgentSkills.js';
+export { collectRegisteredNames, validateSkillAllowedTools, prepareSkillStore, isSkillStore, } from './collectSkills.js';
+export { InlineSkillStore } from './inlineSkillStore.js';

package/dist/skills/inlineSkillStore.d.ts

@@ -0,0 +1,9 @@
+import type { SkillLike, SkillMeta, SkillStoreLike } from '../types/skills.js';
+export declare class InlineSkillStore implements SkillStoreLike {
+    private readonly byName;
+    constructor(skills: SkillLike[]);
+    list(): Promise<SkillMeta[]>;
+    loadBody(name: string): Promise<string>;
+    loadResource(name: string, path: string): Promise<string | Uint8Array>;
+    getAllSkills(): SkillLike[];
+}

package/dist/skills/inlineSkillStore.js

@@ -0,0 +1,37 @@
+export class InlineSkillStore {
+    byName;
+    constructor(skills) {
+        this.byName = new Map(skills.map((s) => [s.name, s]));
+    }
+    async list() {
+        return [...this.byName.values()].map((s) => ({
+            name: s.name,
+            description: s.description,
+        }));
+    }
+    async loadBody(name) {
+        const skill = this.byName.get(name);
+        if (!skill) {
+            throw new Error(`[skills] Skill "${name}" not found.`);
+        }
+        return skill.body;
+    }
+    async loadResource(name, path) {
+        const skill = this.byName.get(name);
+        if (!skill) {
+            throw new Error(`[skills] Skill "${name}" not found.`);
+        }
+        const normalized = path.trim().replace(/^\.?\//, '');
+        if (normalized.includes('..') || normalized.startsWith('/')) {
+            throw new Error(`[skills] Invalid resource path "${path}".`);
+        }
+        const content = skill.resources?.[normalized];
+        if (content === undefined) {
+            throw new Error(`[skills] Resource "${normalized}" not found for skill "${name}".`);
+        }
+        return content;
+    }
+    getAllSkills() {
+        return [...this.byName.values()];
+    }
+}

package/dist/skills/wireAgentSkills.d.ts

@@ -0,0 +1,10 @@
+import { type AnyTool } from '../types/effectTool.js';
+import type { PromptSection } from '../capabilities/index.js';
+import { type SkillWireAgent } from './collectSkills.js';
+import { SkillsCapability } from './SkillsCapability.js';
+export interface WiredAgentSkills {
+    capability: SkillsCapability;
+    tools: Record<string, AnyTool>;
+    promptSections: PromptSection[];
+}
+export declare function wireAgentSkills(agent: SkillWireAgent): Promise<WiredAgentSkills | undefined>;

package/dist/skills/wireAgentSkills.js

@@ -0,0 +1,25 @@
+import { defineTool } from '../types/effectTool.js';
+import { collectRegisteredNames, prepareSkillStore, validateSkillAllowedTools, } from './collectSkills.js';
+import { SkillsCapability } from './SkillsCapability.js';
+export async function wireAgentSkills(agent) {
+    if (!agent.skills)
+        return undefined;
+    const { store, skills } = await prepareSkillStore(agent.skills);
+    validateSkillAllowedTools(skills, collectRegisteredNames(agent));
+    const metas = await store.list();
+    const capability = new SkillsCapability(store, metas);
+    const tools = {};
+    for (const decl of capability.getTools()) {
+        tools[decl.name] = defineTool({
+            name: decl.name,
+            description: decl.description,
+            input: decl.parameters,
+            execute: async (args) => decl.execute(args),
+        });
+    }
+    return {
+        capability,
+        tools,
+        promptSections: capability.getPromptSections(),
+    };
+}