@kinqs/brainrouter-cli 0.3.4

package/dist/runtime/mcpClient.js

@@ -0,0 +1,234 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+export class McpClientWrapper {
+    client;
+    transport = null;
+    /**
+     * True only after a successful `connect()`. Lets the CLI run in a degraded
+     * "offline" mode when the MCP server is unreachable at startup — `listTools`
+     * returns an empty list and `callTool` returns an error envelope instead of
+     * blowing up, which the agent's existing try/catch wrappers already handle.
+     */
+    connected = false;
+    constructor() {
+        this.client = new Client({ name: 'brainrouter-cli', version: '0.3.4' }, { capabilities: {} });
+    }
+    /** Whether this wrapper has an active MCP transport. */
+    isConnected() {
+        return this.connected;
+    }
+    async connect(serverConfig, llmConfig) {
+        if (serverConfig.type === 'stdio') {
+            if (!serverConfig.command) {
+                throw new Error('Stdio server configuration missing "command".');
+            }
+            // Merge environment variables safely. The CLI and MCP server have
+            // separate `.env` files (brainrouter-cli/.env vs brainrouter/.env); we
+            // do NOT want CLI-specific knobs (sandbox, tool-loop limit, web search
+            // backend) leaking into the MCP child, and we do NOT want
+            // process-specific vars where each side wants its own default (e.g.
+            // LLM_MAX_CONCURRENT defaults to 4 in the CLI and 2 in the MCP). The
+            // MCP child's own `dotenv/config` will load brainrouter/.env via the
+            // cwd hint below, so those vars come in from the right source.
+            const CLI_ONLY_VARS = new Set([
+                'BRAINROUTER_MCP_TIMEOUT_MS',
+                'BRAINROUTER_MAX_TOOL_RESULT_CHARS',
+                'BRAINROUTER_AUTO_COMPACT_TOKENS',
+                'BRAINROUTER_MAX_TOOL_LOOPS',
+                'BRAINROUTER_TRACE_LOG',
+                'BRAINROUTER_SANDBOX',
+                'BRAINROUTER_SANDBOX_NETWORK',
+                'BRAINROUTER_SANDBOX_READ_PATHS',
+                'BRAINROUTER_SANDBOX_WRITE_PATHS',
+                'BRAINROUTER_WEB_SEARCH_ENDPOINT',
+            ]);
+            // Process-specific: same var name, but each process has its own
+            // semantic / default. Don't propagate — let brainrouter/.env decide.
+            const PROCESS_SPECIFIC_VARS = new Set([
+                'BRAINROUTER_LLM_MAX_CONCURRENT',
+                'BRAINROUTER_LLM_TIMEOUT_MS',
+            ]);
+            const mergedEnv = {};
+            for (const [k, v] of Object.entries(process.env)) {
+                if (v === undefined)
+                    continue;
+                if (CLI_ONLY_VARS.has(k))
+                    continue;
+                if (PROCESS_SPECIFIC_VARS.has(k))
+                    continue;
+                mergedEnv[k] = v;
+            }
+            if (serverConfig.env) {
+                for (const [k, v] of Object.entries(serverConfig.env)) {
+                    if (v !== undefined) {
+                        // If the shell process environment has a valid key, do not overwrite it with the default config placeholder.
+                        if (k === 'BRAINROUTER_API_KEY' && process.env.BRAINROUTER_API_KEY && v === 'br_admin_key_placeholder') {
+                            continue;
+                        }
+                        mergedEnv[k] = v;
+                    }
+                }
+            }
+            // Auto-propagate the CLI's configured LLM settings to the MCP child so
+            // server-side memory extraction can share the same credentials/endpoint/model.
+            // Existing env vars always win — explicit shell config beats CLI defaults.
+            //
+            // Critical: when only `OPENAI_API_KEY` is set in the user's shell (which
+            // the CLI itself accepts as a fallback in callOpenAI), the MCP child
+            // inherits nothing — its cognitive extractor then silently disables,
+            // sensory rows pile up, the cognitive table stays empty, and every
+            // future recall returns 0 records. The fallback chain below makes the
+            // MCP child see whatever credential the CLI itself would have used.
+            // API-key resolution must use truthy checks, not `??`. The config file
+            // ships with `llm.apiKey: ''` by default — an empty string — and `??`
+            // only falls back on null/undefined. The earlier `??` form let the
+            // empty config string beat the OPENAI_API_KEY env fallback, leaving
+            // the MCP child with no credential, which silently disabled cognitive
+            // extraction. Sensory captures still landed, so the CLI happily
+            // emitted "💾 Captured turn" while 79 extractions failed in the
+            // background. (Verified against scheduler_state.extraction_errors.)
+            if (!mergedEnv.BRAINROUTER_LLM_API_KEY) {
+                const apiKey = (llmConfig?.apiKey && llmConfig.apiKey.trim()) ||
+                    process.env.OPENAI_API_KEY ||
+                    process.env.BRAINROUTER_LLM_API_KEY;
+                if (apiKey) {
+                    mergedEnv.BRAINROUTER_LLM_API_KEY = apiKey;
+                }
+            }
+            if (llmConfig?.endpoint && !mergedEnv.BRAINROUTER_LLM_ENDPOINT) {
+                const ep = llmConfig.endpoint.replace(/\/$/, '');
+                mergedEnv.BRAINROUTER_LLM_ENDPOINT = ep.endsWith('/chat/completions')
+                    ? ep
+                    : `${ep}/chat/completions`;
+            }
+            if (llmConfig?.model && !mergedEnv.BRAINROUTER_LLM_MODEL) {
+                mergedEnv.BRAINROUTER_LLM_MODEL = llmConfig.model;
+            }
+            // Loud diagnostic: if NO LLM key reached the child, server-side
+            // memory extraction is dead — every sensory capture will pile up
+            // un-extracted. Print a yellow banner so the user knows BEFORE they
+            // see "0 records" in every briefing.
+            if (!mergedEnv.BRAINROUTER_LLM_API_KEY) {
+                console.warn('\n⚠️  No LLM API key reached the MCP child. Sensory turns will be ' +
+                    'captured but cognitive extraction (the thing that makes them ' +
+                    'searchable) will fail silently. Set OPENAI_API_KEY or ' +
+                    'BRAINROUTER_LLM_API_KEY before starting brainrouter.\n');
+            }
+            // Spawn the MCP child with cwd set to the MCP package directory if we
+            // can find it from the first arg (typically
+            // `node /path/to/BrainRouter/brainrouter/dist/index.js`). The child
+            // uses `import "dotenv/config"` which resolves `.env` relative to
+            // `process.cwd()` — defaulting to the user's launch dir meant
+            // `brainrouter/.env` was never read. With cwd hinted, dotenv finds
+            // the canonical config without the user having to copy/symlink files.
+            const firstArg = serverConfig.args?.[0];
+            let childCwd;
+            if (firstArg && firstArg.endsWith('.js')) {
+                try {
+                    // brainrouter/dist/index.js → brainrouter/
+                    const distDir = path.dirname(firstArg);
+                    const pkgRoot = path.resolve(distDir, '..');
+                    // Sanity: only set if the directory contains a `.env` or `package.json`
+                    // (avoid pointing the child at /usr/local/lib by accident).
+                    if (fs.existsSync(path.join(pkgRoot, '.env')) ||
+                        fs.existsSync(path.join(pkgRoot, 'package.json'))) {
+                        childCwd = pkgRoot;
+                    }
+                }
+                catch {
+                    // Best-effort; if path resolution fails we just don't set cwd.
+                }
+            }
+            this.transport = new StdioClientTransport({
+                command: serverConfig.command,
+                args: serverConfig.args ?? [],
+                env: mergedEnv,
+                cwd: childCwd,
+            });
+            await this.client.connect(this.transport);
+            this.connected = true;
+        }
+        else if (serverConfig.type === 'http') {
+            if (!serverConfig.url) {
+                throw new Error('HTTP server configuration missing "url".');
+            }
+            const url = new URL(serverConfig.url);
+            const transportOpts = {};
+            if (serverConfig.apiKey) {
+                transportOpts.requestInit = {
+                    headers: {
+                        'Authorization': `Bearer ${serverConfig.apiKey}`,
+                    },
+                };
+            }
+            const httpTransport = new StreamableHTTPClientTransport(url, transportOpts);
+            this.transport = httpTransport;
+            await this.client.connect(httpTransport);
+            this.connected = true;
+        }
+        else {
+            throw new Error(`Unsupported connection type: ${serverConfig.type}`);
+        }
+    }
+    async listTools() {
+        // Offline mode: return an empty tool list so the agent's runTurn proceeds
+        // with only local tools instead of crashing when it tries to enumerate.
+        if (!this.connected)
+            return { tools: [] };
+        return this.client.listTools({});
+    }
+    async callTool(name, args) {
+        // Offline mode: synthesize an error envelope that downstream consumers
+        // (callMcpTool, agent.captureTurn, memory_recall pipelines) already know
+        // how to ignore via their existing isError checks. Without this the SDK
+        // would throw "Not connected" from inside transport code, which surfaces
+        // as a hard crash instead of a graceful degradation.
+        if (!this.connected) {
+            return {
+                isError: true,
+                content: [{
+                        type: 'text',
+                        text: `MCP server is not connected. Tool "${name}" is unavailable in offline mode. Start the BrainRouter MCP server and reconnect (or restart the CLI) to use memory, skills, and recall.`,
+                    }],
+            };
+        }
+        // A hung MCP server used to hang the entire runTurn forever — there was
+        // no per-tool timeout, and the LLM call timeout only fired between tool
+        // rounds. Race the tool call against a configurable timeout so a flaky
+        // child server can't lock up the whole CLI.
+        const timeoutMs = Number(process.env.BRAINROUTER_MCP_TIMEOUT_MS) || 60_000;
+        return Promise.race([
+            this.client.callTool({ name, arguments: args }),
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`MCP tool "${name}" timed out after ${timeoutMs}ms`)), timeoutMs)),
+        ]);
+    }
+    async close() {
+        if (this.transport) {
+            if (this.transport instanceof StreamableHTTPClientTransport) {
+                try {
+                    await this.transport.terminateSession();
+                }
+                catch {
+                    // ignore session termination errors
+                }
+            }
+            try {
+                await this.transport.close();
+            }
+            catch {
+                // ignore
+            }
+        }
+        try {
+            await this.client.close();
+        }
+        catch {
+            // ignore
+        }
+        this.transport = null;
+        this.connected = false;
+    }
+}

package/dist/runtime/mcpUtils.d.ts

@@ -0,0 +1,36 @@
+import type { McpClientWrapper } from './mcpClient.js';
+/**
+ * Centralized helpers for talking to the BrainRouter MCP server.
+ *
+ * Every MCP `callTool` response shares the same wire shape — an `isError`
+ * boolean plus a `content` array of `{ type, text }` entries — and most
+ * callers do the same three things with it: join the text, optionally
+ * `JSON.parse`, and tolerate failures. Centralizing those mechanics here
+ * avoids ~5 nearly-identical extractors scattered across the codebase and
+ * gives us one place to fix bugs (e.g., result shape changes upstream).
+ */
+/** Join the `text` parts of an MCP tool result into a single string. Tolerates non-content payloads. */
+export declare function extractToolText(result: any): string;
+/** JSON.parse that never throws. Returns `undefined` (or the provided fallback) on failure. */
+export declare function safeJsonParse<T = any>(text: string, fallback?: T): T | undefined;
+export interface McpCallResult<T = any> {
+    isError: boolean;
+    text: string;
+    /** Parsed JSON when the tool returned JSON; undefined otherwise. */
+    parsed: T | undefined;
+    /** The raw response object, in case a caller needs metadata we didn't normalize. */
+    raw: any;
+}
+/**
+ * Call an MCP tool and normalize the response into `{ isError, text, parsed }`.
+ *
+ * Network and protocol errors are converted to `{ isError: true, text: errorMessage }`
+ * so callers can branch on a single shape instead of mixing try/catch with isError checks.
+ */
+export declare function callMcpTool<T = any>(client: McpClientWrapper, name: string, args: Record<string, unknown>): Promise<McpCallResult<T>>;
+/**
+ * Canonical convention for naming a child agent's session key relative to its
+ * parent: `<parent>:child:<id>`. Centralized so a future change (e.g. switching
+ * to UUIDs or namespacing per-role) is a one-file edit, not a sweep.
+ */
+export declare function childSessionKey(parentSessionKey: string, childId: string): string;

package/dist/runtime/mcpUtils.js

@@ -0,0 +1,64 @@
+/**
+ * Centralized helpers for talking to the BrainRouter MCP server.
+ *
+ * Every MCP `callTool` response shares the same wire shape — an `isError`
+ * boolean plus a `content` array of `{ type, text }` entries — and most
+ * callers do the same three things with it: join the text, optionally
+ * `JSON.parse`, and tolerate failures. Centralizing those mechanics here
+ * avoids ~5 nearly-identical extractors scattered across the codebase and
+ * gives us one place to fix bugs (e.g., result shape changes upstream).
+ */
+/** Join the `text` parts of an MCP tool result into a single string. Tolerates non-content payloads. */
+export function extractToolText(result) {
+    if (Array.isArray(result?.content)) {
+        return result.content.map((entry) => entry?.text || '').join('\n');
+    }
+    if (typeof result === 'string')
+        return result;
+    return JSON.stringify(result ?? '');
+}
+/** JSON.parse that never throws. Returns `undefined` (or the provided fallback) on failure. */
+export function safeJsonParse(text, fallback) {
+    if (!text)
+        return fallback;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Call an MCP tool and normalize the response into `{ isError, text, parsed }`.
+ *
+ * Network and protocol errors are converted to `{ isError: true, text: errorMessage }`
+ * so callers can branch on a single shape instead of mixing try/catch with isError checks.
+ */
+export async function callMcpTool(client, name, args) {
+    try {
+        const raw = await client.callTool(name, args);
+        const text = extractToolText(raw);
+        return {
+            isError: Boolean(raw?.isError),
+            text,
+            parsed: safeJsonParse(text),
+            raw,
+        };
+    }
+    catch (err) {
+        return {
+            isError: true,
+            text: err?.message ?? String(err),
+            parsed: undefined,
+            raw: undefined,
+        };
+    }
+}
+/**
+ * Canonical convention for naming a child agent's session key relative to its
+ * parent: `<parent>:child:<id>`. Centralized so a future change (e.g. switching
+ * to UUIDs or namespacing per-role) is a one-file edit, not a sweep.
+ */
+export function childSessionKey(parentSessionKey, childId) {
+    return `${parentSessionKey}:child:${childId}`;
+}

package/dist/runtime/sandbox.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Optional sandboxing for `run_command`.
+ *
+ * Activated by setting `BRAINROUTER_SANDBOX=on`. When inactive, commands run
+ * exactly as before (with the existing user confirmation prompt). When
+ * active, the command is wrapped in the platform's native sandboxer:
+ *
+ *   - macOS: `sandbox-exec -f <profile>` with a generated `.sb` profile that
+ *            denies network by default, restricts writes to the workspace, and
+ *            allows reads of `/usr`, `/bin`, `/etc`, the workspace, and any
+ *            extra paths in `BRAINROUTER_SANDBOX_READ_PATHS`.
+ *   - Linux: `bwrap` (bubblewrap) when available; falls back to `firejail`.
+ *            Sets up a fresh mount namespace with the workspace mounted rw and
+ *            the rest of the FS bind-mounted ro.
+ *   - Windows: no native sandbox in stdlib; falls back to unsandboxed run with
+ *              a clear warning so the user knows the flag was honored as a no-op.
+ *
+ * The sandbox is intentionally an *additional* layer on top of the existing
+ * user-confirmation step — confirmation guards intent, sandboxing guards blast
+ * radius if the user approves something they shouldn't have.
+ */
+export interface SandboxConfig {
+    enabled: boolean;
+    workspaceRoot: string;
+    /** Extra read-only paths to allow. */
+    readPaths: string[];
+    /** Extra write-allowed paths beyond the workspace. */
+    writePaths: string[];
+    /** If true, allow outbound network. Off by default. */
+    allowNetwork: boolean;
+}
+export declare function resolveSandboxConfig(workspaceRoot: string, persistedExtras?: {
+    readPaths?: string[];
+    writePaths?: string[];
+}): SandboxConfig;
+export interface SandboxRunResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    sandboxed: boolean;
+    sandboxTool?: 'sandbox-exec' | 'bwrap' | 'firejail' | 'none';
+    notice?: string;
+}
+/**
+ * Execute `command` (a shell string) with optional sandboxing. Returns a
+ * normalized result. Always returns; never throws on non-zero exit.
+ */
+export declare function runShell(command: string, config: SandboxConfig, timeoutMs?: number): Promise<SandboxRunResult>;

package/dist/runtime/sandbox.js

@@ -0,0 +1,156 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export function resolveSandboxConfig(workspaceRoot, persistedExtras) {
+    const enabled = (process.env.BRAINROUTER_SANDBOX ?? '').toLowerCase() === 'on';
+    const envReads = (process.env.BRAINROUTER_SANDBOX_READ_PATHS ?? '')
+        .split(path.delimiter).map((p) => p.trim()).filter(Boolean);
+    const envWrites = (process.env.BRAINROUTER_SANDBOX_WRITE_PATHS ?? '')
+        .split(path.delimiter).map((p) => p.trim()).filter(Boolean);
+    const readPaths = Array.from(new Set([...(persistedExtras?.readPaths ?? []), ...envReads]));
+    const writePaths = Array.from(new Set([...(persistedExtras?.writePaths ?? []), ...envWrites]));
+    const allowNetwork = (process.env.BRAINROUTER_SANDBOX_NETWORK ?? '').toLowerCase() === 'on';
+    return { enabled, workspaceRoot, readPaths, writePaths, allowNetwork };
+}
+/**
+ * Execute `command` (a shell string) with optional sandboxing. Returns a
+ * normalized result. Always returns; never throws on non-zero exit.
+ */
+export async function runShell(command, config, timeoutMs = 120_000) {
+    // Always pin cwd to the workspace root so `run_command` never inherits a
+    // drifted process.cwd() (and writes test files into ~/.brainrouter).
+    const cwd = config.workspaceRoot;
+    if (!config.enabled) {
+        return execShell(command, undefined, cwd, timeoutMs, false, 'none');
+    }
+    if (process.platform === 'darwin') {
+        const profilePath = writeMacSandboxProfile(config);
+        const wrapped = ['sandbox-exec', '-f', profilePath, '/bin/sh', '-c', command];
+        return execShell(wrapped[0], wrapped.slice(1), cwd, timeoutMs, true, 'sandbox-exec');
+    }
+    if (process.platform === 'linux') {
+        if (await binaryAvailable('bwrap')) {
+            const args = buildBwrapArgs(config, command);
+            return execShell('bwrap', args, cwd, timeoutMs, true, 'bwrap');
+        }
+        if (await binaryAvailable('firejail')) {
+            const args = buildFirejailArgs(config, command);
+            return execShell('firejail', args, cwd, timeoutMs, true, 'firejail');
+        }
+        const fallback = await execShell('/bin/sh', ['-c', command], cwd, timeoutMs, false, 'none');
+        fallback.notice = 'BRAINROUTER_SANDBOX=on but neither bwrap nor firejail is installed — command ran UNSANDBOXED.';
+        return fallback;
+    }
+    // Windows / other — no portable sandbox. Run unsandboxed with a notice.
+    const fallback = await execShell(command, undefined, cwd, timeoutMs, false, 'none');
+    fallback.notice = `BRAINROUTER_SANDBOX=on but no sandbox tool is available on ${process.platform} — command ran UNSANDBOXED.`;
+    return fallback;
+}
+function execShell(cmd, args, cwd, timeoutMs, sandboxed, tool) {
+    return new Promise((resolve) => {
+        const useShell = !args; // when no args provided, run as a single shell string
+        const child = useShell
+            ? spawn(cmd, { cwd, shell: true })
+            : spawn(cmd, args, { cwd });
+        let stdout = '';
+        let stderr = '';
+        const timer = setTimeout(() => {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* noop */ }
+        }, timeoutMs);
+        child.stdout?.on('data', (chunk) => { stdout += chunk.toString(); });
+        child.stderr?.on('data', (chunk) => { stderr += chunk.toString(); });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolve({ stdout, stderr, exitCode: code ?? 0, sandboxed, sandboxTool: tool });
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            resolve({ stdout: '', stderr: err.message, exitCode: 127, sandboxed, sandboxTool: tool });
+        });
+    });
+}
+function binaryAvailable(name) {
+    return new Promise((resolve) => {
+        const child = spawn('command', ['-v', name], { shell: true });
+        child.on('close', (code) => resolve(code === 0));
+        child.on('error', () => resolve(false));
+    });
+}
+/**
+ * Generate a macOS sandbox-exec profile and write it to a temp file. The
+ * profile starts from `(deny default)` and explicitly allows the syscalls a
+ * normal build/test command needs.
+ */
+function writeMacSandboxProfile(config) {
+    const lines = [
+        '(version 1)',
+        '(deny default)',
+        '(allow process-fork process-exec)',
+        '(allow signal (target self))',
+        '(allow sysctl-read)',
+        '(allow mach-lookup)',
+        '(allow ipc-posix-shm)',
+        '(allow file-read*)', // permissive on reads — sandboxing writes is the priority
+        `(allow file-write* (subpath "${escapeSb(config.workspaceRoot)}"))`,
+        '(allow file-write* (subpath "/tmp"))',
+        `(allow file-write* (subpath "${escapeSb(os.tmpdir())}"))`,
+    ];
+    for (const p of config.writePaths) {
+        lines.push(`(allow file-write* (subpath "${escapeSb(p)}"))`);
+    }
+    if (config.allowNetwork) {
+        lines.push('(allow network*)');
+    }
+    const profile = lines.join('\n');
+    const file = path.join(os.tmpdir(), `brainrouter-sandbox-${process.pid}.sb`);
+    fs.writeFileSync(file, profile, 'utf8');
+    return file;
+}
+function escapeSb(p) {
+    return p.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+function buildBwrapArgs(config, command) {
+    const args = [
+        '--ro-bind', '/usr', '/usr',
+        '--ro-bind', '/lib', '/lib',
+        '--ro-bind', '/lib64', '/lib64',
+        '--ro-bind', '/etc', '/etc',
+        '--ro-bind', '/bin', '/bin',
+        '--proc', '/proc',
+        '--dev', '/dev',
+        '--tmpfs', '/tmp',
+        '--bind', config.workspaceRoot, config.workspaceRoot,
+        '--chdir', config.workspaceRoot,
+    ];
+    for (const p of config.readPaths) {
+        args.push('--ro-bind', p, p);
+    }
+    for (const p of config.writePaths) {
+        args.push('--bind', p, p);
+    }
+    if (!config.allowNetwork) {
+        args.push('--unshare-net');
+    }
+    args.push('/bin/sh', '-c', command);
+    return args;
+}
+function buildFirejailArgs(config, command) {
+    const args = [
+        '--quiet',
+        `--whitelist=${config.workspaceRoot}`,
+        `--read-only=/usr`,
+        `--read-only=/etc`,
+    ];
+    for (const p of config.readPaths)
+        args.push(`--read-only=${p}`);
+    for (const p of config.writePaths)
+        args.push(`--whitelist=${p}`);
+    if (!config.allowNetwork)
+        args.push('--net=none');
+    args.push('/bin/sh', '-c', command);
+    return args;
+}

package/dist/runtime/tracing.d.ts

@@ -0,0 +1,25 @@
+export declare function traceEnabled(): boolean;
+export declare function newTraceId(): string;
+export declare function newSpanId(): string;
+/**
+ * Emit a one-shot event (no duration). Cheap; the file is opened+appended
+ * synchronously then closed. For higher throughput, swap to a buffered writer
+ * later — this is intentionally simple.
+ */
+export declare function traceEvent(name: string, attributes?: Record<string, unknown>, options?: {
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+}): void;
+/**
+ * Open a span. Call `end(extraAttrs?)` on the returned handle when finished.
+ * Returns a no-op handle when tracing is disabled.
+ */
+export declare function startSpan(name: string, attributes?: Record<string, unknown>, options?: {
+    traceId?: string;
+    parentSpanId?: string;
+}): {
+    end: (extra?: Record<string, unknown>) => void;
+    traceId: string;
+    spanId: string;
+};

package/dist/runtime/tracing.js

@@ -0,0 +1,91 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+let cachedLogPath;
+function resolveLogPath() {
+    if (cachedLogPath !== undefined)
+        return cachedLogPath;
+    const raw = process.env.BRAINROUTER_TRACE_LOG?.trim();
+    cachedLogPath = raw ? path.resolve(raw) : null;
+    if (cachedLogPath) {
+        try {
+            fs.mkdirSync(path.dirname(cachedLogPath), { recursive: true });
+        }
+        catch { /* noop */ }
+    }
+    return cachedLogPath;
+}
+export function traceEnabled() {
+    return resolveLogPath() !== null;
+}
+export function newTraceId() {
+    return randomUUID().replace(/-/g, '').slice(0, 32);
+}
+export function newSpanId() {
+    return randomUUID().replace(/-/g, '').slice(0, 16);
+}
+/**
+ * Emit a one-shot event (no duration). Cheap; the file is opened+appended
+ * synchronously then closed. For higher throughput, swap to a buffered writer
+ * later — this is intentionally simple.
+ */
+export function traceEvent(name, attributes = {}, options) {
+    const logPath = resolveLogPath();
+    if (!logPath)
+        return;
+    const evt = {
+        ts: new Date().toISOString(),
+        trace_id: options?.traceId ?? newTraceId(),
+        span_id: options?.spanId ?? newSpanId(),
+        parent_span_id: options?.parentSpanId,
+        name,
+        attributes,
+    };
+    try {
+        fs.appendFileSync(logPath, JSON.stringify(evt) + '\n', 'utf8');
+    }
+    catch { /* tracing must never break the CLI */ }
+}
+/**
+ * Open a span. Call `end(extraAttrs?)` on the returned handle when finished.
+ * Returns a no-op handle when tracing is disabled.
+ */
+export function startSpan(name, attributes = {}, options) {
+    if (!traceEnabled()) {
+        return { end: () => { }, traceId: '', spanId: '' };
+    }
+    const traceId = options?.traceId ?? newTraceId();
+    const spanId = newSpanId();
+    const startedAt = Date.now();
+    return {
+        traceId,
+        spanId,
+        end: (extra) => {
+            traceEvent(name, { ...attributes, ...(extra ?? {}) }, {
+                traceId,
+                spanId,
+                parentSpanId: options?.parentSpanId,
+            });
+            // Overwrite ts with start time? — keep ts as end-of-span for simplicity;
+            // duration_ms gives the start. Some collectors prefer this shape.
+            const logPath = resolveLogPath();
+            if (logPath) {
+                try {
+                    // Best-effort patch: write a second line with duration_ms so the
+                    // duration is queryable without re-deriving from start/end events.
+                    const dur = Date.now() - startedAt;
+                    fs.appendFileSync(logPath, JSON.stringify({
+                        ts: new Date().toISOString(),
+                        trace_id: traceId,
+                        span_id: spanId,
+                        parent_span_id: options?.parentSpanId,
+                        name: `${name}.end`,
+                        duration_ms: dur,
+                        attributes: { ...attributes, ...(extra ?? {}) },
+                    }) + '\n', 'utf8');
+                }
+                catch { /* noop */ }
+            }
+        },
+    };
+}