@semalt-ai/code 1.8.5 → 1.19.0

package/lib/mcp/client.js

@@ -0,0 +1,270 @@
+'use strict';
+
+// MCP client manager (Task 3.3).
+// ----------------------------------------------------------------------------
+// Connects to the MCP servers configured under `config.mcp.servers`, discovers
+// each server's tools, and registers them into the runtime tool registry
+// (lib/tool_registry.js dynamic API) under the namespace `mcp__<server>__<tool>`
+// so they dispatch through the SAME agent loop as built-ins.
+//
+// Security posture (required by the task):
+//   * MCP tool RESULTS are untrusted external content — the execute() here
+//     returns `{ mcp:true, content, isError }`, and the agent loop wraps that
+//     payload in the UNTRUSTED_EXTERNAL_CONTENT delimiter (lib/agent.js),
+//     identical to http_get.
+//   * MCP tools are arbitrary/external, so they REQUIRE APPROVAL by default —
+//     never auto-allowed by the `--allow-*` tiers. Per-server/per-tool opt-in
+//     comes from config (`allow: [...]` or `allowAll: true`).
+//
+// Robustness: a server that fails to launch/connect degrades gracefully (the
+// failure is recorded in status, a warning is logged, and the CLI continues) —
+// it never crashes the process. The SDK itself is reached only through
+// lib/mcp/boundary.js (the single CJS↔ESM bridge); this module never imports it.
+
+const realBoundary = require('./boundary');
+const {
+  registerDynamicTool, unregisterDynamicTool,
+} = require('../tool_registry');
+const { logToolCall } = require('../audit');
+const { createKeychainOAuthProvider } = require('./oauth');
+
+const realRegistry = { registerDynamicTool, unregisterDynamicTool };
+
+const DEFAULT_CONNECT_TIMEOUT_MS = 15000;
+
+// `mcp__<server>__<tool>` with non-identifier chars folded to `_` so the result
+// is a valid native function name (the LLM echoes it back verbatim in tool_calls).
+function mcpToolName(server, tool) {
+  const s = String(server).replace(/[^a-zA-Z0-9_-]/g, '_');
+  const t = String(tool).replace(/[^a-zA-Z0-9_-]/g, '_');
+  return `mcp__${s}__${t}`;
+}
+
+// Flatten an MCP CallToolResult's content blocks into a single text string.
+// Text blocks pass through; non-text blocks (image/resource/…) are summarized
+// as a JSON line so nothing is silently dropped from the model's view.
+function mcpResultToText(result) {
+  if (!result) return '';
+  const blocks = Array.isArray(result.content) ? result.content : [];
+  const parts = [];
+  for (const b of blocks) {
+    if (b && b.type === 'text' && typeof b.text === 'string') parts.push(b.text);
+    else if (b && typeof b === 'object') parts.push(`[${b.type || 'content'}] ${JSON.stringify(b)}`);
+  }
+  if (!parts.length && result.structuredContent !== undefined) {
+    parts.push(JSON.stringify(result.structuredContent));
+  }
+  return parts.join('\n');
+}
+
+// Decide whether a discovered tool is pre-approved (opt-in) for this server.
+// Matches either the bare tool name or its full namespaced form in `allow`.
+function isToolAllowed(spec, toolName, namespacedName) {
+  if (!spec) return false;
+  if (spec.allowAll === true) return true;
+  const allow = Array.isArray(spec.allow) ? spec.allow : [];
+  return allow.includes(toolName) || allow.includes(namespacedName);
+}
+
+// Build the dynamic tool-registry entry for one discovered MCP tool. Shape is
+// identical to a static entry so the agent loop dispatches it the same way.
+function buildMcpToolEntry({ server, spec, tool, client }) {
+  const name = mcpToolName(server, tool.name);
+  const allowed = isToolAllowed(spec, tool.name, name);
+  const description = `[MCP:${server}] ${tool.description || tool.name}`;
+
+  return {
+    tool: name,
+    mcp: true,
+    server,
+    origName: tool.name,
+    spec: {
+      description,
+      parameters: tool.inputSchema && typeof tool.inputSchema === 'object'
+        ? tool.inputSchema
+        : { type: 'object', properties: {} },
+    },
+    // Native function-calling path: the model emits { name, arguments } → the
+    // whole arguments object becomes the single positional arg of the tuple.
+    fromParams: (p) => [name, p || {}],
+    // XML path (non-native models): <mcp__server__tool>{json args}</mcp__server__tool>.
+    parseXml: (text) => {
+      const out = [];
+      const re = new RegExp(`<${name}\\s*>([\\s\\S]*?)<\\/${name}>`, 'g');
+      for (const m of text.matchAll(re)) {
+        const body = (m[1] || '').trim();
+        let args = {};
+        if (body) { try { args = JSON.parse(body); } catch { args = {}; } }
+        out.push([name, args]);
+      }
+      // Self-closing form with no args: <mcp__server__tool/>
+      const selfRe = new RegExp(`<${name}\\s*/>`, 'g');
+      for (const _m of text.matchAll(selfRe)) out.push([name, {}]);
+      return out;
+    },
+    // Approval gate: MCP tools require approval by DEFAULT. Opt-in via config
+    // (allow/allowAll) returns null → no gate (treated like a read-only tool).
+    permission: () => {
+      if (allowed) return null;
+      return { actionType: 'mcp', description: `MCP ${server}/${tool.name}`, tag: name };
+    },
+    execute: async (_ctx, args, options) => {
+      const params = (args && args[0]) || {};
+      const signal = (options && options.signal) || undefined;
+      try {
+        const res = await client.callTool(
+          { name: tool.name, arguments: params },
+          undefined,
+          signal ? { signal } : undefined,
+        );
+        logToolCall(name, { server, tool: tool.name }, true, res && res.isError ? 'error' : 'ok');
+        return { mcp: true, content: mcpResultToText(res), isError: !!(res && res.isError) };
+      } catch (err) {
+        logToolCall(name, { server, tool: tool.name }, true, 'error');
+        return { error: err && err.message ? err.message : String(err) };
+      }
+    },
+  };
+}
+
+function withTimeout(promise, ms, onTimeoutMessage) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(onTimeoutMessage)), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+function createMcpManager({
+  getConfig,
+  boundary = realBoundary,
+  registry = realRegistry,
+  oauthFactory = createKeychainOAuthProvider,
+  logger = null,
+  connectTimeoutMs = DEFAULT_CONNECT_TIMEOUT_MS,
+} = {}) {
+  const _clients = new Map();   // server name → connected Client
+  const _toolNames = [];        // registered dynamic tool names
+  let _status = [];             // per-server status records
+
+  function warn(msg) {
+    if (typeof logger === 'function') logger(msg);
+  }
+
+  // Resolve the transport for a server spec. Throws on an invalid/missing spec.
+  async function buildTransport(name, spec) {
+    const transport = (spec.transport || (spec.url ? 'http' : 'stdio')).toLowerCase();
+    if (transport === 'stdio') {
+      if (!spec.command) throw new Error(`stdio server "${name}" requires a "command"`);
+      return boundary.createStdioTransport({
+        command: spec.command,
+        args: Array.isArray(spec.args) ? spec.args : [],
+        env: spec.env && typeof spec.env === 'object' ? spec.env : undefined,
+        cwd: spec.cwd || undefined,
+      });
+    }
+    if (transport === 'http' || transport === 'streamable-http' || transport === 'sse') {
+      if (!spec.url) throw new Error(`remote server "${name}" requires a "url"`);
+      const opts = {};
+      if (spec.headers && typeof spec.headers === 'object') {
+        opts.requestInit = { headers: spec.headers };
+      }
+      // OAuth: opt-in via spec.oauth (or spec.auth === 'oauth'). Tokens are
+      // persisted in the OS keychain by the provider, never in config.
+      if (spec.oauth === true || spec.auth === 'oauth') {
+        opts.authProvider = oauthFactory(name, { url: spec.url });
+      }
+      return transport === 'sse'
+        ? boundary.createSseTransport(spec.url, opts)
+        : boundary.createStreamableHttpTransport(spec.url, opts);
+    }
+    throw new Error(`server "${name}" has unknown transport "${transport}"`);
+  }
+
+  async function connectServer(name, spec) {
+    const transportKind = (spec.transport || (spec.url ? 'http' : 'stdio')).toLowerCase();
+    const record = { name, transport: transportKind, state: 'connecting', tools: [], error: null };
+    if (spec.disabled) {
+      record.state = 'disabled';
+      return record;
+    }
+    let client = null;
+    try {
+      const transport = await buildTransport(name, spec);
+      client = await boundary.createClient();
+      await withTimeout(
+        client.connect(transport),
+        connectTimeoutMs,
+        `connect timed out after ${connectTimeoutMs}ms`,
+      );
+      const listed = await client.listTools();
+      const tools = Array.isArray(listed && listed.tools) ? listed.tools : [];
+      for (const tool of tools) {
+        if (!tool || typeof tool.name !== 'string') continue;
+        const entry = buildMcpToolEntry({ server: name, spec, tool, client });
+        registry.registerDynamicTool(entry);
+        record.tools.push(entry.tool);
+        _toolNames.push(entry.tool);
+      }
+      record.state = 'connected';
+      _clients.set(name, client);
+    } catch (err) {
+      record.state = 'failed';
+      record.error = err && err.message ? err.message : String(err);
+      warn(`MCP server "${name}" failed: ${record.error}`);
+      // Best-effort cleanup of a half-open client so a failed server leaks nothing.
+      if (client) { try { await client.close(); } catch { /* ignore */ } }
+    }
+    return record;
+  }
+
+  // Connect to every configured server. Failures are isolated per-server (one
+  // bad server never blocks the others, and never throws out of here).
+  async function connectAll() {
+    const cfg = getConfig ? getConfig() : {};
+    const servers = (cfg && cfg.mcp && cfg.mcp.servers) || {};
+    const names = Object.keys(servers);
+    const records = [];
+    for (const name of names) {
+      records.push(await connectServer(name, servers[name] || {}));
+    }
+    _status = records;
+    return records;
+  }
+
+  function status() {
+    return _status.map((r) => ({ ...r, tools: r.tools.slice() }));
+  }
+
+  function registeredToolNames() {
+    return _toolNames.slice();
+  }
+
+  async function shutdown() {
+    for (const name of _toolNames) {
+      try { registry.unregisterDynamicTool(name); } catch { /* ignore */ }
+    }
+    _toolNames.length = 0;
+    for (const client of _clients.values()) {
+      try { await client.close(); } catch { /* ignore */ }
+    }
+    _clients.clear();
+    _status = [];
+  }
+
+  return {
+    connectAll,
+    connectServer,
+    status,
+    registeredToolNames,
+    shutdown,
+  };
+}
+
+module.exports = {
+  createMcpManager,
+  buildMcpToolEntry,
+  mcpToolName,
+  mcpResultToText,
+  isToolAllowed,
+};

package/lib/mcp/oauth.js

@@ -0,0 +1,134 @@
+'use strict';
+
+// MCP OAuth — keychain-backed token store (Task 3.3).
+// ----------------------------------------------------------------------------
+// Remote MCP servers (HTTP/SSE) may require OAuth. The SDK drives the OAuth 2.1
+// + PKCE flow through an `OAuthClientProvider` interface; this module implements
+// that interface and persists EVERYTHING sensitive — tokens, the dynamically
+// registered client credentials, and the PKCE code verifier — in the OS
+// keychain, never in plaintext config. That mirrors the Phase 0 secret path
+// (lib/secrets.js): secrets live in the keychain, config holds only references.
+//
+// The keychain access is injected (`store`) so it can be unit-tested with an
+// in-memory fake; in production it defaults to the generic keychain helpers in
+// lib/secrets.js under the service `semalt-code-mcp`, keyed per server.
+//
+// Records are JSON blobs stored under three accounts per server:
+//   <server>:tokens    — the OAuthTokens (access/refresh/expiry)
+//   <server>:client    — the registered OAuthClientInformation
+//   <server>:verifier  — the in-flight PKCE code verifier
+//
+// `redirectToAuthorization` opens the user's browser (best-effort) and prints
+// the URL so headless/remote sessions can complete the flow manually.
+
+const { spawn } = require('child_process');
+const {
+  keychainGetItem, keychainSetItem, keychainDeleteItem,
+} = require('../secrets');
+
+const MCP_KEYCHAIN_SERVICE = 'semalt-code-mcp';
+
+// Default production store: the OS keychain via lib/secrets.js generic helpers.
+function keychainStore(service = MCP_KEYCHAIN_SERVICE) {
+  return {
+    get(account) { return keychainGetItem(service, account); },
+    set(account, value) { return keychainSetItem(service, account, value, `MCP OAuth ${account}`); },
+    delete(account) { return keychainDeleteItem(service, account); },
+  };
+}
+
+// Best-effort browser opener — same idea the device-login flow uses. Never
+// throws; if no opener is available the URL is just printed for manual use.
+function _openBrowser(url) {
+  const platform = process.platform;
+  let cmd; let args;
+  if (platform === 'darwin') { cmd = 'open'; args = [url]; }
+  else if (platform === 'win32') { cmd = 'cmd'; args = ['/c', 'start', '', url]; }
+  else { cmd = 'xdg-open'; args = [url]; }
+  try {
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+  } catch { /* ignore — URL is printed below */ }
+}
+
+function _parse(raw) {
+  if (!raw) return undefined;
+  try { return JSON.parse(raw); } catch { return undefined; }
+}
+
+// Build a keychain-backed OAuthClientProvider for one server.
+//   server      — config key, used to namespace keychain accounts.
+//   url         — the server URL (origin used as redirect base).
+//   store       — injectable { get, set, delete } (defaults to OS keychain).
+//   onRedirect  — optional callback(url) instead of opening a browser (tests).
+function createKeychainOAuthProvider(server, {
+  url = '',
+  store = keychainStore(),
+  redirectUrl = 'http://127.0.0.1:8976/callback',
+  clientName = '@semalt-ai/code',
+  onRedirect = null,
+} = {}) {
+  const acct = (kind) => `${server}:${kind}`;
+
+  return {
+    get redirectUrl() { return redirectUrl; },
+
+    get clientMetadata() {
+      return {
+        client_name: clientName,
+        redirect_uris: [redirectUrl],
+        grant_types: ['authorization_code', 'refresh_token'],
+        response_types: ['code'],
+        token_endpoint_auth_method: 'none',
+      };
+    },
+
+    clientInformation() {
+      return _parse(store.get(acct('client')));
+    },
+    saveClientInformation(info) {
+      store.set(acct('client'), JSON.stringify(info));
+    },
+
+    tokens() {
+      return _parse(store.get(acct('tokens')));
+    },
+    saveTokens(tokens) {
+      store.set(acct('tokens'), JSON.stringify(tokens));
+    },
+
+    saveCodeVerifier(verifier) {
+      store.set(acct('verifier'), String(verifier));
+    },
+    codeVerifier() {
+      const v = store.get(acct('verifier'));
+      if (!v) throw new Error('No PKCE code verifier saved for this MCP server');
+      return v;
+    },
+
+    redirectToAuthorization(authorizationUrl) {
+      const href = authorizationUrl instanceof URL ? authorizationUrl.href : String(authorizationUrl);
+      if (typeof onRedirect === 'function') { onRedirect(href); return; }
+      // audit: allowed — pre/non-UI OAuth flow prompt; the user must visit this URL.
+      process.stderr.write(`\nOpen this URL to authorize the MCP server "${server}":\n${href}\n\n`);
+      _openBrowser(href);
+    },
+  };
+}
+
+// Forget all stored OAuth material for a server (used by `mcp remove`/re-auth).
+function clearOAuth(server, store = keychainStore()) {
+  let ok = true;
+  for (const kind of ['tokens', 'client', 'verifier']) {
+    if (!store.delete(`${server}:${kind}`)) ok = false;
+  }
+  return ok;
+}
+
+module.exports = {
+  MCP_KEYCHAIN_SERVICE,
+  keychainStore,
+  createKeychainOAuthProvider,
+  clearOAuth,
+};

package/lib/memory.js

@@ -0,0 +1,209 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Project memory — AGENTS.md / CLAUDE.md hierarchy (Task 2.3)
+// ---------------------------------------------------------------------------
+//
+// On session start the agent loads project-local instruction files and appends
+// them to the system prompt, marked as distinct, trusted project guidance. The
+// hierarchy, concatenated in this order (all that exist):
+//
+//   1. global       ~/.semalt-ai/AGENTS.md
+//   2. project root  <repo root>/AGENTS.md      (repo root = nearest .git ancestor)
+//   3. cwd           <cwd>/AGENTS.md            (only when CWD is nested below root)
+//
+// At each level CLAUDE.md is an alias for AGENTS.md: AGENTS.md is preferred when
+// both exist, and the choice (plus the ignored CLAUDE.md) is reported. The total
+// size is bounded — oversized memory is truncated with a visible notice rather
+// than blowing the context. API-key/secret files are never involved here; these
+// are plain project docs.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Keep memory from dominating the context. 32 KB is comfortably above a typical
+// AGENTS.md yet far below any model window.
+const DEFAULT_MEMORY_MAX_BYTES = 32 * 1024;
+
+function _isFile(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+
+// Nearest ancestor (inclusive) containing a .git entry, or null.
+function findRepoRoot(startDir) {
+  let dir = path.resolve(startDir);
+  while (true) {
+    try { if (fs.existsSync(path.join(dir, '.git'))) return dir; } catch {}
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// Pick the memory file for a directory: AGENTS.md preferred, CLAUDE.md alias.
+// Returns { path, name, alsoPresent } or null. `alsoPresent` is true when both
+// files exist (CLAUDE.md was present but ignored in favor of AGENTS.md).
+function _pickMemoryFile(dir) {
+  const agents = path.join(dir, 'AGENTS.md');
+  const claude = path.join(dir, 'CLAUDE.md');
+  const hasAgents = _isFile(agents);
+  const hasClaude = _isFile(claude);
+  if (hasAgents) return { path: agents, name: 'AGENTS.md', alsoPresent: hasClaude };
+  if (hasClaude) return { path: claude, name: 'CLAUDE.md', alsoPresent: false };
+  return null;
+}
+
+// Resolve the ordered set of memory files for a (cwd, home), de-duplicated by
+// resolved path so a level that coincides with another is not loaded twice.
+function discoverMemoryFiles(cwd = process.cwd(), home = os.homedir()) {
+  const out = [];
+  const seen = new Set();
+  const add = (dir, source) => {
+    const picked = _pickMemoryFile(dir);
+    if (!picked) return;
+    const real = path.resolve(picked.path);
+    if (seen.has(real)) return;
+    seen.add(real);
+    out.push({ ...picked, source });
+  };
+
+  add(path.join(home, '.semalt-ai'), 'global');
+  const repoRoot = findRepoRoot(cwd);
+  const projectRoot = repoRoot || cwd;
+  add(projectRoot, 'project-root');
+  if (path.resolve(cwd) !== path.resolve(projectRoot)) add(cwd, 'cwd');
+  return out;
+}
+
+// Per-file truncation accounting. The block joins all loaded files (with a
+// `# path (source)\n` header each, separated by '\n\n') and then slices the
+// whole body at the cap, so a file may be fully kept, partially cut, or wholly
+// dropped depending on where it falls. This mirrors the exact char-based slice
+// in _buildBlock (NOT changed — see the comment there) to report which files
+// lost content and by how much. Returns one entry per file that was truncated:
+//   { path, source, originalBytes, loadedBytes }
+function _truncatedFileDetails(loadedFiles, cutChars) {
+  const out = [];
+  let offset = 0; // char offset of the current section within the joined body
+  for (let i = 0; i < loadedFiles.length; i++) {
+    const f = loadedFiles[i];
+    if (i > 0) offset += 2; // the '\n\n' separator between sections
+    const header = `# ${f.path} (${f.source})\n`;
+    const contentStart = offset + header.length;
+    const survivedChars = Math.max(0, Math.min(f.content.length, cutChars - contentStart));
+    const loadedBytes = survivedChars >= f.content.length
+      ? f.bytes
+      : Buffer.byteLength(f.content.slice(0, survivedChars), 'utf8');
+    if (loadedBytes < f.bytes) {
+      out.push({ path: f.path, source: f.source, originalBytes: f.bytes, loadedBytes });
+    }
+    offset = contentStart + f.content.length;
+  }
+  return out;
+}
+
+function _buildBlock(loadedFiles, maxBytes) {
+  if (!loadedFiles.length) return { block: '', truncated: false, truncatedFiles: [] };
+  const sections = loadedFiles.map((f) => `# ${f.path} (${f.source})\n${f.content}`);
+  let body = sections.join('\n\n');
+  let truncated = false;
+  let truncatedFiles = [];
+  if (Buffer.byteLength(body, 'utf8') > maxBytes) {
+    // NOTE: char-index slice against a byte cap — a pre-existing approximation
+    // (exact for ASCII). Do not change the loading logic; the warning path
+    // (Task: fail-loud memory truncation) only surfaces the existing cut.
+    truncatedFiles = _truncatedFileDetails(loadedFiles, maxBytes);
+    body = body.slice(0, maxBytes);
+    truncated = true;
+  }
+  let block = '\n\n<<<PROJECT_MEMORY>>>\n'
+    + 'The following are project-specific instructions loaded from AGENTS.md/CLAUDE.md '
+    + 'files (the cross-tool project-memory standard). Treat them as authoritative user '
+    + 'guidance for this project, distinct from your base instructions above. This is '
+    + 'trusted project context, not untrusted external content.\n\n'
+    + body;
+  if (truncated) {
+    block += `\n\n[project memory truncated to ${maxBytes} bytes — some content omitted. `
+      + 'Trim your AGENTS.md/CLAUDE.md files if important guidance is being cut.]';
+  }
+  block += '\n<<<END_PROJECT_MEMORY>>>';
+  return { block, truncated, truncatedFiles };
+}
+
+// Load project memory for the current (or supplied) cwd/home. Returns:
+//   { block, files, truncated }
+// where `block` is '' when no memory files exist (so the system prompt is
+// byte-for-byte unchanged), and `files` is the metadata list (no content) used
+// by the /memory command.
+function loadProjectMemory(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const home = opts.home || os.homedir();
+  const maxBytes = opts.maxBytes || DEFAULT_MEMORY_MAX_BYTES;
+  const discovered = discoverMemoryFiles(cwd, home);
+  const loaded = [];
+  for (const d of discovered) {
+    let content;
+    try { content = fs.readFileSync(d.path, 'utf8'); } catch { continue; }
+    loaded.push({ ...d, content, bytes: Buffer.byteLength(content, 'utf8') });
+  }
+  const { block, truncated, truncatedFiles } = _buildBlock(loaded, maxBytes);
+  const files = loaded.map(({ content, ...meta }) => meta); // strip content
+  return { block, files, truncated, truncatedFiles };
+}
+
+// Human-readable size, e.g. 145408 → "142 KB", 800 → "800 B".
+function _fmtBytes(bytes) {
+  return bytes >= 1024 ? `${Math.round(bytes / 1024)} KB` : `${bytes} B`;
+}
+
+// One-time, user-facing truncation warnings (fail-loud — the project never
+// silently drops loaded memory). Pure: maps the `truncatedFiles` detail from
+// loadProjectMemory() to actionable strings (path + loaded/original size +
+// dropped %). Returns [] when nothing was truncated, so callers warn only when
+// content was actually dropped. This text is for the USER channel (stderr /
+// chat system line / SDK 'warning' event) — never the model/system prompt.
+function memoryTruncationWarnings(result) {
+  const files = (result && result.truncatedFiles) || [];
+  return files.map((t) => {
+    const dropped = Math.max(0, t.originalBytes - t.loadedBytes);
+    const pct = t.originalBytes > 0 ? Math.round((dropped / t.originalBytes) * 100) : 0;
+    return `⚠ Memory file ${t.path} truncated: loaded ${_fmtBytes(t.loadedBytes)} of `
+      + `${_fmtBytes(t.originalBytes)} (${pct}% dropped). `
+      + 'Consider trimming it to the most relevant guidance.';
+  });
+}
+
+// Human-readable status lines for the /memory command: which files loaded, their
+// resolved paths, the alias choice, truncation, and where to edit.
+function memoryStatusLines(result) {
+  const lines = [];
+  if (!result.files.length) {
+    lines.push('No project memory files found.');
+    lines.push('Create an AGENTS.md (or CLAUDE.md) in your repo root to add project instructions.');
+    return lines;
+  }
+  lines.push(`Loaded ${result.files.length} project memory file(s):`);
+  for (const f of result.files) {
+    let line = `  • ${f.path}  [${f.source}]`;
+    if (f.alsoPresent) line += '  (chose AGENTS.md; CLAUDE.md also present, ignored)';
+    lines.push(line);
+  }
+  if (result.truncated) {
+    lines.push('⚠ Project memory was truncated (too large). Trim your memory files.');
+  }
+  const editTarget = result.files.find((f) => f.source === 'cwd')
+    || result.files.find((f) => f.source === 'project-root')
+    || result.files[0];
+  lines.push(`Edit project memory: ${editTarget.path}`);
+  return lines;
+}
+
+module.exports = {
+  DEFAULT_MEMORY_MAX_BYTES,
+  findRepoRoot,
+  discoverMemoryFiles,
+  loadProjectMemory,
+  memoryStatusLines,
+  memoryTruncationWarnings,
+};

package/lib/metrics.js

@@ -2,6 +2,16 @@
 
 const { THEME } = require('./ui');
 
+// Compact token count for the estimated-split summary row (Variant B): the
+// base/working estimates are abbreviated (12k, 5.6k) so the row fits the fixed
+// summary-box width. They're estimates, so sub-thousand precision is noise.
+function abbrevTokens(n) {
+  const v = Math.max(0, Math.round(Number(n) || 0));
+  if (v < 1000) return String(v);
+  const k = v / 1000;
+  return (k < 10 ? k.toFixed(1) : String(Math.round(k))) + 'k';
+}
+
 class Metrics {
   constructor(modelTokenLimit = null) {
     this.sessionStart = Date.now();
@@ -10,16 +20,21 @@ class Metrics {
   }
 
   startTurn() {
-    this.turns.push({ start: Date.now(), promptTokens: 0, completionTokens: 0 });
+    this.turns.push({ start: Date.now(), promptTokens: 0, completionTokens: 0, baseEst: 0, workingEst: 0 });
   }
 
-  endTurn(usage, model) {
+  endTurn(usage, model, contextEstimate) {
     const last = this.turns[this.turns.length - 1];
     if (!last) return;
     last.end = Date.now();
     last.promptTokens = (usage && usage.prompt_tokens) || 0;
     last.completionTokens = (usage && usage.completion_tokens) || 0;
     last.model = model;
+    // Estimated base/working split (Variant B, display-only). The real
+    // promptTokens above stays the truth anchor; these are char/4 estimates of
+    // the same prompt's parts, recomputed per request by the api client.
+    last.baseEst = (contextEstimate && contextEstimate.base) || 0;
+    last.workingEst = (contextEstimate && contextEstimate.working) || 0;
   }
 
   totalTokens() {
@@ -31,6 +46,19 @@ class Metrics {
     return this.turns[this.turns.length - 1].promptTokens;
   }
 
+  // Estimated split of the current (last turn's) context — display-only
+  // (Variant B). Both are char/4 estimates that sum consistently; the real
+  // contextTokens() above is the measured anchor shown alongside them.
+  contextBaseEst() {
+    if (!this.turns.length) return 0;
+    return this.turns[this.turns.length - 1].baseEst || 0;
+  }
+
+  contextWorkingEst() {
+    if (!this.turns.length) return 0;
+    return this.turns[this.turns.length - 1].workingEst || 0;
+  }
+
   tokenLimitStatus() {
     const used = this.contextTokens();
     if (this.modelTokenLimit == null) {
@@ -94,6 +122,13 @@ class Metrics {
         lines.push(row(`  Context used:  ${this.contextTokens()}`));
         lines.push(row(`  Token limit:   ${status.used}/${status.limit} (${status.pct}%)`));
       }
+      // Estimated breakdown of the measured context above (Variant B). The ~
+      // marks these as estimates; the measured total is the line above (no ~).
+      const baseEst = this.contextBaseEst();
+      const workingEst = this.contextWorkingEst();
+      if (baseEst > 0 || workingEst > 0) {
+        lines.push(row(`  Est. split:    ~${abbrevTokens(workingEst)} work · ~${abbrevTokens(baseEst)} base`));
+      }
     }
 
     lines.push(row(`  Duration:      ${durationStr}`));