@kinqs/brainrouter-cli 0.3.4

package/dist/agent/agent.d.ts

@@ -0,0 +1,765 @@
+import type { McpClientWrapper } from '../runtime/mcpClient.js';
+import type { LLMConfig } from '../config/config.js';
+import type { AccessMode } from '../orchestration/roles.js';
+export interface RunTurnCallbacks {
+    onStatusUpdate: (status: string) => void;
+    onToolStart: (name: string, args: Record<string, any>) => void;
+    onToolEnd: (name: string, result: {
+        success: boolean;
+        summary: string;
+        preview?: string;
+    }) => void;
+    /**
+     * Optional: invoked whenever the agent calls update_plan during a turn,
+     * so the REPL can render a live ✓ / ⏳ / ☐ checklist instead of leaving the
+     * plan invisible until the user runs `/plan`.
+     */
+    onPlanUpdate?: (items: Array<{
+        step: string;
+        status: 'pending' | 'in_progress' | 'completed';
+    }>, explanation?: string) => void;
+    /**
+     * Optional: invoked when a child agent (spawn_agent) finishes its runTurn —
+     * either succeeded with a final answer (preview supplied) or failed (error
+     * supplied). Lets the REPL signal "Agent X is done" so the user isn't
+     * staring at silence after the tool stream stops.
+     */
+    onChildComplete?: (event: {
+        childId: string;
+        role: string;
+        status: 'completed' | 'failed';
+        preview?: string;
+        error?: string;
+    }) => void;
+    /**
+     * Optional: invoked when the agent's automatic memory pipeline runs —
+     * pre-turn briefing, post-turn capture, citation marking. Surfacing these
+     * tells the user the BrainRouter cognitive memory engine is active even
+     * though those MCP calls are hidden from the LLM's tool stream.
+     */
+    onMemoryEvent?: (event: MemoryEvent) => void;
+}
+export type MemoryEvent = {
+    kind: 'briefing';
+    sources: string[];
+    recordCount: number;
+} | {
+    kind: 'capture';
+    sessionKey: string;
+    messageCount: number;
+    /** Number of sensory rows the MCP server wrote (raw conversation log). */
+    sensoryRecorded?: number;
+    /** True iff cognitive extraction was attempted this turn (may still have failed). */
+    extractionTriggered?: boolean;
+    /** Number of cognitive records produced — 0 indicates extraction is silently broken. */
+    extractedCount?: number;
+    /** Set when the extractor reports it couldn't reach the LLM. */
+    extractionWarning?: string;
+} | {
+    kind: 'citation';
+    recordIds: string[];
+} | {
+    kind: 'contradiction';
+    warning: string;
+} | {
+    kind: 'skipped';
+    reason: string;
+};
+export interface ChatCompletionPayload {
+    model: string;
+    messages: any[];
+    tools?: Array<{
+        type: 'function';
+        function: {
+            name: string;
+            description: string;
+            parameters: Record<string, any>;
+        };
+    }>;
+    tool_choice?: 'auto';
+}
+export interface AgentOptions {
+    workspaceRoot: string;
+    launchCwd: string;
+    sessionKey?: string;
+    roleOverlay?: string;
+    accessMode?: AccessMode;
+    silent?: boolean;
+    systemPromptOverride?: string;
+    /** When true (default for silent children: false), pre-turn memory recall runs even in silent mode. */
+    enableRecall?: boolean;
+    /**
+     * Parent OTEL trace context. Set by `spawn_agent` so the child's per-turn
+     * spans nest under the parent's `brainrouter.turn` span. Without this each
+     * child started a fresh trace tree and fan-out runs flattened in trace
+     * viewers — you couldn't see "this child belongs to that parent turn".
+     */
+    parentTraceId?: string;
+    parentSpanId?: string;
+}
+export declare const LOCAL_TOOLS: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {};
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+            startLine: {
+                type: string;
+                description: string;
+            };
+            endLine: {
+                type: string;
+                description: string;
+            };
+            content?: undefined;
+            targetContent?: undefined;
+            replacementContent?: undefined;
+            query?: undefined;
+            pattern?: undefined;
+            command?: undefined;
+            url?: undefined;
+            maxResults?: undefined;
+            patch?: undefined;
+            explanation?: undefined;
+            plan?: undefined;
+            proof?: undefined;
+            reason?: undefined;
+            needed?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+            content: {
+                type: string;
+                description: string;
+            };
+            startLine?: undefined;
+            endLine?: undefined;
+            targetContent?: undefined;
+            replacementContent?: undefined;
+            query?: undefined;
+            pattern?: undefined;
+            command?: undefined;
+            url?: undefined;
+            maxResults?: undefined;
+            patch?: undefined;
+            explanation?: undefined;
+            plan?: undefined;
+            proof?: undefined;
+            reason?: undefined;
+            needed?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+            targetContent: {
+                type: string;
+                description: string;
+            };
+            replacementContent: {
+                type: string;
+                description: string;
+            };
+            startLine?: undefined;
+            endLine?: undefined;
+            content?: undefined;
+            query?: undefined;
+            pattern?: undefined;
+            command?: undefined;
+            url?: undefined;
+            maxResults?: undefined;
+            patch?: undefined;
+            explanation?: undefined;
+            plan?: undefined;
+            proof?: undefined;
+            reason?: undefined;
+            needed?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+            startLine?: undefined;
+            endLine?: undefined;
+            content?: undefined;
+            targetContent?: undefined;
+            replacementContent?: undefined;
+            query?: undefined;
+            pattern?: undefined;
+            command?: undefined;
+            url?: undefined;
+            maxResults?: undefined;
+            patch?: undefined;
+            explanation?: undefined;
+            plan?: undefined;
+            proof?: undefined;
+            reason?: undefined;
+            needed?: undefined;
+        };
+        required?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+            query: {
+                type: string;
+                description: string;
+            };
+            startLine?: undefined;
+            endLine?: undefined;
+            content?: undefined;
+            targetContent?: undefined;
+            replacementContent?: undefined;
+            pattern?: undefined;
+            command?: undefined;
+            url?: undefined;
+            maxResults?: undefined;
+            patch?: undefined;
+            explanation?: undefined;
+            plan?: undefined;
+            proof?: undefined;
+            reason?: undefined;
+            needed?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            pattern: {
+                type: string;
+                description: string;
+            };
+            path?: undefined;
+            startLine?: undefined;
+            endLine?: undefined;
+            content?: undefined;
+            targetContent?: undefined;
+            replacementContent?: undefined;
+            query?: undefined;
+            command?: undefined;
+            url?: undefined;
+            maxResults?: undefined;
+            patch?: undefined;
+            explanation?: undefined;
+            plan?: undefined;
+            proof?: undefined;
+            reason?: undefined;
+            needed?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            command: {
+                type: string;
+                description: string;
+            };
+            path?: undefined;
+            startLine?: undefined;
+            endLine?: undefined;
+            content?: undefined;
+            targetContent?: undefined;
+            replacementContent?: undefined;
+            query?: undefined;
+            pattern?: undefined;
+            url?: undefined;
+            maxResults?: undefined;
+            patch?: undefined;
+            explanation?: undefined;
+            plan?: undefined;
+            proof?: undefined;
+            reason?: undefined;
+            needed?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            url: {
+                type: string;
+                description: string;
+            };
+            path?: undefined;
+            startLine?: undefined;
+            endLine?: undefined;
+            content?: undefined;
+            targetContent?: undefined;
+            replacementContent?: undefined;
+            query?: undefined;
+            pattern?: undefined;
+            command?: undefined;
+            maxResults?: undefined;
+            patch?: undefined;
+            explanation?: undefined;
+            plan?: undefined;
+            proof?: undefined;
+            reason?: undefined;
+            needed?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            maxResults: {
+                type: string;
+                description: string;
+            };
+            path?: undefined;
+            startLine?: undefined;
+            endLine?: undefined;
+            content?: undefined;
+            targetContent?: undefined;
+            replacementContent?: undefined;
+            pattern?: undefined;
+            command?: undefined;
+            url?: undefined;
+            patch?: undefined;
+            explanation?: undefined;
+            plan?: undefined;
+            proof?: undefined;
+            reason?: undefined;
+            needed?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            patch: {
+                type: string;
+                description: string;
+            };
+            path?: undefined;
+            startLine?: undefined;
+            endLine?: undefined;
+            content?: undefined;
+            targetContent?: undefined;
+            replacementContent?: undefined;
+            query?: undefined;
+            pattern?: undefined;
+            command?: undefined;
+            url?: undefined;
+            maxResults?: undefined;
+            explanation?: undefined;
+            plan?: undefined;
+            proof?: undefined;
+            reason?: undefined;
+            needed?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            explanation: {
+                type: string;
+                description: string;
+            };
+            plan: {
+                type: string;
+                description: string;
+                items: {
+                    type: string;
+                    properties: {
+                        step: {
+                            type: string;
+                        };
+                        status: {
+                            type: string;
+                            enum: string[];
+                        };
+                    };
+                    required: string[];
+                };
+            };
+            path?: undefined;
+            startLine?: undefined;
+            endLine?: undefined;
+            content?: undefined;
+            targetContent?: undefined;
+            replacementContent?: undefined;
+            query?: undefined;
+            pattern?: undefined;
+            command?: undefined;
+            url?: undefined;
+            maxResults?: undefined;
+            patch?: undefined;
+            proof?: undefined;
+            reason?: undefined;
+            needed?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            proof: {
+                type: string;
+                description: string;
+            };
+            path?: undefined;
+            startLine?: undefined;
+            endLine?: undefined;
+            content?: undefined;
+            targetContent?: undefined;
+            replacementContent?: undefined;
+            query?: undefined;
+            pattern?: undefined;
+            command?: undefined;
+            url?: undefined;
+            maxResults?: undefined;
+            patch?: undefined;
+            explanation?: undefined;
+            plan?: undefined;
+            reason?: undefined;
+            needed?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            reason: {
+                type: string;
+                description: string;
+            };
+            needed: {
+                type: string;
+                description: string;
+            };
+            path?: undefined;
+            startLine?: undefined;
+            endLine?: undefined;
+            content?: undefined;
+            targetContent?: undefined;
+            replacementContent?: undefined;
+            query?: undefined;
+            pattern?: undefined;
+            command?: undefined;
+            url?: undefined;
+            maxResults?: undefined;
+            patch?: undefined;
+            explanation?: undefined;
+            plan?: undefined;
+            proof?: undefined;
+        };
+        required: string[];
+    };
+})[];
+/**
+ * @deprecated Prefer passing an explicit workspaceRoot. Returns process.cwd()
+ * which is brittle when the Agent was constructed with a workspace different
+ * from cwd (e.g. when /resume re-attaches a session originally captured in
+ * another dir, or when the user cd's away after launch).
+ */
+export declare function getWorkspaceRoot(): string;
+/**
+ * Best-effort guidance for the LLM when it calls a tool name that doesn't
+ * exist (JSON-RPC -32601). The most common cause is confusing a BrainRouter
+ * skill (documentation) for an invocable tool. Pattern-match on the name and
+ * return a corrective hint that the next agent turn will see as the tool
+ * result.
+ */
+export declare function explainUnknownToolName(name: string): string;
+/**
+ * Normalize a tool name the LLM emitted into the canonical form used by the
+ * tool registry. Handles common variants: case (`Read_File`), separators
+ * (`read-file`, `read.file`), surrounding whitespace, and a short list of
+ * cross-vendor aliases (`Bash` → `run_command`).
+ *
+ * Returns the exact canonical name if a unique match is found among the
+ * provided candidates; otherwise returns the trimmed input (so the regular
+ * dispatch/explainUnknownToolName path still runs).
+ */
+export declare function normalizeToolName(raw: string, candidates: string[]): string;
+export declare function isPathInside(parent: string, candidate: string): boolean;
+/**
+ * Resolve a workspace-relative path against the given workspaceRoot. Throws
+ * if the result escapes the workspace.
+ *
+ * `workspaceRoot` is REQUIRED — passing a stale `process.cwd()` was the bug
+ * that let tool writes land in `~/.brainrouter` when the user's cwd drifted.
+ *
+ * For backwards compatibility, the workspaceRoot parameter may be omitted; it
+ * then falls back to process.cwd(). New code should always pass it explicitly.
+ */
+export declare function resolveWorkspacePath(workspaceRootOrPath?: string, inputPathOrOptions?: string | {
+    forWrite?: boolean;
+}, maybeOptions?: {
+    forWrite?: boolean;
+}): string;
+export declare class Agent {
+    private mcpClient;
+    private llmConfig;
+    sessionKey: string;
+    workspaceRoot: string;
+    launchCwd: string;
+    private chatHistory;
+    private initialized;
+    private recalledRecordIds;
+    private recalledRecords;
+    private lastBriefingSources;
+    private roleOverlay?;
+    private accessMode;
+    private silent;
+    private enableRecall;
+    private systemPromptOverride?;
+    /**
+     * Name of the BrainRouter skill currently being executed (e.g. via `/skill`
+     * or implicit memetic activation). Threaded into `memory_recall` and
+     * `memory_capture_turn` so skill-scoped recall boost, neural-spark
+     * prewarming, and per-record `skill_tag` extraction all fire correctly.
+     * Null/undefined when no skill is active.
+     */
+    activeSkill?: string;
+    /**
+     * Parent trace context (set by spawn_agent for child agents). When present,
+     * the per-turn span uses these as its trace/parent so OTEL viewers can
+     * stitch the fan-out tree together. Top-level (REPL) agents leave these
+     * undefined and get a fresh trace per turn.
+     */
+    private parentTraceId?;
+    private parentSpanId?;
+    /**
+     * Synthetic agent id used in OTEL attributes so child spans can be grouped
+     * even without trace links. Equals `agent-<6 random hex>` per Agent
+     * instance. Surfaced as the `agent_id` / `parent_agent_id` span attrs.
+     */
+    readonly agentId: string;
+    /** agent_id of the parent (set by spawn_agent for children). */
+    private parentAgentId?;
+    constructor(mcpClient: McpClientWrapper, llmConfig: LLMConfig, options: AgentOptions);
+    /** Expose for orchestration so spawn_agent can record the parent linkage. */
+    getAgentId(): string;
+    /** Internal — used by spawn_agent to record which parent dispatched us. */
+    setParentAgentId(id: string | undefined): void;
+    private allowedToolsForAccess;
+    runTurn(prompt: string, callbacks: RunTurnCallbacks): Promise<string>;
+    /** Rough token estimate (1 token ≈ 4 characters of English / code). */
+    static estimateTokens(text: string): number;
+    private executeLocalTool;
+    clearHistory(): void;
+    /**
+     * Compaction for /compact: summarize current chat history via the LLM,
+     * then replace the verbose log with [system, compactedSummary,
+     * lastUserMessage]. Returns the summary so the REPL can display it.
+     */
+    compactHistory(): Promise<{
+        summary: string;
+        estimatedTokens: number;
+        durationMs: number;
+        replacedMessages: number;
+    } | null>;
+    /** Runtime model switch. Used by `/model` slash command. */
+    setModel(model: string): void;
+    getModel(): string;
+    /** Runtime access-mode cycle for `/permissions` and Shift+Tab plan-mode toggle. */
+    getAccessMode(): AccessMode;
+    setAccessMode(mode: AccessMode): void;
+    /**
+     * Seed the chat history from a persisted transcript so the user can resume
+     * a previous session. The system message is regenerated for the current
+     * runtime so workspace/session context is fresh, but the user/assistant/tool
+     * messages are kept verbatim.
+     */
+    loadHistory(entries: Array<{
+        role: string;
+        content?: unknown;
+        name?: string;
+        tool_call_id?: string;
+        tool_calls?: unknown;
+    }>): number;
+    /** Cumulative token usage across the last runTurn. Cleared at each new turn. */
+    lastTurnUsage: {
+        promptTokens: number;
+        completionTokens: number;
+        calls: number;
+    };
+    /** Cumulative token usage across the WHOLE CLI session (all turns). */
+    sessionUsage: {
+        promptTokens: number;
+        completionTokens: number;
+        calls: number;
+        turns: number;
+    };
+    /**
+     * Memory-derived savings counters. These let `/tokens` produce a "memory
+     * saved you ~N tokens" narrative the user can actually point at.
+     *
+     *  - briefingTokensInjected:  approx tokens added to context as memory
+     *    briefings (recall + persona + scenes + recency). Each briefing
+     *    provides cross-session context that would otherwise require re-reading
+     *    files or re-explaining via prompts.
+     *  - offloadCharsAvoided:     chars of child-agent output that were pushed
+     *    to working memory instead of pasted back into parent context.
+     *  - recallRecordsConsulted:  count of memory record references the
+     *    briefing put in front of the model this session.
+     */
+    memoryMetrics: {
+        briefingTokensInjected: number;
+        offloadCharsAvoided: number;
+        recallRecordsConsulted: number;
+    };
+    /** Last assistant message of the most recent turn — used by `/copy`. */
+    lastAnswer: string;
+    /** Last user prompt (post-mention-expansion). Used by `/continue` to resume after a loop-limit abort. */
+    lastUserPrompt: string;
+    /** True when the most recent turn hit the loop-limit ceiling before producing a final answer. */
+    lastTurnHitLoopLimit: boolean;
+    /** Count of tool calls executed during the most recent runTurn. The goal */
+    /** continuation loop uses this to suppress auto-continuation after prose-only turns. */
+    lastTurnToolCalls: number;
+    /** Goal lifecycle transition the LLM triggered during the most recent turn, if any. */
+    lastGoalTransition: 'complete' | 'blocked' | undefined;
+    /** Allow REPL slash commands to refresh the system prompt without bumping a new turn. */
+    refreshSystemPrompt(): void;
+    /**
+     * Push (or replace) a tagged system message in `chatHistory`. Per-turn
+     * directives like the briefing block and the fan-out hint used to be pushed
+     * unconditionally — each turn added a fresh copy without removing the prior
+     * one, so a 10-turn conversation carried 10 stacked briefings. This helper
+     * removes any older entry with the same tag before appending the new one,
+     * keeping the model's view of "current memory state" current.
+     */
+    replaceTaggedSystemMessage(tag: string, content: string): void;
+    /**
+     * Drop any system message previously installed under `tag`. Used to retract
+     * one-off directives once the condition that motivated them no longer
+     * holds — e.g. the budget-steering "wrap up gracefully" message must
+     * disappear after the user extends the goal's budget, otherwise it keeps
+     * telling the model "this is your last turn" for every subsequent turn.
+     *
+     * Idempotent: calling this with a tag that isn't present is a no-op.
+     */
+    removeTaggedSystemMessage(tag: string): void;
+    /** Fork the current chat history into a fresh sessionKey. Returns the new key. */
+    fork(newSessionKey: string): string;
+    private bootstrapSession;
+    private createSystemMessage;
+    private injectRecallContext;
+    /** Inspectable summary of the most recent memory briefing. Used by the `/briefing` slash command. */
+    getLastBriefing(): {
+        sources: string[];
+        recordIds: string[];
+    };
+    /** One-line summary of any new contradiction surfaced after the last capture, or undefined if none. */
+    private lastContradictionWarning?;
+    takeContradictionWarning(): string | undefined;
+    private checkContradictions;
+    private captureTurn;
+    private recordTranscript;
+}
+/**
+ * Apply a Begin/End-envelope patch:
+ *
+ *   *** Begin Patch
+ *   *** Update File: path/relative/to/workspace
+ *   @@ optional context anchor
+ *   -old line
+ *   +new line
+ *    unchanged line
+ *   *** Add File: another/path
+ *   +line 1
+ *   +line 2
+ *   *** Delete File: third/path
+ *   *** End Patch
+ *
+ * Returns a JSON summary of operations performed; throws on a malformed envelope
+ * or when an Update fails to match its context block uniquely.
+ */
+export declare function applyPatchEnvelope(patch: string, workspaceRoot?: string): string;
+export declare function matchGlob(pattern: string, filePath: string): boolean;
+export declare function globFiles(pattern: string, workspaceRoot?: string, dir?: string): string[];
+export declare function getToolSummary(name: string, args: Record<string, any>, result: string): string;
+/**
+ * Optional inline preview for inspection-style tools. The REPL renders this
+ * indented below the one-line summary so the user can SEE the result even if
+ * the LLM forgets to echo it in its reply. Limited to a handful of tools where
+ * the result is concise and the user's intent is almost always "show me this":
+ * `list_dir`, `grep_search`, `glob_files`. Other tools (read_file, run_command)
+ * fire too often as internal exploration steps — previewing them would flood
+ * the terminal. Returns undefined when no useful preview is available.
+ */
+export declare function getToolPreview(name: string, args: Record<string, any>, result: string): string | undefined;
+export declare function buildChatCompletionPayload(config: LLMConfig, messages: any[], tools: any[]): ChatCompletionPayload;
+export declare function callOpenAI(config: LLMConfig, messages: any[], tools: any[]): Promise<{
+    content: any;
+    toolCalls: any;
+    usage: any;
+}>;