@compilr-dev/cli 0.5.0 → 0.5.2

package/dist/agent.js

@@ -5,178 +5,17 @@
  * ClaudeProvider, OllamaProvider, OpenAIProvider, or GeminiProvider
  * and available tools.
  */
-import { Agent, ClaudeProvider, OllamaProvider, OpenAIProvider, GeminiProvider, ContextManager, DEFAULT_CONTEXT_CONFIG, createTaskTool, createSuggestTool, defaultAgentTypes, TOOL_SETS, BUILTIN_GUARDRAILS, } from '@compilr-dev/agents';
-import { isAutoCompactEnabled } from './settings/index.js';
+import { Agent, ContextManager, DEFAULT_CONTEXT_CONFIG, createTaskTool, createSuggestTool, defaultAgentTypes, TOOL_SETS, BUILTIN_GUARDRAILS, createProviderFromType, } from '@compilr-dev/sdk';
+import { isAutoCompactEnabled, isDelegationEnabled, getSetting } from './settings/index.js';
 import { getApiKey } from './utils/credentials.js';
-import { createToolRegistry, createMinimalToolRegistry } from './tools.js';
+import { createToolRegistry, createMinimalToolRegistry, getDirectTools, getMetaTools, initializeMetaTools, getToolIndexForSystemPrompt, getToolStats, setMetaToolFilter, createToolFallback, } from './tools.js';
 import { getAgentRegistry } from './agents/registry.js';
-const SYSTEM_PROMPT = `You are a coding assistant running in a terminal CLI.
-
-You help users with software engineering tasks: writing code, debugging, refactoring, explaining concepts, managing projects, and more.
-
-## Tone and Style
-
-- Your output displays in a terminal. Keep responses short and concise.
-- Use GitHub-flavored markdown for formatting.
-- Only use emojis if the user explicitly requests them.
-- Output text to communicate. Never use tools (like bash echo) to communicate.
-- NEVER create files unless absolutely necessary. Always prefer editing existing files.
-- When referencing code, include file path and line number: src/utils.ts:42
-
-## Professional Objectivity
-
-Prioritize technical accuracy over validating the user's beliefs. Provide direct, objective technical info without unnecessary praise or emotional validation. Disagree when necessary - objective guidance is more valuable than false agreement.
-
-Avoid phrases like "You're absolutely right!" or "Great question!" - just answer directly.
-
-## No Time Estimates
-
-Never predict how long tasks will take. Avoid phrases like "this will take a few minutes" or "quick fix". Focus on what needs to be done, not duration.
-
----
-
-## Doing Tasks
-
-When the user requests software engineering work:
-
-1. **Read before modifying**: NEVER propose changes to code you haven't read. Always read files first.
-2. **Use todo_write for complex tasks**: Track progress on multi-step work (3+ steps).
-3. **Avoid over-engineering**:
-   - Only make changes that are directly requested
-   - Don't add features beyond what was asked
-   - Don't add error handling for scenarios that can't happen
-   - Don't create abstractions for one-time operations
-   - Three similar lines is better than a premature abstraction
-4. **Security awareness**: Don't introduce vulnerabilities (injection, XSS, SQL injection). If you notice insecure code, fix it immediately.
-5. **Clean up completely**: If something is unused, delete it. No backwards-compatibility hacks.
-
-## Task Management (todo_write)
-
-Use todo_write to track progress on multi-step tasks.
-
-When to use:
-- Tasks with 3+ distinct steps
-- User provides multiple tasks
-- Complex work requiring planning
-
-When NOT to use:
-- Single, trivial tasks
-- Purely informational questions
-- Tasks completable in 1-2 steps
-
-### Example: When to use todo_write
-
-User: Fix the type errors and run the tests
-Assistant: I'll track this multi-step task:
-[Uses todo_write: "Fix type errors", "Run tests"]
-[Marks "Fix type errors" as in_progress]
-[Reads files, fixes errors]
-[Marks "Fix type errors" complete, "Run tests" in_progress]
-[Runs tests]
-[Marks "Run tests" complete]
-
-### Example: When NOT to use todo_write
-
-User: What does this function do?
-Assistant: [Reads the file and explains directly - no todo needed for a simple question]
-
----
-
-## Tool Usage
-
-IMPORTANT: Tool names are lowercase with underscores. Use them exactly as shown.
-
-### File Operations
-- read_file: Read file contents (parameter: path)
-- write_file: Create or overwrite a file (parameters: path, content)
-- edit: Replace text in a file (parameters: path, old_text, new_text)
-- glob: Find files matching a pattern (parameters: pattern, path)
-- grep: Search file contents with regex (parameters: pattern, path)
-
-### Shell
-- bash: Run shell commands (parameter: command)
-  For long-running commands (dev servers), use run_in_background=true
-- bash_output: Get output from background shell (parameter: shell_id)
-- kill_shell: Terminate background shell (parameter: shell_id)
-
-### Git
-- git_status: Show working tree status
-- git_diff: Show file differences
-- git_log: Show commit history
-- git_commit: Create a commit (parameters: message, files)
-- git_branch: List or manage branches
-
-### Project Analysis
-- detect_project: Detect project type and framework
-- find_project_root: Find project root directory
-- run_tests: Run test suite
-- run_lint: Run linter
-
-### Task Management
-- todo_write: Add/update todo items
-- todo_read: View current todo list
-
-### User Interaction
-- ask_user: Ask question with multiple choice options
-- ask_user_simple: Ask simple yes/no or text input question
-- suggest: Suggest next action (appears as ghost text - user presses Tab to accept)
-
-### Sub-agents
-- task: Spawn specialized sub-agent for complex tasks
-  Types: explore, code-review, plan, debug, test-runner, refactor, security-audit, general
-
----
-
-## Git Safety Protocol
-
-When working with git:
-
-1. **Never update git config** without explicit user request
-2. **Never force push** to main/master - warn if requested
-3. **Never use --amend** unless:
-   - User explicitly requested it, AND
-   - Commit was created by you in this session, AND
-   - Commit has NOT been pushed to remote
-4. **Check before destructive operations**:
-   - git reset --hard (loses uncommitted changes)
-   - git checkout -- file (discards local changes)
-   - git clean (deletes untracked files)
-5. **Only commit when asked** - don't commit proactively
-
-### Commit Workflow
-1. Run git_status to see changes
-2. Run git_diff to review what will be committed
-3. Check recent git_log for commit message style
-4. Create focused commit with clear message
-5. Never commit files with secrets (.env, credentials.json)
-
----
-
-## Next Action Suggestions
-
-After completing a task, call the suggest tool to recommend the next action.
-
-Good suggestions are short commands or actions:
-- "run npm test"
-- "commit the changes"
-- "check the error log"
-
-CALL the suggest tool - never write "suggest: ..." as text.
-
----
-
-## IMPORTANT RULES (read carefully)
-
-1. Tool names are lowercase with underscores - use exactly as shown
-2. ALWAYS read files before proposing changes to them
-3. After calling a tool, respond with the result - never end silently
-4. Use todo_write for multi-step tasks (3+ steps)
-5. Don't over-engineer - implement exactly what was asked
-6. Check for security issues - fix insecure code immediately
-7. Use the task tool to delegate complex work to sub-agents
-8. Call suggest tool after completing tasks (don't write "suggest:" as text)
-
-Current working directory: ${process.cwd()}`;
+import { SystemPromptBuilder } from './system-prompt/index.js';
+import { getDefaultModelForTier, getModelContextWindow } from './models/index.js';
+import { PROVIDER_METADATA } from './models/providers.js';
+import { setStaticEstimates, estimateTokens, estimateJsonTokens, } from './utils/token-tracker.js';
+import { createFileLockCheckHook, createFileLockAcquireHook } from './multi-agent/file-lock-hook.js';
+import { getActiveProject } from './tools/project-db.js';
 /**
  * Default permission rules for potentially dangerous operations
  * Note: Tool names are lowercase (bash, write_file, edit, git_commit)
@@ -248,85 +87,57 @@ function getMergedAgentTypes() {
 }
 /**
  * Creates the appropriate LLM provider based on configuration.
+ * Resolves CLI-specific concerns (credentials, settings) then delegates
+ * provider instantiation to the SDK's createProviderFromType().
  */
 function createProvider(options) {
     const providerType = options.provider ?? 'claude';
-    switch (providerType) {
-        case 'ollama': {
-            const model = options.model ?? 'llama3.1';
-            console.log(`Using Ollama provider with model: ${model}`);
-            const provider = new OllamaProvider({
-                model,
-                baseUrl: process.env.OLLAMA_BASE_URL ?? 'http://localhost:11434',
-            });
-            return provider;
-        }
-        case 'openai': {
-            const apiKey = getApiKey('openai');
-            if (!apiKey) {
-                throw new Error('OpenAI API key not found.\n' +
-                    'Run /keys to set it, or: export OPENAI_API_KEY=sk-...');
-            }
-            const model = options.model ?? 'gpt-4o';
-            console.log(`Using OpenAI provider with model: ${model}`);
-            const provider = new OpenAIProvider({ apiKey, model });
-            return provider;
-        }
-        case 'gemini': {
-            const apiKey = getApiKey('google');
-            if (!apiKey) {
-                throw new Error('Google AI API key not found.\n' +
-                    'Run /keys to set it, or: export GOOGLE_API_KEY=AI...');
-            }
-            const model = options.model ?? 'gemini-2.0-flash';
-            console.log(`Using Gemini provider with model: ${model}`);
-            const provider = new GeminiProvider({ apiKey, model });
-            return provider;
-        }
-        case 'claude':
-        default: {
-            const apiKey = getApiKey('anthropic');
-            if (!apiKey) {
-                throw new Error('Anthropic API key not found.\n' +
-                    'Run /keys to set it, or: export ANTHROPIC_API_KEY=sk-ant-...\n' +
-                    'Or use --provider ollama for local models.');
-            }
-            const model = options.model ?? 'claude-sonnet-4-20250514';
-            console.log(`Using Claude provider with model: ${model}`);
-            return new ClaudeProvider({ apiKey, model });
-        }
+    const quiet = options.quiet ?? false;
+    const meta = PROVIDER_METADATA[providerType];
+    // 1. Resolve API key from CLI credential store
+    const apiKey = meta.requiresKey ? getApiKey(meta.credentialKey) : undefined;
+    if (!apiKey && meta.requiresKey) {
+        throw new Error(`${meta.displayName} API key not found.\n` +
+            `Run /keys to set it, or: export ${meta.envVar}=...` +
+            (providerType === 'claude' ? '\nOr use --provider ollama for local models.' : ''));
     }
-}
-/**
- * Returns the context window limit for each provider.
- */
-function getProviderContextLimit(provider) {
-    switch (provider) {
-        case 'gemini':
-            return 1000000; // 1M tokens
-        case 'claude':
-            return 200000; // 200K tokens
-        case 'openai':
-            return 128000; // 128K tokens
-        case 'ollama':
-            return 32000; // Conservative default for local models
-        default:
-            return 200000;
+    // 2. Resolve model (from options or registry default for balanced tier)
+    const model = options.model ?? getDefaultModelForTier(providerType, 'balanced')?.id;
+    // 3. Resolve Ollama base URL from settings
+    const baseUrl = providerType === 'ollama'
+        ? ((typeof getSetting('ollamaBaseUrl') === 'string'
+            ? getSetting('ollamaBaseUrl')
+            : undefined) ??
+            process.env.OLLAMA_BASE_URL ??
+            'http://localhost:11434')
+        : undefined;
+    // 4. Log (unless quiet)
+    if (!quiet)
+        console.log(`Using ${meta.displayName} with model: ${model ?? 'default'}`);
+    if (!quiet && providerType === 'ollama' && baseUrl !== 'http://localhost:11434') {
+        console.log(`  Ollama server: ${baseUrl ?? ''}`);
     }
+    // 5. Delegate to SDK
+    return createProviderFromType(providerType, {
+        model,
+        apiKey: apiKey ?? undefined,
+        baseUrl,
+        siteName: providerType === 'openrouter' ? 'compilr-cli' : undefined,
+    });
 }
 /**
  * Creates an Agent instance configured with all tools.
  */
 export function createAgent(options = {}) {
     const provider = createProvider(options);
-    // Create context manager with provider-appropriate limits
+    // Create context manager with model-specific limits
     // Uses library defaults: compact at 50%, summarize at 90%, emergency at 95%
     // Auto-compact can be disabled via settings (requires restart)
     const autoCompact = isAutoCompactEnabled();
     const contextManager = new ContextManager({
         provider,
         config: {
-            maxContextTokens: getProviderContextLimit(options.provider),
+            maxContextTokens: getModelContextWindow(options.model ?? '', options.provider),
             // If auto-compact disabled, set threshold to 100% (never triggers)
             compaction: autoCompact
                 ? DEFAULT_CONTEXT_CONFIG.compaction
@@ -348,15 +159,63 @@ export function createAgent(options = {}) {
             }
         }
         : undefined;
-    // Build system prompt with optional project context and guided mode context
+    // Build modular system prompt based on current context
     // Note: Anchors are NOT added here - they're handled by library's AnchorManager
     // which re-injects them on every LLM call (survives compaction)
-    let systemPrompt = SYSTEM_PROMPT;
-    if (options.projectContext) {
-        systemPrompt += `\n\n---\n\n## Project Context\n\nThe following is project-specific context loaded from COMPILR.md:\n\n${options.projectContext}`;
+    // Initialize meta-tools if enabled (needed for tool index)
+    let metaToolsIndex;
+    if (options.enableMetaTools && !options.minimal) {
+        initializeMetaTools();
+        metaToolsIndex = getToolIndexForSystemPrompt();
+        // Log tool stats (unless quiet mode)
+        if (!options.quiet) {
+            const stats = getToolStats();
+            console.log(`[Meta-tools] Direct: ${String(stats.directTools)}, ` +
+                `Meta: ${String(stats.metaRegistryTools)}, ` +
+                `Est. savings: ~${String(stats.tokenSavings)} tokens`);
+        }
+    }
+    let systemPrompt;
+    // Check if we should use minimal system prompt (for testing role identity)
+    if (options.useMinimalSystemPrompt && options.systemPromptAddition) {
+        // Skip all modules - just use the role prompt directly
+        systemPrompt = options.systemPromptAddition;
     }
-    if (options.guidedModeContext) {
-        systemPrompt += `\n\n---\n\n${options.guidedModeContext}`;
+    else {
+        // Use modular system prompt builder
+        // When a role-specific identity is provided (systemPromptAddition), skip the default identity module
+        const promptBuilder = new SystemPromptBuilder({
+            enableMetaTools: options.enableMetaTools && !options.minimal,
+            projectName: options.projectName,
+            projectContext: options.projectContext,
+            guidedModeContext: options.guidedModeContext,
+            planModeContext: options.planModeContext,
+            metaToolsIndex,
+            hasRoleIdentity: !!options.systemPromptAddition, // Skip default identity when role is specified
+            // hasGit is auto-detected by builder
+        });
+        const buildResult = promptBuilder.build();
+        systemPrompt = buildResult.prompt;
+        // Prepend role-specific system prompt (for team agents)
+        // The default identity module is already excluded via hasRoleIdentity flag
+        if (options.systemPromptAddition) {
+            // Extract role name from the role prompt (format: "# ROLE: ROLE_NAME")
+            const roleMatch = options.systemPromptAddition.match(/^#\s*ROLE:\s*(.+)$/m);
+            const roleName = roleMatch ? roleMatch[1].trim() : 'specialized team member';
+            // Put FULL role prompt at the END (recency effect is stronger than primacy)
+            // LLMs weight the end of context more heavily
+            const roleEnding = `
+
+---
+
+## YOUR ASSIGNED ROLE: ${roleName}
+
+${options.systemPromptAddition}
+
+**CRITICAL**: When asked "what is your role?", "what are you?", or similar identity questions, your response should acknowledge your assigned role. For example: "In this team, I'm the ${roleName}" or "I'm operating as the ${roleName} in this session."`;
+            // Put role at BOTH beginning AND end, with full role prompt at the end
+            systemPrompt = options.systemPromptAddition + '\n\n' + systemPrompt + roleEnding;
+        }
     }
     const agent = new Agent({
         provider,
@@ -400,6 +259,58 @@ export function createAgent(options = {}) {
                 onTriggered: options.onGuardrailTriggered,
             }
             : undefined,
+        // Tool result delegation — auto-summarize large results to conserve context
+        delegation: isDelegationEnabled()
+            ? {
+                enabled: true,
+                delegationThreshold: 8000,
+                summaryMaxTokens: 800,
+                resultTTL: 600_000,
+                maxStoredResults: 50,
+                strategy: 'auto',
+                toolOverrides: {
+                    // Custom thresholds
+                    bash: { threshold: 12000 },
+                    grep: { threshold: 4000 },
+                    git_diff: { threshold: 6000 },
+                    // Never summarize — agent needs verbatim results
+                    get_tool_info: { enabled: false },
+                    list_tools: { enabled: false },
+                    ask_user: { enabled: false },
+                    ask_user_simple: { enabled: false },
+                    todo_read: { enabled: false },
+                },
+            }
+            : undefined,
+        // Hooks: context pressure, file lock check/acquire
+        hooks: {
+            beforeLLM: [
+                (ctx) => {
+                    const utilization = contextManager.getUtilization();
+                    if (utilization < 0.3)
+                        return undefined;
+                    const pct = Math.round(utilization * 100);
+                    let hint;
+                    if (utilization < 0.6) {
+                        hint = `[Context: ${String(pct)}%] Consider task() for multi-file operations.`;
+                    }
+                    else if (utilization < 0.8) {
+                        hint = `[Context: ${String(pct)}% - HIGH] Prefer task() sub-agents for file reads and code search.`;
+                    }
+                    else {
+                        hint = `[Context: ${String(pct)}% - CRITICAL] Use task() for ALL exploration. Do not read files directly.`;
+                    }
+                    const messages = [...ctx.messages];
+                    messages.splice(1, 0, { role: 'user', content: hint });
+                    return { messages };
+                },
+            ],
+            beforeTool: [createFileLockCheckHook(getActiveProject)],
+            afterTool: [
+                createFileLockAcquireHook(getActiveProject),
+                ...(options.episodeRecorder ? [options.episodeRecorder.createHook()] : []),
+            ],
+        },
     });
     // Load persisted anchors into the agent's AnchorManager
     if (options.enableAnchors && options.persistedAnchors) {
@@ -414,14 +325,52 @@ export function createAgent(options = {}) {
             });
         }
     }
-    // Register tools using registerTools method
-    const tools = options.minimal
-        ? createMinimalToolRegistry()
-        : createToolRegistry();
-    // Type assertion needed for tool registry compatibility
-    agent.registerTools(tools);
+    // Register tools using registerTools method (skip if noTools is set)
+    if (!options.noTools) {
+        // When meta-tools is enabled, use direct tools + meta-tools instead of all tools
+        let tools;
+        if (options.minimal) {
+            tools = createMinimalToolRegistry();
+        }
+        else if (options.enableMetaTools) {
+            // Meta-tools mode: direct tools + get_tool_info (for schema introspection)
+            // Meta-registry tools are accessed transparently via fallback handler
+            tools = [...getDirectTools(), ...getMetaTools()];
+        }
+        else {
+            // Legacy mode: all tools declared directly
+            // eslint-disable-next-line @typescript-eslint/no-deprecated -- Intentional for backward compatibility
+            tools = createToolRegistry();
+        }
+        // Apply tool filter if specified (filter direct tools)
+        if (options.toolFilter && options.toolFilter.length > 0) {
+            const allowedTools = new Set(options.toolFilter);
+            // get_tool_info is always allowed for schema introspection
+            const alwaysAllowed = new Set(['get_tool_info']);
+            tools = tools.filter((tool) => allowedTools.has(tool.definition.name) || alwaysAllowed.has(tool.definition.name));
+            // Also set the meta-tool filter for use_tool/list_tools filtering
+            setMetaToolFilter(options.toolFilter);
+        }
+        else {
+            // No filter - clear any previous filter
+            setMetaToolFilter(null);
+        }
+        // Type assertion needed for tool registry compatibility
+        agent.registerTools(tools);
+        // Register MCP tools (from external MCP servers)
+        // These are registered as direct tools since their schemas are unknown at build time
+        if (options.mcpTools && options.mcpTools.length > 0) {
+            agent.registerTools(options.mcpTools);
+        }
+        // Set up transparent fallback to meta-registry
+        // When the agent calls a tool not in direct tools (e.g., workitem_add),
+        // the fallback handler checks the meta-registry and executes it.
+        if (options.enableMetaTools && !options.minimal) {
+            agent.getToolRegistry().setFallbackHandler(createToolFallback());
+        }
+    }
     // Register Task tool for sub-agent spawning (only in full mode)
-    if (!options.minimal) {
+    if (!options.minimal && !options.noTools) {
         // Track active subagents to correlate spawn/complete/events
         // Track active subagents by toolUseId for token counting
         const activeSubagents = new Map();
@@ -496,5 +445,52 @@ export function createAgent(options = {}) {
         });
         agent.registerTool(suggestTool);
     }
+    // ==========================================================================
+    // Calculate and store token estimates for debugging
+    // ==========================================================================
+    if (!options.quiet) {
+        // Calculate tool tokens from the tools we registered
+        let toolTokens = 0;
+        // Get the tools array based on options
+        let toolsForEstimate = [];
+        if (!options.noTools) {
+            if (options.minimal) {
+                toolsForEstimate = createMinimalToolRegistry();
+            }
+            else if (options.enableMetaTools) {
+                toolsForEstimate = [...getDirectTools(), ...getMetaTools()];
+            }
+            else {
+                // eslint-disable-next-line @typescript-eslint/no-deprecated
+                toolsForEstimate = createToolRegistry();
+            }
+        }
+        for (const tool of toolsForEstimate) {
+            const def = tool.definition;
+            toolTokens += estimateJsonTokens({
+                name: def.name,
+                description: def.description,
+                input_schema: def.inputSchema,
+            });
+        }
+        // Add task tool and suggest tool estimates (if registered)
+        if (!options.minimal && !options.noTools) {
+            // Task tool has a large description with all agent types
+            toolTokens += 700; // Approximate for task tool
+            toolTokens += 200; // Approximate for suggest tool
+        }
+        // Calculate estimates
+        const systemTokens = estimateTokens(systemPrompt);
+        const roleTokens = options.systemPromptAddition
+            ? estimateTokens(options.systemPromptAddition) * 2 // Role appears at start and end
+            : 0;
+        const contextTokens = estimateTokens(options.projectContext);
+        setStaticEstimates({
+            system: systemTokens - roleTokens, // Subtract role since it's counted separately
+            role: roleTokens,
+            tools: toolTokens,
+            context: contextTokens,
+        });
+    }
     return agent;
 }

package/dist/anchors/index.d.ts

@@ -6,4 +6,4 @@
  */
 export { getAnchorManager, getGlobalAnchorManager, clearProjectAnchors, getFormattedAnchors, addAnchor, getAllAnchors, getProjectsWithAnchors, getAnchorStats, clearManagerCache, } from './project-anchors.js';
 export type { Anchor, AnchorInput, AnchorQueryOptions } from './project-anchors.js';
-export { AnchorManager } from '@compilr-dev/agents';
+export { AnchorManager } from '@compilr-dev/sdk';

package/dist/anchors/index.js

@@ -6,4 +6,4 @@
  */
 export { getAnchorManager, getGlobalAnchorManager, clearProjectAnchors, getFormattedAnchors, addAnchor, getAllAnchors, getProjectsWithAnchors, getAnchorStats, clearManagerCache, } from './project-anchors.js';
 // Re-export the AnchorManager type from agents for consumers
-export { AnchorManager } from '@compilr-dev/agents';
+export { AnchorManager } from '@compilr-dev/sdk';

package/dist/anchors/project-anchors.d.ts

@@ -9,8 +9,8 @@
  *     ├── global.json           # Non-project anchors
  *     └── project-{id}.json     # Per-project anchors
  */
-import { AnchorManager } from '@compilr-dev/agents';
-import type { Anchor, AnchorInput, AnchorQueryOptions } from '@compilr-dev/agents';
+import { AnchorManager } from '@compilr-dev/sdk';
+import type { Anchor, AnchorInput, AnchorQueryOptions } from '@compilr-dev/sdk';
 export type { Anchor, AnchorInput, AnchorQueryOptions };
 /**
  * Get anchor manager for a project (or global if projectId is null)

package/dist/anchors/project-anchors.js

@@ -11,7 +11,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { AnchorManager } from '@compilr-dev/agents';
+import { AnchorManager } from '@compilr-dev/sdk';
 import { getDataPath } from '../settings/paths.js';
 // =============================================================================
 // State