@nexus-cortex/cli 4.36.2 → 4.37.1

package/.env.example

@@ -0,0 +1,358 @@
+# Nexus Cortex — Complete Environment Configuration Reference
+# Copy to .env and fill in the API keys for the providers you use. Every other value
+# has a proven-optimal default.
+#
+# WARNING: The Settings Configurator (/config) regenerates .env from SettingsSchema.
+# Runtime-only vars (YOLO, SERVER_IDLE_TIMEOUT, WEB_TOOLS_MODEL, etc.) are NOT in the
+# schema — they will be silently dropped unless the SettingsWriter preserves them.
+#
+# Keep this file and .env structurally in sync: same comments + ordering, only the
+# values differ (.env = your real config, this file = template/defaults).
+
+# ============================================
+# API KEYS
+# ============================================
+# A model is only available if its provider's key is set. Leave the rest blank.
+
+# Claude (Anthropic) — Fable / Opus / Sonnet / Haiku
+ANTHROPIC_API_KEY=
+# OpenAI — GPT / o-series
+OPENAI_API_KEY=
+# Gemini (legacy key; GEMINI_API_KEY takes priority when both are set)
+GOOGLE_API_KEY=
+# Gemini (preferred key; falls back to GOOGLE_API_KEY)
+GEMINI_API_KEY=
+# xAI — Grok
+XAI_API_KEY=
+# DeepSeek (the default model's provider)
+DEEPSEEK_API_KEY=
+# Nvidia (no standalone NVIDIA cards registered yet — currently reached via Cloudflare)
+NVIDIA_API_KEY=
+# Inception Labs (Mercury diffusion models — mercury-2)
+INCEPTION_API_KEY=
+# Cloudflare Workers AI (@cf/* models). Requires CLOUDFLARE_ACCOUNT_ID.
+CLOUDFLARE_API_TOKEN=
+# Cloudflare account id (paired with the token above)
+CLOUDFLARE_ACCOUNT_ID=
+# Alibaba Qwen (DashScope) — qwen-* models
+DASHSCOPE_API_KEY=
+# MiniMax — minimax-* models
+MINIMAX_API_KEY=
+# Moonshot AI (Kimi) — moonshot-* / kimi-* models
+MOONSHOT_API_KEY=
+# Zhipu AI (GLM) — glm-* models
+ZHIPU_API_KEY=
+# Hugging Face Inference (no HF models registered yet; HUGGINGFACE_TOKEN is also accepted)
+HUGGINGFACE_API_KEY=
+HUGGINGFACE_TOKEN=
+
+# Authentication method for Anthropic: auto (try OAuth first, fall back to API key),
+# oauth (OAuth only), api-key (API key only). Options: auto, oauth, api-key
+ANTHROPIC_AUTH_METHOD=api-key
+# OAuth token override (alternative to ~/.claude/.credentials.json)
+CLAUDE_CODE_OAUTH_TOKEN=
+
+# ============================================
+# MODEL CONFIGURATION
+# ============================================
+
+# Default model for new sessions (any registry ID or alias — `cortex models list`)
+DEFAULT_MODEL_ID=deepseek-v4-pro
+# Cheaper model for context compaction & mentorship
+HELPER_MODEL_ID=deepseek-v4-flash
+
+# Model that backs WebSearch / WebFetch tools. Provider auto-detected from ID prefix.
+# When unset, auto-picks based on available API keys (Gemini > Anthropic > XAI),
+# falling back to DuckDuckGo HTML scrape if no provider key configured.
+#
+# Gemini models (uses @google/genai SDK — googleSearch grounding + urlContext):
+#   gemini-2.5-flash       — fast, free-tier friendly, good grounding with citations
+#   gemini-2.5-flash-lite  — cheapest, fewer grounding chunks but still functional
+#   gemini-2.5-pro         — best grounding quality (most chunks/supports), slower
+#   gemini-3.5-flash       — latest GA flash, strong agentic grounding, search + url context
+#   gemini-3.1-pro-preview — latest pro preview, rich grounding, slowest
+#   gemini-3-flash-preview — preview alias for gemini-3.5-flash
+#
+# Other providers (provider-native search APIs with citations):
+#   claude-haiku-4-5          — Anthropic web_search server tool (inline source citations)
+#   grok-4-fast-non-reasoning — XAI Responses API web_search (URL citations)
+#   grok-4.3                  — XAI Responses API web_search (reasoning model, URL citations)
+WEB_TOOLS_MODEL=gemini-2.5-flash
+
+# ============================================
+# SYSTEM SETTINGS
+# ============================================
+
+# Verbose debug logging (system-message assembly, routes). Toggle at runtime via /debug.
+DEBUG=false
+# Allow emoji in CLI output (false = plain text)
+USE_EMOJI=false
+# Project root the tools operate on. Leave EMPTY to use the launch cwd (the cwd
+# model, like Claude Code): cd into your project and run cortex. Only set this for
+# headless setups where the server's cwd is not the project. When set, it becomes
+# canonical and PROJECT_ROOT is derived from it (they can never diverge).
+PROJECT_PATH=
+
+# ============================================
+# REACTIVE MENTORSHIP (AI-to-AI self-improvement)
+# ============================================
+
+# Master switch for the mentorship system
+MENTORSHIP_ENABLED=false
+# Trigger helper-model review on tool errors (only applies when mentorship is enabled)
+MENTORSHIP_TRIGGER_ON_ERROR=false
+# Minimum error severity to trigger. Options: low, medium, high
+MENTORSHIP_ERROR_THRESHOLD=medium
+# React to @ultrathink / @analyze / @rethink keywords
+MENTORSHIP_KEYWORDS_ENABLED=false
+# Additional trigger keywords (comma-separated, e.g. @help,@stuck)
+MENTORSHIP_CUSTOM_KEYWORDS=
+# Model used for mentorship guidance (overrides HELPER_MODEL_ID)
+MENTORSHIP_HELPER_MODEL=@cf/google/gemma-4-26b-a4b-it
+# Periodic mentorship review every N turns
+MENTORSHIP_TURN_BASED_ENABLED=false
+# Turns between periodic reviews (1-50)
+MENTORSHIP_TURN_INTERVAL=10
+# Inject thinking assistance for non-reasoning models
+MENTORSHIP_INTERLEAVED_THINKING=false
+# Detect and alert on repeated failure patterns
+MENTORSHIP_PATTERN_DETECTION=false
+# Number of similar errors to trigger pattern detection (2-10)
+MENTORSHIP_PATTERN_THRESHOLD=3
+# Post-turn summary + next-action prediction via the helper model
+TURN_SUMMARY_PREDICTION=false
+
+# ============================================
+# CONTEXT MANAGEMENT
+# ============================================
+
+# Anthropic prompt caching (up to ~90% input-token savings)
+ANTHROPIC_PROMPT_CACHING=true
+# Strategy when context overflows: priority-based preserves critical context + tool pairs;
+# sliding-window is dumb recency and can orphan tool_use -> Anthropic 400.
+# Options: sliding-window, priority-based
+CONTEXT_BUDGET_STRATEGY=priority-based
+
+# ============================================
+# SESSION CONFIGURATION
+# ============================================
+
+# Where JSONL session files are written
+SESSION_STORAGE_DIR=.cortex/sessions
+# Auto-inject connected MCP servers' tools into every turn
+MCP_AUTO_INJECT=false
+# Auto-research subagents. off = disabled (PM never told; main context stays clean).
+# native = PM delegates to autoresearch-agent subagents that run experiments with the
+# internal tools. mcp = the subagents route experiment-running to the external
+# configured auto-research MCP server instead (MCP integration ships separately). Options: off, native, mcp
+AUTORESEARCH_AGENTS=off
+# Cap on bytes per injected project doc (CORTEX.md, MEMORY.md, etc.). 0 = unlimited.
+SYSTEM_MESSAGE_DOC_MAX_BYTES=0
+
+# ============================================
+# LOOP CONTROL
+# ============================================
+
+# Maximum tool executions per turn
+MAX_TOOL_ITERATIONS=50
+# Stop the turn after this many consecutive all-error iterations
+MAX_CONSECUTIVE_ERRORS=3
+# Soft per-turn tool-call budget (R29b brake: escalating reminders, hard cap at 2x)
+TOOL_BUDGET_SOFT=15
+# Per-tool execution timeout in milliseconds (2 minutes)
+TOOL_TIMEOUT_MS=120000
+# Identical tool calls before loop detection breaks the turn
+MAX_LOOP_REPETITIONS=5
+
+# ============================================
+# PROVIDER TOOLING (server-side tools / API surface)
+# ============================================
+
+# Inject server-side tools (web_search, x_search, code_execution) into XAI/OpenAI requests.
+# When true, overrides to the Responses API at request time regardless of XAI_API_MODE.
+# R37/R38 benchmarks: hybrid (true) is 20-26% faster than client-only with equal accuracy.
+ENABLE_SERVER_SIDE_TOOLS=true
+# Default API pattern for XAI models at registration time (ENABLE_SERVER_SIDE_TOOLS=true
+# overrides at request time). Options: messages | responses
+XAI_API_MODE=messages
+# OpenAI request surface. Options: chat/completions | responses (opt into hosted tools)
+OPENAI_API_MODE=
+# Only load essential tools initially; the model discovers the rest via SearchTools.
+# R43 benchmark: 77% input-token reduction on the first turn.
+ENABLE_DEFERRED_TOOL_LOADING=true
+# Programmatic Tool Calling (compose tool calls in a script) — experimental
+ENABLE_PTC=false
+# Allow local code-execution tooling
+ENABLE_LOCAL_CODE_EXECUTION=false
+
+# ============================================
+# MODEL ROUTER (auto model selection)
+# ============================================
+
+# Auto-select a model based on task type + benchmark history (routes model="auto")
+MODEL_ROUTER_ENABLED=false
+# Routing strategy: auto (classify the prompt) | matrix-only (require explicit task type)
+MODEL_ROUTER_STRATEGY=auto
+# Record turn metrics to .cortex/router-matrix.jsonl (independent of routing being enabled)
+MODEL_ROUTER_RECORD=true
+# Models the router must NEVER auto-select (cost/policy bans), comma-separated.
+# A trailing '*' is a prefix wildcard: 'grok*' excludes EVERY xAI model (present and
+# future) so exploration can never route a sub-agent to a grok model — honors the
+# standing cost constraint.
+MODEL_ROUTER_EXCLUDE=grok*
+# Opt-in explore/exploit (Thompson sampling) for model='auto'. OFF = conservative greedy
+# trust-gated routing. ON = posterior-sample each model and route to the sampled-argmax,
+# so thinly-sampled models get a chance and the matrix stops being self-confirming.
+MODEL_ROUTER_EXPLORATION=false
+# Trust gate for sub-agent model='auto' dispatch (works even when ENABLED=false — passing
+# 'auto' is the orchestrator's explicit per-dispatch opt-in):
+# Min task-classification confidence (0-1) before 'auto' routes; else inherits parent model
+ROUTER_MIN_CONFIDENCE=0.3
+# Min real benchmark samples a task type needs before 'auto' trusts the matrix
+# recommendation; else inherits parent. Met as MODEL_ROUTER_RECORD accumulates data.
+ROUTER_MIN_SAMPLES=3
+
+# ============================================
+# END-OF-TURN AUDIT / TRAINING SUBSTRATE (opt-in)
+# ============================================
+
+# Mandatory EndTurn pre-delivery self-audit + Stage 2/3 verifiers. Default OFF; ON =
+# graded cortex-channel training records (the tool is hidden when off).
+CORTEX_ENDTURN_GATE=false
+
+# ============================================
+# DECISION STORE (prior-recall + recording)
+# ============================================
+
+# Append each tool decision to <PROJECT_ROOT>/.cortex/decisions.jsonl (default ON)
+CORTEX_RECORD_DECISIONS=true
+# Inject prior decisions as a <system-reminder> before tool use (default ON)
+CORTEX_LOOKUP_PRIOR_DECISIONS=true
+# decisions.jsonl self-rotates at this byte cap (default 2 MB)
+CORTEX_DECISIONS_MAX_BYTES=2097152
+# Per-turn "Repository State" harness-note: git branch, uncommitted changes in the project
+# subtree, recent commits, and a cross-agent staleness warning (files you read that another
+# agent/the user has since changed on disk). Lets two agents share one working tree safely.
+# Default ON; set "false" to disable.
+CORTEX_GIT_CONTEXT=true
+
+# ============================================
+# ORCHESTRATOR MODE
+# ============================================
+
+# Orchestrator lifecycle: persistent (default) | stateless (clean per request) | server
+CORTEX_MODE=persistent
+# Server URL when CORTEX_MODE=server (HTTP client mode)
+CORTEX_SERVER_URL=http://localhost:4000
+
+# ============================================
+# AGENT WORKSPACE
+# ============================================
+
+# tmux visual monitoring for parallel agent teams (one live pane per agent)
+AGENT_TMUX_MONITOR=false
+
+# ============================================
+# TESTING
+# ============================================
+
+# Run real-API smoke tests instead of mocked ones
+ENABLE_SMOKE_TESTS=false
+
+# Run the Chromium browser-integration test suite (drives a real browser,
+# downloads http-server via npx — opt-in; default npm test skips it)
+ENABLE_BROWSER_TESTS=false
+
+# ============================================
+# DEBUG FLAGS
+# ============================================
+
+# Log raw API request/response payloads
+DEBUG_PAYLOAD=false
+# Verbose system-message assembly logging (also enabled by DEBUG=true)
+DEBUG_SYSTEM_MESSAGES=false
+# Show thinking/reasoning content in the CLI. For Anthropic Opus 4.7/4.8 (adaptive
+# thinking) 'true' requests display:'summarized', which BILLS extra output tokens
+# ($25/1M on Opus 4.8); 'false' keeps reasoning omitted (empty thinking blocks, $0).
+# Other providers (XAI/DeepSeek/GPT) stream reasoning for free regardless.
+DEBUG_THINKING=false
+
+# ============================================
+# TOOL & PATH OVERRIDES
+# ============================================
+
+# Override the Chromium binary used by web/browse tools (auto-detected if unset)
+CHROMIUM_BIN=
+# Alternate Chromium path honored by Playwright
+PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=
+# Override the tmux binary used by visual agent monitoring (auto-detected if unset)
+TMUX_BIN=
+# Google Vertex AI project (only when using Vertex instead of the Gemini API)
+GOOGLE_CLOUD_PROJECT=
+# Extra directories to grant tool access to, OUTSIDE the project root (the --add-dir
+# mechanism — your explicit permission). Path-delimiter separated (':' on Linux/macOS).
+# Example: /data/shared:/opt/reference. Prefer the --add-dir flag for one-offs.
+CORTEX_ADD_DIRS=
+
+# ============================================
+# GIT / PR ACCESS CONTROL
+# ============================================
+# Controls the git/PR tools (PRAgent, WorkspaceManager) and the /v1/pr/* server routes.
+# Input-format validation (which blocks shell/argument injection) is ALWAYS on; the
+# allow-lists below are opt-in defense-in-depth.
+#
+# Comma list of repos the tools may touch: exact "owner/repo", "owner/*", or "*".
+# Unset = ALL repos are permitted — the convenient default for single-user/local use.
+# For shared or multi-tenant deployments, RESTRICT this to the repos you trust the tools
+# with, e.g. GIT_ALLOWED_REPOS=me/app,me/*
+GIT_ALLOWED_REPOS=
+# Comma list of allowed actions: review,list,create,post-review,clone,worktree,diff,cleanup,status
+# Unset or * = all actions allowed.
+GIT_ALLOWED_ACTIONS=
+# Token for gh/git. Injected into the subprocess env as GH_TOKEN/GITHUB_TOKEN only —
+# never placed on argv or in a clone URL. Leave unset to use gh's own auth.
+GIT_AUTH_TOKEN=
+# GitHub (Enterprise) host for git/PR tools. Default: github.com
+GIT_HOST=github.com
+# HMAC secret for the /v1/pr/webhook endpoint (GitHub X-Hub-Signature-256).
+# Unset = the webhook is DISABLED (returns 401) rather than accepting unsigned calls.
+GITHUB_WEBHOOK_SECRET=
+
+# ============================================
+# SERVER LIFECYCLE (startup / shutdown / resume)
+# ============================================
+
+# HTTP server port (falls back to the next free port if taken)
+PORT=4000
+# Startup resume: load the most recent session on boot — e.g. after an idle-shutdown ->
+# wake cycle. For a specific session set RESUME_SESSION_ID instead. Default: fresh session.
+AUTO_RESUME=false
+# Resume a specific session UUID on boot (overrides AUTO_RESUME)
+RESUME_SESSION_ID=
+# Inactivity shutdown: auto-stop after N seconds with no requests.
+#   0    = never (always-on daemon)
+#   N>0  = stop after N seconds idle. Pair with a process manager (systemd, pm2) +
+#          AUTO_RESUME=true for "sleep when idle, resume on wake" — cost-efficient
+#          on-demand use without losing conversation state.
+SERVER_IDLE_TIMEOUT=0
+# Graceful shutdown: max ms to let in-flight connections drain before forcing exit
+# (0 = wait indefinitely). On shutdown the dashboard view server, idle timer, and
+# cleanup intervals are all closed cleanly first.
+SHUTDOWN_GRACE_MS=10000
+# Opt-in: start the sandbox+tmux dashboard (default off; binds an extra port).
+# MASTER SWITCH for the tmux/sandbox web dashboard (the 4001 view server).
+# false = the dashboard NEVER starts (not at boot, not on TmuxSession/CreateArtifact
+# use) and tools return guidance instead of view URLs. Set true to enable; if it
+# fails to start, check for a port conflict on DASHBOARD_PORT (retries 10 ports).
+ENABLE_DASHBOARD=false
+# Dashboard port — honored whether started eagerly (above) or lazily by a tool
+DASHBOARD_PORT=4001
+
+# ============================================
+# RUNTIME FLAGS
+# ============================================
+
+# Auto-approve ALL tool executions (bypasses the permission system). Use with caution.
+YOLO=false
+# Proactive mentorship discovery (runtime flag)
+MENTORSHIP_ACTIVE_DISCOVERY=false

package/bin/cortex.js

@@ -25,7 +25,7 @@
 import { spawn, spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { dirname, join, resolve } from 'path';
-import { existsSync, readFileSync, realpathSync, mkdirSync, openSync } from 'fs';
+import { existsSync, readFileSync, realpathSync, mkdirSync, openSync, writeFileSync, copyFileSync } from 'fs';
 import { homedir } from 'os';
 import { createRequire } from 'module';
 
@@ -354,8 +354,95 @@ async function startServer() {
 // Where the auto-started background server logs to. Honors CORTEX_HOME/HOME so
 // it lands beside the rest of the global config (~/.cortex/server.log).
 function getServerLogPath() {
+  return join(getGlobalCortexDir(), 'server.log');
+}
+
+function getGlobalCortexDir() {
   const base = process.env.CORTEX_HOME || homedir() || process.cwd();
-  return join(base, '.cortex', 'server.log');
+  return join(base, '.cortex');
+}
+
+// Is at least one provider API key resolvable — from the environment/secrets store
+// OR from a .env file (cwd or global)? A BLANK value in a .env (e.g. `DEEPSEEK_API_KEY=`)
+// does NOT count: the loader treats it as falsy and falls through to process.env, which is
+// exactly how the secrets-store model works (blank .env + key injected via env). So we only
+// count a non-empty, non-commented assignment, or a non-empty process.env var.
+function hasAnyApiKey() {
+  const isKeyName = (k) => /(_API_KEY|_API_TOKEN|_OAUTH_TOKEN)$/.test(k);
+  for (const [k, v] of Object.entries(process.env)) {
+    if (isKeyName(k) && String(v || '').trim()) return true;
+  }
+  for (const p of [join(process.cwd(), '.env'), join(getGlobalCortexDir(), '.env')]) {
+    try {
+      if (!existsSync(p)) continue;
+      for (const line of readFileSync(p, 'utf8').split('\n')) {
+        if (/^\s*#/.test(line)) continue;
+        const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(\S.*?)\s*$/);
+        if (m && isKeyName(m[1]) && m[2].trim()) return true;
+      }
+    } catch { /* unreadable .env — ignore */ }
+  }
+  return false;
+}
+
+// A blank-value config template — mirrors the project's own .env: every key declared but
+// EMPTY, so the loader falls through to the environment/secrets store. NEVER put a non-empty
+// placeholder here — it would override a real secret in process.env.
+const BLANK_ENV_TEMPLATE = `# Nexus Cortex configuration.
+# Blank values are read from your environment / secrets store (a value set in the
+# environment wins when the line below is left blank). Fill a key here for local use,
+# or leave blank and inject it via your secrets store. Run "cortex config init --force"
+# for the full, commented template.
+
+DEFAULT_MODEL_ID=deepseek-v4-pro
+
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=
+GEMINI_API_KEY=
+DEEPSEEK_API_KEY=
+XAI_API_KEY=
+`;
+
+// Preflight for the prompt path: a model run needs a key. If none is resolvable, seed a
+// blank ~/.cortex/.env so there's a findable file to edit (it didn't exist before the first
+// run), print clear guidance, and EXIT WITHOUT starting a server — so we never leave a
+// keyless server running that would force a --shutdown + re-invoke. When a key IS present
+// (a filled .env, or secrets in the environment), this is a no-op and the run proceeds —
+// one-shot. The container case (secrets in env) hits the no-op path and writes nothing.
+async function ensureKeysOrExit() {
+  if (hasAnyApiKey()) return;
+  // No key resolvable. If a server is already running, it was started with no key and has
+  // cached that empty config — so even after you add a key it would keep failing until a
+  // restart. Drain it now (graceful) so the NEXT run (with your key) starts a fresh server
+  // that picks the key up — no manual --shutdown dance.
+  try {
+    if (await isServerUp()) {
+      try { await fetch(`${BASE_URL}/shutdown`, { method: 'POST', signal: AbortSignal.timeout(5000) }); } catch { /* best-effort */ }
+      process.stderr.write('[cortex] Stopped the running server so it will pick up your key on the next run.\n');
+    }
+  } catch { /* never block on the drain */ }
+  const dir = getGlobalCortexDir();
+  const envPath = join(dir, '.env');
+  let seeded = false;
+  if (!existsSync(envPath)) {
+    try {
+      mkdirSync(dir, { recursive: true });
+      // Prefer the shipped .env.example (the full, canonical blank-value template) and
+      // copy it to ~/.cortex/.env — i.e. .env.example becomes .env, no codegen. Fall back
+      // to the minimal inline template only if the example isn't found in the install.
+      const example = [join(CLI_PKG_ROOT, '.env.example'), join(MONOREPO_ROOT, '.env.example')]
+        .find((p) => existsSync(p));
+      if (example) copyFileSync(example, envPath);
+      else writeFileSync(envPath, BLANK_ENV_TEMPLATE);
+      seeded = true;
+    } catch { /* read-only home — still print guidance below */ }
+  }
+  process.stderr.write('\n[cortex] No API key found — a model run needs one.\n');
+  if (seeded) process.stderr.write(`[cortex] Created ${envPath}\n`);
+  process.stderr.write('[cortex] Add a provider key, then run again:\n');
+  process.stderr.write(`[cortex]   - edit ${envPath}  (e.g. DEEPSEEK_API_KEY=sk-...)\n`);
+  process.stderr.write('[cortex]   - or inject it via your environment / secrets store (read from there too)\n');
+  process.exit(1);
 }
 
 async function ensureServer() {
@@ -406,6 +493,14 @@ async function run() {
     await checkForUpdate();
   } catch { /* dist absent in a source checkout, or check failed — never block */ }
 
+  // A prompt/agent run needs a model key. Check BEFORE starting the server so we never
+  // leave a keyless server running (which forced the old --shutdown + re-invoke dance).
+  // Read-only ops (--stats/--sessions/--tmux/--pr, no prompt) don't need a key and are
+  // fine against a keyless server, so only gate the actual prompt path.
+  if (prompt) {
+    await ensureKeysOrExit();
+  }
+
   await ensureServer();
 
   // --tmux: list active tmux sessions (served by SandboxViewServer on port+1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexus-cortex/cli",
-  "version": "4.36.2",
+  "version": "4.37.1",
   "description": "Nexus Cortex CLI - Terminal interface for multi-provider LLM orchestration",
   "main": "dist/index.js",
   "type": "module",
@@ -77,6 +77,7 @@
     "bin",
     "README.md",
     "LICENSE",
-    "NOTICE"
+    "NOTICE",
+    ".env.example"
   ]
 }