@compilr-dev/sdk 0.1.19 → 0.1.21

package/dist/capabilities/catalog.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Capability Catalog Generator
+ *
+ * Generates the system prompt section that lists available (loadable)
+ * capability packs for agent self-loading.
+ */
+import type { CapabilityCatalogEntry } from './types.js';
+/**
+ * Generate a system prompt section listing loadable capability packs.
+ *
+ * @param catalog - Entries from CapabilityManager.getCatalog()
+ * @param loadedPackIds - Currently loaded pack IDs (for "Currently loaded" line)
+ * @returns System prompt section string, or empty string if catalog is empty
+ */
+export declare function generateCapabilityCatalog(catalog: CapabilityCatalogEntry[], loadedPackIds: string[]): string;

package/dist/capabilities/catalog.js

@@ -0,0 +1,32 @@
+/**
+ * Capability Catalog Generator
+ *
+ * Generates the system prompt section that lists available (loadable)
+ * capability packs for agent self-loading.
+ */
+/**
+ * Generate a system prompt section listing loadable capability packs.
+ *
+ * @param catalog - Entries from CapabilityManager.getCatalog()
+ * @param loadedPackIds - Currently loaded pack IDs (for "Currently loaded" line)
+ * @returns System prompt section string, or empty string if catalog is empty
+ */
+export function generateCapabilityCatalog(catalog, loadedPackIds) {
+    if (catalog.length === 0) {
+        return '';
+    }
+    const lines = [
+        '## Available Capabilities',
+        '',
+        'Call `load_capability("name")` to activate additional tools:',
+    ];
+    for (const entry of catalog) {
+        const readOnlySuffix = entry.readOnly ? ', read-only' : '';
+        lines.push(`- ${entry.id}: ${entry.label} (${String(entry.toolCount)} tools${readOnlySuffix})`);
+    }
+    if (loadedPackIds.length > 0) {
+        lines.push('');
+        lines.push(`Currently loaded: ${loadedPackIds.join(', ')}`);
+    }
+    return lines.join('\n');
+}

package/dist/capabilities/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Dynamic Capability Loading
+ *
+ * Provides three-tier capability management for agents:
+ * - Upfront: always active (HOT tools ∩ profile)
+ * - Loadable: on-demand activation (sticky)
+ * - Forbidden: outside profile (triggers handoff)
+ */
+export type { CapabilityPack, CapabilityTier, LoadedCapability, CapabilityCatalogEntry, CapabilityLoadResult, } from './types.js';
+export { CAPABILITY_PACKS, FORBIDDEN_PACK_SUGGESTIONS, getPackCount, getAllPackIds, } from './packs.js';
+export { CapabilityManager } from './manager.js';
+export type { CapabilityManagerConfig } from './manager.js';
+export { createLoadCapabilityTool } from './load-tool.js';
+export { generateCapabilityCatalog } from './catalog.js';

package/dist/capabilities/index.js

@@ -0,0 +1,16 @@
+/**
+ * Dynamic Capability Loading
+ *
+ * Provides three-tier capability management for agents:
+ * - Upfront: always active (HOT tools ∩ profile)
+ * - Loadable: on-demand activation (sticky)
+ * - Forbidden: outside profile (triggers handoff)
+ */
+// Pack definitions
+export { CAPABILITY_PACKS, FORBIDDEN_PACK_SUGGESTIONS, getPackCount, getAllPackIds, } from './packs.js';
+// Manager
+export { CapabilityManager } from './manager.js';
+// Self-loading tool
+export { createLoadCapabilityTool } from './load-tool.js';
+// Catalog generator
+export { generateCapabilityCatalog } from './catalog.js';

package/dist/capabilities/load-tool.d.ts

@@ -0,0 +1,21 @@
+/**
+ * load_capability Tool
+ *
+ * Allows agents to self-load capability packs at runtime.
+ * When called, sets a pending load flag that the BeforeLLM hook
+ * picks up on the next turn.
+ */
+import type { Tool } from '@compilr-dev/agents';
+import type { CapabilityManager } from './manager.js';
+interface LoadCapabilityInput {
+    capability: string;
+}
+/**
+ * Create a load_capability tool bound to a CapabilityManager.
+ *
+ * The tool immediately loads the pack into the manager.
+ * The BeforeLLM hook will see the updated state on the next turn
+ * and rebuild the system prompt + tool filter accordingly.
+ */
+export declare function createLoadCapabilityTool(manager: CapabilityManager): Tool<LoadCapabilityInput>;
+export {};

package/dist/capabilities/load-tool.js

@@ -0,0 +1,62 @@
+/**
+ * load_capability Tool
+ *
+ * Allows agents to self-load capability packs at runtime.
+ * When called, sets a pending load flag that the BeforeLLM hook
+ * picks up on the next turn.
+ */
+import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/agents';
+/**
+ * Create a load_capability tool bound to a CapabilityManager.
+ *
+ * The tool immediately loads the pack into the manager.
+ * The BeforeLLM hook will see the updated state on the next turn
+ * and rebuild the system prompt + tool filter accordingly.
+ */
+export function createLoadCapabilityTool(manager) {
+    return defineTool({
+        name: 'load_capability',
+        description: 'Load a capability pack to gain access to additional tools. ' +
+            'See the "Available Capabilities" section in your instructions for pack IDs.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                capability: {
+                    type: 'string',
+                    description: 'Pack ID from the capability catalog (e.g., "git_read", "runners", "backlog_write")',
+                },
+            },
+            required: ['capability'],
+        },
+        silent: true,
+        execute: (input) => {
+            const { capability } = input;
+            // Check if already loaded
+            if (manager.isLoaded(capability)) {
+                return Promise.resolve(createSuccessResult({
+                    status: 'already_loaded',
+                    message: `Capability "${capability}" is already loaded.`,
+                }));
+            }
+            // Attempt to load
+            const tier = manager.getTier(capability);
+            if (tier === 'forbidden') {
+                const suggested = manager.getSuggestedAgent(capability);
+                const handoffHint = suggested
+                    ? ` Try: handoff("${suggested}", "Need ${capability} access")`
+                    : '';
+                return Promise.resolve(createErrorResult(`Capability "${capability}" is outside your tool profile.${handoffHint}`));
+            }
+            const success = manager.load(capability, 'agent-self');
+            if (success) {
+                return Promise.resolve(createSuccessResult({
+                    status: 'loaded',
+                    message: `Capability "${capability}" loaded. ` +
+                        'The tools will be available on your next response.',
+                }));
+            }
+            return Promise.resolve(createErrorResult(`Unknown capability pack: "${capability}". ` +
+                'Check the "Available Capabilities" section in your instructions.'));
+        },
+    });
+}

package/dist/capabilities/manager.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Dynamic Capability Loading — CapabilityManager
+ *
+ * Manages the three-tier loading model for an agent:
+ * - Upfront: always active from the start
+ * - Loadable: within profile, activated on demand (sticky)
+ * - Forbidden: outside profile, triggers handoff suggestion
+ */
+import type { CapabilityPack, CapabilityTier, LoadedCapability, CapabilityCatalogEntry, CapabilityLoadResult } from './types.js';
+export interface CapabilityManagerConfig {
+    /** All group IDs the agent's profile allows */
+    profileGroups: string[];
+    /** All pack definitions */
+    packs: Record<string, CapabilityPack>;
+    /** Group IDs to load upfront (HOT_TOOLS ∩ profile) */
+    upfrontGroups: string[];
+}
+export declare class CapabilityManager {
+    private readonly profileGroupSet;
+    private readonly packs;
+    private readonly loaded;
+    /** Reverse index: tool name → pack ID */
+    private readonly toolToPackIndex;
+    constructor(config: CapabilityManagerConfig);
+    /**
+     * Get the tier of a capability pack relative to this agent.
+     */
+    getTier(packId: string): CapabilityTier;
+    /**
+     * Load a capability pack. Returns false if forbidden.
+     * Once loaded, packs stay loaded (sticky mode).
+     */
+    load(packId: string, trigger: LoadedCapability['trigger']): boolean;
+    /**
+     * Load multiple packs for a skill invocation.
+     * Maps tool names to pack IDs, then loads each.
+     */
+    loadForSkill(toolNames: string[], trigger: LoadedCapability['trigger']): CapabilityLoadResult;
+    /**
+     * Get all currently loaded tool names (deduplicated).
+     */
+    getActiveToolNames(): string[];
+    /**
+     * Get prompt module IDs to include (deduplicated across loaded packs).
+     */
+    getActivePromptModuleIds(): Set<string>;
+    /**
+     * Get prompt snippets from loaded packs.
+     */
+    getActivePromptSnippets(): string[];
+    /**
+     * Get catalog of loadable (not yet loaded) packs for the system prompt.
+     */
+    getCatalog(): CapabilityCatalogEntry[];
+    /**
+     * Check if any loadable packs remain (not yet loaded).
+     */
+    hasLoadablePacks(): boolean;
+    /**
+     * Find which pack contains a given tool name.
+     */
+    findPackForTool(toolName: string): string | undefined;
+    /**
+     * Get suggested agent for a forbidden pack.
+     */
+    getSuggestedAgent(packId: string): string | undefined;
+    /**
+     * Get all loaded pack IDs.
+     */
+    getLoadedPackIds(): string[];
+    /**
+     * Check if a specific pack is loaded.
+     */
+    isLoaded(packId: string): boolean;
+    /**
+     * Token estimate for currently loaded state.
+     */
+    getTokenEstimate(): {
+        promptTokens: number;
+        toolTokens: number;
+    };
+}

package/dist/capabilities/manager.js

@@ -0,0 +1,223 @@
+/**
+ * Dynamic Capability Loading — CapabilityManager
+ *
+ * Manages the three-tier loading model for an agent:
+ * - Upfront: always active from the start
+ * - Loadable: within profile, activated on demand (sticky)
+ * - Forbidden: outside profile, triggers handoff suggestion
+ */
+import { FORBIDDEN_PACK_SUGGESTIONS } from './packs.js';
+export class CapabilityManager {
+    profileGroupSet;
+    packs;
+    loaded = new Map();
+    /** Reverse index: tool name → pack ID */
+    toolToPackIndex = new Map();
+    constructor(config) {
+        this.profileGroupSet = new Set(config.profileGroups);
+        this.packs = config.packs;
+        // Build tool → pack reverse index
+        for (const [packId, pack] of Object.entries(this.packs)) {
+            for (const tool of pack.tools) {
+                this.toolToPackIndex.set(tool, packId);
+            }
+        }
+        // Load upfront packs
+        for (const groupId of config.upfrontGroups) {
+            if (groupId in this.packs && this.profileGroupSet.has(groupId)) {
+                this.loaded.set(groupId, {
+                    packId: groupId,
+                    loadedAt: Date.now(),
+                    trigger: 'upfront',
+                });
+            }
+        }
+    }
+    /**
+     * Get the tier of a capability pack relative to this agent.
+     */
+    getTier(packId) {
+        if (this.loaded.has(packId)) {
+            return 'upfront'; // Already loaded (whether upfront or later)
+        }
+        if (this.profileGroupSet.has(packId)) {
+            return 'loadable';
+        }
+        return 'forbidden';
+    }
+    /**
+     * Load a capability pack. Returns false if forbidden.
+     * Once loaded, packs stay loaded (sticky mode).
+     */
+    load(packId, trigger) {
+        // Already loaded → no-op success
+        if (this.loaded.has(packId)) {
+            return true;
+        }
+        // Not in profile → forbidden
+        if (!this.profileGroupSet.has(packId)) {
+            return false;
+        }
+        // Pack must exist
+        if (!(packId in this.packs)) {
+            return false;
+        }
+        this.loaded.set(packId, {
+            packId,
+            loadedAt: Date.now(),
+            trigger,
+        });
+        return true;
+    }
+    /**
+     * Load multiple packs for a skill invocation.
+     * Maps tool names to pack IDs, then loads each.
+     */
+    loadForSkill(toolNames, trigger) {
+        const loaded = [];
+        const alreadyLoaded = [];
+        const forbidden = [];
+        // Deduplicate pack IDs from tool names
+        const packIds = new Set();
+        for (const toolName of toolNames) {
+            const packId = this.toolToPackIndex.get(toolName);
+            if (packId) {
+                packIds.add(packId);
+            }
+        }
+        for (const packId of packIds) {
+            if (this.loaded.has(packId)) {
+                alreadyLoaded.push(packId);
+            }
+            else if (this.load(packId, trigger)) {
+                loaded.push(packId);
+            }
+            else {
+                forbidden.push({
+                    packId,
+                    suggestedAgent: this.getSuggestedAgent(packId),
+                });
+            }
+        }
+        return {
+            success: forbidden.length === 0,
+            loaded,
+            alreadyLoaded,
+            forbidden,
+        };
+    }
+    /**
+     * Get all currently loaded tool names (deduplicated).
+     */
+    getActiveToolNames() {
+        const names = new Set();
+        for (const [packId] of this.loaded) {
+            const pack = this.packs[packId];
+            for (const tool of pack.tools) {
+                names.add(tool);
+            }
+        }
+        return [...names];
+    }
+    /**
+     * Get prompt module IDs to include (deduplicated across loaded packs).
+     */
+    getActivePromptModuleIds() {
+        const ids = new Set();
+        for (const [packId] of this.loaded) {
+            const pack = this.packs[packId];
+            for (const moduleId of pack.promptModules) {
+                ids.add(moduleId);
+            }
+        }
+        return ids;
+    }
+    /**
+     * Get prompt snippets from loaded packs.
+     */
+    getActivePromptSnippets() {
+        const snippets = [];
+        for (const [packId] of this.loaded) {
+            const pack = this.packs[packId];
+            if (pack.promptSnippet) {
+                snippets.push(pack.promptSnippet);
+            }
+        }
+        return snippets;
+    }
+    /**
+     * Get catalog of loadable (not yet loaded) packs for the system prompt.
+     */
+    getCatalog() {
+        const entries = [];
+        for (const [packId, pack] of Object.entries(this.packs)) {
+            // Only include packs that are loadable (in profile but not yet loaded)
+            if (this.profileGroupSet.has(packId) && !this.loaded.has(packId)) {
+                entries.push({
+                    id: pack.id,
+                    label: pack.label,
+                    toolCount: pack.tools.length,
+                    readOnly: pack.readOnly,
+                });
+            }
+        }
+        return entries;
+    }
+    /**
+     * Check if any loadable packs remain (not yet loaded).
+     */
+    hasLoadablePacks() {
+        for (const packId of this.profileGroupSet) {
+            if (!this.loaded.has(packId)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Find which pack contains a given tool name.
+     */
+    findPackForTool(toolName) {
+        return this.toolToPackIndex.get(toolName);
+    }
+    /**
+     * Get suggested agent for a forbidden pack.
+     */
+    getSuggestedAgent(packId) {
+        return FORBIDDEN_PACK_SUGGESTIONS[packId];
+    }
+    /**
+     * Get all loaded pack IDs.
+     */
+    getLoadedPackIds() {
+        return [...this.loaded.keys()];
+    }
+    /**
+     * Check if a specific pack is loaded.
+     */
+    isLoaded(packId) {
+        return this.loaded.has(packId);
+    }
+    /**
+     * Token estimate for currently loaded state.
+     */
+    getTokenEstimate() {
+        let promptTokens = 0;
+        let toolTokens = 0;
+        // Track seen prompt module IDs to avoid double-counting shared modules
+        const seenModules = new Set();
+        for (const [packId] of this.loaded) {
+            const pack = this.packs[packId];
+            // Count prompt tokens only for new modules
+            for (const moduleId of pack.promptModules) {
+                if (!seenModules.has(moduleId)) {
+                    seenModules.add(moduleId);
+                    promptTokens += pack.estimatedPromptTokens;
+                }
+            }
+            // Always count tool tokens (tools are unique per pack)
+            toolTokens += pack.estimatedToolTokens;
+        }
+        return { promptTokens, toolTokens };
+    }
+}

package/dist/capabilities/packs.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Dynamic Capability Loading — Pack Definitions
+ *
+ * Maps each tool group (from tool-config.ts) to a capability pack with
+ * associated prompt modules and usage guidance.
+ *
+ * 24 packs total, matching 1:1 with TOOL_GROUPS keys.
+ */
+import type { CapabilityPack } from './types.js';
+/**
+ * All capability pack definitions.
+ *
+ * Tool names are string literals (not imported from TOOL_NAMES) to keep the SDK
+ * independent of CLI-specific tool-names.ts. The CLI validates consistency at startup.
+ */
+export declare const CAPABILITY_PACKS: Record<string, CapabilityPack>;
+/**
+ * Mapping from forbidden pack IDs to suggested agent roles.
+ * Used for handoff suggestions when an agent tries to load a forbidden capability.
+ */
+export declare const FORBIDDEN_PACK_SUGGESTIONS: Record<string, string>;
+/**
+ * Get the total number of defined capability packs.
+ */
+export declare function getPackCount(): number;
+/**
+ * Get all pack IDs.
+ */
+export declare function getAllPackIds(): string[];

package/dist/capabilities/packs.js

@@ -0,0 +1,291 @@
+/**
+ * Dynamic Capability Loading — Pack Definitions
+ *
+ * Maps each tool group (from tool-config.ts) to a capability pack with
+ * associated prompt modules and usage guidance.
+ *
+ * 24 packs total, matching 1:1 with TOOL_GROUPS keys.
+ */
+/**
+ * All capability pack definitions.
+ *
+ * Tool names are string literals (not imported from TOOL_NAMES) to keep the SDK
+ * independent of CLI-specific tool-names.ts. The CLI validates consistency at startup.
+ */
+export const CAPABILITY_PACKS = {
+    // ============= DIRECT TOOL PACKS =============
+    file_read: {
+        id: 'file_read',
+        label: 'File Reading',
+        tools: ['read_file', 'glob', 'grep'],
+        readOnly: true,
+        promptModules: [],
+        estimatedPromptTokens: 0,
+        estimatedToolTokens: 900,
+    },
+    file_write: {
+        id: 'file_write',
+        label: 'File Writing',
+        tools: ['write_file', 'edit'],
+        readOnly: false,
+        promptModules: [],
+        estimatedPromptTokens: 0,
+        estimatedToolTokens: 600,
+    },
+    shell: {
+        id: 'shell',
+        label: 'Shell Commands',
+        tools: ['bash', 'bash_output', 'kill_shell'],
+        readOnly: false,
+        promptModules: [],
+        estimatedPromptTokens: 0,
+        estimatedToolTokens: 900,
+    },
+    tasks: {
+        id: 'tasks',
+        label: 'Task Tracking',
+        tools: ['todo_write', 'todo_read', 'todo_claim', 'todo_handoff'],
+        readOnly: false,
+        promptModules: [],
+        estimatedPromptTokens: 0,
+        estimatedToolTokens: 1200,
+    },
+    interaction: {
+        id: 'interaction',
+        label: 'User Interaction',
+        tools: ['ask_user', 'ask_user_simple', 'suggest'],
+        readOnly: true,
+        promptModules: [],
+        estimatedPromptTokens: 0,
+        estimatedToolTokens: 900,
+    },
+    coordinator: {
+        id: 'coordinator',
+        label: 'Coordination',
+        tools: ['delegate', 'delegate_background', 'delegation_status'],
+        readOnly: false,
+        promptModules: [],
+        estimatedPromptTokens: 0,
+        estimatedToolTokens: 900,
+    },
+    handoff: {
+        id: 'handoff',
+        label: 'Agent Handoff',
+        tools: ['handoff'],
+        readOnly: false,
+        promptModules: [],
+        estimatedPromptTokens: 0,
+        estimatedToolTokens: 300,
+    },
+    guide: {
+        id: 'guide',
+        label: 'CLI Documentation',
+        tools: ['compilr_guide'],
+        readOnly: true,
+        promptModules: [],
+        estimatedPromptTokens: 0,
+        estimatedToolTokens: 300,
+    },
+    meta: {
+        id: 'meta',
+        label: 'Tool Discovery',
+        tools: ['list_tools', 'get_tool_info', 'use_tool'],
+        readOnly: true,
+        promptModules: [],
+        estimatedPromptTokens: 0,
+        estimatedToolTokens: 900,
+    },
+    subagents: {
+        id: 'subagents',
+        label: 'Subagent Delegation',
+        tools: ['task'],
+        readOnly: false,
+        promptModules: [],
+        estimatedPromptTokens: 0,
+        estimatedToolTokens: 300,
+    },
+    // ============= META-REGISTRY TOOL PACKS =============
+    git_read: {
+        id: 'git_read',
+        label: 'Git (Read)',
+        tools: ['git_status', 'git_diff', 'git_log', 'git_blame', 'git_file_history'],
+        readOnly: true,
+        promptModules: ['git-safety'],
+        promptSnippet: 'Git read tools: git_status, git_diff, git_log, git_blame, git_file_history',
+        estimatedPromptTokens: 300,
+        estimatedToolTokens: 1500,
+    },
+    git_write: {
+        id: 'git_write',
+        label: 'Git (Write)',
+        tools: ['git_commit', 'git_branch', 'git_stash'],
+        readOnly: false,
+        promptModules: ['git-safety'],
+        promptSnippet: 'Git write tools: git_commit, git_branch, git_stash. Always check git_status before committing.',
+        estimatedPromptTokens: 300,
+        estimatedToolTokens: 900,
+    },
+    project: {
+        id: 'project',
+        label: 'Project Analysis',
+        tools: [
+            'detect_project',
+            'find_project_root',
+            'get_file_structure',
+            'get_complexity',
+            'read_function',
+            'read_class',
+            'read_type',
+        ],
+        readOnly: true,
+        promptModules: [],
+        promptSnippet: 'Project analysis: detect_project, find_project_root, get_file_structure, get_complexity, read_function, read_class, read_type',
+        estimatedPromptTokens: 30,
+        estimatedToolTokens: 2100,
+    },
+    runners: {
+        id: 'runners',
+        label: 'Runners (Test/Build/Lint)',
+        tools: ['run_tests', 'run_lint', 'run_build', 'run_format'],
+        readOnly: false,
+        promptModules: [],
+        promptSnippet: 'Runner tools: run_tests, run_lint, run_build, run_format',
+        estimatedPromptTokens: 15,
+        estimatedToolTokens: 1200,
+    },
+    search: {
+        id: 'search',
+        label: 'Code Search',
+        tools: ['find_definition', 'find_references', 'find_todos'],
+        readOnly: true,
+        promptModules: [],
+        promptSnippet: 'Code search: find_definition, find_references, find_todos',
+        estimatedPromptTokens: 15,
+        estimatedToolTokens: 900,
+    },
+    dependencies: {
+        id: 'dependencies',
+        label: 'Dependency Analysis',
+        tools: ['check_outdated', 'find_vulnerabilities', 'analyze_test_coverage'],
+        readOnly: true,
+        promptModules: [],
+        promptSnippet: 'Dependencies: check_outdated, find_vulnerabilities, analyze_test_coverage',
+        estimatedPromptTokens: 15,
+        estimatedToolTokens: 900,
+    },
+    backlog_read: {
+        id: 'backlog_read',
+        label: 'Backlog (Read)',
+        tools: ['workitem_query', 'workitem_status_counts'],
+        readOnly: true,
+        promptModules: ['platform-tool-hints'],
+        promptSnippet: 'Backlog read: workitem_query, workitem_status_counts',
+        estimatedPromptTokens: 120,
+        estimatedToolTokens: 600,
+    },
+    backlog_write: {
+        id: 'backlog_write',
+        label: 'Backlog (Write)',
+        tools: [
+            'workitem_add',
+            'workitem_update',
+            'workitem_delete',
+            'workitem_next',
+            'workitem_advance_step',
+            'workitem_claim',
+            'workitem_handoff',
+        ],
+        readOnly: false,
+        promptModules: ['platform-tool-hints'],
+        promptSnippet: 'Backlog write: workitem_add, workitem_update, workitem_delete, workitem_next, workitem_advance_step, workitem_claim, workitem_handoff. Use workitem_query before modifications.',
+        estimatedPromptTokens: 120,
+        estimatedToolTokens: 2100,
+    },
+    documents: {
+        id: 'documents',
+        label: 'Project Documents',
+        tools: [
+            'project_document_add',
+            'project_document_get',
+            'project_document_list',
+            'project_document_delete',
+        ],
+        readOnly: false,
+        promptModules: ['platform-tool-hints'],
+        promptSnippet: 'Documents stored in database, not filesystem. Use project_document_add/get/list/delete. Valid doc_types: prd, architecture, design, notes, session-note',
+        estimatedPromptTokens: 120,
+        estimatedToolTokens: 1200,
+    },
+    plans: {
+        id: 'plans',
+        label: 'Planning',
+        tools: ['plan_create', 'plan_update', 'plan_get', 'plan_list', 'plan_delete'],
+        readOnly: false,
+        promptModules: ['platform-tool-hints'],
+        promptSnippet: 'Plan tools: plan_create, plan_get, plan_list, plan_update, plan_delete. Status flow: draft → approved → in_progress → completed',
+        estimatedPromptTokens: 120,
+        estimatedToolTokens: 1500,
+    },
+    artifacts: {
+        id: 'artifacts',
+        label: 'Team Artifacts',
+        tools: ['artifact_save', 'artifact_get', 'artifact_list', 'artifact_delete'],
+        readOnly: false,
+        promptModules: ['platform-tool-hints'],
+        promptSnippet: 'Artifacts: artifact_save, artifact_get, artifact_list, artifact_delete. Types: design, plan, review, decision, note. Names must be unique within team.',
+        estimatedPromptTokens: 120,
+        estimatedToolTokens: 1200,
+    },
+    anchors: {
+        id: 'anchors',
+        label: 'Context Anchors',
+        tools: ['anchor_add', 'anchor_list', 'anchor_remove'],
+        readOnly: false,
+        promptModules: ['platform-tool-hints'],
+        promptSnippet: 'Anchors survive context compaction. Use "critical" priority sparingly. Most anchors should be "info" priority with "project" scope.',
+        estimatedPromptTokens: 120,
+        estimatedToolTokens: 900,
+    },
+    project_db: {
+        id: 'project_db',
+        label: 'Project Database',
+        tools: ['project_get', 'project_list', 'project_update'],
+        readOnly: false,
+        promptModules: ['platform-tool-hints'],
+        promptSnippet: 'Project database: project_get, project_list, project_update. Default to active project unless targeting a different one.',
+        estimatedPromptTokens: 120,
+        estimatedToolTokens: 900,
+    },
+};
+/**
+ * Mapping from forbidden pack IDs to suggested agent roles.
+ * Used for handoff suggestions when an agent tries to load a forbidden capability.
+ */
+export const FORBIDDEN_PACK_SUGGESTIONS = {
+    file_write: '$dev',
+    shell: '$dev',
+    git_write: '$dev',
+    runners: '$dev',
+    backlog_write: '$pm',
+    backlog_read: '$pm',
+    documents: '$pm',
+    plans: '$pm',
+    search: '$arch',
+    dependencies: '$arch',
+    coordinator: '$default',
+    artifacts: '$pm',
+    anchors: '$pm',
+    project_db: '$pm',
+};
+/**
+ * Get the total number of defined capability packs.
+ */
+export function getPackCount() {
+    return Object.keys(CAPABILITY_PACKS).length;
+}
+/**
+ * Get all pack IDs.
+ */
+export function getAllPackIds() {
+    return Object.keys(CAPABILITY_PACKS);
+}

package/dist/capabilities/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Dynamic Capability Loading — Types
+ *
+ * Capability packs bundle tools, prompt modules, and usage guidance.
+ * Each pack maps 1:1 to an existing tool group from tool-config.ts.
+ */
+/**
+ * A capability pack bundles tools with their associated prompt modules and guidance.
+ */
+export interface CapabilityPack {
+    /** Matches a TOOL_GROUPS key (e.g., 'git_read', 'backlog_write') */
+    id: string;
+    /** Human-readable label (e.g., 'Git (Read)', 'Backlog Management') */
+    label: string;
+    /** Tool names in this pack */
+    tools: readonly string[];
+    /** Whether all tools in this pack are read-only */
+    readOnly: boolean;
+    /** System prompt module IDs to inject when loaded (from modules.ts) */
+    promptModules: readonly string[];
+    /** Optional inline prompt snippet for pack-specific guidance */
+    promptSnippet?: string;
+    /** Estimated token cost: prompt modules + snippet */
+    estimatedPromptTokens: number;
+    /** Estimated token cost: tool schemas in meta-registry index */
+    estimatedToolTokens: number;
+}
+/**
+ * Three-tier loading model for each capability pack relative to an agent.
+ *
+ * - upfront: Always loaded from the start (HOT_TOOLS ∩ profile)
+ * - loadable: Within profile but not yet active; loaded on demand
+ * - forbidden: Outside the agent's tool profile; triggers handoff suggestion
+ */
+export type CapabilityTier = 'upfront' | 'loadable' | 'forbidden';
+/**
+ * Tracks when and how a capability was loaded.
+ */
+export interface LoadedCapability {
+    packId: string;
+    loadedAt: number;
+    trigger: 'upfront' | 'slash-command' | 'agent-self' | 'auto-detect';
+}
+/**
+ * Catalog entry shown in the agent's system prompt for self-loading.
+ */
+export interface CapabilityCatalogEntry {
+    id: string;
+    label: string;
+    toolCount: number;
+    readOnly: boolean;
+}
+/**
+ * Result of attempting to load capabilities (e.g., for a skill invocation).
+ */
+export interface CapabilityLoadResult {
+    success: boolean;
+    /** Packs that were loaded */
+    loaded: string[];
+    /** Packs that were already loaded */
+    alreadyLoaded: string[];
+    /** Packs that are forbidden (with suggested agent) */
+    forbidden: Array<{
+        packId: string;
+        suggestedAgent?: string;
+    }>;
+}

package/dist/capabilities/types.js

@@ -0,0 +1,7 @@
+/**
+ * Dynamic Capability Loading — Types
+ *
+ * Capability packs bundle tools, prompt modules, and usage guidance.
+ * Each pack maps 1:1 to an existing tool group from tool-config.ts.
+ */
+export {};

package/dist/index.d.ts

@@ -45,6 +45,8 @@ export { type ModelTier, type TierInfo, type ProviderModelMap, MODEL_TIERS, TIER
 export { assembleTools, deduplicateTools } from './tools.js';
 export { MetaToolsRegistry, createMetaTools, META_TOOLS_SYSTEM_PROMPT_PREFIX, } from './meta-tools/index.js';
 export type { MetaToolStats, MetaTools } from './meta-tools/index.js';
+export { CapabilityManager, CAPABILITY_PACKS, FORBIDDEN_PACK_SUGGESTIONS, getPackCount, getAllPackIds, createLoadCapabilityTool, generateCapabilityCatalog, } from './capabilities/index.js';
+export type { CapabilityPack, CapabilityTier, LoadedCapability, CapabilityCatalogEntry, CapabilityLoadResult, CapabilityManagerConfig, } from './capabilities/index.js';
 export { SystemPromptBuilder, buildSystemPrompt, detectGitRepository, getModuleStats, ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEMENT_MODULE, TOOL_USAGE_DIRECT_MODULE, TOOL_USAGE_HINTS_MODULE, PLATFORM_TOOL_HINTS_MODULE, FACTORY_TOOL_HINTS_MODULE, TOOL_USAGE_META_MODULE, DELEGATION_MODULE, GIT_SAFETY_MODULE, SUGGEST_MODULE, IMPORTANT_RULES_MODULE, ENVIRONMENT_MODULE, shouldIncludeModule, getEstimatedTokensForConditions, getTotalEstimatedTokens, } from './system-prompt/index.js';
 export type { SystemPromptContext, BuildResult, SystemPromptModule, ModuleConditions, } from './system-prompt/index.js';
 export type { ProjectType, ProjectStatus, RepoPattern, WorkflowMode, LifecycleState, WorkItemType, WorkItemStatus, WorkItemPriority, GuidedStep, DocumentType, PlanStatus, Project, WorkItem, ProjectDocument, Plan, PlanSummary, PlanWithWorkItem, HistoryEntry, CreateProjectInput, UpdateProjectInput, ProjectListOptions, CreateWorkItemInput, UpdateWorkItemInput, QueryWorkItemsInput, CreateDocumentInput, UpdateDocumentInput, CreatePlanInput, UpdatePlanInput, ListPlansOptions, WorkItemQueryResult, ProjectListResult, BulkCreateItem, IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, IAnchorService, IArtifactService, IEpisodeService, AnchorData, ArtifactType, ArtifactData, ArtifactSummaryData, WorkEpisode, ProjectWorkSummary, PlatformContext, PlatformToolsConfig, PlatformHooks, StepCriteria, } from './platform/index.js';

package/dist/index.js

@@ -65,6 +65,18 @@ export { assembleTools, deduplicateTools } from './tools.js';
 // =============================================================================
 export { MetaToolsRegistry, createMetaTools, META_TOOLS_SYSTEM_PROMPT_PREFIX, } from './meta-tools/index.js';
 // =============================================================================
+// Dynamic Capability Loading
+// =============================================================================
+export { 
+// Manager
+CapabilityManager, 
+// Pack definitions
+CAPABILITY_PACKS, FORBIDDEN_PACK_SUGGESTIONS, getPackCount, getAllPackIds, 
+// Self-loading tool
+createLoadCapabilityTool, 
+// Catalog generator
+generateCapabilityCatalog, } from './capabilities/index.js';
+// =============================================================================
 // System Prompt Builder
 // =============================================================================
 export { 

package/dist/meta-tools/registry.js

@@ -260,15 +260,17 @@ export function createMetaTools(registry) {
                     `Available tools include: ${availableTools.join(', ')}... ` +
                     `Check the Tool Index for the full list.`);
             }
-            // 2. Validate args
-            const validationError = registry.validateArgs(tool_name, args);
+            // 2. Coerce + validate args
+            const toolSchema = tool.definition.inputSchema;
+            const coercedArgs = coerceArgs(toolSchema, args);
+            const validationError = registry.validateArgs(tool_name, coercedArgs);
             if (validationError) {
                 return createErrorResult(`Invalid arguments for '${tool_name}': ${validationError}.\n` +
                     `Expected:\n${buildCompactSchema(tool)}`);
             }
             // 3. Execute the tool
             try {
-                const result = await tool.execute(args);
+                const result = await tool.execute(coercedArgs);
                 // Enhance result with clear top-level message for smaller models
                 if (result.success && typeof result.result === 'object' && result.result !== null) {
                     const innerResult = result.result;
@@ -307,15 +309,18 @@ export function createMetaTools(registry) {
                 return createErrorResult(`Tool '${name}' is not available for this agent. ` +
                     `Available tools: ${allowedTools.slice(0, 10).join(', ')}${allowedTools.length > 10 ? '...' : ''}`);
             }
+            // Coerce arguments before validation (handles LLM mistakes without guided decoding)
+            const toolSchema = tool.definition.inputSchema;
+            const coercedInput = coerceArgs(toolSchema, input);
             // Validate args
-            const validationError = registry.validateArgs(name, input);
+            const validationError = registry.validateArgs(name, coercedInput);
             if (validationError) {
                 return createErrorResult(`Invalid arguments for '${name}': ${validationError}. ` +
                     `Call get_tool_info("${name}") to get the exact parameter schema before retrying.`);
             }
             // Execute the tool
             try {
-                return await tool.execute(input);
+                return await tool.execute(coercedInput);
             }
             catch (err) {
                 const errorMessage = err instanceof Error ? err.message : String(err);
@@ -437,6 +442,26 @@ function buildCompactSchema(tool) {
                 detail += ' (required)';
             }
             paramDetails.push(detail);
+            // For array-of-objects, show item properties as indented sub-details
+            if (prop.type === 'array') {
+                const items = prop.items;
+                if (items?.type === 'object' && items.properties) {
+                    const itemProps = items.properties;
+                    const itemRequired = new Set(items.required ?? []);
+                    for (const [itemName, itemProp] of Object.entries(itemProps)) {
+                        const itemDesc = itemProp.description;
+                        const itemEnum = itemProp.enum;
+                        let itemDetail = `    - ${itemName}: ${resolveCompactType(itemProp)}`;
+                        if (itemDesc)
+                            itemDetail += ` — ${itemDesc}`;
+                        if (itemEnum)
+                            itemDetail += ` (${itemEnum.map((v) => `"${v}"`).join('|')})`;
+                        if (itemRequired.has(itemName))
+                            itemDetail += ' (required)';
+                        paramDetails.push(itemDetail);
+                    }
+                }
+            }
         }
     }
     const paramsStr = params.join(', ');
@@ -447,6 +472,45 @@ function buildCompactSchema(tool) {
     }
     return lines.join('\n');
 }
+/**
+ * Attempt to coerce arguments to match the tool schema.
+ * Handles common LLM mistakes when calling tools without guided decoding:
+ * - Single object where array expected → wraps in array
+ * - JSON string where array expected → parses it
+ */
+function coerceArgs(schema, args) {
+    const properties = schema.properties;
+    if (!properties)
+        return args;
+    let changed = false;
+    const coerced = { ...args };
+    for (const [name, prop] of Object.entries(properties)) {
+        if (prop.type === 'array' && name in coerced && !Array.isArray(coerced[name])) {
+            const value = coerced[name];
+            if (value !== null && value !== undefined) {
+                if (typeof value === 'object') {
+                    // Single object → wrap in array
+                    coerced[name] = [value];
+                    changed = true;
+                }
+                else if (typeof value === 'string') {
+                    // JSON string → try parsing
+                    try {
+                        const parsed = JSON.parse(value);
+                        if (Array.isArray(parsed)) {
+                            coerced[name] = parsed;
+                            changed = true;
+                        }
+                    }
+                    catch {
+                        // Leave as-is, will fail validation
+                    }
+                }
+            }
+        }
+    }
+    return changed ? coerced : args;
+}
 /**
  * Format AJV validation errors into a readable string.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",