cliskill 1.0.4 → 1.0.6

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { runCli } from './bootstrap/cli.js';
 import { z } from 'zod';
+import { ChildProcess } from 'node:child_process';
+import { EventEmitter } from 'node:events';
 import React from 'react';
 
 /**
@@ -242,6 +244,31 @@ declare const appConfigSchema: z.ZodObject<{
         maxMemorySize?: number | undefined;
         idleThreshold?: number | undefined;
     }>>;
+    /** MCP servers — external tool providers via Model Context Protocol */
+    mcpServers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        /** Unique name for this MCP server */
+        name: z.ZodString;
+        /** Command to start the MCP server process */
+        command: z.ZodString;
+        /** Arguments passed to the command */
+        args: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        /** Environment variables for the server process */
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        /** Transport type (currently only stdio supported) */
+        transport: z.ZodDefault<z.ZodEnum<["stdio"]>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        command: string;
+        args: string[];
+        transport: "stdio";
+        env?: Record<string, string> | undefined;
+    }, {
+        name: string;
+        command: string;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+        transport?: "stdio" | undefined;
+    }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     providers: {
         name: string;
@@ -305,6 +332,13 @@ declare const appConfigSchema: z.ZodObject<{
         maxMemorySize: number;
         idleThreshold: number;
     };
+    mcpServers: {
+        name: string;
+        command: string;
+        args: string[];
+        transport: "stdio";
+        env?: Record<string, string> | undefined;
+    }[];
     defaultProvider?: string | undefined;
     systemPrompt?: string | undefined;
 }, {
@@ -372,6 +406,13 @@ declare const appConfigSchema: z.ZodObject<{
         maxMemorySize?: number | undefined;
         idleThreshold?: number | undefined;
     } | undefined;
+    mcpServers?: {
+        name: string;
+        command: string;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+        transport?: "stdio" | undefined;
+    }[] | undefined;
 }>;
 type AppConfig = z.infer<typeof appConfigSchema>;
 
@@ -508,6 +549,11 @@ type LoopEvent = {
     type: 'tool_start';
     toolName: string;
     toolId: string;
+} | {
+    type: 'tool_progress';
+    toolName: string;
+    toolId: string;
+    message: string;
 } | {
     type: 'tool_result';
     toolName: string;
@@ -545,6 +591,8 @@ interface ToolExecutionContext {
     checkPermission: (operation: string, details?: string) => Promise<boolean>;
     /** Session identifier for per-session state isolation */
     sessionId?: string;
+    /** P0.2: Progress callback — tools emit intermediate status messages */
+    onProgress?: (message: string) => void;
 }
 
 /** Risk level of a tool operation */
@@ -553,16 +601,22 @@ type RiskLevel = 'readonly' | 'safe' | 'destructive' | 'critical';
 interface ToolContract {
     /** Unique name of the tool */
     name: string;
+    /** Alternative names for the tool (backward-compatible aliases) */
+    aliases?: string[];
     /** Description shown to the AI model */
     description: string;
+    /** Short hint for tool search/discovery */
+    searchHint?: string;
     /** Zod schema for input validation */
     inputSchema: z.ZodType;
     /** Risk level — determines permission requirements */
     riskLevel: RiskLevel;
-    /** Whether this tool can run concurrently with other tools */
-    concurrencySafe: boolean;
+    /** Whether this tool can run concurrently with other tools (static or dynamic per-input) */
+    concurrencySafe: boolean | ((input: Record<string, unknown>) => boolean);
     /** Whether this tool only reads data (no side effects) */
     readOnly: boolean;
+    /** Maximum output chars before truncation (default: 50_000) */
+    maxResultSizeChars?: number;
     /**
      * Execute the tool with validated input.
      * Returns a string result to be sent back to the model.
@@ -601,19 +655,22 @@ declare abstract class BaseTool<T extends z.ZodType> implements ToolContract {
  */
 declare class ToolRegistry {
     private tools;
-    /** Register a tool */
+    private aliasMap;
+    /** Register a tool (with optional aliases) */
     register(tool: ToolContract): void;
-    /** Get a tool by name */
+    /** Get a tool by name or alias */
     get(name: string): ToolContract | undefined;
     /** Get all registered tools */
     getAll(): ToolContract[];
     /** Get tool definitions for AI model requests */
     getToolDefinitions(): ToolDefinition[];
-    /** Check if a tool exists */
+    /** Check if a tool exists (by name or alias) */
     has(name: string): boolean;
-    /** Unregister a tool */
+    /** Search tools by keyword in name, description, or searchHint */
+    search(keyword: string): ToolContract[];
+    /** Unregister a tool (and its aliases) */
     unregister(name: string): void;
-    /** Clear all tools */
+    /** Clear all tools and aliases */
     clear(): void;
 }
 
@@ -677,6 +734,10 @@ type TaskCategory = 'reasoning' | 'code' | 'fast' | 'creative' | 'analysis' | 'd
 interface ModelRouterConfig {
     /** Default model/alias to use when no specific model is requested */
     defaultModel: string;
+    /** Fallback model/alias when primary fails (529/503/overloaded) */
+    fallbackModel?: string;
+    /** Ordered list of fallback models — tried sequentially on failure */
+    fallbackChain?: string[];
     /** Model preferences per task category */
     preferences: Partial<Record<TaskCategory, string>>;
 }
@@ -701,6 +762,36 @@ declare class ModelRouter {
     }>;
     /** Get the effective model name for a given alias or name */
     getEffectiveModel(requestedModel?: string): string;
+    /**
+     * Resolve with fallback: if primary adapter fails (529/503/overloaded),
+     * try the fallback model. Returns both adapters for retry logic.
+     */
+    resolveWithFallback(primaryModel?: string): {
+        primary: ProviderAdapter | null;
+        fallback: ProviderAdapter | null;
+    };
+    /**
+     * Build the full fallback chain for a given primary model.
+     * Returns adapters in priority order: [primary, ...fallbackChain].
+     * Skips duplicates and null entries.
+     */
+    resolveFallbackChain(primaryModel?: string): ProviderAdapter[];
+    /**
+     * Stream with automatic fallback on overloaded errors.
+     * Tries each adapter in the fallback chain until one succeeds.
+     * Yields a mix of the primary response or fallback response events.
+     */
+    streamWithFallback(request: CompletionRequest, primaryModel?: string): AsyncGenerator<StreamEvent>;
+    /**
+     * Complete with automatic fallback on overloaded errors.
+     * Tries each adapter in the fallback chain until one succeeds.
+     */
+    completeWithFallback(request: CompletionRequest, primaryModel?: string): Promise<{
+        result: CompletionResult;
+        usedModel: string;
+    }>;
+    /** Find an alternative adapter different from the excluded one */
+    private findAlternativeAdapter;
     private findAdapterForModel;
 }
 
@@ -1252,6 +1343,75 @@ declare class AgentTool extends BaseTool<typeof agentInputSchema> {
     execute(input: AgentInput, context: ToolExecutionContext): Promise<string>;
 }
 
+type TaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+interface Task {
+    id: string;
+    name: string;
+    description: string;
+    type: 'agent' | 'shell' | 'custom';
+    status: TaskStatus;
+    progress: number;
+    result: string | null;
+    error: string | null;
+    output: string;
+    exitCode: number | null;
+    createdAt: number;
+    completedAt: number | null;
+    /** Shell command (for shell tasks started via startTask) */
+    command: string;
+    /** Command arguments (for shell tasks started via startTask) */
+    args: string[];
+    /** Running child process (only for shell tasks started via startTask) */
+    process?: ChildProcess;
+}
+interface TaskCreateOptions {
+    name: string;
+    description: string;
+    type: 'agent' | 'shell' | 'custom';
+}
+type EventMap = {
+    onProgress: [taskId: string, progress: number, message?: string];
+    onComplete: [taskId: string, result: string];
+    onError: [taskId: string, error: string];
+    onStatusChange: [taskId: string, status: TaskStatus];
+};
+/**
+ * TaskManager — manages background tasks with event emission.
+ * Supports both generic tasks (via createTask) and shell tasks (via startTask).
+ */
+declare class TaskManager extends EventEmitter {
+    private tasks;
+    private completedOrder;
+    /** Create a generic task entry (for agent/shell tasks via executor) */
+    createTask(options: TaskCreateOptions): string;
+    /** Start a shell task with a spawned child process */
+    startTask(command: string, args?: string[], cwd?: string): Task;
+    getTask(id: string): Task | undefined;
+    stopTask(id: string): boolean;
+    /** Update task status (for agent/shell tasks via executor) */
+    updateStatus(id: string, status: TaskStatus): void;
+    /** Update task progress percentage (for agent tasks) */
+    updateProgress(id: string, progress: number, message?: string): void;
+    /** Cancel a task (for agent/shell tasks via executor) */
+    cancelTask(id: string): void;
+    /** Set error result on a task */
+    setError(id: string, error: string): void;
+    /** Set success result on a task */
+    setResult(id: string, result: string): void;
+    /** Remove a completed/failed/cancelled task */
+    removeTask(id: string): void;
+    /** Clear all completed/failed/cancelled tasks */
+    clearCompleted(): void;
+    /** Count of active (pending + running) tasks */
+    getActiveCount(): number;
+    listTasks(filter?: {
+        status?: TaskStatus;
+    } | TaskStatus): Task[];
+    /** Type-safe event listener */
+    on<E extends keyof EventMap>(event: E, listener: (...args: EventMap[E]) => void): this;
+    private evictOldTasks;
+}
+
 /** A memory entry stored in the memory system */
 interface MemoryEntry {
     /** Unique ID */
@@ -1446,27 +1606,49 @@ interface PermissionResult {
     allowed: boolean;
     reason?: string;
 }
+/** Auto-approve rule pattern */
+interface AutoApprovePattern {
+    /** Tool name or glob pattern */
+    tool: string;
+    /** Content regex pattern for auto-approval */
+    inputPattern?: RegExp;
+    /** Max risk level to auto-approve */
+    maxRiskLevel?: RiskLevel;
+}
 /**
  * Permission manager that evaluates tool execution requests
- * against configured rules and the current permission mode.
+ * against configured rules, auto-approve patterns, and the current permission mode.
+ * P3.13: Enhanced with dynamic permission checking, auto-approve patterns, and caching.
  */
 declare class PermissionManager {
     private mode;
     private rules;
     private sessionDecisions;
-    constructor(mode: PermissionMode, rules?: PermissionRule[]);
+    private autoApprovePatterns;
+    private decisionCache;
+    private cacheTtl;
+    constructor(mode: PermissionMode, rules?: PermissionRule[], autoApprovePatterns?: AutoApprovePattern[]);
+    /**
+     * P3.13: Dynamic permission check — evaluates tool + input together.
+     * Uses auto-approve patterns for regex-based matching.
+     */
+    canUseTool(toolName: string, input: Record<string, unknown>, riskLevel: RiskLevel): PermissionResult;
     /**
      * Check if a tool operation is allowed.
      */
     check(toolName: string, riskLevel: RiskLevel, content?: string): PermissionResult;
     /**
-     * Record a user decision for the session.
+     * Record a user decision for the session with caching.
      */
     recordDecision(toolName: string, content: string, allowed: boolean): void;
     /**
      * Add a permission rule.
      */
     addRule(rule: PermissionRule): void;
+    /**
+     * P3.13: Add an auto-approve pattern.
+     */
+    addAutoApprovePattern(pattern: AutoApprovePattern): void;
     /**
      * Set the permission mode.
      */
@@ -1477,6 +1659,7 @@ declare class PermissionManager {
     getMode(): PermissionMode;
     private matchTool;
     private matchContent;
+    private riskLevelOrdinal;
 }
 
 /**
@@ -1526,12 +1709,27 @@ interface CostConfig {
         cacheWrite: number;
     }>;
     budgetLimit?: number;
+    /** Warning thresholds (0-1) — triggers onBudgetWarning callback */
+    warningThreshold?: number;
+    /** Critical threshold (0-1) — triggers onBudgetCritical callback */
+    criticalThreshold?: number;
+}
+type BudgetLevel = 'normal' | 'warning' | 'critical' | 'exceeded';
+interface BudgetStatus {
+    level: BudgetLevel;
+    used: number;
+    limit?: number;
+    percent: number;
+    remainingBudget?: number;
 }
 declare class CostTracker {
     private entries;
     private config;
     private sessionStart;
+    private lastBudgetLevel;
     constructor(config?: Partial<CostConfig>);
+    /** Find prices for a model — exact match first, then fuzzy pattern matching */
+    private findPrices;
     /** Record token usage for a model */
     recordUsage(model: string, usage: Omit<ModelUsage, 'model' | 'totalRequests'>): CostEntry;
     /** Get total session cost in USD */
@@ -1551,6 +1749,24 @@ declare class CostTracker {
         limit?: number;
         percent?: number;
     };
+    /**
+     * Get detailed budget status with warning levels.
+     * Returns current budget level and whether it changed since last check.
+     */
+    getBudgetStatus(): BudgetStatus;
+    /**
+     * Check if budget level changed since last call.
+     * Returns the new status if it escalated, null if unchanged.
+     * Use this to emit budget warnings to the user.
+     */
+    checkBudgetWarning(): BudgetStatus | null;
+    /** Get cache efficiency metrics */
+    getCacheMetrics(): {
+        totalCacheReads: number;
+        totalCacheWrites: number;
+        cacheHitRate: number;
+        savings: number;
+    };
     /** Get session duration in ms */
     getSessionDuration(): number;
     /** Reset for new session */
@@ -1643,6 +1859,16 @@ interface ExecutorResult {
         type: 'tool_result';
     }>;
 }
+interface ProgressEvent {
+    toolName: string;
+    toolId: string;
+    message: string;
+}
+/** Union type for events yielded by getRemainingResults() */
+type ExecutorEvent = ExecutorResult | {
+    type: 'progress';
+    progress: ProgressEvent;
+};
 type ToolExecutionFn = (toolCall: {
     id: string;
     name: string;
@@ -1661,6 +1887,8 @@ declare class StreamingToolExecutor {
     private bashErrorDescription;
     private siblingAbortController;
     private discarded;
+    private pendingProgress;
+    private progressAvailableResolve;
     private readonly toolRegistry;
     private readonly executorConfig;
     private readonly toolContext?;
@@ -1675,6 +1903,8 @@ declare class StreamingToolExecutor {
     constructor(tools: ToolRegistry, configOrContext?: ExecutorConfig | ToolExecutionContext, autoMode?: AutoModeManager, onPermissionRequest?: (operation: string, details?: string) => Promise<boolean>, executeFn?: ToolExecutionFn);
     /** Discard all pending/in-progress tools */
     discard(): void;
+    /** P0.2: Emit a progress event for a running tool */
+    onToolProgress(toolName: string, toolId: string, message: string): void;
     /** Add a tool to the execution queue. Starts immediately if conditions allow. */
     addTool(toolCall: {
         id: string;
@@ -1683,8 +1913,10 @@ declare class StreamingToolExecutor {
     }): void;
     /** Get completed results in queue order (non-blocking) */
     getCompletedResults(): Generator<ExecutorResult, void>;
-    /** Wait for all remaining tools and yield results as they complete */
-    getRemainingResults(): AsyncGenerator<ExecutorResult, void>;
+    /** Drain buffered progress events */
+    drainProgress(): Generator<ProgressEvent, void>;
+    /** Wait for all remaining tools and yield results + progress events as they arrive */
+    getRemainingResults(): AsyncGenerator<ExecutorEvent, void>;
     /** Execute a batch of tool calls and return all results */
     executeTools(requests: ToolCallRequest[], context: ToolExecutionContext): Promise<ToolCallResult[]>;
     /** Cancel all running tools (backward-compatible alias for discard()) */
@@ -1721,6 +1953,7 @@ interface MessageForCompaction {
 declare class ContextCompactor {
     private config;
     private adapter;
+    private consecutiveFailures;
     constructor(config: CompactionConfig, adapter?: ProviderAdapter | null);
     shouldCompact(messages: MessageForCompaction[]): boolean;
     compact(messages: MessageForCompaction[], systemPrompt?: string): Promise<CompactionResult>;
@@ -1884,55 +2117,6 @@ declare class MCPConnectionManager {
     disconnectAll(): Promise<void>;
 }
 
-type TaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
-interface TaskDefinition {
-    id: string;
-    name: string;
-    description: string;
-    type: 'agent' | 'shell' | 'custom';
-    status: TaskStatus;
-    createdAt: number;
-    startedAt?: number;
-    completedAt?: number;
-    error?: string;
-    result?: string;
-    progress?: number;
-}
-interface TaskEvents {
-    onProgress: (taskId: string, progress: number, message?: string) => void;
-    onComplete: (taskId: string, result: string) => void;
-    onError: (taskId: string, error: string) => void;
-    onStatusChange: (taskId: string, status: TaskStatus) => void;
-}
-type TaskEventName = keyof TaskEvents;
-type TaskEventHandler<E extends TaskEventName> = TaskEvents[E];
-
-declare class TaskManager {
-    private tasks;
-    private listeners;
-    private idCounter;
-    createTask(definition: Omit<TaskDefinition, 'id' | 'status' | 'createdAt'>): string;
-    cancelTask(id: string): void;
-    getTask(id: string): TaskDefinition | undefined;
-    listTasks(filter?: {
-        status?: TaskStatus;
-    }): TaskDefinition[];
-    getActiveCount(): number;
-    removeTask(id: string): void;
-    clearCompleted(): void;
-    on<E extends TaskEventName>(event: E, handler: TaskEventHandler<E>): void;
-    off<E extends TaskEventName>(event: E, handler: TaskEventHandler<E>): void;
-    /** @internal Update task status */
-    updateStatus(id: string, status: TaskStatus): void;
-    /** @internal Update task progress */
-    updateProgress(id: string, progress: number, message?: string): void;
-    /** @internal Set task result */
-    setResult(id: string, result: string): void;
-    /** @internal Set task error */
-    setError(id: string, error: string): void;
-    private emit;
-}
-
 declare function executeAgentTask(taskId: string, manager: TaskManager, adapter: ProviderAdapter, tools: ToolRegistry, prompt: string, signal?: AbortSignal): Promise<void>;
 declare function executeShellTask(taskId: string, manager: TaskManager, command: string, cwd: string, signal?: AbortSignal): Promise<void>;
 
@@ -2012,16 +2196,18 @@ interface InkAppProps {
     model: string;
     toolCount: number;
     onSubmit: (message: string, onEvent: LoopEventHandler) => Promise<void>;
+    /** Called when user presses Escape during active processing — should abort the current request */
+    onCancel?: () => void;
 }
 declare const StatusBar: React.NamedExoticComponent<StatusBarProps>;
 declare const Spinner: React.NamedExoticComponent<{
     label: string;
 }>;
-declare function InkApp({ model, toolCount, onSubmit }: InkAppProps): React.ReactElement;
+declare function InkApp({ model, toolCount, onSubmit, onCancel }: InkAppProps): React.ReactElement;
 declare function renderInkApp(props: InkAppProps): void;
 declare function formatAnsiMessage(message: ChatMessage): string;
 declare function MessageList({ messages }: {
     messages: ChatMessage[];
 }): React.ReactElement;
 
-export { AdapterRegistry, type AgentConfig, type AgentRole, AgentTool, type AppConfig, type ChatMessage, type CommandAnalysis, type CompactionConfig, type CompactionResult, type CompletionRequest, type CompletionResult, ContextCompactor, type CostConfig, type CostEntry, CostTracker, type EnhancedMemoryConfig, type EnhancedMemoryEntry, EnhancedMemoryStore, EnterPlanModeTool, type ExecutorConfig, ExitPlanModeTool, GenericCompatAdapter, type HistoryConfig, type HistoryEntry, HistoryManager, type HookCondition, type HookContext, type HookDefinition, type HookEvent, HookExecutor, HookRegistry, type HookResult, InkApp, type InkAppProps, type JSONRPCRequest, type JSONRPCResponse, type LoopEventHandler, LspTool, MCPClient, MCPConnectionManager, type MCPPrompt, type MCPResource, type MCPServerConfig, type MCPTool, type MemoryEntry, type MemorySearchResult, MemoryStore, type Message, type MessageForCompaction, MessageList, type ModelRouterFactory, type ModelUsage, type ParsedCommand, PermissionManager, type ProviderAdapter, type ProviderConfig, QueryEngine, type QueryEngineConfig, type QueryEvent, type QueryResult, type Redirection, type RegistryFactory, type SkillDefinition, SkillRegistry, Spinner, StatusBar, type StatusBarProps, type StreamEvent, StreamingToolExecutor, type SubTask, SwarmCoordinator, type SwarmMessage, type SwarmResult, type TaskDefinition, type TaskEventHandler, type TaskEventName, type TaskEvents, TaskManager, type TaskStatus, type TokenBudgetAnalysis, type ToolCallRequest, type ToolCallResult, type ToolContract, ToolRegistry, WebSearchTool, analyzeCommand, analyzeTokenBudget, createDefaultToolRegistry, estimateMessagesTokens, estimateTokens, executeAgentTask, executeShellTask, formatAnsiMessage, inspectCommand, parseCommand, renderInkApp, runAgentLoop };
+export { AdapterRegistry, type AgentConfig, type AgentRole, AgentTool, type AppConfig, type ChatMessage, type CommandAnalysis, type CompactionConfig, type CompactionResult, type CompletionRequest, type CompletionResult, ContextCompactor, type CostConfig, type CostEntry, CostTracker, type EnhancedMemoryConfig, type EnhancedMemoryEntry, EnhancedMemoryStore, EnterPlanModeTool, type ExecutorConfig, ExitPlanModeTool, GenericCompatAdapter, type HistoryConfig, type HistoryEntry, HistoryManager, type HookCondition, type HookContext, type HookDefinition, type HookEvent, HookExecutor, HookRegistry, type HookResult, InkApp, type InkAppProps, type JSONRPCRequest, type JSONRPCResponse, type LoopEventHandler, LspTool, MCPClient, MCPConnectionManager, type MCPPrompt, type MCPResource, type MCPServerConfig, type MCPTool, type MemoryEntry, type MemorySearchResult, MemoryStore, type Message, type MessageForCompaction, MessageList, type ModelRouterFactory, type ModelUsage, type ParsedCommand, PermissionManager, type ProviderAdapter, type ProviderConfig, QueryEngine, type QueryEngineConfig, type QueryEvent, type QueryResult, type Redirection, type RegistryFactory, type SkillDefinition, SkillRegistry, Spinner, StatusBar, type StatusBarProps, type StreamEvent, StreamingToolExecutor, type SubTask, SwarmCoordinator, type SwarmMessage, type SwarmResult, type Task, type TaskCreateOptions, TaskManager, type TaskStatus, type TokenBudgetAnalysis, type ToolCallRequest, type ToolCallResult, type ToolContract, ToolRegistry, WebSearchTool, analyzeCommand, analyzeTokenBudget, createDefaultToolRegistry, estimateMessagesTokens, estimateTokens, executeAgentTask, executeShellTask, formatAnsiMessage, inspectCommand, parseCommand, renderInkApp, runAgentLoop };