@bcmyguest/openmem 0.0.0-stage → 0.8.0

package/cli/context-management.mjs

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+/**
+ * Context management (smart compaction) per agent: `[context_proxy.agents]` in config.toml (a missing key
+ * follows `[context_proxy] enabled`; with neither set, opencode2 is on and the others off), the agent wiring (install-coding-agent) and the compose
+ * `context-proxy` service. Shared by the setup wizard step, install-coding-agent and `openmem context`.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { contextRoot } from "./coding-agent/context-store.mjs";
+import { proxyCodeVersion, summarizeEvents } from "./coding-agent/session-db.mjs";
+import { agentsPointedAtContextProxy, ensureContextProxyKey, probeContextProxy } from "./coding-agent/install-context-proxy.mjs";
+import { isMainModule } from "./is-main.mjs";
+import { resolveStackRoot } from "./stack.mjs";
+import {
+  CONTEXT_AGENT_KEYS,
+  contextAgentsFromPmConfig,
+  contextProxyFromPmConfig,
+  loadPmConfig,
+  updatePmConfigContextAgents,
+} from "../wizard/lib/pm-config.mjs";
+
+/** Compose service and profile name (compose.yaml). */
+export const CONTEXT_PROXY_SERVICE = "context-proxy";
+/**
+ * Agents whose "on" needs the proxy service. Codex goes through LiteLLM's ChatGPT-subscription pass-through,
+ * which the pinned dev image has (PR #41522; docs/compatibility.md, footnote 9).
+ */
+export const SERVICE_AGENT_KEYS = ["claude-code", "opencode1", "codex"];
+/** How each config key is served. */
+export const CONTEXT_AGENT_ROUTE = {
+  "claude-code": "context-proxy",
+  opencode1: "context-proxy",
+  codex: "context-proxy (ChatGPT login, /backend-api/codex)",
+  opencode2: "native plugin",
+};
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const BIN = "openmem context";
+
+const HELP = `${BIN}: turn context management (smart compaction) on or off per agent
+
+Usage:
+  ${BIN} on  [--dry-run] [--agents a,b]   save [context_proxy.agents] <agent> = true, re-run
+                                           install-coding-agent (starts the context-proxy service
+                                           when a proxy-routed agent is on)
+  ${BIN} off [--dry-run] [--agents a,b]   save <agent> = false, re-run install-coding-agent (stops
+                                           the service when no proxy-routed agent is on)
+  ${BIN} status [--json]                  per-agent values, proxy health, agents pointed at it, and
+                                           the last 24 h of trims and fail-opens from the session store
+
+Agents: ${CONTEXT_AGENT_KEYS.join(", ")} (default: all). claude-code, opencode1 and codex go through
+the context-proxy service (codex keeps its ChatGPT login); opencode2 trims in its own plugin (on when
+config sets neither its key nor enabled).
+Docs: docs/context-management.md`;
+
+/** True when any agent that needs the service resolves on. */
+export function proxyServiceNeeded(agents) {
+  return SERVICE_AGENT_KEYS.some((k) => agents[k]);
+}
+
+/**
+ * Key file and store directories the compose service needs before `up`
+ * (env_file, and a bind mount with create_host_path: false).
+ */
+export function prepareContextProxyFiles(home, env = process.env) {
+  ensureContextProxyKey(home);
+  for (const sub of ["sessions", "blobs"]) fs.mkdirSync(path.join(contextRoot(home, env), sub), { recursive: true, mode: 0o700 });
+}
+
+/**
+ * True when compose reports a container for the service.
+ * @param {string[]} baseArgs `docker` arguments up to (not including) the compose subcommand
+ * @param {{ cwd?: string, env?: Record<string, string | undefined> }} [opts]
+ * @param {typeof spawnSync} [spawn]
+ */
+export function contextProxyRunning(baseArgs, opts = {}, spawn = spawnSync) {
+  const r = spawn("docker", [...baseArgs, "ps", "-q", CONTEXT_PROXY_SERVICE], { encoding: "utf8", ...opts });
+  return r.status === 0 && String(r.stdout || "").trim() !== "";
+}
+
+/** `docker` arguments for compose calls on the context-proxy profile from the stack root. */
+export function contextComposeArgs({ project, stackRoot }) {
+  return ["compose", "-p", project, ...(stackRoot ? ["--project-directory", stackRoot] : []), "--profile", CONTEXT_PROXY_SERVICE];
+}
+
+/**
+ * Start the service (`on`) or stop it when it runs and no agent points at it (`!on`). Skipped when the
+ * stack root has no compose.yaml. Returns what happened.
+ * @param {{ home: string, stackRoot?: string, project: string, on: boolean, dry?: boolean, env?: NodeJS.ProcessEnv,
+ *   spawn?: typeof spawnSync, log: { info: (m: string) => void, warn: (m: string) => void } }} opts
+ * @returns {"started"|"stopped"|"kept"|"not-running"|"no-stack"|"failed"|"dry-run"}
+ */
+export function ensureContextProxyService({ home, stackRoot, project, on, dry = false, env = process.env, spawn = spawnSync, log }) {
+  if (!stackRoot || !fs.existsSync(path.join(stackRoot, "compose.yaml"))) return "no-stack";
+  const base = contextComposeArgs({ project, stackRoot });
+  const opts = { cwd: stackRoot, env: { ...env } };
+  const run = (args) => {
+    const text = `docker ${args.join(" ")}`;
+    if (dry) {
+      log.info(`[dry-run] ${text}`);
+      return 0;
+    }
+    log.info(text);
+    return spawn("docker", args, { stdio: "inherit", ...opts }).status ?? 1;
+  };
+  if (on) {
+    if (!dry) prepareContextProxyFiles(home, env);
+    return run([...base, "up", "-d", CONTEXT_PROXY_SERVICE]) === 0 ? (dry ? "dry-run" : "started") : "failed";
+  }
+  if (!contextProxyRunning(base, opts, spawn)) return "not-running";
+  const pointed = dry ? [] : agentsPointedAtContextProxy(home);
+  if (pointed.length) {
+    log.warn(`context-proxy left running: ${pointed.join(", ")} still point at it`);
+    return "kept";
+  }
+  return run([...base, "stop", CONTEXT_PROXY_SERVICE]) === 0 ? (dry ? "dry-run" : "stopped") : "failed";
+}
+
+/** Proxy code version of the checkout the compose service mounts (stack root, else this package), or null. */
+function checkoutProxyVersion(stackRoot) {
+  for (const root of [stackRoot, PKG_ROOT].filter(Boolean)) {
+    try { return proxyCodeVersion(path.join(root, "proxy", "openmem_context")); } catch { /* not there */ }
+  }
+  return null;
+}
+
+/**
+ * Current state: per-agent values, port, whether the proxy answers, which agents point at it, and the
+ * session store's recent events (summarizeEvents) with the checkout's proxy code version to compare.
+ * @param {{ home: string, stackRoot?: string, fetch?: typeof fetch, env?: NodeJS.ProcessEnv, now?: number }} opts
+ */
+export async function contextStatus({ home, stackRoot, fetch, env = process.env, now }) {
+  const cfg = loadPmConfig(home, stackRoot || home).merged;
+  const { port } = contextProxyFromPmConfig(cfg);
+  const { agents, saved, enabledSaved } = contextAgentsFromPmConfig(cfg);
+  return {
+    enabled: contextProxyFromPmConfig(cfg).enabled,
+    enabledSaved,
+    agents: Object.fromEntries(CONTEXT_AGENT_KEYS.map((k) => [k, { on: agents[k], saved: saved.includes(k), route: CONTEXT_AGENT_ROUTE[k] }])),
+    port,
+    proxyUp: await probeContextProxy(port, fetch ? { fetch } : {}),
+    pointedAgents: agentsPointedAtContextProxy(home),
+    events: summarizeEvents(path.join(contextRoot(home, env), "sessions"), now === undefined ? {} : { now }),
+    checkoutProxyVersion: checkoutProxyVersion(stackRoot),
+  };
+}
+
+/** Text lines for the events part of `status`. */
+export function eventLines(s) {
+  const e = s.events;
+  const lines = [`last ${e.hours} h (${e.sessions} session${e.sessions === 1 ? "" : "s"}): ${e.trims} trim${e.trims === 1 ? "" : "s"}`
+    + (e.trims ? `, ~${e.tokensSaved} tokens saved (estimated ${e.tokensBefore} -> ${e.tokensAfter}), ${e.dropped} messages dropped` : "")
+    + `, ${e.failOpens} fail-open${e.failOpens === 1 ? "" : "s"} (request sent untrimmed)`];
+  for (const x of e.lastErrors) lines.push(`  ${x.at} ${x.error} at ${x.location} (${x.version}, session ${x.session})`);
+  lines.push(...usageLines(e.usage));
+  const running = e.latest.proxy;
+  if (running && s.checkoutProxyVersion) {
+    lines.push(`proxy code: ${running === s.checkoutProxyVersion ? `${running}, matches the checkout`
+      : `${running} in the last event, checkout is ${s.checkoutProxyVersion}; restart the context-proxy service to load it`}`);
+  }
+  lines.push("not recorded here: fail-opens before the session id is known or from the session database itself (proxy stderr only)");
+  return lines;
+}
+
+/** Prompt-cache lines from summarizeEvents' `usage`; none when no usage event was recorded. */
+function usageLines(u) {
+  if (!u?.requests) return [];
+  const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+  const ratio = u.hitRatio === null ? "n/a" : `${(u.hitRatio * 100).toFixed(1)}%`;
+  const lines = [`prompt cache: ${plural(u.requests, "request")} (${u.withCacheCounts} with cache counts), hit ratio ${ratio}`
+    + ` (read ${u.cacheReadTokens} / read + creation ${u.cacheCreationTokens} + uncached ${u.inputTokens})`];
+  const avg = (g) => (g.withCacheCounts ? Math.round(g.cacheCreationTokens / g.withCacheCounts) : "n/a");
+  lines.push(`  cache creation: ${u.newCut.cacheCreationTokens} on ${plural(u.newCut.requests, "request")} making a new cut`
+    + ` (avg ${avg(u.newCut)}), ${u.other.cacheCreationTokens} on ${plural(u.other.requests, "other")} (avg ${avg(u.other)})`);
+  const counts = Object.entries(u.breakpoints).map(([n, k]) => `${n}: ${k}`).join(", ");
+  if (counts) {
+    lines.push(`  cache_control breakpoints per request: ${counts}; top layouts `
+      + u.breakpointLayouts.map((x) => `${x.at} (${x.requests})`).join(", "));
+  }
+  return lines;
+}
+
+function parseArgs(argv) {
+  const flags = { action: argv[0], dry: false, json: false, agents: [], help: false, unknown: [] };
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--dry-run") flags.dry = true;
+    else if (a === "--json") flags.json = true;
+    else if (a === "--agents") flags.agents = String(argv[++i] || "").split(",").map((s) => s.trim()).filter(Boolean);
+    else if (a === "--help" || a === "-h") flags.help = true;
+    else flags.unknown.push(a);
+  }
+  if (["--help", "-h", "help"].includes(flags.action)) flags.help = true;
+  return flags;
+}
+
+/**
+ * `openmem context on|off|status`. Returns the exit code.
+ * @param {{ argv: string[], home: string, stackRoot: string, env?: NodeJS.ProcessEnv,
+ *   log?: { info: (m: string) => void, warn: (m: string) => void },
+ *   spawn?: typeof spawnSync, fetch?: typeof fetch }} opts
+ */
+export async function runContextCommand(opts) {
+  const { home, stackRoot } = opts;
+  const env = opts.env || process.env;
+  const log = opts.log || { info: (m) => console.log(m), warn: (m) => console.warn(m) };
+  const spawn = opts.spawn || spawnSync;
+  const flags = parseArgs(opts.argv);
+  if (flags.help) {
+    log.info(HELP);
+    return 0;
+  }
+  const badAgents = flags.agents.filter((a) => !CONTEXT_AGENT_KEYS.includes(a));
+  if (!["on", "off", "status"].includes(flags.action) || flags.unknown.length || badAgents.length) {
+    if (badAgents.length) log.warn(`unknown agent: ${badAgents.join(", ")} (known: ${CONTEXT_AGENT_KEYS.join(", ")})`);
+    log.warn(HELP);
+    return 2;
+  }
+  if (flags.action === "status") {
+    const s = await contextStatus({ home, stackRoot, fetch: opts.fetch, env });
+    if (flags.json) log.info(JSON.stringify(s, null, 2));
+    else {
+      for (const [k, a] of Object.entries(s.agents)) {
+        log.info(`${k.padEnd(12)} ${a.on ? "on " : "off"}  ${a.saved ? "saved" : s.enabledSaved ? `follows enabled = ${s.enabled}` : "default"}  (${a.route})`);
+      }
+      log.info(`context proxy http://127.0.0.1:${s.port}: ${s.proxyUp ? "up" : "not answering"}`);
+      log.info(`agents pointed at the proxy: ${s.pointedAgents.length ? s.pointedAgents.join(", ") : "none"}`);
+      for (const line of eventLines(s)) log.info(line);
+    }
+    return 0;
+  }
+  const on = flags.action === "on";
+  const keys = flags.agents.length ? flags.agents : CONTEXT_AGENT_KEYS;
+  const saved = updatePmConfigContextAgents(home, Object.fromEntries(keys.map((k) => [k, on])), { dry: flags.dry });
+  const summary = keys.map((k) => `${k} = ${on}`).join(", ");
+  log.info(`${saved.result === "dry-run" ? "[dry-run] would save" : "saved"} [context_proxy.agents] ${summary}`);
+  // install-coding-agent follows the saved values: it wires agents and starts or stops the service.
+  const args = [path.join(PKG_ROOT, "cli", "install-coding-agent.mjs"), "--yes"];
+  if (flags.dry) args.push("--dry-run");
+  return spawn(process.execPath, args, { stdio: "inherit", env }).status ?? 1;
+}
+
+if (isMainModule(import.meta.url)) {
+  const home = process.env.HOME || "";
+  const sr = resolveStackRoot({ pkgRoot: PKG_ROOT });
+  runContextCommand({ argv: process.argv.slice(2), home, stackRoot: sr.root }).then(
+    (code) => process.exit(code),
+    (err) => {
+      console.error(err);
+      process.exit(1);
+    },
+  );
+}

package/cli/feed-sync.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/** Run indexer/feed_sync.py (RSS + OpenAlex → markdown cache). */
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isMainModule } from "./is-main.mjs";
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const script = path.join(PKG_ROOT, "indexer", "feed_sync.py");
+
+export function pythonCandidates(platform = process.platform, env = process.env) {
+  if (env.PYTHON) return [[env.PYTHON, []]];
+  return platform === "win32" ? [["py", ["-3"]], ["python", []]] : [["python3", []], ["python", []]];
+}
+
+if (isMainModule(import.meta.url)) {
+  let missing = true;
+  for (const [command, prefix] of pythonCandidates()) {
+    const result = spawnSync(command, [...prefix, script, ...process.argv.slice(2)], { stdio: "inherit", cwd: PKG_ROOT });
+    if (result.error?.code === "ENOENT") continue;
+    missing = false;
+    if (result.error) console.error(`feed-sync: ${result.error.message}`);
+    process.exit(result.status ?? 1);
+  }
+  if (missing) console.error("feed-sync: Python 3 not found; install Python 3 with PyYAML or set PYTHON to its executable");
+  process.exit(1);
+}

package/cli/install-coding-agent.mjs

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+/**
+ * Install coding-agent session memory for Claude Code, Codex, OpenCode, Cursor CLI.
+ * All providers: unified MCP. Session hooks come from OpenMem ([agents] integration =
+ * "openmem", default) or the provider's own plugin ("provider", Hindsight only); never both.
+ * Optional: rtk command rewriting when rtk is on PATH, and the local context proxy.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CODING_AGENTS, DEFAULT_AGENT_IDS } from "./coding-agent/agents.mjs";
+import { AGENT_IDS, PROVIDER_CAPABILITIES } from "./coding-agent/capabilities.mjs";
+import { installSessionShim, removeSessionShim, removeUpstreamHooks } from "./coding-agent/install-shim.mjs";
+import { installAgentAccess } from "./coding-agent/install-access.mjs";
+import { contextProxyStartCommand, installContextProxy, probeContextProxy } from "./coding-agent/install-context-proxy.mjs";
+import { upsertEnvFile } from "./coding-agent/file-io.mjs";
+import { installRtk } from "./coding-agent/install-rtk.mjs";
+import { removeUpstreamAccess } from "./coding-agent/remove-upstream-access.mjs";
+import { opencodeMajorVersion } from "./coding-agent/opencode-config.mjs";
+import { prepareAgentRuntime } from "./coding-agent/runtime.mjs";
+import { SHIM_AGENT_IDS } from "./coding-agent/hook-harnesses.mjs";
+import { resolveMemoryProvider } from "./install-memory-mcp.mjs";
+import { isMainModule } from "./is-main.mjs";
+import { resolveHindsightApiUrl } from "./mcp/context.mjs";
+import { resolveStackRoot } from "./stack.mjs";
+import { runInstallMemoryMcp } from "./install-memory-mcp.mjs";
+import { ensureContextProxyService, proxyServiceNeeded } from "./context-management.mjs";
+import {
+  agentIntegrationFromPmConfig,
+  contextAgentsFromPmConfig,
+  contextProxyFromPmConfig,
+  contextProxyStackEnvFromPmConfig,
+  loadPmConfig,
+  updatePmConfigTable,
+} from "../wizard/lib/pm-config.mjs";
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const BIN = "openmem-install-coding-agent";
+/** Providers that ship their own coding-agent plugin. */
+const PROVIDER_PLUGINS = ["hindsight"];
+
+const HELP = `${BIN}: wire session memory for coding agents
+
+Usage:
+  npx openmem install-coding-agent [--yes] [--dry-run] [--agents a,b]
+      [--provider-plugin | --no-provider-plugin] [--no-rtk]
+      [--context-proxy | --no-context-proxy]
+
+Default agents: ${DEFAULT_AGENT_IDS.join(", ")}
+All known agents: ${CODING_AGENTS.map((a) => a.id).join(", ")}
+
+Every provider gets install-mcp. Session hooks are exclusive:
+  default             openmem hooks (SessionStart / prompt / Stop); removes upstream Hindsight
+                      hooks, its "hindsight" MCP server and its hindsight-coding-agent skill
+  --provider-plugin   the provider's own plugin (Hindsight: hindsight-coding-agents); removes openmem hooks
+  --no-provider-plugin  switch back to openmem hooks
+The choice is saved as [agents] integration in ~/.config/personal-memory/config.toml.
+--hindsight-plugin was renamed to --provider-plugin.
+
+rtk on PATH: runs rtk init for each supported agent (skip with --no-rtk).
+Context proxy: without a flag, [context_proxy.agents] claude-code / opencode1 / codex (missing keys follow
+[context_proxy] enabled) choose which agents go through the local context proxy. With a stack root,
+the installer starts the context-proxy service when one of them is on and stops it when none is.
+--context-proxy / --no-context-proxy override every agent for this run and save [context_proxy] enabled.
+`;
+
+function parseArgs(argv) {
+  const flags = {
+    yes: false,
+    dry: false,
+    help: false,
+    providerPlugin: undefined,
+    rtk: true,
+    contextProxy: undefined,
+    agents: [...DEFAULT_AGENT_IDS],
+    unknown: [],
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--yes" || a === "-y") flags.yes = true;
+    else if (a === "--dry-run") flags.dry = true;
+    else if (a === "--help" || a === "-h") flags.help = true;
+    else if (a === "--provider-plugin") flags.providerPlugin = true;
+    else if (a === "--no-provider-plugin") flags.providerPlugin = false;
+    else if (a === "--no-rtk") flags.rtk = false;
+    else if (a === "--context-proxy") flags.contextProxy = true;
+    else if (a === "--no-context-proxy") flags.contextProxy = false;
+    else if (a === "--agents") flags.agents = String(argv[++i] || "").split(",").map((s) => s.trim()).filter(Boolean);
+    else flags.unknown.push(a);
+  }
+  return flags;
+}
+
+function h() {
+  return {
+    info: (m) => console.log(m),
+    ok: (m) => console.log(m),
+    warn: (m) => console.warn(m),
+  };
+}
+
+/** Resolve integration and proxy settings from flags, then config; persist flag choices. */
+function resolveSettings({ home, stackRoot, flags, write, log }) {
+  const cfg = loadPmConfig(home, stackRoot || home).merged;
+  const providerFlag = flags.providerPlugin;
+  const integration = providerFlag === undefined ? agentIntegrationFromPmConfig(cfg) : providerFlag ? "provider" : "openmem";
+  const proxy = contextProxyFromPmConfig(cfg);
+  const contextAgents = contextAgentsFromPmConfig(cfg).agents;
+  if (flags.contextProxy !== undefined) {
+    proxy.enabled = flags.contextProxy;
+    for (const k of Object.keys(contextAgents)) contextAgents[k] = flags.contextProxy;
+  }
+  if (providerFlag !== undefined) {
+    const r = updatePmConfigTable(home, "agents", { integration }, { dry: !write });
+    log.info(`${r === "dry-run" ? "dry-run: would save" : "saved"} [agents] integration = "${integration}"`);
+  }
+  if (flags.contextProxy !== undefined) {
+    const r = updatePmConfigTable(home, "context_proxy", { enabled: proxy.enabled }, { dry: !write });
+    log.info(`${r === "dry-run" ? "dry-run: would save" : "saved"} [context_proxy] enabled = ${proxy.enabled}`);
+  }
+  return { integration, proxy, contextAgents, cfg };
+}
+
+/** Copy config.toml's proxy settings into the stack .env compose reads, when that file exists. */
+function syncProxyStackEnv({ stackRoot, cfg, log }) {
+  const entries = contextProxyStackEnvFromPmConfig(cfg);
+  const file = stackRoot ? path.join(stackRoot, ".env") : "";
+  if (!file || !Object.keys(entries).length || !fs.existsSync(file)) return;
+  upsertEnvFile(file, entries);
+  log.ok(`context proxy settings → ${file} (${Object.keys(entries).join(", ")})`);
+}
+
+/** Warn loudly when the proxy is not answering: Claude Code fails every request until it runs. */
+async function warnIfProxyDown({ port, startCommand, log, fetch }) {
+  if (await probeContextProxy(port, { fetch })) {
+    log.ok(`context proxy is up on http://127.0.0.1:${port}`);
+    return true;
+  }
+  const bar = "!".repeat(72);
+  log.warn([
+    bar,
+    `! Context proxy is NOT running on http://127.0.0.1:${port}.`,
+    "! Claude Code (and OpenCode 1) now send every request there and will fail until it runs.",
+    `! Start it:   ${startCommand}`,
+    "! Or disable: npx openmem install-coding-agent --yes --no-context-proxy",
+    bar,
+  ].join("\n"));
+  return false;
+}
+
+export async function runInstallCodingAgent(opts) {
+  const home = opts.home;
+  const env = opts.env || process.env;
+  const flags = opts.flags;
+  const log = opts.h || h();
+  for (const agentId of flags.agents) {
+    if (!AGENT_IDS.includes(agentId)) {
+      log.warn(`Unknown agent "${agentId}" (known: ${AGENT_IDS.join(", ")})`);
+    }
+  }
+  const provider = resolveMemoryProvider(home, env);
+  const caps = PROVIDER_CAPABILITIES[provider] || {};
+  log.info(`Provider ${provider}: capabilities ${JSON.stringify(caps)}`);
+
+  const dry = flags.dry || !flags.yes;
+  const { integration, proxy, contextAgents, cfg } = resolveSettings({ home, stackRoot: opts.stackRoot, flags, write: !dry, log });
+  const project = env.PM_PROJECT || String(cfg.stack?.project || "") || "openmem";
+  const startCommand = contextProxyStartCommand({ stackRoot: opts.stackRoot, project });
+  // OpenCode 2 never uses the proxy; its plugin reads [context_proxy.agents] opencode2 itself.
+  const agentEnabled = { "claude-code": contextAgents["claude-code"], opencode: contextAgents.opencode1, codex: contextAgents.codex };
+  const serviceOn = proxyServiceNeeded(contextAgents);
+  const service = (dryRun) => ensureContextProxyService({
+    home, stackRoot: opts.stackRoot, project, on: serviceOn, dry: dryRun, env, spawn: opts.docker, log,
+  });
+  const useProviderPlugin = integration === "provider" && PROVIDER_PLUGINS.includes(provider);
+  if (integration === "provider" && !useProviderPlugin) {
+    log.warn(`Provider ${provider} has no coding-agent plugin; installing openmem hooks instead`);
+  }
+  const shimAgents = flags.agents.filter((id) => SHIM_AGENT_IDS.includes(id) || id === "opencode");
+  const opencodeMajor = flags.agents.includes("opencode") ? opencodeMajorVersion({ env }) : 1;
+  const runtimeRoot = prepareAgentRuntime({
+    home, repoRoot: opts.repoRoot, stackRoot: opts.stackRoot, dry, h: log,
+  });
+  const upstreamCmd = () => {
+    const apiUrl = resolveHindsightApiUrl({ home, stackRoot: opts.stackRoot, env });
+    return ["npx", "-y", "@vectorize-io/hindsight-coding-agents", "install", ...flags.agents, "--server", "self-hosted", "--api-url", apiUrl];
+  };
+  if (flags.dry) {
+    log.info("dry-run: would run install-mcp --yes");
+    if (useProviderPlugin) {
+      removeSessionShim({ home, agents: shimAgents, dry: true, h: log });
+    } else {
+      installSessionShim({ home, repoRoot: runtimeRoot, agents: shimAgents, dry: true, h: log, opencodeMajor });
+      removeUpstreamHooks({ home, agents: shimAgents, dry: true, h: log });
+      removeUpstreamAccess({ home, agents: flags.agents, dry: true, h: log });
+    }
+    installAgentAccess({ home, runtimeRoot, stackRoot: opts.stackRoot, agents: flags.agents, dry: true, h: log });
+    if (flags.rtk) installRtk({ agents: flags.agents, env, dry: true, h: log, opencodeMajor });
+    installContextProxy({ home, agents: flags.agents, enabled: proxy.enabled, agentEnabled, port: proxy.port, dry: true, h: log, opencodeMajor });
+    service(true);
+    if (useProviderPlugin) log.info(`dry-run: would also run ${upstreamCmd().join(" ")}`);
+    return { provider, integration, ran: false };
+  }
+  if (!flags.yes) {
+    log.warn("Re-run with --yes to install MCP + session hooks");
+    return { provider, integration, ran: false };
+  }
+
+  await runInstallMemoryMcp({
+    home,
+    repoRoot: runtimeRoot,
+    stackRoot: opts.stackRoot,
+    flags: { yes: true, dry: false, notebooklm: false, notebooklmOnly: false, providerOnly: false, noUnifiedMcp: false, help: false, unknown: [] },
+    env,
+    h: log,
+  });
+  if (useProviderPlugin) {
+    removeSessionShim({ home, agents: shimAgents, h: log });
+  } else {
+    installSessionShim({ home, repoRoot: runtimeRoot, agents: shimAgents, dry: false, h: log, opencodeMajor });
+    removeUpstreamHooks({ home, agents: shimAgents, h: log });
+    removeUpstreamAccess({ home, agents: flags.agents, h: log });
+  }
+  installAgentAccess({
+    home, runtimeRoot, stackRoot: opts.stackRoot, agents: flags.agents, dry: false, h: log,
+  });
+  const rtk = flags.rtk ? installRtk({ agents: flags.agents, env, h: log, spawn: opts.spawn, opencodeMajor }) : { rtk: null, ran: [] };
+  // On: start the service before agents point at it. Off: stop it after they are unwired.
+  if (serviceOn) service(false);
+  const proxyOut = installContextProxy({ home, agents: flags.agents, enabled: proxy.enabled, agentEnabled, port: proxy.port, h: log, opencodeMajor });
+  if (!serviceOn) service(false);
+  const proxyUsed = flags.agents.some((id) => id in agentEnabled && agentEnabled[id] && !proxyOut.pluginTrimmed.includes(id));
+  if (proxyUsed) {
+    syncProxyStackEnv({ stackRoot: opts.stackRoot, cfg, log });
+    await warnIfProxyDown({ port: proxy.port, startCommand, log, fetch: opts.fetch });
+  }
+
+  let status = 0;
+  if (useProviderPlugin) {
+    const cmd = upstreamCmd();
+    log.info(`Installing upstream Hindsight plugin: ${cmd.join(" ")}`);
+    const r = (opts.spawn || spawnSync)(cmd[0], cmd.slice(1), { stdio: "inherit", env });
+    status = r.status ?? 1;
+  }
+
+  for (const agentId of flags.agents) {
+    if (shimAgents.includes(agentId)) {
+      const hooks = useProviderPlugin ? "upstream Hindsight hooks" : "openmem session hooks";
+      const extras = [
+        rtk.ran.includes(agentId) ? "rtk" : "",
+        proxyOut.changed.includes(agentId) && agentEnabled[agentId] ? "context proxy" : "",
+        !useProviderPlugin && proxyOut.pluginTrimmed.includes(agentId) ? "native context trimming (OpenCode 2; context proxy not used)" : "",
+      ].filter(Boolean);
+      log.info(`  ${agentId}: ${hooks} + unified MCP${extras.length ? ` + ${extras.join(" + ")}` : ""}`);
+    } else {
+      const row = CODING_AGENTS.find((a) => a.id === agentId);
+      log.info(`  ${agentId}: ${row?.sessionPath || "unified MCP memory_*"}`);
+    }
+  }
+  if (agentEnabled["claude-code"] && flags.agents.includes("claude-code")) {
+    log.info(`Context proxy enabled: Claude Code now sends every request to http://127.0.0.1:${proxy.port}; start the proxy before using Claude Code: ${startCommand}`);
+  }
+  return { provider, integration, ran: true, status };
+}
+
+async function main() {
+  const flags = parseArgs(process.argv.slice(2));
+  if (flags.unknown.includes("--hindsight-plugin")) {
+    console.error("install-coding-agent: --hindsight-plugin was renamed to --provider-plugin");
+    process.exit(2);
+  }
+  if (flags.help || flags.unknown.length) {
+    console.log(HELP);
+    process.exit(flags.unknown.length ? 2 : 0);
+  }
+  const home = process.env.HOME || "";
+  const sr = resolveStackRoot({ pkgRoot: PKG_ROOT });
+  const out = await runInstallCodingAgent({
+    home,
+    repoRoot: PKG_ROOT,
+    stackRoot: sr.root,
+    flags,
+    env: process.env,
+    h: h(),
+  });
+  return typeof out.status === "number" ? out.status : 0;
+}
+
+if (isMainModule(import.meta.url)) {
+  main().then(
+    (code) => process.exit(code ?? 0),
+    (err) => {
+      console.error(err);
+      process.exit(1);
+    },
+  );
+}