@hncode/hncode 0.4.2 → 0.5.1

package/src/lsp.js

@@ -0,0 +1,401 @@
+// LSP client: real diagnostics and symbol lookup from a language server.
+//
+// WHY THIS IS NOT AN MCP SERVER
+// ----------------------------
+// `src/mcp.js` already speaks JSON-RPC, and the temptation is to reuse it. But MCP frames
+// messages as NEWLINE-DELIMITED JSON while LSP frames them with a `Content-Length` header —
+// mcp.js says so itself ("MCP's stdio transport is line-delimited (NOT Content-Length
+// framed — that is the LSP convention, and mixing them up is the usual way this breaks)").
+// Sharing the transport would mean one of the two protocols being wrong. So the framing is
+// implemented here, and only the framing: everything above it is plain JSON-RPC.
+//
+// WHAT IT IS FOR
+// --------------
+// A model editing code benefits from the same thing a human does: being told that the line
+// it just wrote does not compile. This gives the agent that, without a build step and
+// without guessing — the compiler's own answer, over the protocol its own tooling speaks.
+//
+// NO SERVER IS NOT AN ERROR
+// -------------------------
+// Most machines have no language server installed. That is the normal case, not a broken
+// one: `findServer` returns null, callers report "no server for this file", and everything
+// else in hncode works exactly as before. A missing server must never make a turn fail.
+
+import cp from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+
+/** A server definition: how to start it and which files it handles. */
+export const SERVERS = [
+  {
+    id: 'rust-analyzer',
+    command: 'rust-analyzer',
+    extensions: ['.rs'],
+    // rust-analyzer only speaks stdio when told to; it otherwise looks for a socket.
+    args: [],
+  },
+  {
+    id: 'typescript',
+    command: 'typescript-language-server',
+    args: ['--stdio'],
+    extensions: ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'],
+  },
+  {
+    id: 'pyright',
+    command: 'pyright-langserver',
+    args: ['--stdio'],
+    extensions: ['.py', '.pyi'],
+  },
+  {
+    id: 'gopls',
+    command: 'gopls',
+    extensions: ['.go'],
+  },
+  {
+    id: 'clangd',
+    command: 'clangd',
+    extensions: ['.c', '.h', '.cc', '.cpp', '.hpp', '.cxx'],
+  },
+];
+
+/** Is `command` runnable? Checked without spawning, so a probe costs nothing. */
+export function commandExists(command) {
+  const dirs = String(process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  const exts = process.platform === 'win32'
+    ? String(process.env.PATHEXT || '.EXE;.CMD;.BAT').split(';').filter(Boolean)
+    : [''];
+  for (const d of dirs) {
+    for (const ext of exts) {
+      try {
+        const p = path.join(d, command + ext);
+        fs.accessSync(p, fs.constants.X_OK);
+        return p;
+      } catch { /* keep looking */ }
+    }
+  }
+  return null;
+}
+
+/**
+ * The server that handles a file, or null.
+ *
+ * @param {string} file
+ * @returns {{id:string, command:string, args:string[], bin:string}|null}
+ */
+export function findServer(file) {
+  const ext = path.extname(String(file || '')).toLowerCase();
+  if (!ext) return null;
+  for (const s of SERVERS) {
+    if (!s.extensions.includes(ext)) continue;
+    const bin = commandExists(s.command);
+    if (bin) return { ...s, bin };
+  }
+  return null;
+}
+
+/** Every server that is actually installed here, for /doctor and the tool's error text. */
+export function availableServers() {
+  return SERVERS.map((s) => ({ id: s.id, command: s.command, bin: commandExists(s.command) }))
+    .filter((s) => s.bin)
+    .map((s) => ({ id: s.id, command: s.command, bin: s.bin }));
+}
+
+// ---- framing ---------------------------------------------------------------
+
+/**
+ * Encode one JSON-RPC message with an LSP `Content-Length` header.
+ *
+ * The length is BYTES, not characters. A message containing a non-ASCII identifier —
+ * a Rust symbol with a Greek letter, a comment in Chinese — would be cut short by a
+ * character count, and the server would then desynchronise on the next frame, which shows
+ * up as every subsequent request hanging.
+ */
+export function encodeMessage(obj) {
+  const json = JSON.stringify(obj);
+  const len = Buffer.byteLength(json, 'utf8');
+  return Buffer.concat([
+    Buffer.from(`Content-Length: ${len}\r\n\r\n`, 'ascii'),
+    Buffer.from(json, 'utf8'),
+  ]);
+}
+
+/**
+ * A streaming decoder for `Content-Length` frames.
+ *
+ * Chunk boundaries are arbitrary, so a frame can arrive split or several at once. State is
+ * kept between calls; `push` returns whatever complete messages are available NOW.
+ */
+export function createDecoder() {
+  let buf = Buffer.alloc(0);
+  return {
+    push(chunk) {
+      buf = buf.length ? Buffer.concat([buf, chunk]) : chunk;
+      const out = [];
+      for (;;) {
+        const sep = buf.indexOf('\r\n\r\n');
+        if (sep < 0) break;
+        const header = buf.slice(0, sep).toString('ascii');
+        const m = /Content-Length:\s*(\d+)/i.exec(header);
+        if (!m) {
+          // An unparseable header means the stream is lost: drop what we have rather than
+          // spinning on it forever.
+          buf = buf.slice(sep + 4);
+          continue;
+        }
+        const len = Number(m[1]);
+        const start = sep + 4;
+        if (buf.length < start + len) break;      // the rest has not arrived yet
+        const body = buf.slice(start, start + len).toString('utf8');
+        // Advance past the EXACT byte length, which is why the header was byte-counted.
+        buf = buf.slice(start + len);
+        try { out.push(JSON.parse(body)); } catch { /* a malformed frame is skipped */ }
+      }
+      return out;
+    },
+    /** Bytes held back waiting for the rest of a frame. */
+    get pending() { return buf.length; },
+  };
+}
+
+// ---- the client ------------------------------------------------------------
+
+/** How long to wait for a server to answer before giving up. A language server that has
+ *  not indexed a project will not answer at all, and a hung request is worse than an
+ *  honest "no answer". */
+const DEFAULT_TIMEOUT_MS = 20_000;
+/** How long to let the server finish its handshake and initial analysis. */
+const INIT_TIMEOUT_MS = 30_000;
+
+/**
+ * Start a server and complete the LSP handshake.
+ *
+ * @returns {Promise<{ok:true, client:object} | {ok:false, error:string}>}
+ */
+export async function startClient(server, root, opts = {}) {
+  const log = opts.log || (() => {});
+  let child;
+  try {
+    child = cp.spawn(server.bin, server.args || [], {
+      cwd: root,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      // A shell is NOT used: the argv is already resolved, and a shell would let a path
+      // with a space in it split into two arguments.
+      shell: false,
+    });
+  } catch (e) {
+    return { ok: false, error: `could not start ${server.command}: ${e.message}` };
+  }
+
+  const decoder = createDecoder();
+  const pending = new Map();
+  let nextId = 1;
+  let dead = null;
+  let stderrTail = '';
+  const notifications = [];
+
+  child.stdout.on('data', (chunk) => {
+    for (const msg of decoder.push(chunk)) {
+      if (msg.id != null && (msg.result !== undefined || msg.error !== undefined)) {
+        const waiter = pending.get(msg.id);
+        if (waiter) { pending.delete(msg.id); waiter(msg); }
+      } else if (msg.method) {
+        // Server-initiated notifications and requests (publishDiagnostics, and the
+        // registerCapability requests a server sends during init). Requests are answered
+        // with a null result so the server does not block waiting on us.
+        notifications.push(msg);
+        if (msg.id != null) {
+          try { child.stdin.write(encodeMessage({ jsonrpc: '2.0', id: msg.id, result: null })); }
+          catch { /* the pipe is already gone */ }
+        }
+      }
+    }
+  });
+  child.stderr.on('data', (d) => {
+    // Keep only the tail: rust-analyzer is chatty and the useful error is the last line.
+    stderrTail = (stderrTail + d.toString()).slice(-2000);
+  });
+  const onExit = (code, signal) => {
+    dead = `the language server exited (${signal || code})${stderrTail ? `: ${stderrTail.trim().split('\n').slice(-1)[0]}` : ''}`;
+    for (const [, waiter] of pending) waiter({ error: { message: dead } });
+    pending.clear();
+  };
+  child.on('exit', onExit);
+  child.on('error', (e) => { dead = `the language server failed: ${e.message}`; });
+
+  function send(msg) {
+    if (dead) return Promise.reject(new Error(dead));
+    try { child.stdin.write(encodeMessage(msg)); }
+    catch (e) { return Promise.reject(e); }
+    return null;
+  }
+
+  function request(method, params, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    if (dead) return Promise.reject(new Error(dead));
+    const id = nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        reject(new Error(`${method} timed out after ${Math.round(timeoutMs / 1000)}s`));
+      }, timeoutMs);
+      pending.set(id, (msg) => {
+        clearTimeout(timer);
+        if (msg.error) reject(new Error(msg.error.message || JSON.stringify(msg.error)));
+        else resolve(msg.result);
+      });
+      try { child.stdin.write(encodeMessage({ jsonrpc: '2.0', id, method, params })); }
+      catch (e) { clearTimeout(timer); pending.delete(id); reject(e); }
+    });
+  }
+
+  function notify(method, params) {
+    try { child.stdin.write(encodeMessage({ jsonrpc: '2.0', method, params })); }
+    catch { /* a dead pipe: the exit handler has already recorded why */ }
+  }
+
+  const rootUri = pathToFileURL(path.resolve(root)).href;
+  const capabilities = {
+    textDocument: {
+      synchronization: { dynamicRegistration: false, didSave: true },
+      publishDiagnostics: { relatedInformation: true },
+      hover: { contentFormat: ['plaintext', 'markdown'] },
+      definition: { linkSupport: false },
+      documentSymbol: { hierarchicalDocumentSymbolSupport: true },
+    },
+    workspace: { workspaceFolders: true, configuration: true },
+  };
+
+  try {
+    await request('initialize', {
+      processId: process.pid,
+      rootUri,
+      rootPath: path.resolve(root),
+      workspaceFolders: [{ uri: rootUri, name: path.basename(path.resolve(root)) }],
+      capabilities,
+      initializationOptions: opts.initializationOptions || {},
+    }, INIT_TIMEOUT_MS);
+  } catch (e) {
+    try { child.kill(); } catch { /* already gone */ }
+    return { ok: false, error: `initialize failed: ${e.message}` };
+  }
+  notify('initialized', {});
+
+  return {
+    ok: true,
+    client: {
+      root,
+      serverId: server.id,
+      request,
+      notify,
+      notifications,
+      stderrTail: () => stderrTail,
+      dead: () => dead,
+      async stop() {
+        try { await request('shutdown', null, 3000); } catch { /* shutting down anyway */ }
+        notify('exit', null);
+        setTimeout(() => { try { child.kill(); } catch { /* gone */ } }, 250);
+      },
+      _child: child,
+      _raw: { log },
+    },
+  };
+}
+
+/** Turn a file path into the `file://` URI LSP expects. */
+export function fileUri(file) {
+  return pathToFileURL(path.resolve(file)).href;
+}
+
+/** And back, for the locations a server reports. */
+export function uriToPath(uri) {
+  try { return fileURLToPath(uri); } catch { return String(uri); }
+}
+
+/**
+ * Open a document. LSP has no "read this file" request — a server only knows about
+ * documents the client has TOLD it about, so `didOpen` is mandatory before any query
+ * about a file will answer.
+ */
+export function openDocument(client, file, text, languageId) {
+  client.notify('textDocument/didOpen', {
+    textDocument: {
+      uri: fileUri(file),
+      languageId: languageId || languageFor(file),
+      version: 1,
+      text,
+    },
+  });
+}
+
+/** Re-send a document's content after it changed on disk. */
+export function changeDocument(client, file, text, version) {
+  client.notify('textDocument/didChange', {
+    textDocument: { uri: fileUri(file), version: version || 2 },
+    contentChanges: [{ text }],
+  });
+}
+
+/** The LSP `languageId` for a file, which servers key their behaviour on. */
+export function languageFor(file) {
+  const ext = path.extname(String(file || '')).toLowerCase();
+  return {
+    '.rs': 'rust',
+    '.ts': 'typescript', '.tsx': 'typescriptreact',
+    '.js': 'javascript', '.jsx': 'javascriptreact', '.mjs': 'javascript', '.cjs': 'javascript',
+    '.py': 'python', '.pyi': 'python',
+    '.go': 'go',
+    '.c': 'c', '.h': 'c',
+    '.cc': 'cpp', '.cpp': 'cpp', '.cxx': 'cpp', '.hpp': 'cpp',
+  }[ext] || 'plaintext';
+}
+
+/**
+ * Diagnostics for one file, from the notifications the server has sent.
+ *
+ * LSP has no "give me diagnostics" request: the server PUSHES them as `publishDiagnostics`
+ * when it has computed them, which for a cold server is after it has indexed the project.
+ * So this waits for the notification for this file, up to `waitMs`. Returning `[]` on a
+ * timeout would claim the file is clean when the truth is "not known yet", so the caller
+ * gets `settled` and can say which it was.
+ *
+ * @returns {Promise<{diagnostics: Array, settled: boolean}>}
+ */
+export async function waitForDiagnostics(client, file, waitMs = 15_000) {
+  const want = fileUri(file);
+  const latest = () => {
+    for (let i = client.notifications.length - 1; i >= 0; i--) {
+      const n = client.notifications[i];
+      if (n.method === 'textDocument/publishDiagnostics' && n.params && n.params.uri === want) {
+        return n.params.diagnostics || [];
+      }
+    }
+    return null;
+  };
+  const now = latest();
+  if (now) return { diagnostics: now, settled: true };
+
+  const deadline = Date.now() + waitMs;
+  while (Date.now() < deadline) {
+    if (client.dead()) return { diagnostics: [], settled: false };
+    await new Promise((r) => setTimeout(r, 100));
+    const got = latest();
+    if (got) return { diagnostics: got, settled: true };
+  }
+  // An empty list IS a valid answer (a clean file), so the caller must be able to tell
+  // "no problems" from "no answer", which is what `settled` is for.
+  return { diagnostics: [], settled: false };
+}
+
+/** Severity numbers LSP uses, in words. */
+export const SEVERITY_NAMES = ['', 'error', 'warning', 'information', 'hint'];
+
+/** One diagnostic as a readable line: `error 12:5  cannot find value \`x\``. */
+export function formatDiagnostic(d, root) {
+  const sev = SEVERITY_NAMES[d.severity || 1] || 'info';
+  const line = (d.range && d.range.start ? d.range.start.line : 0) + 1;
+  const col = (d.range && d.range.start ? d.range.start.character : 0) + 1;
+  const where = root ? path.relative(root, d._file || '').split(path.sep).join('/') : (d._file || '');
+  const src = d.source ? ` [${d.source}]` : '';
+  const msg = String(d.message || '').replace(/\s+/g, ' ').trim();
+  return `${sev.padEnd(7)} ${where}${where ? ':' : ''}${line}:${col}${src}  ${msg}`;
+}

package/src/memory-profile.js

@@ -0,0 +1,247 @@
+// Session memory profiler — where the bytes actually go.
+//
+// WHY THIS EXISTS
+// ---------------
+// Two questions came up that nothing here could answer: "why is the process using so much
+// memory", and "did the transcript-amplification fix actually save anything". Both are
+// unanswerable without knowing WHICH content is large, because "the session" is not one
+// thing — the same conversation exists in several forms at once:
+//
+//   * `session.messages`   what gets sent to the model (text + tool args + tool results)
+//   * `state.chat`         what the renderer draws (a DIFFERENT array of rows)
+//   * `session.transcript` the display-only record that is written to disk
+//
+// and within `messages` the bytes are not where a count of rows suggests. Measured on a
+// real 2.6 MB session: text was 0.28 MB, tool RESULTS 0.34 MB, and tool-call ARGUMENTS
+// 0.66 MB — the arguments, which no row count hints at, were more than everything else
+// combined. On that same session the serialised JSON was 2.29 MB while the sum of its
+// parts was 1.27 MB, so roughly as much again is STRUCTURE: keys, role tags, escaped
+// strings.
+//
+// Modelled on jcode's `jcode-base/src/session/memory_profile.rs`, which records the same
+// split plus the extremes (largest single block), because a profile without a maximum
+// hides the one item that actually caused the problem.
+//
+// Pure and read-only: it measures, it never trims, loads or rewrites anything.
+
+/** Content larger than this is counted separately — a single 16 KB block is the shape of
+ *  a runaway, while 16 KB spread evenly is nothing. */
+const LARGE_BLOB_BYTES = 16 * 1024;
+
+/** Byte size of a value as it would sit in memory: strings as-is, everything else as JSON. */
+function bytes(v) {
+  if (v == null) return 0;
+  if (typeof v === 'string') return Buffer.byteLength(v, 'utf8');
+  if (typeof v === 'number' || typeof v === 'boolean') return 8;
+  try { return Buffer.byteLength(JSON.stringify(v), 'utf8'); } catch { return 0; }
+}
+
+/** One accumulating bucket. Every measurement lands in exactly one category. */
+function bucket() {
+  return { bytes: 0, count: 0, max: 0 };
+}
+
+function add(b, n) {
+  b.bytes += n;
+  b.count += 1;
+  if (n > b.max) b.max = n;
+}
+
+const mb = (n) => (n / 1048576).toFixed(2);
+
+/**
+ * Profile the memory a session occupies, broken down by content type.
+ *
+ * @param {object} input
+ * @param {object} [input.session]   a loaded session ({ messages, transcript })
+ * @param {Array}  [input.chat]      `state.chat` — the renderer's rows, if present
+ * @param {object} [input.state]     the live TUI state, to measure chat and caches
+ * @returns {object} a plain report; see `renderMemoryProfile` for the human form
+ */
+export function profileMemory(input = {}) {
+  const session = input.session || {};
+  const messages = Array.isArray(session.messages) ? session.messages : [];
+  const transcript = Array.isArray(session.transcript) ? session.transcript : [];
+
+  // ---- session.messages, split by what the bytes are --------------------
+  const text = bucket();
+  const toolResults = bucket();
+  const toolArgs = bucket();
+  const images = bucket();
+  const argsByTool = new Map();
+
+  for (const m of messages) {
+    if (!m || typeof m !== 'object') continue;
+    const isResult = m.role === 'tool';
+    add(isResult ? toolResults : text, bytes(m.content));
+    // An image rides as a data: URL or a base64 field rather than in `content`, so it is
+    // measured separately — base64 inflates 4/3, and that is worth knowing.
+    const img = m.image || m.images || m.media;
+    if (img) add(images, bytes(img));
+    for (const tc of Array.isArray(m.toolCalls) ? m.toolCalls : []) {
+      if (!tc || typeof tc !== 'object') continue;
+      const n = bytes(tc.args);
+      add(toolArgs, n);
+      const name = String(tc.name || '?');
+      if (!argsByTool.has(name)) argsByTool.set(name, bucket());
+      add(argsByTool.get(name), n);
+    }
+  }
+
+  // ---- session.transcript, which is display-only and can dwarf everything
+  const transcriptByRole = new Map();
+  let transcriptBytes = 0;
+  let transcriptLarge = 0;
+  let transcriptMax = 0;
+  for (const e of transcript) {
+    const row = e && e.row;
+    if (!row) continue;
+    const n = bytes(row.text);
+    transcriptBytes += n;
+    if (n > transcriptMax) transcriptMax = n;
+    if (n >= LARGE_BLOB_BYTES) transcriptLarge += n;
+    const role = String(row.role || '?');
+    if (!transcriptByRole.has(role)) transcriptByRole.set(role, bucket());
+    add(transcriptByRole.get(role), n);
+  }
+
+  // ---- the renderer's copy ----------------------------------------------
+  // Derived from `messages` when the caller does not supply the live `state.chat`, so a
+  // profile of a session loaded off disk still accounts for what the renderer would build.
+  // `convRowFor` maps ONE message to rows, so it has to be applied per message — handing it
+  // the array returns a single empty row and the copy silently measured as zero, which is
+  // exactly what the first run of this printed.
+  let chat = Array.isArray(input.chat) ? input.chat : null;
+  if (!chat && input.state && Array.isArray(input.state.chat)) chat = input.state.chat;
+  if (!chat && messages.length && typeof input.convRowFor === 'function') {
+    chat = [];
+    for (const m of messages) {
+      const rows = input.convRowFor(m);
+      if (Array.isArray(rows)) chat.push(...rows);
+    }
+  }
+  chat = chat || [];
+  const chatBytes = chat.reduce((a, r) => a + bytes(r && r.text), 0);
+
+  // ---- what it costs as one JSON document -------------------------------
+  // Reported because it is usually the biggest single number and nobody expects it: the
+  // serialised form carries every key and escape, which no content sum shows.
+  let jsonBytes = 0;
+  try { jsonBytes = Buffer.byteLength(JSON.stringify({ messages, transcript }), 'utf8'); } catch { /* */ }
+
+  const contentBytes = text.bytes + toolResults.bytes + toolArgs.bytes + images.bytes;
+  const measured = contentBytes + transcriptBytes;
+
+  return {
+    messages: {
+      count: messages.length,
+      text,
+      toolResults,
+      toolArgs,
+      images,
+      argsByTool,
+      contentBytes,
+      // The gap between the parts and the document: keys, role tags, escapes, and the
+    // array/record overhead of 3000 messages each carrying a role and a shape.
+    structuralBytes: Math.max(0, jsonBytes - measured),
+    jsonBytes,
+  },
+    transcript: {
+      count: transcript.length,
+      bytes: transcriptBytes,
+      largeBytes: transcriptLarge,
+      maxRowBytes: transcriptMax,
+      byRole: transcriptByRole,
+    },
+    chat: { count: chat.length, bytes: chatBytes },
+    // The three forms coexist, so the process holds roughly all of them at once.
+    totalBytes: measured + chatBytes,
+    totals: { messages: contentBytes, transcript: transcriptBytes, chat: chatBytes },
+  };
+}
+
+/**
+ * The profile as lines for a panel or a tool result.
+ *
+ * @param {object} p      from profileMemory
+ * @param {object} [opts]
+ * @param {number} [opts.top]  how many rows of the per-tool table to show
+ * @param {boolean} [opts.verbose]  include the per-tool breakdown
+ */
+export function renderMemoryProfile(p, opts = {}) {
+  const lines = [];
+  const total = p.totalBytes || 0;
+  // The document size is reported in the same table, so it must NOT join the percentage
+  // base — it is a different measure of the same data (serialised vs in-memory), and
+  // including it produced totals over 100%.
+  const contentBase = (p.messages.contentBytes || 0) + (p.transcript.bytes || 0) + (p.chat.bytes || 0);
+  // Rounding to 2 places on a few HUNDRED bytes made "5 bytes / 5 bytes" print as
+  // 100.0% but a document row print 1280.0% — a percentage over 100 is never a real
+  // share, so it is clamped rather than trusted.
+  const pct = (n) => {
+    if (!contentBase || !n) return '';
+    const v = Math.min(100, (100 * n) / contentBase);
+    return ` ${v.toFixed(1)}%`.padStart(7);
+  };
+  const row = (label, b, n, share = true) => {
+    lines.push(`  ${label.padEnd(18)} ${mb(b).padStart(9)} MB${n != null ? `  x${n}` : ''}${share ? pct(b) : ''}`);
+  };
+
+  lines.push(`Memory profile — ${mb(total)} MB across the forms a session holds`);
+  lines.push('');
+  lines.push('  content (session.messages)');
+  row('text', p.messages.text.bytes, p.messages.text.count);
+  row('tool results', p.messages.toolResults.bytes, p.messages.toolResults.count);
+  row('tool arguments', p.messages.toolArgs.bytes, p.messages.toolArgs.count);
+  if (p.messages.images.bytes) row('images', p.messages.images.bytes, p.messages.images.count);
+
+  if (p.transcript.count) {
+    lines.push('');
+    lines.push('  transcript (display-only, on disk)');
+    row('all rows', p.transcript.bytes, p.transcript.count);
+    if (p.transcript.largeBytes) {
+      lines.push(`    of which >=16 KB:  ${mb(p.transcript.largeBytes).padStart(9)} MB`);
+    }
+    lines.push(`    largest row:     ${mb(p.transcript.maxRowBytes).padStart(9)} MB`);
+    if (opts.verbose) {
+      for (const [role, b] of [...p.transcript.byRole].sort((a, c) => c[1].bytes - a[1].bytes)) {
+        row(`    ${role}`, b.bytes, b.count);
+      }
+    }
+  }
+
+  lines.push('');
+  lines.push('  other copies held at the same time');
+  row('state.chat (render)', p.chat.bytes, p.chat.count);
+
+  lines.push('');
+  lines.push('  as one JSON document (a different measure of the same data)');
+  // Measured against the CONTENT, not the content-plus-content the base holds, so these
+  // two rows carry no share: they re-measure what the rows above already report.
+  row('serialised size', p.messages.jsonBytes, null, false);
+  row('structure + escapes', p.messages.structuralBytes, null, false);
+  if (p.messages.structuralBytes > p.messages.contentBytes) {
+    lines.push('    (structure is larger than the content — that is normal for many short messages)');
+  }
+
+  if (opts.verbose && p.messages.argsByTool.size) {
+    lines.push('');
+    lines.push('  tool arguments by tool');
+    const rows = [...p.messages.argsByTool].sort((a, b) => b[1].bytes - a[1].bytes);
+    for (const [name, b] of (opts.top ? rows.slice(0, opts.top) : rows)) {
+      row(name, b.bytes, b.count);
+    }
+  }
+  return lines;
+}
+
+/**
+ * A short verdict, for a place that wants one line rather than a table.
+ * @returns {string}
+ */
+export function memoryHeadline(p) {
+  const total = mb(p.totalBytes);
+  const args = mb(p.messages.toolArgs.bytes);
+  const tr = p.transcript.count ? mb(p.transcript.bytes) : '0';
+  return `${total} MB total · text ${mb(p.messages.text.bytes)} · tool results ${mb(p.messages.toolResults.bytes)} · tool args ${args} · transcript ${tr}`;
+}