@remnic/plugin-claude-code 9.45.4 → 9.46.0

package/.claude-plugin/plugin.json

@@ -1,8 +1,10 @@
 {
   "name": "remnic",
   "description": "Universal memory for AI agents — automatic recall, observation, and cross-agent knowledge sharing",
-  "version": "9.45.4",
-  "author": "Joshua Warren",
+  "version": "9.46.0",
+  "author": {
+    "name": "Joshua Warren"
+  },
   "homepage": "https://github.com/joshuaswarren/remnic",
   "repository": "https://github.com/joshuaswarren/remnic"
 }

package/README.md

@@ -68,6 +68,38 @@ The plugin expects a Remnic daemon reachable at `http://localhost:4318/mcp` with
 
 Replace `{{REMNIC_TOKEN}}` with a token minted via `remnic token generate <connector-id>`.
 
+### Hook credentials
+
+The hook runner resolves its own bearer token independently of the MCP block
+above, in this order:
+
+1. `~/.remnic/tokens.json`, then legacy `~/.engram/tokens.json` — the
+   `claude-code` connector entry first, then `openclaw`.
+2. `OPENCLAW_REMNIC_ACCESS_TOKEN`, then `REMNIC_AUTH_TOKEN`.
+3. Legacy aliases: `OPENCLAW_ENGRAM_ACCESS_TOKEN`, then `ENGRAM_AUTH_TOKEN`.
+
+Current names outrank legacy ones, so a leftover pre-rename value cannot
+shadow the credential the daemon is actually running with. `REMNIC_AUTH_TOKEN`
+covers the standalone-server setup, which authenticates the daemon with that
+variable and never mints a connector token. Against an auth-gated daemon the
+hook needs one of these: every route, including `/engram/v1/health`, returns
+401 without a bearer, so an unauthenticated hook reports `daemon not running`
+and silently skips auto-recall and auto-observe.
+
+`REMNIC_HOOK_TOKEN` is not part of this chain — it is an internal channel the
+foreground hook uses to hand its already-resolved token to the detached
+observe worker, so the worker does not re-read the token store. Nothing in
+the foreground path reads it.
+
+### Namespace targeting
+
+`REMNIC_NAMESPACE`, then legacy `ENGRAM_NAMESPACE` — optional. When set, the
+hook adds the namespace to the **request body** of recall and observe (the
+REST surface reads it from the body, not a header). An explicit
+`body.namespace` already on the request wins. Unset → the daemon resolves the
+namespace for the `claude-code` client id, which on a namespaced daemon is the
+adapter's own empty namespace, so recall returns nothing.
+
 ## Agent note
 
 If you're an AI agent scaffolding a Claude Code integration: **do not** hand-edit hook scripts in a user's `~/.claude/` tree. The full setup has two components:

package/hooks/bin/remnic-cc-hook.cjs

@@ -169,6 +169,15 @@ function onPath(bin) {
 }
 
 // ── token resolution (per-plugin token store, then env) ────────────────────
+// Env precedence is primary-before-legacy per AGENTS.md §9: the two current
+// names (OPENCLAW_REMNIC_ACCESS_TOKEN, REMNIC_AUTH_TOKEN) before the two
+// legacy aliases (OPENCLAW_ENGRAM_ACCESS_TOKEN, ENGRAM_AUTH_TOKEN), so a
+// stale leftover from a pre-rename install cannot outrank the credential the
+// daemon is actually running with. REMNIC_AUTH_TOKEN matters because the
+// documented standalone-server setup authenticates the daemon with it alone
+// and never mints a connector token — without it the health probe 401s and
+// the hook wrongly reports "daemon not running", silently skipping
+// recall/observe.
 function resolveToken() {
   for (const file of [
     path.join(HOME, ".remnic", "tokens.json"),
@@ -192,7 +201,9 @@ function resolveToken() {
   }
   return (
     process.env.OPENCLAW_REMNIC_ACCESS_TOKEN ||
+    process.env.REMNIC_AUTH_TOKEN ||
     process.env.OPENCLAW_ENGRAM_ACCESS_TOKEN ||
+    process.env.ENGRAM_AUTH_TOKEN ||
     ""
   );
 }
@@ -203,7 +214,19 @@ function httpPost(urlPath, token, bodyObj, timeoutMs) {
   return new Promise((resolve) => {
     let data;
     try {
-      data = Buffer.from(JSON.stringify(bodyObj), "utf8");
+      // Namespace targeting for namespaced daemons: when REMNIC_NAMESPACE (or
+      // ENGRAM_NAMESPACE) is set, include it in the request body. On the REST
+      // surface the namespace is read from the body, not a header, and the
+      // "claude-code" client id otherwise resolves to the adapter's own
+      // (empty) namespace — so recall/observe silently return nothing. Opt-in:
+      // when the env var is unset this is a no-op and behaviour is unchanged.
+      // An explicit bodyObj.namespace still takes precedence.
+      const ns = process.env.REMNIC_NAMESPACE || process.env.ENGRAM_NAMESPACE;
+      const outBody =
+        ns && bodyObj && typeof bodyObj === "object" && !Array.isArray(bodyObj)
+          ? { namespace: ns, ...bodyObj }
+          : bodyObj;
+      data = Buffer.from(JSON.stringify(outBody), "utf8");
     } catch {
       resolve({ ok: false, status: 0, body: "" });
       return;
@@ -246,10 +269,27 @@ function httpPost(urlPath, token, bodyObj, timeoutMs) {
   });
 }
 
-function httpHealthy(timeoutMs) {
+// `token` is the caller's already-resolved credential, NOT a second
+// resolveToken() call: the probe must authenticate with the exact bearer the
+// operation it gates will send. Re-resolving could pick up a rotated
+// tokens.json (or an inherited REMNIC_HOOK_TOKEN the foreground handlers
+// ignore) and green-light a probe whose recall then 401s.
+//
+// When the daemon has an auth token configured (REMNIC_AUTH_TOKEN), every
+// route — including /engram/v1/health — returns 401 to unauthenticated
+// requests, so an unauthenticated probe makes the hook wrongly report
+// "daemon not running" and skip recall/observe. Unauthenticated daemons
+// ignore the header.
+function httpHealthy(timeoutMs, token) {
   return new Promise((resolve) => {
     const req = http.request(
-      { host: HOST, port: PORT, path: "/engram/v1/health", method: "GET" },
+      {
+        host: HOST,
+        port: PORT,
+        path: "/engram/v1/health",
+        method: "GET",
+        headers: token ? { Authorization: `Bearer ${token}` } : {},
+      },
       (res) => {
         res.resume();
         resolve(res.statusCode >= 200 && res.statusCode < 300);
@@ -551,7 +591,7 @@ async function handleSessionStart(input, token, log) {
   log(`session=${sessionId} project=${projectName} coding-context=${codingContext ? "yes" : ""}`);
 
   // Health check — start daemon if not running.
-  if (!(await httpHealthy(2000))) {
+  if (!(await httpHealthy(2000, token))) {
     log("daemon not responding, attempting start...");
     // Try `remnic` first, fall through to legacy `engram` when only the older
     // CLI is on PATH. spawn() emits ENOENT *asynchronously* via 'error', so we
@@ -575,7 +615,7 @@ async function handleSessionStart(input, token, log) {
       }
     }
     await new Promise((r) => setTimeout(r, 2000));
-    if (!(await httpHealthy(2000))) {
+    if (!(await httpHealthy(2000, token))) {
       log("daemon still not responding after start attempt");
       emit({
         continue: true,

package/hooks/bin/remnic-cc-hook.test.cjs

@@ -62,14 +62,20 @@ function runHook(event, input, { port, home, env = {} } = {}) {
         XDG_STATE_HOME: path.join(home, "state"),
         REMNIC_HOST: "127.0.0.1",
         REMNIC_PORT: String(port),
-        // Default to an env token unless a test overrides it. When a test
-        // asks for "no token", explicitly clear BOTH legacy env vars so a
-        // value inherited from the parent shell (e.g.
-        // OPENCLAW_ENGRAM_ACCESS_TOKEN in a developer's environment) cannot
-        // leak through `...process.env` and make the no-token path take a
-        // token (#1518 test isolation).
+        // Default to an env token unless a test overrides it. Every env name
+        // resolveToken() consults is pinned here — including the canonical
+        // REMNIC_AUTH_TOKEN / ENGRAM_AUTH_TOKEN pair — so a value inherited
+        // from the parent shell (a developer or CI runner that authenticates
+        // a local daemon) cannot leak through `...process.env` and make the
+        // no-token path take a token (#1518 test isolation). Tests that want
+        // a specific name set it through `env.extra`, which is spread last.
         OPENCLAW_REMNIC_ACCESS_TOKEN: env.token === null ? "" : env.token || "test-token",
-        OPENCLAW_ENGRAM_ACCESS_TOKEN: env.token === null ? "" : "",
+        OPENCLAW_ENGRAM_ACCESS_TOKEN: "",
+        REMNIC_AUTH_TOKEN: "",
+        ENGRAM_AUTH_TOKEN: "",
+        // Internal worker-propagation channel, not a user credential. Pinned
+        // so an inherited value cannot reach the detached observe worker.
+        REMNIC_HOOK_TOKEN: "",
         ...env.extra,
       },
       stdio: ["pipe", "pipe", "pipe"],
@@ -135,6 +141,139 @@ test("session-start: healthy server returns recall context with codingContext cl
   }
 });
 
+test("session-start: health probe carries the bearer token (auth-gated daemons)", async () => {
+  const home = mkHome();
+  let healthAuth = "unset";
+  const { server, port } = await startServer((req, res) => {
+    if (req.url === "/engram/v1/health") {
+      healthAuth = req.headers.authorization || null;
+      return res.writeHead(200).end("ok");
+    }
+    if (req.url === "/engram/v1/recall") {
+      return res
+        .writeHead(200, { "Content-Type": "application/json" })
+        .end(JSON.stringify({ context: "ctx", count: 1, mode: "auto" }));
+    }
+    res.writeHead(404).end();
+  });
+  try {
+    await runHook("session-start", { session_id: "s1", cwd: home }, { port, home });
+    // Without this header an auth-gated daemon 401s the probe and the hook
+    // reports "daemon not running", silently skipping recall/observe.
+    assert.equal(healthAuth, "Bearer test-token");
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("recall body targets REMNIC_NAMESPACE when set, and omits namespace when unset", async () => {
+  const mk = () =>
+    startServer((req, res) => {
+      if (req.url === "/engram/v1/health") return res.writeHead(200).end("ok");
+      if (req.url === "/engram/v1/recall") {
+        return res
+          .writeHead(200, { "Content-Type": "application/json" })
+          .end(JSON.stringify({ context: "ctx", count: 1, mode: "auto" }));
+      }
+      res.writeHead(404).end();
+    });
+
+  // set → namespace travels in the request body (REST reads it from the body,
+  // not a header; the "claude-code" client id otherwise resolves to the
+  // adapter's own empty namespace and recall returns nothing).
+  {
+    const home = mkHome();
+    const { server, port, calls } = await mk();
+    try {
+      await runHook(
+        "session-start",
+        { session_id: "s1", cwd: home },
+        { port, home, env: { extra: { REMNIC_NAMESPACE: "team-shared" } } },
+      );
+      const recall = calls.find((c) => c.url === "/engram/v1/recall");
+      assert.ok(recall, "recall was called");
+      assert.equal(recall.body.namespace, "team-shared");
+    } finally {
+      server.close();
+      fs.rmSync(home, { recursive: true, force: true });
+    }
+  }
+
+  // unset → opt-in no-op, no namespace field (behaviour unchanged for existing users).
+  // Explicitly clear both env vars so a value inherited from the developer's
+  // shell (`...process.env`) can't leak in and make this path look "set".
+  {
+    const home = mkHome();
+    const { server, port, calls } = await mk();
+    try {
+      await runHook(
+        "session-start",
+        { session_id: "s1", cwd: home },
+        { port, home, env: { extra: { REMNIC_NAMESPACE: "", ENGRAM_NAMESPACE: "" } } },
+      );
+      const recall = calls.find((c) => c.url === "/engram/v1/recall");
+      assert.ok(recall, "recall was called");
+      assert.equal("namespace" in recall.body, false);
+    } finally {
+      server.close();
+      fs.rmSync(home, { recursive: true, force: true });
+    }
+  }
+});
+
+test("namespace targeting: ENGRAM_NAMESPACE fallback (recall) and observe body both honor it", async () => {
+  // ENGRAM_NAMESPACE is the fallback when REMNIC_NAMESPACE is unset → recall body carries it.
+  {
+    const home = mkHome();
+    const { server, port, calls } = await startServer((req, res) => {
+      if (req.url === "/engram/v1/health") return res.writeHead(200).end("ok");
+      if (req.url === "/engram/v1/recall") {
+        return res
+          .writeHead(200, { "Content-Type": "application/json" })
+          .end(JSON.stringify({ context: "ctx", count: 1, mode: "auto" }));
+      }
+      res.writeHead(404).end();
+    });
+    try {
+      await runHook(
+        "session-start",
+        { session_id: "s1", cwd: home },
+        { port, home, env: { extra: { REMNIC_NAMESPACE: "", ENGRAM_NAMESPACE: "legacy-ns" } } },
+      );
+      const recall = calls.find((c) => c.url === "/engram/v1/recall");
+      assert.ok(recall, "recall was called");
+      assert.equal(recall.body.namespace, "legacy-ns");
+    } finally {
+      server.close();
+      fs.rmSync(home, { recursive: true, force: true });
+    }
+  }
+
+  // observe uses the same httpPost path, so its body carries the namespace too.
+  {
+    const home = mkHome();
+    const { server, port, calls } = await startServer((req, res) => res.writeHead(200).end("{}"));
+    try {
+      const tpath = transcript(home, [
+        { role: "user", content: "first" },
+        { role: "assistant", content: "second" },
+      ]);
+      await runHook(
+        "__observe-worker__",
+        JSON.stringify({ session_id: "sObsNs", transcript_path: tpath }),
+        { port, home, env: { extra: { REMNIC_NAMESPACE: "team-shared", ENGRAM_NAMESPACE: "" } } },
+      );
+      const observe = calls.find((c) => c.url === "/engram/v1/observe");
+      assert.ok(observe, "observe was called");
+      assert.equal(observe.body.namespace, "team-shared");
+    } finally {
+      server.close();
+      fs.rmSync(home, { recursive: true, force: true });
+    }
+  }
+});
+
 test("session-start: falls back to minimal mode when full recall fails", async () => {
   const home = mkHome();
   let recallHits = 0;
@@ -476,6 +615,122 @@ test("token resolution: legacy ~/.engram/tokens.json is the read fallback", asyn
   }
 });
 
+// The documented standalone-server setup (docs/guides/standalone-server.md,
+// README) authenticates the daemon with REMNIC_AUTH_TOKEN and never mints a
+// connector token, so nothing lands in ~/.remnic/tokens.json and none of the
+// OPENCLAW_* names are set. Before the canonical pair was added to
+// resolveToken(), that shape sent an unauthenticated health probe, took a 401,
+// and reported "daemon not running" — silently skipping recall and observe.
+function authEnvServer() {
+  const seen = { health: "unset", recall: "unset" };
+  return startServer((req, res) => {
+    if (req.url === "/engram/v1/health") {
+      seen.health = req.headers.authorization || null;
+      return res.writeHead(200).end("ok");
+    }
+    if (req.url === "/engram/v1/recall") {
+      seen.recall = req.headers.authorization || null;
+      return res
+        .writeHead(200, { "Content-Type": "application/json" })
+        .end(JSON.stringify({ context: "ctx", count: 1, mode: "auto" }));
+    }
+    res.writeHead(404).end();
+  }).then((started) => ({ ...started, seen }));
+}
+
+for (const name of ["REMNIC_AUTH_TOKEN", "ENGRAM_AUTH_TOKEN"]) {
+  test(`token resolution: ${name} authenticates health and recall (no token store)`, async () => {
+    const home = mkHome();
+    const { server, port, seen } = await authEnvServer();
+    try {
+      const res = await runHook(
+        "session-start",
+        { session_id: "sEnv", cwd: home },
+        { port, home, env: { token: null, extra: { [name]: "operator-secret" } } },
+      );
+      assert.equal(seen.health, "Bearer operator-secret");
+      assert.equal(seen.recall, "Bearer operator-secret");
+      assert.doesNotMatch(
+        res.json.hookSpecificOutput.additionalContext,
+        /daemon not running/,
+        "an authenticated daemon must not be reported as down",
+      );
+    } finally {
+      server.close();
+      fs.rmSync(home, { recursive: true, force: true });
+    }
+  });
+}
+
+test("token resolution: OPENCLAW_REMNIC_ACCESS_TOKEN outranks REMNIC_AUTH_TOKEN", async () => {
+  const home = mkHome();
+  const { server, port, seen } = await authEnvServer();
+  try {
+    await runHook(
+      "session-start",
+      { session_id: "sPrec", cwd: home },
+      { port, home, env: { token: "connector-tok", extra: { REMNIC_AUTH_TOKEN: "operator-secret" } } },
+    );
+    // Both are current names; the connector-scoped one stays first, so an
+    // install that already worked keeps its existing credential.
+    assert.equal(seen.health, "Bearer connector-tok");
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("token resolution: REMNIC_AUTH_TOKEN outranks the legacy OPENCLAW_ENGRAM_ACCESS_TOKEN", async () => {
+  const home = mkHome();
+  const { server, port, seen } = await authEnvServer();
+  try {
+    await runHook(
+      "session-start",
+      { session_id: "sLegacyPrec", cwd: home },
+      {
+        port,
+        home,
+        env: {
+          token: null,
+          extra: {
+            OPENCLAW_ENGRAM_ACCESS_TOKEN: "stale-legacy-tok",
+            REMNIC_AUTH_TOKEN: "operator-secret",
+          },
+        },
+      },
+    );
+    // Primary-before-legacy (AGENTS.md §9). A migrated deployment often still
+    // exports the pre-rename alias; if that stale value outranked the token
+    // the daemon actually runs with, the probe would 401 and land back on
+    // "daemon not running".
+    assert.equal(seen.health, "Bearer operator-secret");
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("token resolution: tokens.json still outranks REMNIC_AUTH_TOKEN", async () => {
+  const home = mkHome();
+  fs.mkdirSync(path.join(home, ".remnic"), { recursive: true });
+  fs.writeFileSync(
+    path.join(home, ".remnic", "tokens.json"),
+    JSON.stringify({ tokens: [{ connector: "claude-code", token: "cc-tok" }] }),
+  );
+  const { server, port, seen } = await authEnvServer();
+  try {
+    await runHook(
+      "session-start",
+      { session_id: "sStore", cwd: home },
+      { port, home, env: { token: null, extra: { REMNIC_AUTH_TOKEN: "operator-secret" } } },
+    );
+    assert.equal(seen.health, "Bearer cc-tok");
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
 // ── hooks.json Windows parity ─────────────────────────────────────────────
 
 test("hooks.json: every event uses cross-platform exec form with ${CLAUDE_PLUGIN_ROOT} (#1518)", () => {
@@ -531,6 +786,23 @@ test("hooks.json: every event uses cross-platform exec form with ${CLAUDE_PLUGIN
   }
 });
 
+test("plugin.json: manifest conforms to the Claude Code plugin schema (author is an object)", () => {
+  const manifest = JSON.parse(
+    fs.readFileSync(path.join(__dirname, "..", "..", ".claude-plugin", "plugin.json"), "utf8"),
+  );
+  // Claude Code's plugin-manifest validator rejects a string `author`
+  // ("Invalid input: expected object, received string"), which blocks
+  // installing this plugin from a Claude Code marketplace. `author` must be an
+  // object carrying at least a `name`.
+  assert.equal(typeof manifest.author, "object", "author must be an object, not a string");
+  assert.ok(manifest.author !== null && !Array.isArray(manifest.author), "author must be a plain object");
+  assert.equal(typeof manifest.author.name, "string", "author.name must be a string");
+  assert.ok(manifest.author.name.length > 0, "author.name must be non-empty");
+  // Sanity-check the other required identity fields while we're here.
+  assert.equal(typeof manifest.name, "string", "name must be a string");
+  assert.equal(typeof manifest.version, "string", "version must be a string");
+});
+
 test("runner source: payload fields never reach a shell — spawn uses fixed argv (#1518 guard shell interpolation)", () => {
   const src = fs.readFileSync(RUNNER, "utf8");
   // Every spawn/spawnSync must use a fixed literal argument array, never a
@@ -579,3 +851,49 @@ test("runner source: path inputs are type-validated before use (#1518 validate p
     "transcript_path must be defaulted to empty string",
   );
 });
+
+test("token resolution: REMNIC_AUTH_TOKEN outranks ENGRAM_AUTH_TOKEN when both are set", async () => {
+  const home = mkHome();
+  const { server, port, seen } = await authEnvServer();
+  try {
+    await runHook(
+      "session-start",
+      { session_id: "sBothCanonical", cwd: home },
+      {
+        port,
+        home,
+        env: {
+          token: null,
+          extra: { REMNIC_AUTH_TOKEN: "current-tok", ENGRAM_AUTH_TOKEN: "legacy-tok" },
+        },
+      },
+    );
+    assert.equal(seen.health, "Bearer current-tok");
+    assert.equal(seen.recall, "Bearer current-tok");
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("health probe uses the same bearer as the operation it gates", async () => {
+  const home = mkHome();
+  const { server, port, seen } = await authEnvServer();
+  try {
+    // REMNIC_HOOK_TOKEN is the detached observe worker's internal propagation
+    // channel; the foreground handlers never read it. If the probe consulted
+    // it, an inherited value would authenticate health with one bearer while
+    // recall sent another — a false "healthy" followed by a 401, or the
+    // reverse. Probe and operation must carry one snapshot.
+    await runHook(
+      "session-start",
+      { session_id: "sSnapshot", cwd: home },
+      { port, home, env: { extra: { REMNIC_HOOK_TOKEN: "inherited-worker-tok" } } },
+    );
+    assert.equal(seen.health, "Bearer test-token");
+    assert.equal(seen.recall, seen.health);
+  } finally {
+    server.close();
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/plugin-claude-code",
-  "version": "9.45.4",
+  "version": "9.46.0",
   "description": "Remnic memory plugin for Claude Code — hooks, skills, MCP integration",
   "type": "module",
   "license": "MIT",