@nxuss/lemma 1.43.0 → 1.45.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@nxuss/lemma.svg?color=orange&style=flat-square)](https://www.npmjs.com/package/@nxuss/lemma)
 ![License](https://img.shields.io/npm/l/@nxuss/lemma.svg?color=blue&style=flat-square)
-![MCP](https://img.shields.io/badge/MCP-91%20tools-ff69b4?style=flat-square)
+![MCP](https://img.shields.io/badge/MCP-92%20tools-ff69b4?style=flat-square)
 ![Local-first](https://img.shields.io/badge/local--first-no%20cloud%20required-success?style=flat-square)
 
 **A memory your AI agent can verify, and a context window that only holds what matters.**
@@ -43,23 +43,26 @@ in a local index (BM25, no embeddings service, no cloud). Every memory is tied t
 symbols it's about, so when the code changes it comes back **stale** instead of confidently
 wrong — and a memory with no evidence is labelled as such, never sold as a verified answer.
 
-**↪ Work that survives the session (Pro).** A session that edited code leaves a hand-off built from the
-transcript and git, with no model tokens: the task exactly as it was given, the files changed, the last test
-run. The next session's briefing points at it, so "continue where we left off" has something to continue from.
+**↪ Work that survives the session (Pro, Claude Code and OpenCode).** A session that edited code leaves a hand-off
+built from the transcript and git, with no model tokens: the task exactly as it was given, the files changed, the last
+test run, and what each subagent did (its description, the files it edited, its last run), so an orchestrator that
+delegated everything still leaves one. The next session's briefing points at it, so "continue where we left off" has
+something to continue from.
 An agent's own note tends to keep function names and drop their parameter lists; the hand-off keeps the plan
 verbatim. In our benchmark (a plan said only in the first session, graded by hidden tests) agents with Lemma
 finished it in 3 of 3 runs, Claude Code's built-in memory in 1 of 3 and another agent-memory tool in 0 of 3 (3-run
 cells, one model, our own benchmark: a lead, not a proof). It costs more per task, not less, because the agent
 does the work the others skip.
 
-**↪ …and the compaction (Pro, Claude Code only).** When Claude Code compacts a long conversation, a `PreCompact` hook
+**↪ …and the compaction (Pro, Claude Code and OpenCode).** When Claude Code compacts a long conversation, a `PreCompact` hook
 saves the same hand-off first, and the `SessionStart` that follows puts its content (the plan exactly as it was given,
 the files, the last run) back in context, not a pointer to it. The agent has the plan in front of it without going
 back to the session transcript: in `bench/compaction` the agents with the hook finished the task in 15 of 15 runs
 (Sonnet and Haiku), the Haiku ones without a single trip back to the transcript, and where the transcript could not be
 read it was 5 of 5 against 2 of 5 without the hook (n=5 per arm). It never blocks the compaction: it prints nothing,
-always exits 0 and takes about 0.1 s on a 1.5 MB transcript. Claude Code only; the other clients have no
-pre-compaction event, so nothing is installed for them.
+always exits 0 and takes about 0.1 s on a 1.5 MB transcript. OpenCode gets the same hand-off through its plugin's
+compaction hook, added to the compaction prompt (verified live; the benchmark numbers above are Claude Code's). Codex
+and Cursor have no pre-compaction event, so nothing is installed for them.
 
 **✍️ It fills itself.** A test, build or lint command that goes red → green is saved as
 `fix: <the error>` with the diff that fixed it. Commits become memories. Next time the same
@@ -125,6 +128,21 @@ it adds a `SessionStart` briefing and a prompt-time recall too, and pre-approves
 memory tools so using them never costs a permission prompt. Existing hooks are kept; `--no-hooks`
 skips them. Health check: `lemma doctor`.
 
+What each client gets beyond the MCP tools:
+
+| | Claude Code | OpenCode | Codex | Cursor |
+| :--- | :---: | :---: | :---: | :---: |
+| 🧠 notes when a native read, edit or failing test touches a memory | ✅ | ✅ | ✅ | ✅ |
+| red → green fix captured from the native shell | ✅ | ✅ | ✅ | ✅ |
+| briefing at session start | ✅ | ✅ (plugin) | — | — |
+| hand-off between sessions, with subagents (Pro) | ✅ | ✅ (plugin) | — | — |
+| hand-off put back after a compaction (Pro) | ✅ | ✅ (plugin) | — | — |
+| warning when a native tool prints a credential | ✅ | ✅ | ✅ | ✅ |
+
+Windsurf and Kiro get the MCP server and the agent rules only. OpenCode's MCP server is registered in
+`~/.config/opencode/opencode.json` (or the `.jsonc` you use); an older `lemma init` wrote `~/.opencode.json`, which
+OpenCode does not read, so run `lemma init` again.
+
 ### After an upgrade
 
 After `npm install -g @nxuss/lemma` and reconnecting the MCP server, a project that already ran
@@ -133,7 +151,7 @@ After `npm install -g @nxuss/lemma` and reconnecting the MCP server, a project t
 | | Comes with the upgrade | Needs `lemma init` again |
 | :--- | :---: | :---: |
 | New and fixed tool behaviour (freshness checks, the diff shown on a STALE memory, the hand-off logic) | ✅ | |
-| Missing Claude Code hooks (`SessionStart`, prompt recall, the note before an edit, `SessionEnd`, `PreCompact`), added at the next MCP start | ✅ | |
+| Missing Claude Code hooks (`SessionStart`, prompt recall, the note before an edit, `SessionEnd`, `PreCompact`, `Stop`), added at the next MCP start | ✅ | |
 | Agent rules in `CLAUDE.md` / `AGENTS.md` (when to search, store and leave a hand-off) | | ✅ |
 | Pre-approved read and memory tool permissions (otherwise the agent is asked each time) | | ✅ |
 | Hooks and config for Codex, Cursor, OpenCode, Windsurf and Kiro | | ✅ |

package/bin/brain-ingest.js

@@ -15,11 +15,15 @@
  *
  * Usage: lemma-brain-ingest [projectRoot] [--commits [--max N]] [--changelog] [--team-pull]
  *        lemma-brain-ingest --hook-result [--host=claude|codex|cursor|opencode] < payload.json
- *        lemma-brain-ingest --hook-failure < payload.json   (PostToolUseFailure: only the leak warning)
+ *        lemma-brain-ingest --hook-failure < payload.json   (PostToolUseFailure: a failing Bash run, handled like --hook-result)
  *        lemma-brain-ingest --prompt-submit < payload.json
  *        lemma-brain-ingest --pre-tool < payload.json
  *        lemma-brain-ingest --session-end < payload.json
  *        lemma-brain-ingest --pre-compact < payload.json   (PreCompact: saves the hand-off; prints nothing, never blocks)
+ *        lemma-brain-ingest --stop < payload.json   (Stop: once per session, asks the agent to leave the team what the code cannot show)
+ *        lemma-brain-ingest --opencode-idle < snapshot.json        (OpenCode session.idle: saves/refreshes the hand-off; prints nothing)
+ *        lemma-brain-ingest --opencode-compacting < snapshot.json  (OpenCode compaction: saves the hand-off, prints it for the context)
+ *        lemma-brain-ingest --session-start --host=opencode         (prints the briefing as plain text)
  *
  * --team-pull   Import the repo's shared memories from .lemma-brain/ (post-merge/post-checkout).
  * --hook-result Read a host PostToolUse hook payload on stdin (Claude Code shape) and:
@@ -87,8 +91,10 @@ async function hookResult(args) {
   } catch {
     return;
   }
-  // PostToolUseFailure (a command that exited non-zero) carries the output in `error`, with no tool_response. It only
-  // feeds the leak warning: a failing run that dumps its environment is the likeliest way a secret reaches the model.
+  // PostToolUseFailure (a command that exited non-zero) carries the output in `error`, with no tool_response. Claude Code
+  // sends EVERY failing Bash run here and never to PostToolUse, so this path must do all PostToolUse does: when it only
+  // fed the leak warning, the red half of a red → green fix was never recorded (no fix memory was ever captured from a
+  // native test run) and a failure matching a recorded fix was never recalled.
   const failure = args.includes('--hook-failure');
   if (failure) {
     if (!raw || typeof raw.error !== 'string' || raw.tool_name !== 'Bash') return;
@@ -98,13 +104,6 @@ async function hookResult(args) {
   const recalled = [];
   let root;
   for (const payload of normalizeHostPayload(host, raw)) {
-    if (failure) {
-      try {
-        const leak = leakNote(payload, payload.cwd);
-        if (leak && !notes.includes(leak)) notes.push(leak);
-      } catch { /* a warning failing must not fail the hook */ }
-      continue;
-    }
     try {
       const res = recordHookPayload(payload, payload.cwd);
       if (res && res.captured) console.error(res.note.trim());
@@ -171,7 +170,7 @@ async function preTool() {
 
 // SessionStart hook (Claude Code): the Brain's briefing and the Lemma playbook, in context
 // before the first prompt — no tool call for the agent to remember or skip.
-async function sessionStart() {
+async function sessionStart(args = []) {
   const dist = path.join(__dirname, '..', 'dist', 'cjs');
   let sessionRecall, compactRecall, formatHostOutput;
   try {
@@ -197,7 +196,9 @@ async function sessionStart() {
   }
   // After a compaction the hand-off's content goes back in; any other start (or no hand-off) is the usual briefing.
   const recall = (payload.source === 'compact' && compactRecall(payload, payload.cwd)) || sessionRecall(payload, payload.cwd);
-  const out = formatHostOutput('claude', recall ? recall.text : '', 'SessionStart');
+  const { parseHost } = require(path.join(dist, 'subconscious', 'HostAdapters.js'));
+  const host = parseHost((args.find((a) => a.startsWith('--host=')) || '').slice('--host='.length) || undefined);
+  const out = formatHostOutput(host, recall ? recall.text : '', 'SessionStart');
   if (out) process.stdout.write(out);
   await reportOffered(dist, payload.cwd, [recall]);
 }
@@ -229,11 +230,45 @@ async function preCompact() {
   }
 }
 
+// Stop hook (Claude Code): runs at the end of EVERY agent response, so the cheap checks come first and
+// anything that goes wrong lets the agent stop. The only output is a block decision, once per session.
+async function stop() {
+  try {
+    const dist = path.join(__dirname, '..', 'dist', 'cjs');
+    const payload = JSON.parse(readStdin()) || {};
+    const { cloudConfigStatus } = require(path.join(dist, 'cloud', 'CloudBrainClient.js'));
+    if (process.env.LEMMA_STOP_NUDGE !== '1' && !cloudConfigStatus(process.env).config) return;
+    const { stopNudge } = require(path.join(dist, 'utils', 'StopNudge.js'));
+    const decision = stopNudge(payload);
+    if (decision.block) process.stdout.write(JSON.stringify({ decision: 'block', reason: decision.reason }));
+  } catch {
+    // no build, no payload, no transcript: the agent just stops
+  }
+}
+
+// OpenCode plugin (session.idle / experimental.session.compacting): the session snapshot from the SDK
+// becomes the same hand-off a Claude Code session leaves (see OpenCodeSession). Idle prints nothing;
+// compacting prints the hand-off for the plugin to add to the compaction context. Never fails loudly.
+async function openCode(compacting) {
+  try {
+    const dist = path.join(__dirname, '..', 'dist', 'cjs');
+    const snap = JSON.parse(readStdin());
+    const { captureOpenCodeSession } = require(path.join(dist, 'utils', 'OpenCodeSession.js'));
+    const res = captureOpenCodeSession(snap, { compacting });
+    if (compacting && res.text) process.stdout.write(res.text);
+  } catch {
+    // no build, no snapshot: the session goes on untouched
+  }
+}
+
 async function main() {
   const args = process.argv.slice(2);
+  if (args.includes('--opencode-idle')) return openCode(false);
+  if (args.includes('--opencode-compacting')) return openCode(true);
+  if (args.includes('--stop')) return stop();
   if (args.includes('--pre-compact')) return preCompact();
   if (args.includes('--session-end')) return sessionEnd();
-  if (args.includes('--session-start')) return sessionStart();
+  if (args.includes('--session-start')) return sessionStart(args);
   if (args.includes('--prompt-submit')) return promptSubmit();
   if (args.includes('--pre-tool')) return preTool();
   if (args.includes('--hook-result') || args.includes('--hook-failure')) return hookResult(args);

package/bin/cloud.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * lemma cloud — connect this machine to your team's Brain on Lemma Cloud.
+ *
+ *   lemma cloud login [--url URL] [--key-stdin | --key KEY] [--no-autoshare] [--no-verify]
+ *   lemma cloud logout
+ *   lemma cloud status
+ *   lemma cloud link --url URL        write the committed, secret-free .lemma-cloud.json
+ *
+ * The key is stored in ~/.lemma/cloud.json (owner-only) bound to the URL it was issued for; the
+ * repo marker only ever supplies a default URL. This file prints a key NEVER, not even masked
+ * beyond its last four characters, and `login` verifies it against the server before saving.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const D = '\x1b[2m', G = '\x1b[32m', Y = '\x1b[33m', RED = '\x1b[31m', B = '\x1b[1m', R = '\x1b[0m';
+
+function load() {
+  const attempt = (base, ext) => ({
+    cfg: require(path.join(base, 'CloudConfig' + ext)),
+    client: require(path.join(base, 'CloudBrainClient' + ext)),
+    ent: require(path.join(base, 'CloudEntitlement' + ext)),
+  });
+  try {
+    return attempt(path.join(__dirname, '..', 'dist', 'cjs', 'cloud'), '');
+  } catch {
+    // Same fallback as lemma-proxy.cjs: a source checkout that has not been built yet.
+    try {
+      process.env.TS_NODE_PROJECT = process.env.TS_NODE_PROJECT || path.join(__dirname, '..', 'tsconfig.cjs.json');
+      require('ts-node/register/transpile-only');
+      return attempt(path.join(__dirname, '..', 'src', 'cloud'), '.ts');
+    } catch {
+      console.error('lemma cloud needs the compiled package (dist/cjs). Run `npm run build`, or reinstall @nxuss/lemma.');
+      process.exit(1);
+    }
+  }
+}
+
+function repoRoot() {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' }).trim() || process.cwd();
+  } catch {
+    return process.cwd();
+  }
+}
+
+function parse(argv) {
+  const out = { _: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--url' || a === '--key') out.flags[a.slice(2)] = argv[++i];
+    else if (a.startsWith('--url=')) out.flags.url = a.slice(6);
+    else if (a.startsWith('--key=')) out.flags.key = a.slice(6);
+    else if (a.startsWith('--')) out.flags[a.slice(2)] = true;
+    else out._.push(a);
+  }
+  return out;
+}
+
+const host = (url) => { try { return new URL(url).host; } catch { return String(url); } };
+const mask = (key) => `${key.slice(0, key.indexOf('_', 3) + 1)}…${key.slice(-4)}`;
+const fail = (msg) => { console.error(`${RED}✗${R} ${msg}`); return 1; };
+
+function promptHidden(question) {
+  return new Promise((resolve) => {
+    const rl = require('readline').createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    process.stdout.write(question);
+    rl._writeToOutput = () => {}; // do not echo the key
+    rl.question('', (answer) => { rl.close(); process.stdout.write('\n'); resolve(answer.trim()); });
+  });
+}
+
+async function readKey(flags) {
+  if (flags['key-stdin']) return fs.readFileSync(0, 'utf8').trim();
+  if (typeof flags.key === 'string') {
+    console.error(`${Y}!${R} --key puts the key in your shell history; prefer \`--key-stdin\` or the prompt.`);
+    return flags.key.trim();
+  }
+  if (process.env.LEMMA_CLOUD_KEY) return process.env.LEMMA_CLOUD_KEY.trim();
+  if (process.stdin.isTTY) return promptHidden('Your Lemma Cloud key (input hidden): ');
+  return '';
+}
+
+async function login(flags) {
+  const { cfg, client, ent } = load();
+  const marker = cfg.readMarker(repoRoot());
+  const url = (typeof flags.url === 'string' && flags.url) || process.env.LEMMA_CLOUD_URL || (marker && marker.url) || '';
+  if (!url) return fail('No URL. Pass --url https://…, or run this inside a repo that has a .lemma-cloud.json.');
+  const key = await readKey(flags);
+  if (!key) return fail('No key. Ask your Lemma Cloud admin for yours, then pass --key-stdin or run this in a terminal.');
+
+  // Validate with the same rules the MCP applies, using only these two values (never the saved file).
+  const checked = client.cloudConfigStatus({ LEMMA_CLOUD_URL: url, LEMMA_CLOUD_KEY: key });
+  if (!checked.config) return fail(checked.problem);
+
+  // The entitlement call doubles as the key check. A server from before that endpoint answers 404:
+  // then the old check (usage) still proves the key, and there is simply no plan to report.
+  let answer = null;
+  if (!flags['no-verify']) {
+    const api = new client.CloudBrainClient({ ...checked.config, timeoutMs: 8000 });
+    try {
+      try {
+        answer = await api.entitlement();
+      } catch (err) {
+        if (!err || err.status !== 404) throw err;
+        await api.usage();
+      }
+    } catch (err) {
+      if (err && err.status === 401) return fail(`${host(url)} rejected that key (wrong, or revoked). Nothing was saved.`);
+      const why = err && err.message ? err.message : 'unknown error';
+      return fail(`Could not verify the key against ${host(url)}: ${why}. Nothing was saved (use --no-verify to save it anyway).`);
+    }
+  }
+
+  const baseUrl = checked.config.baseUrl.replace(/\/v2$/, '');
+  const autoshare = !flags['no-autoshare'];
+  const file = cfg.writeUserConfig({ url: baseUrl, key, autoshare });
+  // A different account or server must not inherit the previous one's answer.
+  ent.clearEntitlement();
+  if (answer && typeof answer.plan === 'string' && typeof answer.includesPro === 'boolean') ent.recordEntitlement(checked.config, answer);
+  console.log(`${G}✓${R} Connected to ${B}${host(baseUrl)}${R}${flags['no-verify'] ? ` ${D}(not verified)${R}` : ''}.`);
+  console.log(`  Saved to ${file} ${D}(readable only by you)${R}`);
+  console.log(autoshare
+    ? `  Memories you store are ${B}shared with your team${R} automatically (secrets are redacted first). Turn that off with: lemma cloud login --no-autoshare`
+    : `  Sharing is off: nothing leaves your machine unless you call cloud_push. Teammates' memories still show up in search.`);
+  if (answer && answer.includesPro === true) {
+    console.log(`  Plan ${B}${answer.plan}${R}: this seat also unlocks ${B}Lemma Pro${R} on this machine. Pro tools show up in new sessions; a session already open gets them when it reconnects.`);
+  } else if (answer && typeof answer.plan === 'string') {
+    console.log(`  Plan ${B}${answer.plan}${R}: Pro tools are not included.`);
+  }
+  console.log(`  ${D}Active now, including in sessions already running: nothing to restart or reconnect.${R}`);
+  if (process.env.LEMMA_CLOUD_URL || process.env.LEMMA_CLOUD_KEY) {
+    console.log(`${Y}!${R} LEMMA_CLOUD_URL / LEMMA_CLOUD_KEY are set in this shell and override the saved connection.`);
+  }
+  return 0;
+}
+
+function logout() {
+  const { cfg, ent } = load();
+  const removed = cfg.removeUserConfig();
+  ent.clearEntitlement();
+  console.log(removed ? `${G}✓${R} Disconnected: removed ${cfg.userConfigPath()}` : 'Nothing to remove: this machine was not logged in.');
+  if (process.env.LEMMA_CLOUD_KEY) console.log(`${Y}!${R} LEMMA_CLOUD_KEY is still set in this shell.`);
+  return 0;
+}
+
+async function status() {
+  const { cfg, client, ent } = load();
+  const s = client.cloudConfigStatus(process.env);
+  const marker = cfg.readMarker(repoRoot());
+  if (!s.config) {
+    if (s.problem) return fail(`Lemma Cloud is configured but not usable: ${s.problem}`);
+    console.log('Not connected. Run `lemma cloud login`.');
+    if (marker) console.log(`${D}This repo's team is at ${cfg.markerHost(marker)}.${R}`);
+    return 0;
+  }
+  const c = s.config;
+  console.log(`${B}Lemma Cloud${R}`);
+  console.log(`  server     ${host(c.baseUrl)}`);
+  console.log(`  key        ${mask(c.apiKey)} ${D}(from ${c.source === 'file' ? cfg.userConfigPath() : 'environment variables'})${R}`);
+  console.log(`  sharing    ${client.autoShareFor(s, process.env) ? 'automatic (every memory you store)' : 'off (cloud_push shares one on request)'}`);
+  try {
+    await new client.CloudBrainClient({ ...c, timeoutMs: 6000 }).usage();
+    console.log(`  reachable  ${G}yes${R}, key accepted`);
+  } catch (err) {
+    console.log(`  reachable  ${RED}no${R}: ${err && err.status === 401 ? 'the server rejected this key (revoked or wrong)' : err && err.message ? err.message : 'unknown error'}`);
+  }
+  // Refreshing here keeps `status` truthful about Pro: it records what the server says now.
+  const r = await ent.refreshEntitlement(c, process.env);
+  const pro = ent.cloudGrantsPro(process.env);
+  const plan = r.plan ? ` ${D}(plan ${r.plan})${R}` : '';
+  if (r.state === 'revoked') console.log(`  pro        ${RED}off${R}: the server rejected this key, so this seat no longer includes Pro`);
+  else if (r.state === 'not-included') console.log(`  pro        not included${plan}`);
+  else if (r.state === 'unsupported') console.log(`  pro        ${D}unknown: this server predates seat-based Pro${R}`);
+  else if (pro) console.log(`  pro        ${G}included${R}${plan}${r.state === 'unreachable' ? ` ${D}(last answer; the server could not be asked now)${R}` : ''}`);
+  else console.log(`  pro        ${D}not confirmed (the server could not be asked)${R}`);
+  if (marker && host(marker.url) !== host(c.baseUrl)) {
+    console.log(`${Y}!${R} This repo's team lives at ${cfg.markerHost(marker)}, but you are connected to ${host(c.baseUrl)}.`);
+  }
+  return 0;
+}
+
+function link(flags) {
+  const { cfg } = load();
+  const url = (typeof flags.url === 'string' && flags.url) || process.env.LEMMA_CLOUD_URL || '';
+  if (!url) return fail('Pass --url https://… (the address of your team\'s Lemma Cloud).');
+  const root = repoRoot();
+  const file = cfg.writeMarker(root, url);
+  if (!cfg.readMarker(root)) {
+    fs.unlinkSync(file);
+    return fail('That URL is not valid for the marker (it must be https, or http://localhost, with no credentials).');
+  }
+  console.log(`${G}✓${R} Wrote ${path.relative(process.cwd(), file) || cfg.MARKER_FILE}. Commit it: it holds no secret, only the address.`);
+  console.log(`  Teammates then run ${B}lemma cloud login${R} once and need nothing else.`);
+  return 0;
+}
+
+const HELP = `lemma cloud — your team's Brain on Lemma Cloud
+
+  login [--url URL] [--key-stdin] [--no-autoshare] [--no-verify]
+  logout
+  status
+  link --url URL      write .lemma-cloud.json (commit it; no secret inside)
+`;
+
+async function main(argv = process.argv.slice(3)) {
+  const { _: pos, flags } = parse(argv);
+  switch (pos[0]) {
+    case 'login': return login(flags);
+    case 'logout': return logout();
+    case 'status': return status();
+    case 'link': return link(flags);
+    default:
+      console.log(HELP);
+      return pos[0] ? 1 : 0;
+  }
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then((code) => process.exit(code), (e) => { console.error(e && e.message ? e.message : e); process.exit(1); });
+}

package/dist/cjs/cli/hostHooks.d.ts

@@ -38,8 +38,15 @@ export declare const CLAUDE_SESSION_END_HOOK_COMMAND = "command -v lemma-brain-i
  */
 export declare const CLAUDE_PRE_COMPACT_HOOK_COMMAND = "command -v lemma-brain-ingest >/dev/null 2>&1 && lemma-brain-ingest --pre-compact || true";
 /**
- * PostToolUseFailure (Bash): Claude Code sends a command that exits non-zero here and NOT to PostToolUse, so
- * a failing run that dumps its environment never reached the leak warning. Only the warning is wired to it.
+ * Stop: once per session, when a fix is done and the team shares memories (Lemma Cloud connected), asks the
+ * agent to leave what the code cannot show — see StopNudge. Inert for anyone who is not on a team, and it
+ * answers with a decision only that one time, so it cannot loop.
+ */
+export declare const CLAUDE_STOP_HOOK_COMMAND = "command -v lemma-brain-ingest >/dev/null 2>&1 && lemma-brain-ingest --stop || true";
+/**
+ * PostToolUseFailure (Bash): Claude Code sends a command that exits non-zero here and NOT to PostToolUse, so a
+ * failing test run never reached FixCapture (no red, so no red → green fix memory), the recall of a recorded fix,
+ * or the leak warning. The handler treats it exactly like PostToolUse.
  */
 export declare const CLAUDE_FAILURE_HOOK_COMMAND = "command -v lemma-brain-ingest >/dev/null 2>&1 && lemma-brain-ingest --hook-failure || true";
 export declare const CLAUDE_FAILURE_MATCHER = "Bash";
@@ -68,12 +75,42 @@ export declare function installCodexHooks(home?: string): HookInstallOutcome;
 /** Cursor format: `{ version: 1, hooks: { <event>: [{ command, matcher? }] } }`. */
 export declare function installCursorHooks(home?: string): HookInstallOutcome;
 /**
- * OpenCode has no hook protocol, so the hook is a plugin: it forwards each finished tool call
- * to `lemma-brain-ingest --host=opencode` and appends the note it prints (if any) to the tool's
- * output — the only place a plugin can put text the model reads. Arguments are taken from
- * tool.execute.before, keyed by call id, because the after-hook's input doesn't carry them.
+ * OpenCode has no hook protocol, so the hook is a plugin:
+ *  - each finished tool call goes to `lemma-brain-ingest --host=opencode`, and the note it prints (if
+ *    any) is appended to the tool's output, the only place a plugin can put text the model reads.
+ *    Arguments are taken from tool.execute.before, keyed by call id: the after-hook's input lacks them.
+ *  - session.idle (OpenCode has no session end) sends the session and its subagents' child sessions to
+ *    `--opencode-idle`, which saves the hand-off (see OpenCodeSession); experimental.session.compacting
+ *    does the same and adds the hand-off to the compaction context, so the plan survives it.
+ *  - experimental.chat.system.transform adds the session briefing (what `SessionStart` gives Claude
+ *    Code) to the system prompt, computed once per session and repeated on every step so the prompt
+ *    stays the same between steps. Subagent sessions get none of this: they are the parent's work.
+ * The session is NOT fetched from the SDK on every turn: measured on real sessions, one message's
+ * `summary.diffs` held 99.7 MB and whole sessions 170-207 MB, all of which `client.session.messages`
+ * returns. The plugin keeps its own trimmed log from the bus events it already receives
+ * (message.updated, message.part.updated, session.created/updated). A session it joined midway (opened with
+ * -s / --continue) is not fetched either: no SDK query can leave that one message out. Its hand-off then
+ * covers what this process saw, and the previous process's hand-off carries the plan and the files over
+ * (SessionCapture's continuation). Only session.get, which is small, is asked for, to tell a subagent.
+ * The idle/compaction/briefing calls are async (a spawnSync would freeze OpenCode's UI meanwhile) and
+ * every hook swallows its errors: Lemma must never be the reason a session fails.
+ */
+export declare const OPENCODE_PLUGIN = "// managed by `lemma init` \u2014 delete this file to disable Lemma Brain recall in OpenCode\nimport { spawn, spawnSync } from \"node:child_process\";\n\nconst MAX_TEXT = 8000;\nconst OUTPUT_HEAD = 1500;\nconst OUTPUT_TAIL = 4500;\nconst MAX_PARTS = 4000;\nconst INPUT_KEYS = [\"filePath\", \"file_path\", \"path\", \"command\", \"description\", \"subagent_type\", \"patchText\", \"searchContent\", \"replaceContent\", \"patches\"];\n\nconst clip = (s, n) => (typeof s === \"string\" && s.length > n ? s.slice(0, n) : s);\nconst ends = (s) => (typeof s === \"string\" && s.length > OUTPUT_HEAD + OUTPUT_TAIL ? s.slice(0, OUTPUT_HEAD) + \"\\n\u2026\\n\" + s.slice(-OUTPUT_TAIL) : s);\n\n// What Lemma reads of a part (see OpenCodeSession): nothing else crosses the process boundary.\nfunction slimPart(p) {\n  if (!p || typeof p !== \"object\") return null;\n  if (p.type === \"text\") return p.synthetic || typeof p.text !== \"string\" ? null : { type: \"text\", text: clip(p.text, MAX_TEXT) };\n  if (p.type === \"patch\") return Array.isArray(p.files) ? { type: \"patch\", files: p.files.slice(0, 50) } : null;\n  if (p.type !== \"tool\" || typeof p.tool !== \"string\") return null;\n  const st = p.state || {};\n  const raw = st.input && typeof st.input === \"object\" ? st.input : {};\n  const input = {};\n  for (const k of INPUT_KEYS) if (raw[k] !== undefined) input[k] = typeof raw[k] === \"string\" ? clip(raw[k], 20000) : raw[k];\n  const meta = st.metadata || {};\n  return { type: \"tool\", tool: p.tool, callID: p.callID, state: { status: st.status, input, output: ends(typeof st.output === \"string\" ? st.output : \"\"), error: clip(st.error, 2000), time: st.time, metadata: { sessionId: meta.sessionId, exit: meta.exit } } };\n}\n\nexport const LemmaBrainRecall = async ({ client, directory }) => {\n  const argsByCall = new Map();\n  const sessions = new Map(); // id -> { parentID, title, agent, joined, messages: Map(msgId -> { info, parts: Map(partId -> slim) }) }\n  const briefings = new Map();\n  const ingest = (args, payload, timeoutMs) => new Promise((resolve) => {\n    let out = \"\";\n    let done = false;\n    const finish = () => { if (!done) { done = true; clearTimeout(timer); resolve(out.trim()); } };\n    const child = spawn(\"lemma-brain-ingest\", args, { stdio: [\"pipe\", \"pipe\", \"ignore\"] });\n    const timer = setTimeout(() => { try { child.kill(); } catch {} finish(); }, timeoutMs);\n    child.stdout.on(\"data\", (d) => { out += d; });\n    child.on(\"error\", finish);\n    child.on(\"close\", finish);\n    child.stdin.on(\"error\", () => {});\n    child.stdin.end(JSON.stringify(payload));\n  });\n  const session = (id) => {\n    if (!sessions.has(id)) sessions.set(id, { parentID: undefined, title: undefined, agent: undefined, joined: false, messages: new Map(), parts: 0 });\n    return sessions.get(id);\n  };\n  const learn = (info) => {\n    if (!info || typeof info.id !== \"string\") return;\n    const s = session(info.id);\n    s.parentID = info.parentID || null;\n    s.title = info.title;\n    s.agent = info.agent;\n  };\n  const message = (s, info) => {\n    const m = s.messages.get(info.id) || { info: {}, parts: new Map() };\n    // A part can arrive before its message: the placeholder's role and time are corrected here.\n    m.info = { role: info.role, time: { created: info.time && info.time.created } };\n    s.messages.set(info.id, m);\n    return m;\n  };\n  const addPart = (s, messageID, part) => {\n    const slim = slimPart(part);\n    if (!slim || !messageID) return;\n    const m = s.messages.get(messageID) || (s.messages.set(messageID, { info: { role: \"assistant\", time: {} }, parts: new Map() }), s.messages.get(messageID));\n    if (!m.parts.has(part.id)) s.parts++;\n    m.parts.set(part.id || String(m.parts.size), slim);\n    // A runaway session keeps its first parts (the task) and its latest ones (the work at hand).\n    if (s.parts > MAX_PARTS) {\n      const ids = [...s.messages.keys()];\n      for (const id of ids.slice(2, Math.max(2, ids.length - 300))) { s.parts -= s.messages.get(id).parts.size; s.messages.delete(id); if (s.parts <= MAX_PARTS * 0.8) break; }\n    }\n  };\n  // A session this process did not see start (opened with -s / --continue): only ask whether it is a subagent.\n  const join = async (id) => {\n    const s = session(id);\n    if (s.joined) return s;\n    s.joined = true;\n    try {\n      if (s.parentID === undefined) learn(((await client.session.get({ path: { id } })).data) || { id });\n    } catch { /* unknown parent: treated as a main session */ }\n    return s;\n  };\n  const isSubagent = async (id) => !!(await join(id)).parentID;\n  const plain = (s) => [...s.messages.values()].sort((a, b) => (a.info.time.created || 0) - (b.info.time.created || 0)).map((m) => ({ info: m.info, parts: [...m.parts.values()] }));\n  const snapshot = async (id) => {\n    const s = await join(id);\n    const kids = [];\n    for (const [kid, k] of sessions) if (k.parentID === id) kids.push({ session: { id: kid, title: k.title, agent: k.agent }, messages: plain(k) });\n    return { sessionID: id, directory, messages: plain(s), children: kids };\n  };\n  return {\n    \"tool.execute.before\": async (input, output) => {\n      if (!input || !input.callID) return;\n      argsByCall.set(input.callID, (output && output.args) || {});\n      if (argsByCall.size > 200) argsByCall.delete(argsByCall.keys().next().value);\n    },\n    \"tool.execute.after\": async (input, output) => {\n      try {\n        const args = argsByCall.get(input.callID) || input.args || {};\n        argsByCall.delete(input.callID);\n        if (!output || typeof output.output !== \"string\") return;\n        const payload = { tool: input.tool, sessionID: input.sessionID, args, output: output.output, metadata: output.metadata || {}, directory };\n        const r = spawnSync(\"lemma-brain-ingest\", [\"--hook-result\", \"--host=opencode\"], { input: JSON.stringify(payload), encoding: \"utf8\", timeout: 5000 });\n        const note = typeof r.stdout === \"string\" ? r.stdout.trim() : \"\";\n        if (note) output.output += \"\\n\\n\" + note;\n      } catch {\n        // A recall hint must never be the reason a tool call fails.\n      }\n    },\n    event: async ({ event }) => {\n      try {\n        if (!event || !event.properties) return;\n        const props = event.properties;\n        if (event.type === \"session.created\" || event.type === \"session.updated\") {\n          learn(props.info);\n          if (event.type === \"session.created\" && props.info) session(props.info.id).joined = true; // seen from its start\n          return;\n        }\n        if (event.type === \"message.updated\" && props.info && props.info.sessionID) { message(session(props.info.sessionID), props.info); return; }\n        if (event.type === \"message.part.updated\" && props.part && props.part.sessionID) { addPart(session(props.part.sessionID), props.part.messageID, props.part); return; }\n        if (event.type !== \"session.idle\") return;\n        const id = props.sessionID;\n        if (!id || (await isSubagent(id))) return;\n        await ingest([\"--opencode-idle\", \"--host=opencode\"], await snapshot(id), 15000);\n      } catch {\n        // the hand-off is a courtesy; the session is never held up by it\n      }\n    },\n    \"experimental.session.compacting\": async (input, output) => {\n      try {\n        if (!input || !input.sessionID || (await isSubagent(input.sessionID))) return;\n        const text = await ingest([\"--opencode-compacting\", \"--host=opencode\"], await snapshot(input.sessionID), 15000);\n        if (text && output && Array.isArray(output.context)) output.context.push(text);\n      } catch {\n        // the compaction goes ahead without the hand-off\n      }\n    },\n    \"experimental.chat.system.transform\": async (input, output) => {\n      try {\n        const id = input && input.sessionID;\n        if (!id || !output || !Array.isArray(output.system)) return;\n        if (!briefings.has(id)) {\n          briefings.set(id, (await isSubagent(id)) ? \"\" : await ingest([\"--session-start\", \"--host=opencode\"], { cwd: directory, session_id: id, host: \"opencode\" }, 5000));\n        }\n        const text = briefings.get(id);\n        if (text) output.system.push(text);\n      } catch {\n        // no briefing this time\n      }\n    },\n  };\n};\n";
+/** What `lemma init` registers as OpenCode's MCP server: OpenCode's local-server shape (`type`, argv array). */
+export declare const OPENCODE_MCP_ENTRY: {
+    type: string;
+    command: string[];
+    enabled: boolean;
+};
+/**
+ * Register Lemma's MCP server where OpenCode reads it: `~/.config/opencode/opencode.json` (or the
+ * `.jsonc` beside it, when that is the one in use). `lemma init` used to write `~/.opencode.json`, a path
+ * OpenCode no longer reads, in the old `{command, args}` shape, so outside a repo with its own
+ * opencode.json OpenCode had no Lemma tools at all (`opencode mcp list`: "No MCP servers configured").
+ * An existing `mcp.lemma` is kept as it is (it may point at a local build on purpose); a file that is
+ * not plain JSON (a .jsonc with comments) is left alone and the caller gets the snippet to add.
  */
-export declare const OPENCODE_PLUGIN = "// managed by `lemma init` \u2014 delete this file to disable Lemma Brain recall in OpenCode\nimport { spawnSync } from \"node:child_process\";\n\nexport const LemmaBrainRecall = async ({ directory }) => {\n  const argsByCall = new Map();\n  return {\n    \"tool.execute.before\": async (input, output) => {\n      if (!input || !input.callID) return;\n      argsByCall.set(input.callID, (output && output.args) || {});\n      if (argsByCall.size > 200) argsByCall.delete(argsByCall.keys().next().value);\n    },\n    \"tool.execute.after\": async (input, output) => {\n      try {\n        const args = argsByCall.get(input.callID) || input.args || {};\n        argsByCall.delete(input.callID);\n        if (!output || typeof output.output !== \"string\") return;\n        const payload = { tool: input.tool, sessionID: input.sessionID, args, output: output.output, metadata: output.metadata || {}, directory };\n        const r = spawnSync(\"lemma-brain-ingest\", [\"--hook-result\", \"--host=opencode\"], { input: JSON.stringify(payload), encoding: \"utf8\", timeout: 5000 });\n        const note = typeof r.stdout === \"string\" ? r.stdout.trim() : \"\";\n        if (note) output.output += \"\\n\\n\" + note;\n      } catch {\n        // A recall hint must never be the reason a tool call fails.\n      }\n    },\n  };\n};\n";
+export declare function registerOpenCodeMcp(home?: string): HookInstallOutcome;
 export declare function installOpenCodePlugin(home?: string): HookInstallOutcome;
 export interface HostHookReport {
     host: 'Claude Code' | 'Codex' | 'Cursor' | 'OpenCode';

package/dist/cjs/cli/hostHooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hostHooks.d.ts","sourceRoot":"","sources":["../../../src/cli/hostHooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAeH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAGvE;AAED,eAAO,MAAM,mBAAmB,QAAwB,CAAC;AACzD,0FAA0F;AAC1F,eAAO,MAAM,0BAA0B,gGAA4E,CAAC;AACpH,uGAAuG;AACvG,eAAO,MAAM,4BAA4B,2FAA8E,CAAC;AACxH,eAAO,MAAM,uBAAuB,sCAAsC,CAAC;AAC3E,4FAA4F;AAC5F,eAAO,MAAM,2BAA2B,gGAA6E,CAAC;AACtH,sGAAsG;AACtG,eAAO,MAAM,+BAA+B,8FAAiF,CAAC;AAC9H;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,8FAAiF,CAAC;AAC9H;;;GAGG;AACH,eAAO,MAAM,2BAA2B,+FAA6E,CAAC;AACtH,eAAO,MAAM,sBAAsB,SAAS,CAAC;AAC7C,eAAO,MAAM,mBAAmB,gDAAgD,CAAC;AACjF,eAAO,MAAM,kBAAkB,gCAAgC,CAAC;AAChE,eAAO,MAAM,mBAAmB,qBAAqB,CAAC;AACtD,eAAO,MAAM,sBAAsB,UAAU,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,UAWD,CAAC;AAEjC,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6FAA6F;IAC7F,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AA6FD,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAsB,EAAE,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,kBAAkB,CA4B3H;AAED,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,MAAqB,GAAG,kBAAkB,CAEjF;AAED,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,MAAqB,GAAG,kBAAkB,CAkClF;AAID;;;;;GAKG;AACH,eAAO,MAAM,eAAe,szCA0B3B,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,MAAqB,GAAG,kBAAkB,CAYrF;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,aAAa,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAC;IACtD,OAAO,EAAE,kBAAkB,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAsB,EAAE,IAAI,GAAE,MAAqB,GAAG,cAAc,EAAE,CAO3G;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAsB,GAAG,kBAAkB,GAAG,IAAI,CAWxF"}
+{"version":3,"file":"hostHooks.d.ts","sourceRoot":"","sources":["../../../src/cli/hostHooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAgBH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAGvE;AAED,eAAO,MAAM,mBAAmB,QAAwB,CAAC;AACzD,0FAA0F;AAC1F,eAAO,MAAM,0BAA0B,gGAA4E,CAAC;AACpH,uGAAuG;AACvG,eAAO,MAAM,4BAA4B,2FAA8E,CAAC;AACxH,eAAO,MAAM,uBAAuB,sCAAsC,CAAC;AAC3E,4FAA4F;AAC5F,eAAO,MAAM,2BAA2B,gGAA6E,CAAC;AACtH,sGAAsG;AACtG,eAAO,MAAM,+BAA+B,8FAAiF,CAAC;AAC9H;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,8FAAiF,CAAC;AAC9H;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,uFAA0E,CAAC;AAChH;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,+FAA6E,CAAC;AACtH,eAAO,MAAM,sBAAsB,SAAS,CAAC;AAC7C,eAAO,MAAM,mBAAmB,gDAAgD,CAAC;AACjF,eAAO,MAAM,kBAAkB,gCAAgC,CAAC;AAChE,eAAO,MAAM,mBAAmB,qBAAqB,CAAC;AACtD,eAAO,MAAM,sBAAsB,UAAU,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,UAWD,CAAC;AAEjC,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6FAA6F;IAC7F,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AA6FD,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAsB,EAAE,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,kBAAkB,CA8B3H;AAED,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,MAAqB,GAAG,kBAAkB,CAEjF;AAED,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,MAAqB,GAAG,kBAAkB,CAkClF;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe,suQAwJ3B,CAAC;AAEF,gHAAgH;AAChH,eAAO,MAAM,kBAAkB;;;;CAAkF,CAAC;AAElH;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,MAAqB,GAAG,kBAAkB,CAsBnF;AAED,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,MAAqB,GAAG,kBAAkB,CAYrF;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,aAAa,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAC;IACtD,OAAO,EAAE,kBAAkB,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAsB,EAAE,IAAI,GAAE,MAAqB,GAAG,cAAc,EAAE,CAO3G;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAsB,GAAG,kBAAkB,GAAG,IAAI,CAWxF"}