@compilr-dev/sdk 0.1.23 → 0.1.25

package/dist/capabilities/types.d.ts

@@ -39,7 +39,7 @@ export type CapabilityTier = 'upfront' | 'loadable' | 'forbidden';
 export interface LoadedCapability {
     packId: string;
     loadedAt: number;
-    trigger: 'upfront' | 'slash-command' | 'agent-self' | 'auto-detect';
+    trigger: 'upfront' | 'slash-command' | 'agent-self' | 'auto-detect' | 'auto-load';
 }
 /**
  * Catalog entry shown in the agent's system prompt for self-loading.

package/dist/index.d.ts

@@ -44,7 +44,7 @@ export { DEFAULT_MODELS, getContextWindow, DEFAULT_CONTEXT_WINDOW } from './mode
 export { type ModelTier, type TierInfo, type ProviderModelMap, MODEL_TIERS, TIER_INFO, isValidTier, type ThinkingFormat, type ModelStatus, type ModelInfo, MODEL_REGISTRY, getModelsForProvider, getModelsSortedForDisplay, getModelInfo, isKnownModel, isModelSupported, getThinkingFormat, getStatusIndicator, getStatusLabel, getDefaultModelForTier, areThinkingFormatsCompatible, shouldClearHistoryOnModelChange, getModelContextWindow, getModelDisplayName, getModelDescription, getModelForTier, getTierMappings, getTierDisplayName, getShortModelName, getDefaultTierMappings, type ProviderMetadata, type OthersProviderModel, PROVIDER_METADATA, TOGETHER_MODELS, GROQ_MODELS, FIREWORKS_MODELS, PERPLEXITY_MODELS, OPENROUTER_MODELS, getModelsForOthersProvider, getOthersProviders, getProviderMetadata, isOthersProvider, } from './models/index.js';
 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 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 { 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';

package/dist/meta-tools/index.d.ts

@@ -13,4 +13,4 @@
  * // Use metaTools.createFallback() for transparent routing
  * ```
  */
-export { MetaToolsRegistry, createMetaTools, META_TOOLS_SYSTEM_PROMPT_PREFIX, type MetaToolStats, type MetaTools, } from './registry.js';
+export { MetaToolsRegistry, createMetaTools, META_TOOLS_SYSTEM_PROMPT_PREFIX, type MetaToolStats, type MetaTools, type FallbackOptions, } from './registry.js';

package/dist/meta-tools/registry.d.ts

@@ -21,6 +21,14 @@ export interface MetaToolStats {
     /** Estimated token savings vs declaring all tools directly */
     estimatedTokenSavings: number;
 }
+/**
+ * Options for the fallback handler created by createFallback().
+ */
+export interface FallbackOptions {
+    /** Called when a tool exists in the registry but is blocked by the filter.
+     *  Return true if the filter was updated and the tool should be retried. */
+    onFilteredTool?: (toolName: string) => boolean;
+}
 /**
  * The set of meta-tools and fallback handler returned by createMetaTools().
  */
@@ -32,7 +40,7 @@ export interface MetaTools {
     /** Executes any registered tool by name */
     useToolTool: Tool;
     /** Creates a fallback handler for transparent tool routing */
-    createFallback: () => (name: string, input: Record<string, unknown>) => Promise<ToolExecutionResult | null>;
+    createFallback: (options?: FallbackOptions) => (name: string, input: Record<string, unknown>) => Promise<ToolExecutionResult | null>;
 }
 export declare class MetaToolsRegistry {
     private readonly toolRegistry;
@@ -89,6 +97,7 @@ export declare class MetaToolsRegistry {
 }
 /**
  * Create the three meta-tools + fallback handler, all bound to a registry instance.
+ * Pass FallbackOptions to enable auto-loading in both use_tool and createFallback paths.
  */
-export declare function createMetaTools(registry: MetaToolsRegistry): MetaTools;
+export declare function createMetaTools(registry: MetaToolsRegistry, options?: FallbackOptions): MetaTools;
 export declare const META_TOOLS_SYSTEM_PROMPT_PREFIX = "\n## Tool Index (Specialized Tools)\n\nThese tools are called **exactly like direct tools** \u2014 just use the tool name with parameters. No special syntax or wrapper needed. The system routes them automatically.\n\n**IMPORTANT \u2014 These are CLI system tools, NOT your project's backend. Never use localhost/curl to access them.**\n\n**Parameter Rules:**\n- For **zero-parameter calls**: call the tool directly (e.g., `workitem_query()`, `git_status()`).\n- For **calls WITH parameters**: you MUST call `get_tool_info(\"tool_name\")` first to get parameter details. The signatures below are summaries only \u2014 do NOT guess parameter structure from them.\n- After a failed tool call, always call `get_tool_info()` before retrying.\n\n";

package/dist/meta-tools/registry.js

@@ -143,8 +143,9 @@ export class MetaToolsRegistry {
 // =============================================================================
 /**
  * Create the three meta-tools + fallback handler, all bound to a registry instance.
+ * Pass FallbackOptions to enable auto-loading in both use_tool and createFallback paths.
  */
-export function createMetaTools(registry) {
+export function createMetaTools(registry, options) {
     // -------------------------------------------------------------------------
     // list_tools
     // -------------------------------------------------------------------------
@@ -240,13 +241,16 @@ export function createMetaTools(registry) {
         execute: async ({ tool_name, args }) => {
             // 0. Check tool filter
             if (!registry.isToolAllowed(tool_name)) {
-                const filter = registry.getFilter();
-                const allowedTools = filter
-                    ? Array.from(filter).filter((t) => registry.getTool(t) !== undefined)
-                    : [];
-                return createErrorResult(`Tool '${tool_name}' is not available for this agent. ` +
-                    `Your available meta-registry tools: ${allowedTools.slice(0, 10).join(', ')}${allowedTools.length > 10 ? '...' : ''} ` +
-                    `Call list_tools() to see all available tools.`);
+                // Give consumer a chance to load the capability and update the filter
+                if (!(options?.onFilteredTool?.(tool_name) && registry.isToolAllowed(tool_name))) {
+                    const filter = registry.getFilter();
+                    const allowedTools = filter
+                        ? Array.from(filter).filter((t) => registry.getTool(t) !== undefined)
+                        : [];
+                    return createErrorResult(`Tool '${tool_name}' is not available for this agent. ` +
+                        `Your available meta-registry tools: ${allowedTools.slice(0, 10).join(', ')}${allowedTools.length > 10 ? '...' : ''} ` +
+                        `Call list_tools() to see all available tools.`);
+                }
             }
             // 1. Find the tool
             const tool = registry.getTool(tool_name);
@@ -293,7 +297,7 @@ export function createMetaTools(registry) {
     // -------------------------------------------------------------------------
     // Fallback handler factory
     // -------------------------------------------------------------------------
-    function createFallback() {
+    function createFallback(options) {
         return async (name, input) => {
             // Check if tool exists in registry
             const tool = registry.getTool(name);
@@ -302,12 +306,18 @@ export function createMetaTools(registry) {
             }
             // Check tool filter
             if (!registry.isToolAllowed(name)) {
-                const filter = registry.getFilter();
-                const allowedTools = filter
-                    ? Array.from(filter).filter((t) => registry.getTool(t) !== undefined)
-                    : [];
-                return createErrorResult(`Tool '${name}' is not available for this agent. ` +
-                    `Available tools: ${allowedTools.slice(0, 10).join(', ')}${allowedTools.length > 10 ? '...' : ''}`);
+                // Give consumer a chance to load the capability and update the filter
+                if (options?.onFilteredTool?.(name) && registry.isToolAllowed(name)) {
+                    // Filter updated — fall through to execute
+                }
+                else {
+                    const filter = registry.getFilter();
+                    const allowedTools = filter
+                        ? Array.from(filter).filter((t) => registry.getTool(t) !== undefined)
+                        : [];
+                    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;

package/package.json

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