@compilr-dev/sdk 0.1.20 → 0.1.22

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/models/model-registry.js

@@ -17,7 +17,7 @@
  */
 export const MODEL_REGISTRY = [
     // ---------------------------------------------------------------------------
-    // Claude Models (Anthropic)
+    // Claude Models (Anthropic) — Current generation (4.6 + Haiku 4.5)
     // ---------------------------------------------------------------------------
     {
         id: 'claude-haiku-4-5-20251001',
@@ -30,8 +30,8 @@ export const MODEL_REGISTRY = [
         contextWindow: 200000,
     },
     {
-        id: 'claude-sonnet-4-5-20250929',
-        displayName: 'Sonnet 4.5',
+        id: 'claude-sonnet-4-6',
+        displayName: 'Sonnet 4.6',
         description: 'Balanced (recommended)',
         provider: 'claude',
         defaultTier: 'balanced',
@@ -40,8 +40,8 @@ export const MODEL_REGISTRY = [
         contextWindow: 200000,
     },
     {
-        id: 'claude-opus-4-5-20251101',
-        displayName: 'Opus 4.5',
+        id: 'claude-opus-4-6',
+        displayName: 'Opus 4.6',
         description: 'Most capable',
         provider: 'claude',
         defaultTier: 'powerful',
@@ -49,26 +49,36 @@ export const MODEL_REGISTRY = [
         status: 'supported',
         contextWindow: 200000,
     },
-    // Older Claude models (still supported)
+    // Legacy Claude models (still supported)
     {
-        id: 'claude-3-5-sonnet-20241022',
-        displayName: 'Sonnet 3.5',
+        id: 'claude-sonnet-4-5-20250929',
+        displayName: 'Sonnet 4.5',
+        description: 'Previous generation',
+        provider: 'claude',
+        thinkingFormat: 'claude',
+        status: 'supported',
+        contextWindow: 200000,
+        notes: 'Legacy — consider upgrading to Sonnet 4.6',
+    },
+    {
+        id: 'claude-opus-4-5-20251101',
+        displayName: 'Opus 4.5',
         description: 'Previous generation',
         provider: 'claude',
         thinkingFormat: 'claude',
         status: 'supported',
         contextWindow: 200000,
-        notes: 'Previous generation',
+        notes: 'Legacy — consider upgrading to Opus 4.6',
     },
     {
-        id: 'claude-3-5-haiku-20241022',
-        displayName: 'Haiku 3.5',
+        id: 'claude-sonnet-4-20250514',
+        displayName: 'Sonnet 4',
         description: 'Previous generation',
         provider: 'claude',
         thinkingFormat: 'claude',
         status: 'supported',
         contextWindow: 200000,
-        notes: 'Previous generation',
+        notes: 'Legacy',
     },
     // ---------------------------------------------------------------------------
     // Gemini Models (Google)
@@ -413,8 +423,8 @@ export const MODEL_REGISTRY = [
         status: 'supported',
     },
     {
-        id: 'anthropic/claude-3-5-sonnet',
-        displayName: 'Claude 3.5 Sonnet',
+        id: 'anthropic/claude-sonnet-4-6',
+        displayName: 'Claude Sonnet 4.6',
         description: 'Balanced (via OpenRouter)',
         provider: 'openrouter',
         defaultTier: 'balanced',
@@ -422,8 +432,8 @@ export const MODEL_REGISTRY = [
         status: 'supported',
     },
     {
-        id: 'anthropic/claude-3-opus',
-        displayName: 'Claude 3 Opus',
+        id: 'anthropic/claude-opus-4-6',
+        displayName: 'Claude Opus 4.6',
         description: 'Most capable (via OpenRouter)',
         provider: 'openrouter',
         defaultTier: 'powerful',

package/package.json

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