forget-connect 0.5.1 → 0.6.0

package/src/hooks.js

@@ -1,8 +1,7 @@
 // The hooks layer is the product thesis made real: memory that arrives
-// without being asked. Claude Code gets four harness hooks — a session-start
-// context capsule, per-turn push recall with conflict-zone alerts, and
-// session capture feeding the outcome flywheel. Other clients (Codex,
-// Desktop) rely on instruction rules until they grow hook systems.
+// without being asked. Claude Code and Codex share the same scripts and
+// ownership rules, while each receives only lifecycle events its client
+// actually emits. Desktop continues to rely on instruction rules.
 //
 // First rule of touching ~/.claude/settings.json: it is the user's file.
 // Foreign hooks (other tools register there too) must survive connect,
@@ -20,6 +19,7 @@ export const HOOK_SCRIPTS = [
   "forget_sessionstart.py",
   "forget_turnrecall.py",
   "forget_capture.py",
+  "forget_bstate.py", // compact structured working state shared by both clients
   "forget_project.py", // shared project-boundary detection (imported by the others)
   "forget_projecttag.py", // PreToolUse: stamps memory/task writes with the cwd's project
 ];
@@ -47,6 +47,9 @@ export function hooksDirFor(options = {}) {
 export function settingsPathFor(options = {}) {
   const env = options.env ?? process.env;
   const home = options.home ?? env.HOME ?? env.USERPROFILE ?? os.homedir();
+  if (options.clientId === "codex") {
+    return path.join(env.CODEX_HOME ?? path.join(home, ".codex"), "hooks.json");
+  }
   return path.join(home, ".claude", "settings.json");
 }
 
@@ -55,8 +58,8 @@ export function hookCommand(script, { hooksDir, url }) {
   return `FORGET_MCP_URL=${shellQuote(url)} python3 ${shellQuote(scriptPath)}`;
 }
 
-export function hookEntries({ hooksDir, url }) {
-  return {
+export function hookEntries({ hooksDir, url, clientId = "claude-code" }) {
+  const shared = {
     SessionStart: {
       command: hookCommand("forget_sessionstart.py", { hooksDir, url }),
       timeout: 12,
@@ -67,6 +70,23 @@ export function hookEntries({ hooksDir, url }) {
       timeout: 6,
       statusMessage: "forget: checking relevant memories",
     },
+  };
+  if (clientId === "codex") {
+    return {
+      ...shared,
+      SessionStart: {
+        ...shared.SessionStart,
+        matcher: "startup|resume|compact",
+      },
+      Stop: {
+        command: hookCommand("forget_capture.py", { hooksDir, url }),
+        timeout: 10,
+        statusMessage: "forget: capturing turn + outcome",
+      },
+    };
+  }
+  return {
+    ...shared,
     PreCompact: {
       command: hookCommand("forget_capture.py", { hooksDir, url }),
       timeout: 10,
@@ -127,10 +147,11 @@ function validatedHooks(config, label) {
   return hooks;
 }
 
-export function connectHooksSettings(raw, { hooksDir, url }) {
-  const config = parseJsonStrict(raw, "settings.json");
-  const hooks = validatedHooks(config, "settings.json");
-  for (const [event, entry] of Object.entries(hookEntries({ hooksDir, url }))) {
+export function connectHooksSettings(raw, { hooksDir, url, clientId = "claude-code" }) {
+  const label = clientId === "codex" ? "hooks.json" : "settings.json";
+  const config = parseJsonStrict(raw, label);
+  const hooks = validatedHooks(config, label);
+  for (const [event, entry] of Object.entries(hookEntries({ hooksDir, url, clientId }))) {
     const groups = withoutOurHooks(hooks[event] ?? []);
     const group = {
       hooks: [{
@@ -148,10 +169,11 @@ export function connectHooksSettings(raw, { hooksDir, url }) {
   return `${JSON.stringify(config, null, 2)}\n`;
 }
 
-export function disconnectHooksSettings(raw) {
-  const config = parseJsonStrict(raw, "settings.json");
+export function disconnectHooksSettings(raw, { clientId = "claude-code" } = {}) {
+  const label = clientId === "codex" ? "hooks.json" : "settings.json";
+  const config = parseJsonStrict(raw, label);
   if (config.hooks === undefined) return raw;
-  const hooks = validatedHooks(config, "settings.json");
+  const hooks = validatedHooks(config, label);
   let touched = false;
   for (const [event, groups] of Object.entries(hooks)) {
     const cleaned = withoutOurHooks(groups);
@@ -168,15 +190,19 @@ export function disconnectHooksSettings(raw) {
   return `${JSON.stringify(config, null, 2)}\n`;
 }
 
-export function hooksInstalled(raw, { hooksDir } = {}) {
+export function hooksInstalled(raw, { hooksDir, clientId = "claude-code" } = {}) {
   let config;
   try {
-    config = parseJsonStrict(raw, "settings.json");
+    config = parseJsonStrict(raw, clientId === "codex" ? "hooks.json" : "settings.json");
   } catch {
     return false;
   }
   if (!isObject(config.hooks)) return false;
-  const events = Object.keys(hookEntries({ hooksDir: hooksDir ?? "", url: "http://x" }));
+  const events = Object.keys(hookEntries({
+    hooksDir: hooksDir ?? "",
+    url: "http://x",
+    clientId,
+  }));
   return events.every((event) => {
     const groups = config.hooks[event];
     return Array.isArray(groups) && groups.some(
@@ -214,16 +240,16 @@ export async function installHookScripts(hooksDir) {
   return written;
 }
 
-export async function inspectHooks({ env } = {}) {
+export async function inspectHooks({ env, clientId = "claude-code" } = {}) {
   const hooksDir = hooksDirFor({ env });
-  const settingsPath = settingsPathFor({ env });
+  const settingsPath = settingsPathFor({ env, clientId });
   let settingsRaw = "";
   try {
     settingsRaw = await readFile(settingsPath, "utf8");
   } catch {
     settingsRaw = "";
   }
-  const registered = hooksInstalled(settingsRaw, { hooksDir });
+  const registered = hooksInstalled(settingsRaw, { hooksDir, clientId });
   let scriptsPresent = true;
   for (const script of HOOK_SCRIPTS) {
     try {
@@ -258,3 +284,57 @@ export async function removeHookScripts(hooksDir) {
   }
   return removed;
 }
+
+// --- slash commands (/forget, /forget-settings) — the dial in the editor ---
+//
+// Same file-ownership rule as settings.json: a command file without our
+// marker is the user's (hand-written or edited with the marker removed) and
+// is never touched — not on connect, not on disconnect.
+
+export const COMMAND_ASSETS = ["forget.md", "forget-settings.md"];
+export const COMMAND_MARKER = "forget-connect:command";
+
+export function commandsDirFor(options = {}) {
+  const env = options.env ?? process.env;
+  const home = options.home ?? env.HOME ?? env.USERPROFILE ?? os.homedir();
+  return path.join(home, ".claude", "commands");
+}
+
+function commandAssetsDir() {
+  return fileURLToPath(new URL("../assets/commands/", import.meta.url));
+}
+
+export async function installCommandAssets(commandsDir) {
+  const written = [];
+  for (const name of COMMAND_ASSETS) {
+    const target = path.join(commandsDir, name);
+    let existing = null;
+    try {
+      existing = await readFile(target, "utf8");
+    } catch (error) {
+      if (!error || error.code !== "ENOENT") throw error;
+    }
+    if (existing !== null && !existing.includes(COMMAND_MARKER)) continue;
+    const content = await readFile(path.join(commandAssetsDir(), name), "utf8");
+    if (existing === content) continue;
+    await atomicWrite(target, content, 0o644);
+    written.push(target);
+  }
+  return written;
+}
+
+export async function removeCommandAssets(commandsDir) {
+  const removed = [];
+  for (const name of COMMAND_ASSETS) {
+    const target = path.join(commandsDir, name);
+    try {
+      const existing = await readFile(target, "utf8");
+      if (!existing.includes(COMMAND_MARKER)) continue;
+      await unlink(target);
+      removed.push(target);
+    } catch (error) {
+      if (!error || error.code !== "ENOENT") throw error;
+    }
+  }
+  return removed;
+}

package/src/proxy.js

@@ -0,0 +1,431 @@
+// Zero-config capture proxy wiring (proxy-native redesign §1).
+//
+// The proxy is the data plane's spine: pointing Claude Code's
+// ANTHROPIC_BASE_URL at a local passthrough proxy turns every LLM call into
+// an out-of-band capture, no cooperation from the agent required. The user
+// never has to know it exists — connect registers a launchd KeepAlive
+// service (`ai.forget.proxy`, same convention as ai.forget.server) plus a
+// health watchdog, and writes the env override into ~/.claude/settings.json.
+//
+// Three wiring rules, in priority order:
+//   (a) an existing custom base URL is *chained* as the proxy's --upstream,
+//       never discarded — the user's gateway keeps seeing their traffic;
+//   (b) a value that is already our proxy is a no-op;
+//   (c) anything unparseable or structurally odd skips the wiring entirely
+//       with a warning. Zero-config must never mean silently broken.
+// Disconnect and the watchdog are symmetric: they only ever remove the value
+// *we* wrote, and they restore the original the user had.
+
+import { execFile } from "node:child_process";
+import { constants as fsConstants } from "node:fs";
+import { access, readFile, unlink } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { atomicWrite, parseJsonStrict } from "./core.js";
+
+export const PROXY_LABEL = "ai.forget.proxy";
+export const WATCHDOG_LABEL = "ai.forget.proxy.watchdog";
+export const PROXY_HOST = "127.0.0.1";
+export const PROXY_PORT = 8377;
+export const PROXY_BASE_URL = `http://${PROXY_HOST}:${PROXY_PORT}`;
+export const WATCHDOG_SCRIPT = "forget_proxy_watchdog.py";
+export const WATCHDOG_INTERVAL_SECONDS = 60;
+
+const ENV_KEY = "ANTHROPIC_BASE_URL";
+const LOOPBACK_HOSTS = new Set([PROXY_HOST, "localhost", "[::1]"]);
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// --- paths -------------------------------------------------------------------
+
+function homeFor(options = {}) {
+  const env = options.env ?? process.env;
+  return options.home ?? env.HOME ?? env.USERPROFILE ?? os.homedir();
+}
+
+export function forgetHomeFor(options = {}) {
+  const env = options.env ?? process.env;
+  return env.FORGET_HOME || path.join(homeFor(options), ".forget");
+}
+
+export function proxyDirFor(options = {}) {
+  return path.join(forgetHomeFor(options), "proxy");
+}
+
+export function wiringStatePathFor(options = {}) {
+  return path.join(proxyDirFor(options), "wiring.json");
+}
+
+export function watchdogStatePathFor(options = {}) {
+  return path.join(proxyDirFor(options), "watchdog-state.json");
+}
+
+export function watchdogScriptPathFor(options = {}) {
+  return path.join(proxyDirFor(options), WATCHDOG_SCRIPT);
+}
+
+export function launchAgentsDirFor(options = {}) {
+  return path.join(homeFor(options), "Library", "LaunchAgents");
+}
+
+export function plistPathFor(label, options = {}) {
+  return path.join(launchAgentsDirFor(options), `${label}.plist`);
+}
+
+// --- settings.json env wiring (pure) ----------------------------------------
+
+export function isProxyBaseUrl(value) {
+  if (typeof value !== "string") return false;
+  let parsed;
+  try {
+    parsed = new URL(value.trim());
+  } catch {
+    return false;
+  }
+  return (
+    parsed.protocol === "http:"
+    && LOOPBACK_HOSTS.has(parsed.hostname.toLowerCase())
+    && (parsed.port || "80") === String(PROXY_PORT)
+    && (parsed.pathname === "/" || parsed.pathname === "")
+    && !parsed.search
+  );
+}
+
+function chainableUpstream(value) {
+  let parsed;
+  try {
+    parsed = new URL(value.trim());
+  } catch {
+    return null;
+  }
+  if (!["http:", "https:"].includes(parsed.protocol)) return null;
+  return value.trim().replace(/\/+$/, "");
+}
+
+/**
+ * Decide what connect does to the settings.json env block.
+ * Returns { status: "wire"|"noop"|"skip", next, upstream, original, reason }.
+ * Pure: never touches the filesystem, never throws on user data.
+ */
+export function wireProxyEnv(raw) {
+  let config;
+  try {
+    config = parseJsonStrict(raw, "settings.json");
+  } catch {
+    // (c) a settings file we cannot parse is a settings file we do not edit.
+    return {
+      status: "skip",
+      next: raw,
+      upstream: null,
+      original: null,
+      reason: "settings.json is not valid JSON",
+    };
+  }
+  if (config.env !== undefined && !isObject(config.env)) {
+    return {
+      status: "skip",
+      next: raw,
+      upstream: null,
+      original: null,
+      reason: "the existing env value in settings.json is not a JSON object",
+    };
+  }
+  const env = config.env ?? {};
+  const current = env[ENV_KEY];
+  if (current === undefined || current === "") {
+    // Fresh wire: no override existed; upstream stays the proxy's default.
+    env[ENV_KEY] = PROXY_BASE_URL;
+    config.env = env;
+    return {
+      status: "wire",
+      next: `${JSON.stringify(config, null, 2)}\n`,
+      upstream: null,
+      original: null,
+      reason: "",
+    };
+  }
+  if (isProxyBaseUrl(current)) {
+    // (b) already us — nothing to do.
+    return { status: "noop", next: raw, upstream: null, original: null, reason: "" };
+  }
+  if (typeof current !== "string") {
+    return {
+      status: "skip",
+      next: raw,
+      upstream: null,
+      original: null,
+      reason: `the existing ${ENV_KEY} in settings.json is not a string`,
+    };
+  }
+  const upstream = chainableUpstream(current);
+  if (!upstream) {
+    return {
+      status: "skip",
+      next: raw,
+      upstream: null,
+      original: null,
+      reason: `the existing ${ENV_KEY} in settings.json is not an http(s) URL`,
+    };
+  }
+  // (a) chain the user's gateway behind the proxy and take its place.
+  env[ENV_KEY] = PROXY_BASE_URL;
+  config.env = env;
+  return {
+    status: "wire",
+    next: `${JSON.stringify(config, null, 2)}\n`,
+    upstream,
+    original: current,
+    reason: "",
+  };
+}
+
+/**
+ * Remove the env override — only when the current value is ours — and put
+ * back whatever the user originally had. Symmetric with wireProxyEnv.
+ * Returns { status: "unwired"|"noop"|"skip", next, reason }.
+ */
+export function unwireProxyEnv(raw, { original = null } = {}) {
+  let config;
+  try {
+    config = parseJsonStrict(raw, "settings.json");
+  } catch {
+    return { status: "skip", next: raw, reason: "settings.json is not valid JSON" };
+  }
+  if (!isObject(config.env) || !(ENV_KEY in config.env)) {
+    return { status: "noop", next: raw, reason: "" };
+  }
+  if (!isProxyBaseUrl(config.env[ENV_KEY])) {
+    // Not our value — the user owns it now; never touch.
+    return { status: "noop", next: raw, reason: "" };
+  }
+  if (typeof original === "string" && original) {
+    config.env[ENV_KEY] = original;
+  } else {
+    delete config.env[ENV_KEY];
+    if (!Object.keys(config.env).length) delete config.env;
+  }
+  return { status: "unwired", next: `${JSON.stringify(config, null, 2)}\n`, reason: "" };
+}
+
+// --- launchd plists (same convention as forget/cli.py's ai.forget.server) ---
+
+function xmlEscape(value) {
+  return String(value)
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+}
+
+export function proxyPlist({ execPath, upstream = null, forgetHome, logPath }) {
+  const args = [execPath, "--host", PROXY_HOST, "--port", String(PROXY_PORT)];
+  // --upstream only when chaining a custom gateway; the default upstream
+  // stays owned by the proxy binary so it cannot drift in a stale plist.
+  if (upstream) args.push("--upstream", upstream);
+  const argStrings = args
+    .map((arg) => `    <string>${xmlEscape(arg)}</string>`)
+    .join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${PROXY_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${argStrings}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict><key>FORGET_HOME</key><string>${xmlEscape(forgetHome)}</string></dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${xmlEscape(logPath)}</string>
+  <key>StandardErrorPath</key><string>${xmlEscape(logPath)}</string>
+</dict>
+</plist>
+`;
+}
+
+export function watchdogPlist({ python3, scriptPath, forgetHome, logPath }) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${WATCHDOG_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xmlEscape(python3)}</string>
+    <string>${xmlEscape(scriptPath)}</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict><key>FORGET_HOME</key><string>${xmlEscape(forgetHome)}</string></dict>
+  <key>RunAtLoad</key><true/>
+  <key>StartInterval</key><integer>${WATCHDOG_INTERVAL_SECONDS}</integer>
+  <key>StandardOutPath</key><string>${xmlEscape(logPath)}</string>
+  <key>StandardErrorPath</key><string>${xmlEscape(logPath)}</string>
+</dict>
+</plist>
+`;
+}
+
+// --- wiring state (what the watchdog and disconnect need to undo us) --------
+
+export async function readWiringState(options = {}) {
+  let raw;
+  try {
+    raw = await readFile(wiringStatePathFor(options), "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return isObject(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeWiringState(options, { upstream, original }) {
+  const state = {
+    proxy_url: PROXY_BASE_URL,
+    original_base_url: original ?? null,
+    upstream: upstream ?? null,
+    wired_at: new Date().toISOString(),
+  };
+  await atomicWrite(
+    wiringStatePathFor(options),
+    `${JSON.stringify(state, null, 2)}\n`,
+    0o600,
+  );
+  return state;
+}
+
+// --- executables -------------------------------------------------------------
+
+export async function findExecutable(name, options = {}) {
+  const env = options.env ?? process.env;
+  for (const dir of (env.PATH ?? "").split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, name);
+    try {
+      await access(candidate, fsConstants.X_OK);
+      return candidate;
+    } catch {
+      // keep looking
+    }
+  }
+  return null;
+}
+
+// --- launchd side effects -----------------------------------------------------
+
+function launchctl(args) {
+  // bootout of a not-loaded service and bootstrap of an already-running one
+  // both fail by design; callers decide which failures matter.
+  return new Promise((resolve) => {
+    execFile("launchctl", args, (error, stdout, stderr) => {
+      resolve({ ok: !error, stdout: String(stdout), stderr: String(stderr) });
+    });
+  });
+}
+
+export function launchctlEnabled(options = {}) {
+  const env = options.env ?? process.env;
+  const platform = options.platform ?? process.platform;
+  // FORGET_PROXY_LAUNCHCTL=skip is the test seam: file wiring is exercised
+  // end-to-end while the real launchd is never touched from a test run.
+  return platform === "darwin" && env.FORGET_PROXY_LAUNCHCTL !== "skip";
+}
+
+function watchdogAssetPath() {
+  return fileURLToPath(new URL(`../assets/proxy/${WATCHDOG_SCRIPT}`, import.meta.url));
+}
+
+/**
+ * Install everything except the settings.json edit (the caller owns that
+ * through the normal change plan): watchdog script, both plists, launchd
+ * registration. Returns { installed, written, reason }.
+ */
+export async function installProxyServices(options, { upstream = null } = {}) {
+  const execPath = await findExecutable("forget-proxy", options);
+  if (!execPath) {
+    return {
+      installed: false,
+      written: [],
+      reason: "forget-proxy executable not found on PATH (pip install 'forget-ai[server]')",
+    };
+  }
+  const python3 = (await findExecutable("python3", options)) ?? "/usr/bin/python3";
+  const forgetHome = forgetHomeFor(options);
+  const written = [];
+
+  const scriptPath = watchdogScriptPathFor(options);
+  await atomicWrite(scriptPath, await readFile(watchdogAssetPath(), "utf8"), 0o755);
+  written.push(scriptPath);
+
+  const proxyPlistPath = plistPathFor(PROXY_LABEL, options);
+  await atomicWrite(
+    proxyPlistPath,
+    proxyPlist({ execPath, upstream, forgetHome, logPath: path.join(forgetHome, "proxy.log") }),
+    0o644,
+  );
+  written.push(proxyPlistPath);
+
+  const watchdogPlistPath = plistPathFor(WATCHDOG_LABEL, options);
+  await atomicWrite(
+    watchdogPlistPath,
+    watchdogPlist({
+      python3,
+      scriptPath,
+      forgetHome,
+      logPath: path.join(forgetHome, "proxy-watchdog.log"),
+    }),
+    0o644,
+  );
+  written.push(watchdogPlistPath);
+
+  if (launchctlEnabled(options)) {
+    const domain = `gui/${typeof process.getuid === "function" ? process.getuid() : 0}`;
+    for (const [label, plistFile] of [
+      [PROXY_LABEL, proxyPlistPath],
+      [WATCHDOG_LABEL, watchdogPlistPath],
+    ]) {
+      await launchctl(["bootout", `${domain}/${label}`]);
+      const boot = await launchctl(["bootstrap", domain, plistFile]);
+      if (!boot.ok) {
+        return {
+          installed: false,
+          written,
+          reason: `launchctl bootstrap ${label} failed: ${boot.stderr.trim() || "unknown error"}`,
+        };
+      }
+    }
+  }
+  return { installed: true, written, reason: "", execPath };
+}
+
+/** Symmetric teardown: bootout, then remove every file connect created. */
+export async function removeProxyServices(options = {}) {
+  if (launchctlEnabled(options)) {
+    const domain = `gui/${typeof process.getuid === "function" ? process.getuid() : 0}`;
+    await launchctl(["bootout", `${domain}/${WATCHDOG_LABEL}`]);
+    await launchctl(["bootout", `${domain}/${PROXY_LABEL}`]);
+  }
+  const removed = [];
+  for (const target of [
+    plistPathFor(WATCHDOG_LABEL, options),
+    plistPathFor(PROXY_LABEL, options),
+    watchdogScriptPathFor(options),
+    wiringStatePathFor(options),
+    watchdogStatePathFor(options),
+  ]) {
+    try {
+      await unlink(target);
+      removed.push(target);
+    } catch (error) {
+      if (!error || error.code !== "ENOENT") throw error;
+    }
+  }
+  return removed;
+}