@kinqs/brainrouter-cli 0.3.5 → 0.3.7

package/dist/agent/agent.d.ts

@@ -1,6 +1,8 @@
-import type { McpClientWrapper } from '../runtime/mcpClient.js';
+import type { McpClientPool as McpClientWrapper } from '../runtime/mcpPool.js';
 import type { LLMConfig } from '../config/config.js';
 import type { AccessMode } from '../orchestration/roles.js';
+import { type RecalledRecord } from '../memory/briefing.js';
+import { type EffortLevel } from '../state/preferencesStore.js';
 export interface RunTurnCallbacks {
     onStatusUpdate: (status: string) => void;
     onToolStart: (name: string, args: Record<string, any>) => void;
@@ -77,6 +79,12 @@ export interface ChatCompletionPayload {
         };
     }>;
     tool_choice?: 'auto';
+    /**
+     * OpenAI Chat Completions reasoning slot — accepted by gpt-5 / o-series.
+     * Only set when the user has chosen a non-default `/effort` AND the
+     * endpoint+model combo accepts the field (see `supportsReasoningEffortField`).
+     */
+    reasoning_effort?: EffortLevel;
 }
 export interface AgentOptions {
     workspaceRoot: string;
@@ -96,6 +104,10 @@ export interface AgentOptions {
      */
     parentTraceId?: string;
     parentSpanId?: string;
+    /** Agent tier — propagated from the definition so hierarchy checks work in grandchildren. */
+    tier?: 'chat' | 'reasoning' | 'worker';
+    /** Nesting depth in the spawn chain; 0 = direct child of the chat root (default). */
+    agentDepth?: number;
 }
 export declare const LOCAL_TOOLS: ({
     name: string;
@@ -131,6 +143,10 @@ export declare const LOCAL_TOOLS: ({
             url?: undefined;
             maxResults?: undefined;
             patch?: undefined;
+            question?: undefined;
+            header?: undefined;
+            options?: undefined;
+            multiSelect?: undefined;
             explanation?: undefined;
             plan?: undefined;
             proof?: undefined;
@@ -163,6 +179,10 @@ export declare const LOCAL_TOOLS: ({
             url?: undefined;
             maxResults?: undefined;
             patch?: undefined;
+            question?: undefined;
+            header?: undefined;
+            options?: undefined;
+            multiSelect?: undefined;
             explanation?: undefined;
             plan?: undefined;
             proof?: undefined;
@@ -198,6 +218,10 @@ export declare const LOCAL_TOOLS: ({
             url?: undefined;
             maxResults?: undefined;
             patch?: undefined;
+            question?: undefined;
+            header?: undefined;
+            options?: undefined;
+            multiSelect?: undefined;
             explanation?: undefined;
             plan?: undefined;
             proof?: undefined;
@@ -227,6 +251,10 @@ export declare const LOCAL_TOOLS: ({
             url?: undefined;
             maxResults?: undefined;
             patch?: undefined;
+            question?: undefined;
+            header?: undefined;
+            options?: undefined;
+            multiSelect?: undefined;
             explanation?: undefined;
             plan?: undefined;
             proof?: undefined;
@@ -259,6 +287,10 @@ export declare const LOCAL_TOOLS: ({
             url?: undefined;
             maxResults?: undefined;
             patch?: undefined;
+            question?: undefined;
+            header?: undefined;
+            options?: undefined;
+            multiSelect?: undefined;
             explanation?: undefined;
             plan?: undefined;
             proof?: undefined;
@@ -288,6 +320,10 @@ export declare const LOCAL_TOOLS: ({
             url?: undefined;
             maxResults?: undefined;
             patch?: undefined;
+            question?: undefined;
+            header?: undefined;
+            options?: undefined;
+            multiSelect?: undefined;
             explanation?: undefined;
             plan?: undefined;
             proof?: undefined;
@@ -317,6 +353,10 @@ export declare const LOCAL_TOOLS: ({
             url?: undefined;
             maxResults?: undefined;
             patch?: undefined;
+            question?: undefined;
+            header?: undefined;
+            options?: undefined;
+            multiSelect?: undefined;
             explanation?: undefined;
             plan?: undefined;
             proof?: undefined;
@@ -346,6 +386,10 @@ export declare const LOCAL_TOOLS: ({
             command?: undefined;
             maxResults?: undefined;
             patch?: undefined;
+            question?: undefined;
+            header?: undefined;
+            options?: undefined;
+            multiSelect?: undefined;
             explanation?: undefined;
             plan?: undefined;
             proof?: undefined;
@@ -378,6 +422,10 @@ export declare const LOCAL_TOOLS: ({
             command?: undefined;
             url?: undefined;
             patch?: undefined;
+            question?: undefined;
+            header?: undefined;
+            options?: undefined;
+            multiSelect?: undefined;
             explanation?: undefined;
             plan?: undefined;
             proof?: undefined;
@@ -407,6 +455,68 @@ export declare const LOCAL_TOOLS: ({
             command?: undefined;
             url?: undefined;
             maxResults?: undefined;
+            question?: undefined;
+            header?: undefined;
+            options?: undefined;
+            multiSelect?: undefined;
+            explanation?: undefined;
+            plan?: undefined;
+            proof?: undefined;
+            reason?: undefined;
+            needed?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            question: {
+                type: string;
+                description: string;
+            };
+            header: {
+                type: string;
+                description: string;
+            };
+            options: {
+                type: string;
+                description: string;
+                minItems: number;
+                maxItems: number;
+                items: {
+                    type: string;
+                    properties: {
+                        label: {
+                            type: string;
+                            description: string;
+                        };
+                        description: {
+                            type: string;
+                            description: string;
+                        };
+                    };
+                    required: string[];
+                };
+            };
+            multiSelect: {
+                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;
@@ -454,6 +564,10 @@ export declare const LOCAL_TOOLS: ({
             url?: undefined;
             maxResults?: undefined;
             patch?: undefined;
+            question?: undefined;
+            header?: undefined;
+            options?: undefined;
+            multiSelect?: undefined;
             proof?: undefined;
             reason?: undefined;
             needed?: undefined;
@@ -482,6 +596,10 @@ export declare const LOCAL_TOOLS: ({
             url?: undefined;
             maxResults?: undefined;
             patch?: undefined;
+            question?: undefined;
+            header?: undefined;
+            options?: undefined;
+            multiSelect?: undefined;
             explanation?: undefined;
             plan?: undefined;
             reason?: undefined;
@@ -515,6 +633,10 @@ export declare const LOCAL_TOOLS: ({
             url?: undefined;
             maxResults?: undefined;
             patch?: undefined;
+            question?: undefined;
+            header?: undefined;
+            options?: undefined;
+            multiSelect?: undefined;
             explanation?: undefined;
             plan?: undefined;
             proof?: undefined;
@@ -575,6 +697,28 @@ export declare class Agent {
     private recalledRecordIds;
     private recalledRecords;
     private lastBriefingSources;
+    /**
+     * 10b: latest MCP tool inventory captured by `listTools()` calls. Used by
+     * `createSystemMessage` to decide whether the BrainRouter memory section
+     * should render — when `memory_recall` is missing from this list (the
+     * cloud brain is offline), the prompt swaps to a brain-offline notice so
+     * the model doesn't try to call tools that aren't there. Undefined until
+     * the first successful list; treated as "assume online" by the prompt
+     * builder until then (back-compat for callers that don't list pre-turn).
+     */
+    private lastKnownMcpTools?;
+    /**
+     * 9b: gated recall state. `recallHasFiredThisSession` flips to true on the
+     * first successful briefing injection so subsequent turns can skip the
+     * fresh recall pull unless a gated trigger fires. `recallNextTurnIsPost-
+     * Compaction` is set by `compactHistory()` to force the next turn through
+     * the full briefing path (compaction just dropped the prior briefing as
+     * collateral; replay it once so the model isn't blind). Both are
+     * cleared on `loadHistory` / `fork` / `bootstrapSession` so a fresh
+     * session re-pulls.
+     */
+    private recallHasFiredThisSession;
+    private recallNextTurnIsPostCompaction;
     private roleOverlay?;
     private accessMode;
     private silent;
@@ -604,11 +748,18 @@ export declare class Agent {
     readonly agentId: string;
     /** agent_id of the parent (set by spawn_agent for children). */
     private parentAgentId?;
+    /** Agent tier — forwarded to OrchestrationContext so grandchildren can inherit hierarchy checks. */
+    readonly tier?: 'chat' | 'reasoning' | 'worker';
+    /** Spawn-chain depth (0 = direct chat-root child). Forwarded to hierarchy checks. */
+    readonly agentDepth: number;
     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 isModelVisibleMcpTool;
+    private rawMcpToolName;
+    private serverIdFromMcpToolName;
     private allowedToolsForAccess;
     runTurn(prompt: string, callbacks: RunTurnCallbacks): Promise<string>;
     /** Rough token estimate (1 token ≈ 4 characters of English / code). */
@@ -708,9 +859,30 @@ export declare class Agent {
      * Idempotent: calling this with a tag that isn't present is a no-op.
      */
     removeTaggedSystemMessage(tag: string): void;
+    /**
+     * Zero the in-process counters that back `/tokens`. Call this on any
+     * conceptual session boundary (`/resume`, `fork`) — otherwise the parent
+     * row keeps accumulating across the switch and "this session" no longer
+     * matches the displayed sessionKey.
+     */
+    resetSessionCounters(): void;
     /** Fork the current chat history into a fresh sessionKey. Returns the new key. */
     fork(newSessionKey: string): string;
     private bootstrapSession;
+    /**
+     * Public, callback-free wrapper around bootstrapSession for slash commands
+     * that mutate per-session state (notably `/goal`) BEFORE any runTurn has
+     * fired. Without this, the FIRST `/goal` of a session writes goal.json
+     * under the deterministic fallback sessionKey ("brainrouter-cli:<path>")
+     * because bootstrap hasn't happened yet, but every subsequent runTurn
+     * reads from the MCP-resolved UUID sessionKey — split-brain that left
+     * the agent reading a stale goal from a different directory.
+     *
+     * Idempotent: returns immediately if already initialized. Tolerates
+     * missing MCP — falls back to the deterministic key the same way
+     * bootstrapSession does.
+     */
+    ensureInitialized(): Promise<void>;
     private createSystemMessage;
     private injectRecallContext;
     /** Inspectable summary of the most recent memory briefing. Used by the `/briefing` slash command. */
@@ -718,6 +890,13 @@ export declare class Agent {
         sources: string[];
         recordIds: string[];
     };
+    /**
+     * Snapshot of the records produced by the most recent pre-turn briefing.
+     * `/where` surfaces a few of these to give the user a sense of what the
+     * agent is leaning on right now. Returns a shallow copy so callers can't
+     * mutate the agent's internal state.
+     */
+    getRecalledRecords(): RecalledRecord[];
     /** One-line summary of any new contradiction surfaced after the last capture, or undefined if none. */
     private lastContradictionWarning?;
     takeContradictionWarning(): string | undefined;
@@ -757,8 +936,50 @@ export declare function getToolSummary(name: string, args: Record<string, any>,
  * 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<{
+/**
+ * Heuristic for "does this model accept the OpenAI Chat Completions
+ * `reasoning_effort` field?". The signal that actually matters is the
+ * **model name**, not the endpoint hostname — modern OpenAI-compatible
+ * servers (LM Studio 0.3.29+, Ollama, vLLM, OpenRouter, OpenAI itself)
+ * all accept the field on /v1/chat/completions for the reasoning-capable
+ * model classes below, and silently ignore it for everything else. So a
+ * `gpt-oss-20b` served from localhost via LM Studio gets the same
+ * treatment as `gpt-5` on `api.openai.com`.
+ *
+ * Borrowed shape from openai-node's `ReasoningEffort` enum
+ * (openSrc/openai-node/src/resources/shared.ts) — `low|medium|high` map
+ * straight through to the provider field across OpenAI, DeepSeek,
+ * LM Studio, Ollama, and OpenRouter's pass-through. Anthropic models
+ * (`claude-*`) use a different field shape (`thinking: { budget_tokens }`)
+ * and a different endpoint (`/v1/messages`), so they're intentionally
+ * skipped here — brainrouter would need a separate provider adapter to
+ * forward into Anthropic's native API.
+ */
+/**
+ * 9b: resolve the recall-gating mode for this process. `BRAINROUTER_RECALL_MODE`
+ * env var beats everything; unset defaults to `gated`. Anything outside the
+ * three valid values falls back to `gated` (defensive — better to be helpful
+ * than crash on a typo). Re-resolved each turn so users can flip with
+ * `export BRAINROUTER_RECALL_MODE=always` mid-session via a /run command.
+ */
+export declare function resolveRecallMode(): 'always' | 'gated' | 'off';
+/**
+ * 9b: cheap local heuristic for "the user message names something specific
+ * memory might have history on." Counts entity-shaped tokens: proper nouns
+ * (capitalized words that aren't sentence-starting), file paths (anything
+ * with `/` or `\\` or a `.<ext>` suffix), and identifier-shaped tokens (`camelCase`
+ * / `snake_case` / `PascalCase` longer than 4 chars). Crude but the bar is
+ * "is recall plausibly worth it?" — false positives waste a recall call,
+ * false negatives waste an ask. Tunable threshold via the caller.
+ */
+export declare function countEntityTokens(text: string): number;
+export declare function supportsReasoningEffortField(config: LLMConfig): boolean;
+export interface BuildPayloadOptions {
+    /** Reasoning-depth preference, when provider supports it. `medium` is a no-op. */
+    effort?: EffortLevel;
+}
+export declare function buildChatCompletionPayload(config: LLMConfig, messages: any[], tools: any[], options?: BuildPayloadOptions): ChatCompletionPayload;
+export declare function callOpenAI(config: LLMConfig, messages: any[], tools: any[], options?: BuildPayloadOptions): Promise<{
     content: any;
     toolCalls: any;
     usage: any;