@kinqs/brainrouter-cli 0.3.5 → 0.3.7

package/dist/state/workflowArtifacts.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { getCliStateFile, getWorkspaceLocalDir, isPathInside, readJsonFile, writeJsonFile } from './cliState.js';
+import { getCliStateFile, getSessionStateFile, getWorkspaceLocalDir, isPathInside, readJsonFile, writeJsonFile } from './cliState.js';
 /**
  * Canonical home for durable workflow artifacts produced by the multi-agent
  * commands (/feature-dev, /spec, /review, /implement-plan).
@@ -18,12 +18,42 @@ import { getCliStateFile, getWorkspaceLocalDir, isPathInside, readJsonFile, writ
  * team shares them, and (b) the agent's `write_file` tool only accepts paths
  * relative to the workspace root. Personal CLI state (sessions, hooks,
  * memories, preferences) lives in `~/.brainrouter/workspaces/<encoded>/` and
- * never touches the project tree. The current-workflow pointer is still per-
- * user (it tracks which workflow YOU are focused on right now) so it lives
- * with the CLI state, not the workspace.
+ * never touches the project tree.
+ *
+ * **Workflows do NOT carry goal state.** Earlier 0.3.6 (Item 3) stored a
+ * `goal.json` inside each workflow folder so switching workflows would
+ * "carry the goal with it." That conflated two different concerns — a goal
+ * is **per-session runtime intent** (let the agent run autonomously until
+ * complete) while a workflow is **durable storage** (committed artifacts
+ * shared across users and CLIs). The conflation produced a cross-session
+ * goal leak (two CLIs in the same workspace bound to the same workflow
+ * shared a goal). The decoupling lives in goalStore.ts's `resolveGoalScope`
+ * — goals are always session-scoped, workflows are pure navigation. The
+ * per-session `workflow.json` pointer here is for "which folder am I
+ * writing artifacts to RIGHT NOW", not "which goal am I working on."
  */
 const WORKFLOWS_SUBDIR = 'workflows';
+/**
+ * Workspace-level "last used workflow" pointer. Pre-9d-bugfix this was
+ * BOTH the source of truth for "which workflow is the current CLI
+ * session bound to" AND the display-only "what was the last workflow
+ * touched in this workspace" hint. The two responsibilities are now
+ * split: this file is the hint (any CLI in this workspace can see it),
+ * while `SESSION_POINTER_FILE` carries the per-session binding that
+ * actually drives goal scoping. The hint is still useful for the
+ * `/workflows` listing and for surfacing "you were last on X" in a
+ * fresh CLI without auto-binding it to that workflow's goal.
+ */
 const CURRENT_POINTER_FILE = 'current-workflow.json';
+/**
+ * Per-session workflow binding (the actual source of truth for goal
+ * scoping). Lives under the session state directory so two CLIs in the
+ * same workspace can have independent workflows bound — fixes the
+ * "session A's `/feature-dev` automatically becomes session B's active
+ * workflow + active goal" leak that reintroduced Item 1's cross-session
+ * leak via the Item 3 workspace pointer.
+ */
+const SESSION_POINTER_FILE = 'workflow.json';
 /** Canonical artifact names. Use the constants rather than hard-coded strings so a future rename is one edit. */
 export const ARTIFACT = {
     spec: 'spec.md',
@@ -58,6 +88,16 @@ export function getWorkflowDir(workspaceRoot, slug) {
     fs.mkdirSync(dir, { recursive: true });
     return dir;
 }
+/**
+ * Create (or reopen) a workflow folder + bind it as the current
+ * workflow.
+ *
+ * `sessionKey` is threaded through to `setCurrentWorkflow` so that the
+ * created workflow is bound to THIS session (not to every other CLI
+ * session in the workspace via the workspace-level pointer). Legacy
+ * callers without a session context fall through to workspace-level
+ * binding only — same back-compat path `setCurrentWorkflow` provides.
+ */
 export function createWorkflow(workspaceRoot, input) {
     const slug = slugify(input.slug ?? input.title);
     const dir = getWorkflowDir(workspaceRoot, slug);
@@ -81,7 +121,7 @@ export function createWorkflow(workspaceRoot, input) {
             meta.kind = input.kind;
     }
     writeJsonFile(metaPath, meta);
-    setCurrentWorkflow(workspaceRoot, slug);
+    setCurrentWorkflow(workspaceRoot, slug, input.sessionKey);
     return meta;
 }
 export function updateWorkflowStatus(workspaceRoot, slug, status) {
@@ -111,13 +151,85 @@ export function listWorkflows(workspaceRoot) {
     }
     return out.sort((a, b) => (b.updatedAt ?? '').localeCompare(a.updatedAt ?? ''));
 }
-export function setCurrentWorkflow(workspaceRoot, slug) {
-    writeJsonFile(getCliStateFile(workspaceRoot, CURRENT_POINTER_FILE), { slug, at: new Date().toISOString() });
+/**
+ * Bind a workflow to the current CLI session AND update the workspace-
+ * level "last used" hint. When `sessionKey` is omitted (legacy callers,
+ * some first-run paths), only the workspace pointer is written — those
+ * callers don't have a session context yet, so per-session binding
+ * doesn't apply.
+ *
+ * The workspace pointer is updated unconditionally because we still
+ * want a fresh CLI in the same workspace to be ABLE to see "X is the
+ * last workflow that was touched here" — for display via
+ * `getLastUsedWorkflow`, for the `/workflows` listing's `★` marker, and
+ * for the post-9d "do you want to switch to <X>?" UX (the latter not
+ * yet shipped, tracked separately).
+ */
+export function setCurrentWorkflow(workspaceRoot, slug, sessionKey) {
+    const ts = new Date().toISOString();
+    writeJsonFile(getCliStateFile(workspaceRoot, CURRENT_POINTER_FILE), { slug, at: ts });
+    if (sessionKey) {
+        writeJsonFile(getSessionStateFile(workspaceRoot, sessionKey, SESSION_POINTER_FILE), { slug, at: ts });
+    }
 }
-export function getCurrentWorkflow(workspaceRoot) {
+/**
+ * Which workflow is bound to THIS CLI session?
+ *
+ * - With `sessionKey`: reads ONLY the session-level pointer. A fresh
+ *   CLI session has no session-level pointer → returns `undefined`,
+ *   even when a workspace-level "last used" hint exists. This is the
+ *   load-bearing fix: new sessions don't auto-inherit another session's
+ *   workflow binding (which previously dragged that workflow's goal
+ *   into the new session via `resolveGoalScope`).
+ * - Without `sessionKey` (legacy / display-only callers): falls back
+ *   to the workspace-level pointer for back-compat.
+ *
+ * Display surfaces that want to show "the last workflow touched here,
+ * regardless of session binding" should call `getLastUsedWorkflow`
+ * instead so the distinction stays explicit.
+ */
+export function getCurrentWorkflow(workspaceRoot, sessionKey) {
+    if (sessionKey) {
+        const sessionPtr = readJsonFile(getSessionStateFile(workspaceRoot, sessionKey, SESSION_POINTER_FILE), null);
+        return sessionPtr?.slug || undefined;
+    }
+    const ptr = readJsonFile(getCliStateFile(workspaceRoot, CURRENT_POINTER_FILE), null);
+    return ptr?.slug;
+}
+/**
+ * Display-only "last workflow used in this workspace" lookup. Reads
+ * the workspace-level pointer unconditionally — never consults the
+ * session-level binding. Use when you want to render a hint like
+ * "you were last on workflow X" without implying that the current
+ * session is bound to it.
+ */
+export function getLastUsedWorkflow(workspaceRoot) {
     const ptr = readJsonFile(getCliStateFile(workspaceRoot, CURRENT_POINTER_FILE), null);
     return ptr?.slug;
 }
+/**
+ * Clear the session-level workflow binding (workspace-level hint
+ * preserved). Used by `/new` and `/fork` so a freshly-forked session
+ * doesn't drag the parent's binding along.
+ */
+export function clearSessionWorkflow(workspaceRoot, sessionKey) {
+    const pointerPath = getSessionStateFile(workspaceRoot, sessionKey, SESSION_POINTER_FILE);
+    try {
+        fs.unlinkSync(pointerPath);
+    }
+    catch { /* idempotent — no file to remove is fine */ }
+}
+/**
+ * True iff a workflow folder with the given slug exists (and carries a
+ * meta.json). Used by `/workflow switch <slug>` to surface "no such
+ * workflow" without the side-effect mkdir that `getWorkflowDir` performs.
+ */
+export function workflowExists(workspaceRoot, slug) {
+    const safeSlug = slugify(slug);
+    const root = getWorkflowsRoot(workspaceRoot);
+    const candidate = path.join(root, safeSlug, 'meta.json');
+    return fs.existsSync(candidate);
+}
 /**
  * Path (relative to workspace root) the LLM should `write_file` to for a
  * given artifact. We return a workspace-relative path because that's the

package/dist/tests/_helpers.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared fixtures + harness for the split-up CLI test suites.
+ *
+ * Lives under `src/tests/` alongside the actual `*.test.ts` files. The
+ * leading underscore is convention only — the test runner picks up files by
+ * the `*.test.js` glob, so a non-test filename is enough to keep node:test
+ * from trying to execute this module as a suite.
+ *
+ * Everything here was lifted verbatim out of the original `src/agent.test.ts`
+ * during the split. Don't add new fixtures unless they're used by ≥2 files.
+ */
+import { Agent } from '../agent/agent.js';
+/**
+ * Construct an Agent without touching MCP or the LLM. Only safe for tests
+ * that exercise pure state-machine extensions (model, accessMode, history,
+ * fork, refreshSystemPrompt) — anything that triggers `bootstrapSession`
+ * will hit the stub MCP and either no-op or surface a misleading error.
+ */
+export declare function makeAgent(workspace: string): Agent;
+/**
+ * Run a synchronous test body inside a fresh temp workspace. Restores cwd,
+ * BRAINROUTER_WORKSPACE, and BRAINROUTER_HOME afterwards. BRAINROUTER_HOME
+ * is also pinned to a sibling tmp dir so tests never touch the real
+ * `~/.brainrouter` on the developer's machine.
+ */
+export declare function withTempWorkspace(fn: (workspace: string) => void): void;
+/**
+ * Async sibling of `withTempWorkspace`. Same restore semantics; awaits the
+ * body so promise rejections still tear the workspace down.
+ */
+export declare function withTempWorkspaceAsync<T>(fn: (workspace: string) => Promise<T>): Promise<T>;

package/dist/tests/_helpers.js

@@ -0,0 +1,91 @@
+/**
+ * Shared fixtures + harness for the split-up CLI test suites.
+ *
+ * Lives under `src/tests/` alongside the actual `*.test.ts` files. The
+ * leading underscore is convention only — the test runner picks up files by
+ * the `*.test.js` glob, so a non-test filename is enough to keep node:test
+ * from trying to execute this module as a suite.
+ *
+ * Everything here was lifted verbatim out of the original `src/agent.test.ts`
+ * during the split. Don't add new fixtures unless they're used by ≥2 files.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Agent } from '../agent/agent.js';
+/**
+ * Construct an Agent without touching MCP or the LLM. Only safe for tests
+ * that exercise pure state-machine extensions (model, accessMode, history,
+ * fork, refreshSystemPrompt) — anything that triggers `bootstrapSession`
+ * will hit the stub MCP and either no-op or surface a misleading error.
+ */
+export function makeAgent(workspace) {
+    const stubMcp = {
+        listTools: async () => ({ tools: [] }),
+        callTool: async () => ({ content: [{ text: '{}' }] }),
+        close: async () => { },
+    };
+    const llm = { provider: 'openai', apiKey: 'k', model: 'test-model' };
+    return new Agent(stubMcp, llm, {
+        workspaceRoot: workspace,
+        launchCwd: workspace,
+        sessionKey: 'session:test',
+        silent: true, // skip bootstrap + briefing so we don't touch MCP at all
+    });
+}
+/**
+ * Run a synchronous test body inside a fresh temp workspace. Restores cwd,
+ * BRAINROUTER_WORKSPACE, and BRAINROUTER_HOME afterwards. BRAINROUTER_HOME
+ * is also pinned to a sibling tmp dir so tests never touch the real
+ * `~/.brainrouter` on the developer's machine.
+ */
+export function withTempWorkspace(fn) {
+    const previousCwd = process.cwd();
+    const previousWorkspace = process.env.BRAINROUTER_WORKSPACE;
+    const previousHome = process.env.BRAINROUTER_HOME;
+    const workspace = fs.mkdtempSync(path.join(os.tmpdir(), 'brainrouter-cli-'));
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), 'brainrouter-home-'));
+    try {
+        delete process.env.BRAINROUTER_WORKSPACE;
+        process.env.BRAINROUTER_HOME = home;
+        process.chdir(workspace);
+        fn(workspace);
+    }
+    finally {
+        process.chdir(previousCwd);
+        if (previousWorkspace === undefined)
+            delete process.env.BRAINROUTER_WORKSPACE;
+        else
+            process.env.BRAINROUTER_WORKSPACE = previousWorkspace;
+        if (previousHome === undefined)
+            delete process.env.BRAINROUTER_HOME;
+        else
+            process.env.BRAINROUTER_HOME = previousHome;
+        fs.rmSync(workspace, { recursive: true, force: true });
+        fs.rmSync(home, { recursive: true, force: true });
+    }
+}
+/**
+ * Async sibling of `withTempWorkspace`. Same restore semantics; awaits the
+ * body so promise rejections still tear the workspace down.
+ */
+export async function withTempWorkspaceAsync(fn) {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'brainrouter-test-'));
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), 'brainrouter-home-'));
+    const previousCwd = process.cwd();
+    const previousHome = process.env.BRAINROUTER_HOME;
+    process.env.BRAINROUTER_HOME = home;
+    process.chdir(tmp);
+    try {
+        return await fn(tmp);
+    }
+    finally {
+        process.chdir(previousCwd);
+        if (previousHome === undefined)
+            delete process.env.BRAINROUTER_HOME;
+        else
+            process.env.BRAINROUTER_HOME = previousHome;
+        fs.rmSync(tmp, { recursive: true, force: true });
+        fs.rmSync(home, { recursive: true, force: true });
+    }
+}

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@kinqs/brainrouter-cli",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Memory-native terminal coding agent. Talks to the BrainRouter MCP cognitive engine for recall, skills, capture, persona, focus scenes, and contradiction tracking.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "brainrouter": "dist/index.js"
+    "brainrouter": "bin/cli.cjs"
   },
   "files": [
+    "agents",
+    "bin",
     "dist",
     "README.md",
     ".env.example"
@@ -21,21 +23,26 @@
     "prepack": "npm run build && find dist -name '*.test.*' -delete"
   },
   "dependencies": {
-    "@kinqs/brainrouter-sdk": "^0.3.5",
-    "@kinqs/brainrouter-types": "^0.3.5",
+    "@kinqs/brainrouter-sdk": "^0.3.6",
+    "@kinqs/brainrouter-types": "^0.3.6",
     "@modelcontextprotocol/sdk": "^1.11.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "dotenv": "^16.4.5",
+    "ink": "^7.0.3",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
     "inquirer": "^9.3.2",
     "marked": "^12.0.1",
     "marked-terminal": "^7.0.0",
-    "ora": "^8.0.1"
+    "ora": "^8.0.1",
+    "react": "^19.2.6"
   },
   "devDependencies": {
     "@types/inquirer": "^9.0.7",
     "@types/marked": "^4.0.8",
     "@types/node": "^22.0.0",
+    "@types/react": "^19.2.15",
     "tsx": "^4.7.0",
     "typescript": "^5.5.4"
   },

package/.env.example

@@ -1,109 +0,0 @@
-# BrainRouter CLI agent — environment
-#
-# 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
-#
-# MCP-server concerns (cognitive extraction, embeddings, reranker, 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.
-
-# ==========================================
-# 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
-# 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
-
-# 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
-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.
-# 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.
-# BRAINROUTER_LLM_MAX_CONCURRENT=4
-
-# ==========================================
-# 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.
-# BRAINROUTER_MAX_TOOL_RESULT_CHARS=8000
-
-# 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.
-# BRAINROUTER_AUTO_COMPACT_TOKENS=80000
-
-# ==========================================
-# 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.
-# BRAINROUTER_SANDBOX=on
-
-# Allow outbound network from sandboxed commands. Off by default.
-# BRAINROUTER_SANDBOX_NETWORK=off
-
-# Colon-separated read/write path allowlists.
-# 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.
-# 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
-# ==========================================
-# Custom search backend for the web_search tool. Must accept
-#   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.
-# BRAINROUTER_WEB_SEARCH_ENDPOINT=https://your-search-proxy.example.com/search
-
-# ==========================================
-# 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