@remnic/plugin-codex 1.0.1 → 9.3.517

package/README.md

@@ -14,7 +14,7 @@ Three discrete steps. None is automated end-to-end today; each writes to a diffe
 
     This writes `~/.remnic/connectors/codex-cli.json` (Remnic's connector-state file), stores a bearer token, and calls `@remnic/core`'s `installCodexMemoryExtension` which materializes `~/.codex/memories_extensions/remnic/instructions.md` (the local-only phase-2 consolidation guide; see the file-table row below). It does NOT write `~/.codex/config.toml` and it does NOT deploy `.codex-plugin/`, `hooks/`, or `skills/`.
 
-2. **Add Remnic as an MCP server in `~/.codex/config.toml`.** Paste the TOML block from the "MCP setup" section below, replacing `{{REMNIC_TOKEN}}` with the token from step 1. Without this step Codex has no way to talk to the Remnic daemon.
+2. **Add Remnic as an MCP server in `~/.codex/config.toml`.** Paste the TOML block from the "MCP setup" section below unchanged, then set `REMNIC_AUTH_TOKEN` in Codex's environment to the bearer token generated in step 1. Without this step Codex has no way to talk to the Remnic daemon.
 
 3. **Install this package and load it through Codex's plugin system** so the hooks, skills, and `.codex-plugin` manifest are actually active:
 
@@ -57,7 +57,7 @@ bearer_token_env_var = "REMNIC_AUTH_TOKEN"
 http_headers = { "X-Engram-Client-Id" = "codex" }
 ```
 
-Then export the token Codex looks up. `remnic token generate` prints a multi-line status block (not just the raw token), so either:
+Then export the token Codex looks up. Use the bearer token printed by `remnic connectors install codex-cli`. If you need to mint a replacement, `remnic token generate` prints a multi-line status block (not just the raw token), so either:
 
 Copy the `Token:` value from:
 
@@ -84,10 +84,11 @@ See `docs/integration/connector-setup.md` in the Remnic repo for the canonical s
 
 ## Agent note
 
-If you're an AI agent scaffolding a Codex integration: **do not** hand-edit `~/.codex/` directly. The full setup has two components:
+If you're an AI agent scaffolding a Codex integration: **do not** hand-edit `~/.codex/` directly. The full setup has three components:
 
-1. `remnic connectors install codex-cli` (drives `@remnic/core`'s `installCodexMemoryExtension`) handles the MCP config, token rotation, and writes `memories_extensions/remnic/instructions.md`. It does NOT deploy `.codex-plugin/`, `hooks/`, or `skills/`.
-2. Load this package into Codex via Codex's own plugin loader to activate the hooks and skills.
+1. `remnic connectors install codex-cli` mints/stores the Remnic bearer token, records connector state, and drives `@remnic/core`'s `installCodexMemoryExtension` to write `memories_extensions/remnic/instructions.md`. It does NOT write `~/.codex/config.toml` and does NOT deploy `.codex-plugin/`, `hooks/`, or `skills/`.
+2. Add the MCP TOML block above unchanged and expose the generated token as `REMNIC_AUTH_TOKEN`.
+3. Load this package into Codex via Codex's own plugin loader to activate the hooks and skills.
 
 `bin/materialize.cjs` is a runtime helper called only by the Codex `Stop` hook to refresh `~/.codex/memories` from the live Remnic store at session end; it's not an installer and not wired into any `remnic` CLI command, so re-running it manually won't recover a broken plugin install.
 

package/bin/materialize.cjs

@@ -68,58 +68,141 @@ function parseArgs(argv) {
   return args;
 }
 
+function isPlainRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+const OPENCLAW_REMNIC_PLUGIN_IDS = ["openclaw-remnic", "openclaw-engram"];
+
+function getOpenClawPluginEntries(raw) {
+  const plugins = isPlainRecord(raw.plugins) ? raw.plugins : undefined;
+  return plugins && isPlainRecord(plugins.entries) ? plugins.entries : undefined;
+}
+
+function getOpenClawMemorySlotId(raw) {
+  const plugins = isPlainRecord(raw.plugins) ? raw.plugins : undefined;
+  const slots = plugins && isPlainRecord(plugins.slots) ? plugins.slots : undefined;
+  return typeof slots?.memory === "string" ? slots.memory : undefined;
+}
+
+function resolveOpenClawRemnicPluginEntry(raw, resolveEntry) {
+  return resolveEntry(raw, {
+    candidateIds: OPENCLAW_REMNIC_PLUGIN_IDS,
+    getEntries: getOpenClawPluginEntries,
+    getSlotId: getOpenClawMemorySlotId,
+  });
+}
+
+class MaterializeConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MaterializeConfigError";
+  }
+}
+
+function envValue(env, key) {
+  const value = env[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function expandConfigPathForEnv(filePath, home) {
+  if (filePath === undefined) return undefined;
+  if (filePath === "~") return home.length > 0 ? home : filePath;
+  if (filePath.startsWith("~/") || filePath.startsWith("~\\")) {
+    return home.length > 0 ? path.join(home, filePath.slice(2)) : filePath;
+  }
+  return filePath;
+}
+
+function safeErrorDetail(error) {
+  const raw = error instanceof Error ? error.message : String(error);
+  const cleaned = raw
+    .replace(/[\r\n\t]+/g, " ")
+    .replace(/[^\w .,:;()[\]{}'"!?/@+-]/g, "?")
+    .trim();
+  return cleaned.length > 240 ? `${cleaned.slice(0, 237)}...` : cleaned;
+}
+
 /**
  * Return candidate config file paths to search, in priority order.
  * The caller is responsible for parsing and entry-resolution.
  */
-function configCandidates() {
-  const home = process.env.HOME || "";
+function configCandidates(env = process.env) {
+  const home = envValue(env, "HOME") || "";
   const openclawConfigPath =
-    process.env.OPENCLAW_ENGRAM_CONFIG_PATH ||
-    process.env.OPENCLAW_CONFIG_PATH ||
+    envValue(env, "OPENCLAW_CONFIG_PATH") ||
+    envValue(env, "OPENCLAW_ENGRAM_CONFIG_PATH") ||
     path.join(home, ".openclaw", "openclaw.json");
   return [
-    process.env.REMNIC_CONFIG,
-    openclawConfigPath,
+    {
+      path: expandConfigPathForEnv(envValue(env, "REMNIC_CONFIG"), home),
+      label: "REMNIC_CONFIG",
+    },
+    {
+      path: expandConfigPathForEnv(openclawConfigPath, home),
+      label:
+        envValue(env, "OPENCLAW_CONFIG_PATH") !== undefined
+          ? "OPENCLAW_CONFIG_PATH"
+          : envValue(env, "OPENCLAW_ENGRAM_CONFIG_PATH") !== undefined
+            ? "OPENCLAW_ENGRAM_CONFIG_PATH"
+            : "default OpenClaw config",
+    },
     path.join(home, ".config", "remnic", "config.json"),
     path.join(home, ".config", "engram", "config.json"),
     path.join(home, ".remnic", "config.json"),
-  ].filter((p) => typeof p === "string" && p.length > 0);
+  ]
+    .map((candidate) => {
+      return typeof candidate === "string"
+        ? { path: candidate, label: candidate }
+        : candidate;
+    })
+    .filter(
+      (candidate) =>
+        typeof candidate.path === "string" && candidate.path.length > 0,
+    );
+}
+
+function extractRemnicConfigFromRaw(raw, resolveEntry) {
+  const entry = resolveOpenClawRemnicPluginEntry(raw, resolveEntry);
+  if (isPlainRecord(entry)) {
+    return isPlainRecord(entry.config) ? entry.config : entry;
+  }
+  // Legacy / developer config layout: the top-level object IS the config.
+  // Honour it only when the file is not an OpenClaw-shaped config.
+  if (!Object.prototype.hasOwnProperty.call(raw, "plugins")) {
+    return raw;
+  }
+  return undefined;
 }
 
 /**
  * Load the Remnic plugin config block from the first matching config file.
  *
- * Entry resolution is delegated to `resolveRemnicPluginEntry` from
- * `@remnic/core` so the slot → PLUGIN_ID → LEGACY_PLUGIN_ID logic lives
- * in exactly one place across all five config-loader sites (#403).
+ * Entry resolution is delegated to the generic plugin-entry resolver from
+ * `@remnic/core` with OpenClaw ids supplied by this adapter wrapper.
  *
- * @param {Function} resolveEntry - resolveRemnicPluginEntry from @remnic/core
+ * @param {Function} resolveEntry - resolvePluginEntry from @remnic/core
+ * @param {NodeJS.ProcessEnv} env - environment override for tests
  */
-function loadRawConfig(resolveEntry) {
-  for (const candidate of configCandidates()) {
-    if (!fs.existsSync(candidate)) continue;
+function loadRawConfig(resolveEntry, env = process.env) {
+  for (const candidate of configCandidates(env)) {
+    if (!fs.existsSync(candidate.path)) continue;
+    let raw;
     try {
-      const raw = JSON.parse(fs.readFileSync(candidate, "utf-8"));
-      if (!raw || typeof raw !== "object") continue;
-      // Try the structured OpenClaw config layout first (plugins.entries).
-      // resolveEntry returns the full plugin entry (including .config).
-      const entry = resolveEntry(raw);
-      if (entry && typeof entry === "object") {
-        return entry.config && typeof entry.config === "object"
-          ? entry.config
-          : entry;
-      }
-      // Legacy / developer config layout: the top-level object IS the config.
-      // Honour it as long as it has no `plugins` subtree (so we don't
-      // accidentally treat a complete OpenClaw config with an unknown plugin
-      // slot as a flat Remnic config).
-      if (!raw.plugins) {
-        return raw;
-      }
-      // OpenClaw config but no Remnic entry found — skip to next candidate.
-    } catch (_err) {
-      // fall through to next candidate
+      raw = JSON.parse(fs.readFileSync(candidate.path, "utf-8"));
+    } catch (err) {
+      throw new MaterializeConfigError(
+        `codex-materialize config error: invalid JSON in ${candidate.label} (${candidate.path}): ${safeErrorDetail(err)}`,
+      );
+    }
+    if (!isPlainRecord(raw)) {
+      throw new MaterializeConfigError(
+        `codex-materialize config error: invalid config in ${candidate.label} (${candidate.path}): expected a JSON object`,
+      );
+    }
+    const resolved = extractRemnicConfigFromRaw(raw, resolveEntry);
+    if (resolved) {
+      return resolved;
     }
   }
   return {};
@@ -152,21 +235,28 @@ async function main() {
 
   // Dynamic import because @remnic/core is ESM-only.
   const core = await import("@remnic/core");
-  const { parseConfig, runCodexMaterialize, resolveRemnicPluginEntry } = core;
+  const { parseConfig, runCodexMaterialize, resolvePluginEntry } = core;
   if (
     typeof parseConfig !== "function" ||
     typeof runCodexMaterialize !== "function" ||
-    typeof resolveRemnicPluginEntry !== "function"
+    typeof resolvePluginEntry !== "function"
   ) {
     throw new Error(
-      "codex-materialize: @remnic/core is missing expected exports (parseConfig, runCodexMaterialize, resolveRemnicPluginEntry)",
+      "codex-materialize: @remnic/core is missing expected exports (parseConfig, runCodexMaterialize, resolvePluginEntry)",
     );
   }
 
-  // Pass the shared resolver so loadRawConfig uses the same slot → id lookup
-  // logic as all other config-loader sites (#403).
-  const rawConfig = loadRawConfig(resolveRemnicPluginEntry);
-  const config = parseConfig(rawConfig);
+  // Pass the generic resolver so loadRawConfig uses the same slot → id lookup
+  // semantics as the other OpenClaw config-loader sites (#403).
+  const rawConfig = loadRawConfig(resolvePluginEntry);
+  let config;
+  try {
+    config = parseConfig(rawConfig);
+  } catch (err) {
+    throw new MaterializeConfigError(
+      `codex-materialize config error: parseConfig rejected the resolved config: ${safeErrorDetail(err)}`,
+    );
+  }
   if (args.memoryDir) {
     // parseConfig already locked in a memoryDir, but the CLI override wins.
     config.memoryDir = args.memoryDir;
@@ -201,12 +291,25 @@ async function main() {
   return 0;
 }
 
-main().then(
-  (code) => process.exit(code),
-  (error) => {
-    console.error(
-      `codex-materialize failed: ${error instanceof Error ? error.message : String(error)}`,
-    );
-    process.exit(1);
-  },
-);
+module.exports = {
+  configCandidates,
+  extractRemnicConfigFromRaw,
+  loadRawConfig,
+};
+
+function formatFatalError(error) {
+  if (error instanceof MaterializeConfigError) {
+    return error.message;
+  }
+  return "codex-materialize failed; see logs for details";
+}
+
+if (require.main === module) {
+  main().then(
+    (code) => process.exit(code),
+    (error) => {
+      console.error(formatFatalError(error));
+      process.exit(1);
+    },
+  );
+}

package/hooks/bin/session-start.sh

@@ -57,7 +57,85 @@ SESSION_ID="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write
 CWD="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(d.cwd||'')" "$INPUT" 2>/dev/null || echo "")"
 PROJECT_NAME="$(basename "$CWD" 2>/dev/null || echo "unknown")"
 
-log "session=$SESSION_ID project=$PROJECT_NAME"
+# Resolve git context for the session's cwd (issue #569 PR 6).
+# Produces either a JSON `codingContext` object to embed in the recall
+# request, or an empty string when the cwd is not inside a git repo.
+# Any failure silently drops back to no-context (CLAUDE.md #30 escape hatch).
+CODING_CONTEXT_JSON=""
+if [ -n "$CWD" ] && [ -d "$CWD" ] && command -v git >/dev/null 2>&1; then
+  REMNIC_GIT_TOP="$(git -C "$CWD" rev-parse --show-toplevel 2>/dev/null || echo "")"
+  if [ -n "$REMNIC_GIT_TOP" ]; then
+    REMNIC_GIT_BRANCH="$(git -C "$REMNIC_GIT_TOP" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "HEAD")"
+    [ "$REMNIC_GIT_BRANCH" = "HEAD" ] && REMNIC_GIT_BRANCH=""
+    REMNIC_GIT_ORIGIN="$(git -C "$REMNIC_GIT_TOP" remote get-url origin 2>/dev/null || echo "")"
+    REMNIC_GIT_DEFAULT_BRANCH="$(git -C "$REMNIC_GIT_TOP" symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null | sed 's|^refs/remotes/origin/||' || echo "")"
+    CODING_CONTEXT_JSON="$(REMNIC_GIT_TOP="$REMNIC_GIT_TOP" REMNIC_GIT_BRANCH="$REMNIC_GIT_BRANCH" REMNIC_GIT_ORIGIN="$REMNIC_GIT_ORIGIN" REMNIC_GIT_DEFAULT_BRANCH="$REMNIC_GIT_DEFAULT_BRANCH" node -e "
+      // Mirror @remnic/core's resolveGitContext for projectId derivation.
+      // FNV-1a 32-bit stable hash.
+      const rootPath = process.env.REMNIC_GIT_TOP || '';
+      const branch = process.env.REMNIC_GIT_BRANCH || null;
+      const origin = process.env.REMNIC_GIT_ORIGIN || '';
+      const defaultBranch = process.env.REMNIC_GIT_DEFAULT_BRANCH || null;
+      function stableHash(input) {
+        let hash = 0x811c9dc5;
+        for (let i = 0; i < input.length; i++) {
+          hash ^= input.charCodeAt(i);
+          hash = Math.imul(hash, 0x01000193) >>> 0;
+        }
+        return hash.toString(16).padStart(8, '0');
+      }
+      // Mirrors packages/remnic-core/src/coding/git-context.ts
+      // normalizeOriginUrl. Keep the two in sync so the hook-computed
+      // projectId matches what the daemon computes on the same origin.
+      function normalizeOriginUrl(raw) {
+        let u = (raw || '').trim();
+        if (!u) return '';
+        // Case-insensitive .git strip — matches the TS canonical form.
+        if (/\\.git\$/i.test(u)) u = u.slice(0, -4);
+        // Windows drive-letter: short-circuit scp parsing.
+        if (/^[A-Za-z]:[\\\\/]/.test(u)) return u.toLowerCase();
+        // Protocol form: handles ssh://, https://, file:///, bracketed
+        // IPv6 hosts, optional user, optional port, and empty host
+        // (file:///path).
+        const proto = /^[a-z][a-z0-9+.-]*:\\/\\/(?:[^@/]+@)?(\\[[^\\]]+\\]|[^/:]*)(?::(\\d+))?(\\/.*)?\$/i.exec(u);
+        if (proto) {
+          let host = proto[1] || '';
+          const wasBracketed = host.startsWith('[') && host.endsWith(']');
+          if (wasBracketed) host = host.slice(1, -1);
+          const port = proto[2];
+          const p = (proto[3] || '').replace(/^\\/+/, '');
+          const hostPort = port
+            ? (wasBracketed ? '[' + host + ']:' + port : host + ':' + port)
+            : host;
+          const prefix = hostPort.length > 0 ? hostPort : 'localhost';
+          return (prefix + '/' + p).toLowerCase();
+        }
+        // scp form: [user@]host:path — user@ optional, bracketed IPv6 host
+        // supported. A matched path starting with // is a protocol-URL
+        // leftover and is rejected.
+        const scp = /^(?:([^@\\s\\/]+)@)?(\\[[^\\]]+\\]|[^:@\\s\\/]+):(.+)\$/.exec(u);
+        if (scp) {
+          let host = scp[2] || '';
+          if (host.startsWith('[') && host.endsWith(']')) host = host.slice(1, -1);
+          const p = scp[3] || '';
+          if (p.startsWith('//')) return u.toLowerCase();
+          return (host + '/' + p.replace(/^\\/+/, '')).toLowerCase();
+        }
+        return u.toLowerCase();
+      }
+      const normalized = normalizeOriginUrl(origin);
+      const projectId = normalized ? 'origin:' + stableHash(normalized) : 'root:' + stableHash(rootPath);
+      process.stdout.write(JSON.stringify({
+        projectId,
+        branch: branch || null,
+        rootPath,
+        defaultBranch: defaultBranch || null,
+      }));
+    " 2>/dev/null || echo "")"
+  fi
+fi
+
+log "session=$SESSION_ID project=$PROJECT_NAME coding-context=${CODING_CONTEXT_JSON:+yes}"
 
 # Health check — start daemon if not running
 if ! curl -sf --max-time 2 "$REMNIC_HEALTH_URL" >/dev/null 2>&1; then
@@ -83,12 +161,29 @@ fi
 
 QUERY="Starting a new coding session in project: ${PROJECT_NAME}. Recall relevant memories, preferences, decisions, patterns, and context about this project and the user."
 
-REQUEST_BODY="$(node -e "process.stdout.write(JSON.stringify({
-  query: process.argv[1],
-  sessionKey: process.argv[2],
-  topK: 12,
-  mode: 'auto'
-}))" "$QUERY" "$SESSION_ID" 2>/dev/null)"
+REQUEST_BODY="$(REMNIC_CODING_CONTEXT_JSON="$CODING_CONTEXT_JSON" node -e "
+  const body = {
+    query: process.argv[1],
+    sessionKey: process.argv[2],
+    topK: 12,
+    mode: 'auto',
+  };
+  const raw = process.env.REMNIC_CODING_CONTEXT_JSON || '';
+  if (raw) {
+    try { body.codingContext = JSON.parse(raw); } catch (_) {
+      // Context envelope was provided but failed to parse. Explicitly
+      // clear any previously-attached context for this session so a
+      // malformed envelope does not silently keep stale state.
+      body.codingContext = null;
+    }
+  } else {
+    // No git context resolvable for this cwd. Explicitly clear any
+    // previously-attached context so a session that moves out of a repo
+    // does not keep routing to the old project namespace.
+    body.codingContext = null;
+  }
+  process.stdout.write(JSON.stringify(body));
+" "$QUERY" "$SESSION_ID" 2>/dev/null)"
 
 [ -z "$REQUEST_BODY" ] && echo '{"continue":true}' && exit 0
 
@@ -105,12 +200,23 @@ RESPONSE="$(echo "$RAW" | sed '$d')"
 
 if [ $CURL_EXIT -ne 0 ] || ! [[ "$HTTP_STATUS" =~ ^2 ]] || [ -z "$RESPONSE" ]; then
   log "full recall failed (curl=$CURL_EXIT http=$HTTP_STATUS) — falling back to minimal"
-  MINIMAL_BODY="$(node -e "process.stdout.write(JSON.stringify({
-    query: process.argv[1],
-    sessionKey: process.argv[2],
-    topK: 8,
-    mode: 'minimal'
-  }))" "$QUERY" "$SESSION_ID" 2>/dev/null)"
+  MINIMAL_BODY="$(REMNIC_CODING_CONTEXT_JSON="$CODING_CONTEXT_JSON" node -e "
+    const body = {
+      query: process.argv[1],
+      sessionKey: process.argv[2],
+      topK: 8,
+      mode: 'minimal',
+    };
+    const raw = process.env.REMNIC_CODING_CONTEXT_JSON || '';
+    if (raw) {
+      try { body.codingContext = JSON.parse(raw); } catch (_) {
+        body.codingContext = null;
+      }
+    } else {
+      body.codingContext = null;
+    }
+    process.stdout.write(JSON.stringify(body));
+  " "$QUERY" "$SESSION_ID" 2>/dev/null)"
   RAW="$(curl -s -w "\n%{http_code}" --max-time 20 \
     -X POST "$REMNIC_URL" \
     -H "Authorization: Bearer ${REMNIC_TOKEN}" \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/plugin-codex",
-  "version": "1.0.1",
+  "version": "9.3.517",
   "description": "Remnic memory plugin for Codex CLI — hooks, skills, MCP integration",
   "type": "module",
   "license": "MIT",
@@ -30,6 +30,6 @@
     ".mcp.json"
   ],
   "dependencies": {
-    "@remnic/core": "^1.0.3"
+    "@remnic/core": "^9.3.517"
   }
 }