@compilr-dev/sdk 0.2.15 → 0.3.0

package/dist/agent.js

@@ -6,6 +6,15 @@ import { resolveProvider } from './provider.js';
 import { resolvePreset } from './presets/index.js';
 import { assembleTools, deduplicateTools } from './tools.js';
 import { getContextWindow } from './models.js';
+// Capability loading imports
+import { TOOL_GROUPS } from './team/tool-config.js';
+import { CAPABILITY_PACKS } from './capabilities/packs.js';
+import { CapabilityManager } from './capabilities/manager.js';
+import { CapabilityContext } from './capabilities/context.js';
+import { createCapabilityHook } from './capabilities/hook.js';
+import { createLoadCapabilityTool } from './capabilities/load-tool.js';
+import { resolveProfileGroups, resolveUpfrontGroups } from './capabilities/profile-resolver.js';
+import { MetaToolsRegistry, createMetaTools } from './meta-tools/registry.js';
 /**
  * Convert an AgentRunResult to our simplified RunResult
  */
@@ -77,6 +86,8 @@ class CompilrAgentImpl {
     agent;
     abortController;
     totalUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+    /** Meta-tools fallback handler (set when capabilities.enabled) */
+    _metaToolsFallback;
     constructor(config) {
         this.abortController = new AbortController();
         // Resolve provider
@@ -98,8 +109,8 @@ class CompilrAgentImpl {
         else {
             systemPrompt = preset.systemPrompt;
         }
-        // Assemble tools
-        const tools = deduplicateTools(assembleTools(preset, config?.tools));
+        // Assemble all tools from preset + config
+        const allTools = deduplicateTools(assembleTools(preset, config?.tools));
         // Build context manager if configured
         let contextManager;
         if (config?.context) {
@@ -114,6 +125,110 @@ class CompilrAgentImpl {
         // Build agent config
         const permissionsConfig = buildPermissions(config?.permissions, preset.defaultPermissions, config?.permissionRules, config?.includeDefaultRules);
         const guardrailsConfig = buildGuardrails(config?.guardrails);
+        // Merge hooks: user-provided + capability hook (if enabled)
+        const capabilityHooks = [];
+        let finalTools = allTools;
+        // --- Dynamic Capability Loading ---
+        if (config?.capabilities?.enabled) {
+            const capConfig = config.capabilities;
+            // 1. Resolve profile → groups → upfront groups
+            const profileGroups = resolveProfileGroups(capConfig.profile ?? 'full');
+            const upfrontGroups = resolveUpfrontGroups(profileGroups);
+            // 2. Create capability manager
+            const manager = new CapabilityManager({
+                profileGroups,
+                packs: CAPABILITY_PACKS,
+                upfrontGroups,
+            });
+            // 3. Build direct-tier tool name set (tools in upfront groups)
+            const directToolNames = new Set();
+            for (const groupId of upfrontGroups) {
+                const group = TOOL_GROUPS[groupId];
+                for (const toolName of group.tools) {
+                    directToolNames.add(toolName);
+                }
+            }
+            // 4. Split tools into direct (registered on Agent) and meta (registry)
+            const directTools = [];
+            const metaRegistryTools = [];
+            for (const tool of allTools) {
+                const t = tool;
+                if (directToolNames.has(t.definition.name)) {
+                    directTools.push(t);
+                }
+                else {
+                    metaRegistryTools.push(t);
+                }
+            }
+            // 5. Initialize meta-tools registry
+            const registry = new MetaToolsRegistry();
+            const additionalTools = capConfig.additionalTools ?? [];
+            registry.initialize([...metaRegistryTools, ...additionalTools]);
+            // 6. Compute orphan tools (in registry but not in any capability pack)
+            const packedToolNames = new Set();
+            for (const pack of Object.values(CAPABILITY_PACKS)) {
+                for (const toolName of pack.tools) {
+                    packedToolNames.add(toolName);
+                }
+            }
+            const orphanTools = registry
+                .getRegisteredTools()
+                .map((t) => t.definition.name)
+                .filter((name) => !packedToolNames.has(name));
+            // 7. Create capability context with filter sync
+            const capCtx = new CapabilityContext({
+                manager,
+                orphanTools,
+                onFilterUpdate: (allowed) => {
+                    registry.setFilter(allowed);
+                },
+            });
+            capCtx.syncFilter();
+            // 8. Create meta-tools (get_tool_info) + fallback handler
+            const metaTools = createMetaTools(registry, {
+                onFilteredTool: (name) => capCtx.onFilteredTool(name),
+            });
+            // 9. Assemble final tool list: direct + get_tool_info + load_capability
+            finalTools = [...directTools, metaTools.getToolInfoTool];
+            if (manager.hasLoadablePacks()) {
+                finalTools.push(createLoadCapabilityTool(manager));
+            }
+            // 10. Create BeforeLLM hook for dynamic prompt assembly
+            const basePrompt = systemPrompt ?? '';
+            const capHook = createCapabilityHook(capCtx, basePrompt, {
+                maxAutoLoadsPerTurn: capConfig.maxAutoLoadsPerTurn,
+                conditionalModules: capConfig.conditionalModules,
+                staticSections: capConfig.staticSections,
+                getToolIndex: (allowedNames) => {
+                    registry.setFilter(allowedNames);
+                    return registry.getToolIndexForSystemPrompt();
+                },
+            });
+            capabilityHooks.push(capHook);
+            // Store registry for fallback handler setup (after Agent creation)
+            this._metaToolsFallback = metaTools.createFallback({
+                onFilteredTool: (name) => capCtx.onFilteredTool(name),
+            });
+        }
+        else {
+            // Legacy mode: register all tools directly (no capability loading)
+            finalTools = allTools;
+            // Include additional tools if provided (even without capabilities)
+            if (config?.capabilities?.additionalTools) {
+                finalTools = [...finalTools, ...config.capabilities.additionalTools];
+            }
+        }
+        // Merge hooks: capability hook + user-provided hooks
+        const mergedHooks = { ...config?.hooks };
+        if (capabilityHooks.length > 0) {
+            const existingBeforeLLM = config?.hooks?.beforeLLM;
+            const existingHooks = existingBeforeLLM
+                ? Array.isArray(existingBeforeLLM)
+                    ? existingBeforeLLM
+                    : [existingBeforeLLM]
+                : [];
+            mergedHooks.beforeLLM = [...existingHooks, ...capabilityHooks];
+        }
         this.agent = new Agent({
             provider,
             systemPrompt,
@@ -121,7 +236,7 @@ class CompilrAgentImpl {
             toolTimeoutMs: config?.toolTimeoutMs,
             contextManager,
             autoContextManagement: contextManager !== undefined,
-            hooks: config?.hooks,
+            hooks: mergedHooks,
             pins: {},
             permissions: {
                 defaultLevel: permissionsConfig.defaultLevel,
@@ -142,8 +257,12 @@ class CompilrAgentImpl {
                 }
             },
         });
-        // Register tools (cast AnyTool[] → Tool[] for the Agent API)
-        this.agent.registerTools(tools);
+        // Register tools
+        this.agent.registerTools(finalTools);
+        // Set fallback handler for meta-tools (if capabilities enabled)
+        if (this._metaToolsFallback) {
+            this.agent.getToolRegistry().setFallbackHandler(this._metaToolsFallback);
+        }
     }
     async run(message, options) {
         const result = await this.agent.run(message, {

package/dist/capabilities/auto-detect.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Auto-Detect Capabilities — scans agent messages for "Tool not found"
+ * errors and auto-loads the corresponding capability packs.
+ */
+import type { Message } from '@compilr-dev/agents';
+import type { CapabilityManager } from './manager.js';
+export interface AutoDetectResult {
+    /** Pack IDs that were auto-loaded */
+    loaded: string[];
+    /** Forbidden tool names with suggested agents */
+    forbidden: Array<{
+        toolName: string;
+        packId: string;
+        suggestedAgent?: string;
+    }>;
+}
+/**
+ * Scan recent messages for "Tool not found: X" errors and auto-load
+ * the corresponding capability packs (max N per turn, loadable only).
+ * Also detects forbidden tool access for handoff suggestions.
+ */
+export declare function autoDetectCapabilities(manager: CapabilityManager, messages: Message[], maxLoads?: number): AutoDetectResult;

package/dist/capabilities/auto-detect.js

@@ -0,0 +1,49 @@
+/**
+ * Auto-Detect Capabilities — scans agent messages for "Tool not found"
+ * errors and auto-loads the corresponding capability packs.
+ */
+/**
+ * Scan recent messages for "Tool not found: X" errors and auto-load
+ * the corresponding capability packs (max N per turn, loadable only).
+ * Also detects forbidden tool access for handoff suggestions.
+ */
+export function autoDetectCapabilities(manager, messages, maxLoads = 2) {
+    const result = { loaded: [], forbidden: [] };
+    const toolNotFoundPattern = /Tool not found: (\w+)/;
+    // Find the most recent user message (contains the last turn's tool results)
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg.role !== 'user' || typeof msg.content === 'string')
+            continue;
+        // Scan this message's tool_result blocks for "Tool not found" errors
+        for (const block of msg.content) {
+            if (block.type !== 'tool_result' || !block.isError || !block.content)
+                continue;
+            // Extract text from tool_result content (may be string or structured)
+            const rawContent = block.content;
+            const content = typeof rawContent === 'string' ? rawContent : String(rawContent);
+            const match = toolNotFoundPattern.exec(content);
+            if (!match)
+                continue;
+            const toolName = match[1];
+            const packId = manager.findPackForTool(toolName);
+            if (!packId || manager.isLoaded(packId))
+                continue;
+            const tier = manager.getTier(packId);
+            if (tier === 'loadable' && result.loaded.length < maxLoads) {
+                manager.load(packId, 'auto-detect');
+                result.loaded.push(packId);
+            }
+            else if (tier === 'forbidden') {
+                result.forbidden.push({
+                    toolName,
+                    packId,
+                    suggestedAgent: manager.getSuggestedAgent(packId),
+                });
+            }
+        }
+        // Only scan the most recent user message
+        break;
+    }
+    return result;
+}

package/dist/capabilities/context.d.ts

@@ -0,0 +1,46 @@
+/**
+ * CapabilityContext — encapsulates the CapabilityManager + meta-tool
+ * filter synchronization for a single agent.
+ *
+ * Replaces the CLI's global setCapabilityManager/getCapabilityManager
+ * pattern with a per-agent instance.
+ */
+import type { CapabilityManager } from './manager.js';
+export interface CapabilityContextConfig {
+    manager: CapabilityManager;
+    /**
+     * Tools in the meta-registry that aren't in any capability pack.
+     * These are always visible regardless of which packs are loaded.
+     */
+    orphanTools: string[];
+    /**
+     * Callback to update the meta-tool filter with allowed tool names.
+     * Called whenever loaded packs change (auto-detect, auto-load, manual load).
+     */
+    onFilterUpdate: (allowedTools: string[]) => void;
+}
+export declare class CapabilityContext {
+    readonly manager: CapabilityManager;
+    private readonly orphanTools;
+    private readonly onFilterUpdate;
+    constructor(config: CapabilityContextConfig);
+    /**
+     * Update the meta-tool filter to match current loaded state.
+     * Call after loading packs or during BeforeLLM hook.
+     */
+    syncFilter(): void;
+    /**
+     * Get all currently allowed tool names (loaded packs + orphans).
+     */
+    getAllowedToolNames(): string[];
+    /**
+     * Auto-load callback for meta-registry fallback.
+     *
+     * When the agent tries to call a tool that's in the meta-registry
+     * but filtered out, this callback loads the corresponding pack
+     * and updates the filter so the tool can be retried.
+     *
+     * @returns true if the tool was successfully loaded (retry the call)
+     */
+    onFilteredTool(toolName: string): boolean;
+}

package/dist/capabilities/context.js

@@ -0,0 +1,50 @@
+/**
+ * CapabilityContext — encapsulates the CapabilityManager + meta-tool
+ * filter synchronization for a single agent.
+ *
+ * Replaces the CLI's global setCapabilityManager/getCapabilityManager
+ * pattern with a per-agent instance.
+ */
+export class CapabilityContext {
+    manager;
+    orphanTools;
+    onFilterUpdate;
+    constructor(config) {
+        this.manager = config.manager;
+        this.orphanTools = config.orphanTools;
+        this.onFilterUpdate = config.onFilterUpdate;
+    }
+    /**
+     * Update the meta-tool filter to match current loaded state.
+     * Call after loading packs or during BeforeLLM hook.
+     */
+    syncFilter() {
+        const activeTools = this.manager.getActiveToolNames();
+        this.onFilterUpdate([...activeTools, ...this.orphanTools]);
+    }
+    /**
+     * Get all currently allowed tool names (loaded packs + orphans).
+     */
+    getAllowedToolNames() {
+        return [...this.manager.getActiveToolNames(), ...this.orphanTools];
+    }
+    /**
+     * Auto-load callback for meta-registry fallback.
+     *
+     * When the agent tries to call a tool that's in the meta-registry
+     * but filtered out, this callback loads the corresponding pack
+     * and updates the filter so the tool can be retried.
+     *
+     * @returns true if the tool was successfully loaded (retry the call)
+     */
+    onFilteredTool(toolName) {
+        const packId = this.manager.findPackForTool(toolName);
+        if (!packId || this.manager.isLoaded(packId))
+            return false;
+        if (this.manager.getTier(packId) !== 'loadable')
+            return false;
+        this.manager.load(packId, 'auto-load');
+        this.syncFilter();
+        return true;
+    }
+}

package/dist/capabilities/hook.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Capability Hook — BeforeLLM hook that dynamically rebuilds the
+ * system prompt based on loaded capability packs.
+ *
+ * Responsibilities:
+ * 1. Auto-detect "Tool not found" in recent messages → auto-load packs
+ * 2. Sync meta-tool filter with loaded state
+ * 3. Rebuild system prompt with dynamic sections (modules, snippets, catalog)
+ * 4. Preserve anchor blocks from agent library injection
+ * 5. Inject forbidden tool boundary hints as messages
+ */
+import type { Message, BeforeLLMHookResult } from '@compilr-dev/agents';
+import type { CapabilityContext } from './context.js';
+/**
+ * A conditional system prompt module that gets included
+ * when certain capability packs are loaded.
+ */
+export interface ConditionalModule {
+    /** Module content to append to the system prompt */
+    content: string;
+    /** Include when ANY of these prompt module IDs are active */
+    whenModuleActive: string[];
+}
+export interface CapabilityHookConfig {
+    /** Max packs to auto-load per turn from "Tool not found" detection */
+    maxAutoLoadsPerTurn?: number;
+    /** Conditional prompt modules to include based on loaded packs */
+    conditionalModules?: ConditionalModule[];
+    /**
+     * Callback to generate the filtered tool index section.
+     * Receives the list of currently allowed tool names.
+     * Should return a string to append to the system prompt (e.g., meta-tool index).
+     */
+    getToolIndex?: (allowedToolNames: string[]) => string;
+    /**
+     * Static prompt section to always include (e.g., meta-tools protocol).
+     * Appended before conditional modules.
+     */
+    staticSections?: string[];
+}
+/**
+ * Create a BeforeLLM hook that dynamically manages the system prompt
+ * based on loaded capabilities.
+ *
+ * @param ctx - CapabilityContext for this agent
+ * @param basePrompt - Base system prompt (without dynamic sections)
+ * @param config - Optional configuration
+ */
+export declare function createCapabilityHook(ctx: CapabilityContext, basePrompt: string, config?: CapabilityHookConfig): (hookCtx: {
+    messages: Message[];
+    systemPrompt: string;
+}) => BeforeLLMHookResult;

package/dist/capabilities/hook.js

@@ -0,0 +1,110 @@
+/**
+ * Capability Hook — BeforeLLM hook that dynamically rebuilds the
+ * system prompt based on loaded capability packs.
+ *
+ * Responsibilities:
+ * 1. Auto-detect "Tool not found" in recent messages → auto-load packs
+ * 2. Sync meta-tool filter with loaded state
+ * 3. Rebuild system prompt with dynamic sections (modules, snippets, catalog)
+ * 4. Preserve anchor blocks from agent library injection
+ * 5. Inject forbidden tool boundary hints as messages
+ */
+import { autoDetectCapabilities } from './auto-detect.js';
+import { generateCapabilityCatalog } from './catalog.js';
+/**
+ * Create a BeforeLLM hook that dynamically manages the system prompt
+ * based on loaded capabilities.
+ *
+ * @param ctx - CapabilityContext for this agent
+ * @param basePrompt - Base system prompt (without dynamic sections)
+ * @param config - Optional configuration
+ */
+export function createCapabilityHook(ctx, basePrompt, config) {
+    const maxAutoLoads = config?.maxAutoLoadsPerTurn ?? 2;
+    const conditionalModules = config?.conditionalModules ?? [];
+    const staticSections = config?.staticSections ?? [];
+    const getToolIndex = config?.getToolIndex;
+    return (hookCtx) => {
+        const manager = ctx.manager;
+        // 1. Auto-detect capability needs from tool failures (safety net)
+        let forbiddenHints = [];
+        if (manager.hasLoadablePacks() || hookCtx.messages.length > 1) {
+            const detected = autoDetectCapabilities(manager, hookCtx.messages, maxAutoLoads);
+            if (detected.forbidden.length > 0) {
+                forbiddenHints = detected.forbidden.map((f) => {
+                    const agentHint = f.suggestedAgent
+                        ? ` Consider using handoff("${f.suggestedAgent}", "Need ${f.packId} access for ${f.toolName}").`
+                        : '';
+                    return `[System] Tool "${f.toolName}" requires ${f.packId} capability which is outside your tool profile.${agentHint}`;
+                });
+            }
+        }
+        // 2. Sync meta-tool filter with current loaded state
+        ctx.syncFilter();
+        // 3. Build dynamic system prompt sections
+        const dynamicSections = [];
+        // Static sections (e.g., meta-tools protocol)
+        for (const section of staticSections) {
+            dynamicSections.push(section);
+        }
+        // Conditional modules based on loaded packs
+        const activeModuleIds = manager.getActivePromptModuleIds();
+        for (const mod of conditionalModules) {
+            if (mod.whenModuleActive.some((id) => activeModuleIds.has(id))) {
+                dynamicSections.push(mod.content);
+            }
+        }
+        // Prompt snippets from loaded packs
+        const snippets = manager.getActivePromptSnippets();
+        if (snippets.length > 0) {
+            dynamicSections.push('## Active Tool Capabilities\n' + snippets.join('\n'));
+        }
+        // Filtered tool index
+        if (getToolIndex) {
+            const allowedTools = ctx.getAllowedToolNames();
+            dynamicSections.push(getToolIndex(allowedTools));
+        }
+        // Capability catalog (if loadable packs remain)
+        if (manager.hasLoadablePacks()) {
+            const catalog = manager.getCatalog();
+            const catalogSection = generateCapabilityCatalog(catalog, manager.getLoadedPackIds());
+            if (catalogSection) {
+                dynamicSections.push(catalogSection);
+            }
+        }
+        // 4. Preserve anchors from the current system prompt.
+        // The agents library injects anchors into systemContent BEFORE this hook runs.
+        // We must extract and re-append them since we rebuild from basePrompt.
+        const anchorsBlock = extractAnchorsBlock(hookCtx.systemPrompt);
+        const hookResult = {
+            systemPrompt: basePrompt + '\n\n' + dynamicSections.join('\n\n') + anchorsBlock,
+        };
+        // 5. Inject forbidden boundary messages (handoff suggestions)
+        if (forbiddenHints.length > 0) {
+            const hintContent = forbiddenHints.join('\n');
+            const hintMessage = { role: 'user', content: hintContent };
+            hookResult.messages = [...hookCtx.messages, hintMessage];
+        }
+        return hookResult;
+    };
+}
+/**
+ * Extract the anchors block from a system prompt.
+ * The agents library injects "## Active Anchors (Critical Information)"
+ * before BeforeLLM hooks run. We need to preserve it when rebuilding.
+ */
+function extractAnchorsBlock(systemPrompt) {
+    const anchorMarker = '## Active Anchors (Critical Information)';
+    const anchorIdx = systemPrompt.indexOf(anchorMarker);
+    if (anchorIdx <= 0)
+        return '';
+    // Find the preceding "---" separator
+    const separatorBefore = systemPrompt.lastIndexOf('---', anchorIdx);
+    const startIdx = separatorBefore > 0 ? separatorBefore : anchorIdx;
+    // Find the end: either the next "---" after the anchor block, or end of string
+    const afterAnchor = systemPrompt.indexOf('\n\n---\n\n', anchorIdx);
+    if (afterAnchor > 0) {
+        return '\n\n' + systemPrompt.substring(startIdx, afterAnchor + 7);
+    }
+    return '\n\n' + systemPrompt.substring(startIdx);
+}

package/dist/capabilities/index.d.ts

@@ -12,3 +12,10 @@ export { CapabilityManager } from './manager.js';
 export type { CapabilityManagerConfig } from './manager.js';
 export { createLoadCapabilityTool } from './load-tool.js';
 export { generateCapabilityCatalog } from './catalog.js';
+export { CapabilityContext } from './context.js';
+export type { CapabilityContextConfig } from './context.js';
+export { createCapabilityHook } from './hook.js';
+export type { CapabilityHookConfig, ConditionalModule } from './hook.js';
+export { autoDetectCapabilities } from './auto-detect.js';
+export type { AutoDetectResult } from './auto-detect.js';
+export { resolveProfileGroups, resolveUpfrontGroups } from './profile-resolver.js';

package/dist/capabilities/index.js

@@ -14,3 +14,11 @@ export { CapabilityManager } from './manager.js';
 export { createLoadCapabilityTool } from './load-tool.js';
 // Catalog generator
 export { generateCapabilityCatalog } from './catalog.js';
+// Context — per-agent capability state + filter sync
+export { CapabilityContext } from './context.js';
+// Hook — BeforeLLM hook for dynamic prompt assembly
+export { createCapabilityHook } from './hook.js';
+// Auto-detection — scan messages for "Tool not found" errors
+export { autoDetectCapabilities } from './auto-detect.js';
+// Profile resolver — convert profiles/tool lists to group IDs
+export { resolveProfileGroups, resolveUpfrontGroups } from './profile-resolver.js';

package/dist/capabilities/profile-resolver.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Profile Resolver — converts tool profiles or custom tool lists
+ * into capability group IDs for the CapabilityManager.
+ */
+import { type ToolProfile } from '../team/tool-config.js';
+/**
+ * Convert a profile name or custom tool list into capability group IDs.
+ *
+ * @param profile - A named profile ('full', 'developer', etc.) or a custom tool name list
+ * @returns Array of group IDs that the profile allows
+ */
+export declare function resolveProfileGroups(profile: ToolProfile | string[]): string[];
+/**
+ * Determine which groups should be loaded upfront (direct tier).
+ * Upfront = groups marked as 'direct' tier AND in the agent's profile.
+ */
+export declare function resolveUpfrontGroups(profileGroups: string[]): string[];

package/dist/capabilities/profile-resolver.js

@@ -0,0 +1,38 @@
+/**
+ * Profile Resolver — converts tool profiles or custom tool lists
+ * into capability group IDs for the CapabilityManager.
+ */
+import { TOOL_GROUPS, TOOL_PROFILES } from '../team/tool-config.js';
+/**
+ * Convert a profile name or custom tool list into capability group IDs.
+ *
+ * @param profile - A named profile ('full', 'developer', etc.) or a custom tool name list
+ * @returns Array of group IDs that the profile allows
+ */
+export function resolveProfileGroups(profile) {
+    if (typeof profile === 'string') {
+        // Named profile — look up in TOOL_PROFILES
+        const groups = TOOL_PROFILES[profile];
+        return [...groups];
+    }
+    // Custom tool list — find groups that contain at least one of these tools
+    const toolSet = new Set(profile);
+    const groups = [];
+    for (const [groupId, group] of Object.entries(TOOL_GROUPS)) {
+        if (group.tools.some((t) => toolSet.has(t))) {
+            groups.push(groupId);
+        }
+    }
+    return groups;
+}
+/**
+ * Determine which groups should be loaded upfront (direct tier).
+ * Upfront = groups marked as 'direct' tier AND in the agent's profile.
+ */
+export function resolveUpfrontGroups(profileGroups) {
+    const profileSet = new Set(profileGroups);
+    return Object.entries(TOOL_GROUPS)
+        .filter(([, group]) => group.tier === 'direct')
+        .map(([id]) => id)
+        .filter((id) => profileSet.has(id));
+}

package/dist/config.d.ts

@@ -3,6 +3,49 @@
  */
 import type { LLMProvider, Message, Tool, ToolPermission, HooksConfig, AnchorInput, AgentEvent, ToolExecutionResult } from '@compilr-dev/agents';
 import type { Preset } from './presets/types.js';
+import type { ToolProfile } from './team/tool-config.js';
+import type { ConditionalModule } from './capabilities/hook.js';
+/**
+ * Dynamic capability loading configuration.
+ *
+ * When enabled, tools are loaded on-demand instead of all upfront,
+ * reducing token usage by ~50-60% on initial turns.
+ */
+export interface CapabilitiesConfig {
+    /** Enable dynamic capability loading. Default: false (all tools upfront) */
+    enabled: boolean;
+    /**
+     * Tool profile — determines which capability packs are available.
+     * Named profile ('full', 'developer', etc.) or custom tool name list.
+     * Default: 'full'
+     */
+    profile?: ToolProfile | string[];
+    /**
+     * Whether to enable meta-tools mode (get_tool_info + registry fallback).
+     * Loadable tools go through the meta-registry instead of being declared directly.
+     * Default: true when capabilities.enabled is true
+     */
+    metaTools?: boolean;
+    /**
+     * Max packs to auto-load per turn when "Tool not found" detected.
+     * Default: 2
+     */
+    maxAutoLoadsPerTurn?: number;
+    /**
+     * Additional tools to include that aren't in any capability pack
+     * (e.g., MCP tools, platform tools). Always available.
+     */
+    additionalTools?: Tool[];
+    /**
+     * Conditional prompt modules to include based on loaded packs.
+     * Default: git-safety, platform-tool-hints, factory-tool-hints
+     */
+    conditionalModules?: ConditionalModule[];
+    /**
+     * Static prompt sections to always include (e.g., meta-tools protocol).
+     */
+    staticSections?: string[];
+}
 /**
  * Supported provider types for auto-detection
  */
@@ -147,6 +190,12 @@ export interface CompilrAgentConfig {
     hooks?: HooksConfig;
     /** Context management configuration */
     context?: ContextConfig;
+    /**
+     * Dynamic capability loading configuration.
+     * When enabled, tools are loaded on-demand for token efficiency.
+     * Omit or set enabled: false for the legacy all-tools-upfront mode.
+     */
+    capabilities?: CapabilitiesConfig;
 }
 /**
  * High-level agent interface

package/dist/index.d.ts

@@ -34,7 +34,7 @@
  * ```
  */
 export { createCompilrAgent } from './agent.js';
-export type { CompilrAgentConfig, CompilrAgent, RunOptions, RunResult, ToolCallRecord, ToolConfig, UsageInfo, ProviderType, PermissionCallback, GuardrailConfig, ContextConfig, } from './config.js';
+export type { CompilrAgentConfig, CompilrAgent, RunOptions, RunResult, ToolCallRecord, ToolConfig, UsageInfo, ProviderType, PermissionCallback, GuardrailConfig, ContextConfig, CapabilitiesConfig, } from './config.js';
 export { AgentTeam, TeamAgent, SharedContextManager, ArtifactStore, DelegationTracker, ContextResolver, } from './team/index.js';
 export type { AgentTeamConfig, TeamAgentConfig, ITeamPersistence, IArtifactStorage, ISessionRegistry, CustomAgentDefinition, ToolConfig as TeamToolConfig, ToolTier, ToolGroup, ProfileInfo, } from './team/index.js';
 export type { AgentRole, RoleMetadata, ToolProfile, MascotExpression, BackgroundSessionInfo, SerializedTeam, SerializedTeamAgent, TeamMetadata, TeamEvent, TeamEventType, TeamEventHandler, Artifact, ArtifactType as TeamArtifactType, ArtifactSummary as TeamArtifactSummary, CreateArtifactOptions, UpdateArtifactOptions, SerializedArtifact, SharedContext, SharedProjectInfo, SharedTeamInfo, TeamRosterEntry, TeamActivity, TeamActivityType, SharedDecision, TokenBudget, SerializedSharedContext, ParsedMention, ParsedInput, ResolvedMention, ResolveOptions, ResolutionSource, Delegation, DelegationStatus, DelegationResult, CompletionEvent, CreateDelegationOptions, DelegationStats, DelegationTrackerEvents, SkillToolRequirement, } from './team/index.js';
@@ -49,8 +49,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, FallbackOptions } 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 { CapabilityManager, CapabilityContext, createCapabilityHook, autoDetectCapabilities, resolveProfileGroups, resolveUpfrontGroups, CAPABILITY_PACKS, FORBIDDEN_PACK_SUGGESTIONS, getPackCount, getAllPackIds, createLoadCapabilityTool, generateCapabilityCatalog, } from './capabilities/index.js';
+export type { CapabilityPack, CapabilityTier, LoadedCapability, CapabilityCatalogEntry, CapabilityLoadResult, CapabilityManagerConfig, CapabilityContextConfig, CapabilityHookConfig, ConditionalModule, AutoDetectResult, } 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, VISUAL_OUTPUT_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, WorkItemComment, CreateCommentInput, UpdateCommentInput, IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, ICommentRepository, IAnchorService, IArtifactService, IEpisodeService, AnchorData, ArtifactType, ArtifactData, ArtifactSummaryData, WorkEpisode, ProjectWorkSummary, PlatformContext, PlatformToolsConfig, PlatformHooks, StepCriteria, } from './platform/index.js';

package/dist/index.js

@@ -96,6 +96,14 @@ export { MetaToolsRegistry, createMetaTools, META_TOOLS_SYSTEM_PROMPT_PREFIX, }
 export { 
 // Manager
 CapabilityManager, 
+// Context (per-agent state + filter sync)
+CapabilityContext, 
+// Hook (BeforeLLM dynamic prompt assembly)
+createCapabilityHook, 
+// Auto-detection (tool-not-found scanning)
+autoDetectCapabilities, 
+// Profile resolution
+resolveProfileGroups, resolveUpfrontGroups, 
 // Pack definitions
 CAPABILITY_PACKS, FORBIDDEN_PACK_SUGGESTIONS, getPackCount, getAllPackIds, 
 // Self-loading tool

package/dist/platform/tools/backlog-tools.js

@@ -104,17 +104,26 @@ export function createBacklogTools(config) {
                     if (!item) {
                         return createErrorResult(`Item not found: ${input.id}`);
                     }
+                    const itemData = {
+                        id: item.itemId,
+                        type: TYPE_TO_LIBRARY[item.type],
+                        title: item.title,
+                        description: item.description ?? '',
+                        status: STATUS_TO_LIBRARY[item.status],
+                        priority: item.priority,
+                    };
+                    // Include comments when available
+                    if (ctx.comments) {
+                        const itemComments = await ctx.comments.listByWorkItem(item.id);
+                        itemData.comments = itemComments.map((c) => ({
+                            id: c.id,
+                            author: c.author,
+                            content: c.content,
+                            createdAt: c.createdAt.toISOString(),
+                        }));
+                    }
                     return createSuccessResult({
-                        items: [
-                            {
-                                id: item.itemId,
-                                type: TYPE_TO_LIBRARY[item.type],
-                                title: item.title,
-                                description: item.description ?? '',
-                                status: STATUS_TO_LIBRARY[item.status],
-                                priority: item.priority,
-                            },
-                        ],
+                        items: [itemData],
                         total: 1,
                         filtered: 1,
                     });

package/dist/platform/tools/workitem-tools.d.ts

@@ -13,12 +13,14 @@
  */
 import type { PlatformToolsConfig } from '../context.js';
 export declare function createWorkItemTools(config: PlatformToolsConfig): (import("@compilr-dev/agents").Tool<{
+    item_id?: string;
     project_id?: number;
     status?: string;
     type?: string;
     priority?: string;
     owner?: string;
     search?: string;
+    include_comments?: boolean;
     limit?: number;
     offset?: number;
 }> | import("@compilr-dev/agents").Tool<{

package/dist/platform/tools/workitem-tools.js

@@ -21,10 +21,14 @@ export function createWorkItemTools(config) {
     // ---------------------------------------------------------------------------
     const workitemQueryTool = defineTool({
         name: 'workitem_query',
-        description: 'Query work items from the project backlog. Supports filtering by status, type, priority, owner, and search.',
+        description: 'Query work items from the project backlog. Use item_id for a single item with full details and comments. Supports filtering by status, type, priority, owner, and search.',
         inputSchema: {
             type: 'object',
             properties: {
+                item_id: {
+                    type: 'string',
+                    description: 'Get a specific item by ID (e.g., "REQ-001"). Returns full details with comments.',
+                },
                 status: {
                     type: 'string',
                     enum: ['backlog', 'in_progress', 'completed', 'skipped', 'all'],
@@ -49,6 +53,10 @@ export function createWorkItemTools(config) {
                     type: 'string',
                     description: 'Search in title and description',
                 },
+                include_comments: {
+                    type: 'boolean',
+                    description: 'Include full comments for each item (default: false for lists, always true for single item_id lookup)',
+                },
                 limit: {
                     type: 'number',
                     description: 'Max items to return',
@@ -72,7 +80,47 @@ export function createWorkItemTools(config) {
                 if (!projectId) {
                     return createErrorResult('No project specified and no active project. Use project_get or /projects to select a project first.');
                 }
-                // Resolve "self" to the active agent ID via hook
+                const comments = ctx.comments;
+                // Single item lookup by item_id
+                if (input.item_id) {
+                    const item = await ctx.workItems.getByItemId(projectId, input.item_id);
+                    if (!item) {
+                        return createErrorResult(`Work item "${input.item_id}" not found in current project`);
+                    }
+                    const itemData = {
+                        id: item.id,
+                        itemId: item.itemId,
+                        type: item.type,
+                        status: item.status,
+                        priority: item.priority,
+                        owner: item.owner,
+                        guidedStep: item.guidedStep,
+                        title: item.title,
+                        description: item.description,
+                        estimatedEffort: item.estimatedEffort,
+                        completedAt: item.completedAt?.toISOString(),
+                        commitHash: item.commitHash,
+                        createdAt: item.createdAt.toISOString(),
+                    };
+                    // Always include full comments for single-item lookup
+                    if (comments) {
+                        const itemComments = await comments.listByWorkItem(item.id);
+                        itemData.comments = itemComments.map((c) => ({
+                            id: c.id,
+                            author: c.author,
+                            content: c.content,
+                            createdAt: c.createdAt.toISOString(),
+                        }));
+                    }
+                    return createSuccessResult({
+                        success: true,
+                        items: [itemData],
+                        total: 1,
+                        hasMore: false,
+                        projectId,
+                    });
+                }
+                // List query
                 let resolvedOwner = input.owner;
                 if (input.owner === 'self') {
                     resolvedOwner = hooks?.resolveOwner?.('self') ?? undefined;
@@ -88,7 +136,7 @@ export function createWorkItemTools(config) {
                     offset: input.offset ?? 0,
                 };
                 const result = await ctx.workItems.query(queryInput);
-                const comments = ctx.comments;
+                const wantFullComments = input.include_comments === true;
                 const items = await Promise.all(result.items.map(async (item) => {
                     const base = {
                         id: item.id,
@@ -107,16 +155,19 @@ export function createWorkItemTools(config) {
                     };
                     if (!comments)
                         return base;
-                    const itemComments = await comments.listByWorkItem(item.id);
-                    return {
-                        ...base,
-                        comments: itemComments.map((c) => ({
+                    if (wantFullComments) {
+                        const itemComments = await comments.listByWorkItem(item.id);
+                        base.comments = itemComments.map((c) => ({
                             id: c.id,
                             author: c.author,
                             content: c.content,
                             createdAt: c.createdAt.toISOString(),
-                        })),
-                    };
+                        }));
+                    }
+                    else {
+                        base.commentCount = await comments.countByWorkItem(item.id);
+                    }
+                    return base;
                 }));
                 return createSuccessResult({
                     success: true,

package/package.json

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