@kinqs/brainrouter-cli 0.3.5 → 0.3.6

package/.env.example

@@ -1,77 +1,81 @@
-# BrainRouter CLI agent — environment
+# BrainRouter CLI agent — environment template
 #
-# Copy to brainrouter-cli/.env. Loaded by the CLI at startup.
+# Copy to `brainrouter-cli/.env`. Loaded by the CLI at startup.
 #
 # This file is for CLI-AGENT concerns only:
-#   - chat LLM the terminal agent talks to
-#   - tool runtime knobs (loop limit, result clamp, MCP timeout)
-#   - auto-compaction trigger
-#   - sandbox configuration for run_command
-#   - web search backend
-#   - trace logging
-#   - workspace override
+#   1. Chat LLM                  (the model the terminal agent talks to)
+#   2. Tool runtime              (loop limit, result clamp, MCP timeout, auto-compact)
+#   3. Sandbox                   (run_command wrapping)
+#   4. Workspace                 (root override + shared state root)
+#   5. Web search                (custom backend for the web_search tool)
+#   6. Observability             (trace log path)
 #
-# MCP-server concerns (cognitive extraction, embeddings, reranker, memory
-# engine knobs, server auth) live in brainrouter/.env.example.
+# MCP-server concerns (cognitive extraction, embeddings, reranker, judge,
+# memory engine knobs, server auth) live in `brainrouter/.env.example`.
 #
 # Why split: the MCP and the CLI are separate processes with different
 # concerns. The CLI's chat LLM can be a smart cloud model while the MCP's
 # cognitive extractor is a cheap local one. Their concurrency caps differ
 # too (CLI default 4, MCP default 2). Keep them independent.
+#
+# All values in this template are blank placeholders. Fill in only what
+# you actually need — most settings have sensible defaults.
+
 
-# ==========================================
-# Chat LLM (for the agent's own conversation)
-# ==========================================
+# =============================================================================
+# 1. Chat LLM (for the agent's own conversation)
+# =============================================================================
 # Same var names as the MCP, but a separate process — set them here for the
 # CLI's chat model. Falls back to OPENAI_API_KEY.
 #
 # If you don't set BRAINROUTER_LLM_API_KEY here, the CLI also reads it from
-# brainrouter/.env as a transitional fallback. Setting it here makes the
+# `brainrouter/.env` as a transitional fallback. Setting it here makes the
 # CLI's choice explicit and lets you use a different chat model than the
 # MCP's extractor (e.g. gpt-4o for chat, gpt-4o-mini for extraction).
-BRAINROUTER_LLM_API_KEY=your_api_key_here
+BRAINROUTER_LLM_API_KEY=
 
 # OpenAI-compatible chat-completions endpoint.
 # Examples:
-#   OpenAI:     https://api.openai.com/v1/chat/completions
-#   OpenRouter: https://openrouter.ai/api/v1/chat/completions
-#   Anthropic via OpenRouter: anthropic/claude-sonnet-4
-#   LM Studio:  http://localhost:1234/v1/chat/completions
+#   OpenAI:                   https://api.openai.com/v1/chat/completions
+#   OpenRouter:               https://openrouter.ai/api/v1/chat/completions
+#   Anthropic via OpenRouter: model id "anthropic/claude-sonnet-4"
+#   LM Studio:                http://localhost:1234/v1/chat/completions
 BRAINROUTER_LLM_ENDPOINT=https://api.openai.com/v1/chat/completions
-
 BRAINROUTER_LLM_MODEL=gpt-4o-mini
 
-# Per-call timeout for the CLI's chat LLM. Default: 120000.
+# Per-call timeout for the CLI's chat LLM. Default 120000 (2 min).
 # BRAINROUTER_LLM_TIMEOUT_MS=120000
 
 # Cap on concurrent in-flight chat LLM calls FROM THE CLI PROCESS.
-# Default: 4 (separate from the MCP's own cap). Set to 1 for consumer-grade
-# local backends; crank to 16+ for cloud APIs.
+# Default 4 (separate from the MCP's own cap). Set to 1 for consumer-grade
+# local backends; raise to 16+ for cloud APIs.
 # BRAINROUTER_LLM_MAX_CONCURRENT=4
 
-# ==========================================
-# Tool runtime
-# ==========================================
-# Per-tool timeout for CLI → MCP requests. Default: 60000.
+
+# =============================================================================
+# 2. Tool runtime
+# =============================================================================
+# Per-tool timeout for CLI → MCP requests. Default 60000.
 # BRAINROUTER_MCP_TIMEOUT_MS=60000
 
 # LLM-visible clamp on a single tool-result body (full text still recorded
-# in the transcript on disk). Default: 8000.
+# in the transcript on disk). Default 8000.
 # BRAINROUTER_MAX_TOOL_RESULT_CHARS=8000
 
-# Hard ceiling on tool-call iterations per turn. Default: 60.
+# Hard ceiling on tool-call iterations per turn. Default 60.
 # BRAINROUTER_MAX_TOOL_LOOPS=60
 
-# Estimated history-size trigger for auto-`/compact`. Default: 80000 tokens.
+# Estimated history-size trigger for auto-`/compact`. Default 80000 tokens.
 # BRAINROUTER_AUTO_COMPACT_TOKENS=80000
 
-# ==========================================
-# Sandbox (run_command)
-# ==========================================
+
+# =============================================================================
+# 3. Sandbox (run_command)
+# =============================================================================
 # Wrap shell commands in the platform sandbox:
 #   macOS: sandbox-exec
 #   Linux: bwrap (preferred) or firejail
-# Set 'on' to enable. Off by default.
+# Set `on` to enable. Off by default.
 # BRAINROUTER_SANDBOX=on
 
 # Allow outbound network from sandboxed commands. Off by default.
@@ -81,29 +85,32 @@ BRAINROUTER_LLM_MODEL=gpt-4o-mini
 # BRAINROUTER_SANDBOX_READ_PATHS=/usr/local:/opt
 # BRAINROUTER_SANDBOX_WRITE_PATHS=/tmp
 
-# ==========================================
-# Workspace
-# ==========================================
-# Override workspace root the CLI uses for file tools + session key.
-# Most users let the CLI auto-detect via git/closest package.json.
+
+# =============================================================================
+# 4. Workspace
+# =============================================================================
+# Override the workspace root the CLI uses for file tools + session key.
+# Most users let the CLI auto-detect via git / closest package.json.
 # BRAINROUTER_WORKSPACE=/path/to/project
 
 # Override per-user state root. Default: ~/.brainrouter.
 # Both the CLI and MCP honor this — set it once and both processes use it.
 # BRAINROUTER_HOME=/path/to/state
 
-# ==========================================
-# Web search
-# ==========================================
+
+# =============================================================================
+# 5. Web search
+# =============================================================================
 # Custom search backend for the web_search tool. Must accept
-#   POST { query, maxResults } → { results: [{ title, url, snippet }] }.
+#   POST { query, maxResults } → { results: [{ title, url, snippet }] }
 # Falls back to DuckDuckGo's Instant Answer API when unset.
-# Compatible with Brave Search API wrappers, Tavily, SerpAPI proxies.
+# Compatible with Brave Search API wrappers, Tavily, SerpAPI proxies, etc.
 # BRAINROUTER_WEB_SEARCH_ENDPOINT=https://your-search-proxy.example.com/search
 
-# ==========================================
-# Observability
-# ==========================================
+
+# =============================================================================
+# 6. Observability
+# =============================================================================
 # Path for OTEL-style JSONL turn traces. One line per turn/tool span.
 # Toggle at runtime with /trace on|off.
 # BRAINROUTER_TRACE_LOG=/path/to/trace.jsonl

package/bin/cli.cjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+/**
+ * Thin CommonJS shim that runs BEFORE the real ESM CLI entrypoint.
+ *
+ * Why CJS for the bin: ESM hoists all `import` statements above any
+ * top-level code in the module that owns them. The CLI imports
+ * `node:sqlite` transitively via `config/config.ts`, which triggers
+ * Node's `ExperimentalWarning` the FIRST time the module is touched —
+ * and that happens during import resolution, before any line of code
+ * in `src/index.ts` runs. So a warning filter installed inside that
+ * file always fires too late.
+ *
+ * This shim does three things synchronously, with zero ESM imports
+ * blocking it, and only then hands off:
+ *
+ *   1. Remove Node's default "warning" printer.
+ *   2. Install a filtered listener that drops `ExperimentalWarning`
+ *      (sqlite, ESM in older Node) and dotenv self-promotion lines.
+ *   3. Override `process.emitWarning` so future direct callers also
+ *      route through the same filter.
+ *
+ * Anything BrainRouter itself emits via `process.emitWarning('…',
+ * 'BrainRouterWarning')` (or any non-suppressible type) flows through
+ * unchanged. NODE_NO_WARNINGS=1 would silence those too, which is why
+ * we don't just set that env.
+ *
+ * The shim then dynamically imports the ESM entry. Dynamic `import()`
+ * is the only way to load ESM from CJS; it returns a promise we await
+ * so an unhandled rejection during boot still surfaces as an error.
+ */
+
+function isSuppressibleWarning(message, type) {
+  const looksExperimental =
+    type === 'ExperimentalWarning' ||
+    /experimental feature|SQLite is an experimental/i.test(message);
+  const looksDotenvNoise = /dotenv@\d|dotenvx|dotenv\.org/i.test(message);
+  return looksExperimental || looksDotenvNoise;
+}
+
+for (const listener of process.listeners('warning')) {
+  process.removeListener('warning', listener);
+}
+process.on('warning', (warning) => {
+  const message = (warning && warning.message) || '';
+  const type = (warning && warning.name) || '';
+  if (isSuppressibleWarning(message, type)) return;
+  process.stderr.write(`(node:${process.pid}) ${type || 'Warning'}: ${message || warning}\n`);
+});
+
+const originalEmitWarning = process.emitWarning.bind(process);
+process.emitWarning = function emitWarning(warning, ...rest) {
+  const message = typeof warning === 'string' ? warning : (warning && warning.message) || '';
+  const type =
+    typeof rest[0] === 'string' ? rest[0] :
+    (rest[0] && typeof rest[0] === 'object' && 'type' in rest[0]) ? rest[0].type :
+    (warning && warning.name) || '';
+  if (isSuppressibleWarning(message, type)) return;
+  return originalEmitWarning(warning, ...rest);
+};
+
+// Path to the compiled ESM entry, resolved relative to this shim.
+const path = require('node:path');
+const url = require('node:url');
+const entry = path.resolve(__dirname, '..', 'dist', 'index.js');
+import(url.pathToFileURL(entry).href).catch((err) => {
+  // Surface boot-time errors verbatim — a silent exit would just look like
+  // the CLI never started.
+  process.stderr.write(`brainrouter: failed to load CLI entrypoint: ${(err && err.stack) || err}\n`);
+  process.exit(1);
+});

package/dist/agent/agent.d.ts

@@ -1,6 +1,8 @@
 import type { McpClientWrapper } from '../runtime/mcpClient.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;
@@ -131,6 +139,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 +175,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 +214,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 +247,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 +283,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 +316,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 +349,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 +382,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 +418,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 +451,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 +560,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 +592,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 +629,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 +693,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;
@@ -708,9 +848,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 +879,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 +925,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;