@remnic/core 1.1.31 → 9.3.515

package/src/access-service.ts

@@ -7,6 +7,7 @@ import { AccessIdempotencyStore, hashAccessIdempotencyPayload } from "./access-i
 import { AccessAuditAdapter, type AccessAuditConfig, type AccessAuditResult } from "./access-audit.js";
 import type { AnomalyDetectorResult } from "./recall-audit-anomaly.js";
 import { resolveGitContext } from "./coding/git-context.js";
+import { projectTagProjectId } from "./coding/coding-namespace.js";
 import { WorkStorage } from "./work/storage.js";
 import {
   exportWorkBoardMarkdown,
@@ -809,6 +810,7 @@ export interface EngramAccessObserveResponse {
 export interface EngramAccessLcmSearchRequest {
   query: string;
   sessionKey?: string;
+  sessionPrefix?: string;
   namespace?: string;
   limit?: number;
   authenticatedPrincipal?: string;
@@ -1721,11 +1723,11 @@ export class EngramAccessService {
     if (this.orchestrator.getCodingContextForSession(sessionKey)) return;
     // projectTag takes priority over cwd.
     if (typeof options.projectTag === "string" && options.projectTag.trim().length > 0) {
-      const tag = options.projectTag.trim();
+      const projectId = projectTagProjectId(options.projectTag);
       this.orchestrator.setCodingContextForSession(sessionKey, {
-        projectId: `tag:${tag}`,
+        projectId,
         branch: null,
-        rootPath: `tag:${tag}`,
+        rootPath: projectId,
         defaultBranch: null,
       });
       return;
@@ -3910,10 +3912,14 @@ export class EngramAccessService {
     const lcmSessionKey = request.sessionKey && namespace !== this.orchestrator.config.defaultNamespace
       ? `${namespace}:${request.sessionKey}`
       : request.sessionKey;
+    const lcmSessionPrefix = request.sessionPrefix && namespace !== this.orchestrator.config.defaultNamespace
+      ? `${namespace}:${request.sessionPrefix}`
+      : request.sessionPrefix;
     const rawResults = await this.orchestrator.lcmEngine.searchContextFull(
       request.query,
       limit,
       lcmSessionKey,
+      lcmSessionPrefix,
     );
 
     const results = rawResults.map((r: { session_id: string; content: string; turn_index: number }) => ({
@@ -4611,13 +4617,8 @@ export class EngramAccessService {
     const resolvedNs = this.resolveReadableNamespace(namespace, principal);
     const namespaceFilter = resolvedNs !== this.orchestrator.config.defaultNamespace ? resolvedNs : undefined;
 
-    const results = collection === "global"
-      ? (await this.orchestrator.qmd.searchGlobal(query, maxResults)).filter((r) =>
-          namespaceFilter
-            ? r.path.includes(`/namespaces/${namespaceFilter}/`) ||
-              (!r.path.includes("/namespaces/") && namespaceFilter === this.orchestrator.config.defaultNamespace)
-            : true,
-        )
+    const results = collection === "global" && !namespaceFilter
+      ? await this.orchestrator.qmd.searchGlobal(query, maxResults)
       : await this.orchestrator.searchAcrossNamespaces({
           query,
           namespaces: namespaceFilter ? [namespaceFilter] : undefined,

package/src/active-recall.test.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { mkdtemp, readFile } from "node:fs/promises";
+import { mkdtemp, readFile, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -452,6 +452,34 @@ test("active recall transcript persistence sanitizes agent and session path segm
   assert.match(raw, /"sessionKey":"session\/\.\.\/\.\.\/escape"/);
 });
 
+test("active recall transcript persistence failures do not abort generated summaries", async () => {
+  const transcriptFile = path.join(
+    await mkdtemp(path.join(os.tmpdir(), "active-recall-transcript-file-")),
+    "not-a-directory",
+  );
+  await writeFile(transcriptFile, "existing file", "utf8");
+  const engine = createActiveRecallEngine(
+    {
+      async recall() {
+        return "Primary recall";
+      },
+      async generateSummary() {
+        return { text: "useful summary", modelUsed: "gpt-5.5" };
+      },
+    },
+    baseConfig({
+      persistTranscripts: true,
+      transcriptDir: transcriptFile,
+    }),
+  );
+
+  const result = await engine.run(baseInput());
+
+  assert.equal(result.summary, "useful summary");
+  assert.equal(result.modelUsed, "gpt-5.5");
+  assert.equal(result.transcriptPath, null);
+});
+
 test("active recall transcript persistence encodes bare dot path segments", async () => {
   const transcriptDir = await mkdtemp(path.join(os.tmpdir(), "active-recall-transcript-"));
   const engine = createActiveRecallEngine(

package/src/active-recall.ts

@@ -436,13 +436,17 @@ export function createActiveRecallEngine(
         transcriptPath: null,
       };
       if (config.persistTranscripts) {
-        result.transcriptPath = await appendActiveRecallTranscript(
-          config.transcriptDir,
-          input,
-          config,
-          result,
-          queryBundle,
-        );
+        try {
+          result.transcriptPath = await appendActiveRecallTranscript(
+            config.transcriptDir,
+            input,
+            config,
+            result,
+            queryBundle,
+          );
+        } catch {
+          result.transcriptPath = null;
+        }
       }
 
       if (cacheEnabled) {

package/src/adapters/claude-code.ts

@@ -11,9 +11,13 @@ import { headerValue, type AdapterContext, type EngramAdapter, type ResolvedIden
  * For HTTP REST (non-MCP) requests, detection relies on User-Agent or
  * user-configured X-Engram-Client-Id header in .claude.json headers.
  *
- * Namespace/principal can be set by configuring custom headers in
+ * Namespace can be set by configuring custom headers in
  * .claude.json or .mcp.json:
- *   "headers": { "X-Engram-Namespace": "my-project", "X-Engram-Principal": "my-team" }
+ *   "headers": { "X-Engram-Namespace": "my-project" }
+ *
+ * Principal overrides are intentionally handled only by the HTTP server's
+ * trustPrincipalHeader gate. Adapters must not independently trust
+ * X-Engram-Principal.
  */
 export class ClaudeCodeAdapter implements EngramAdapter {
   readonly id = "claude-code";
@@ -37,20 +41,15 @@ export class ClaudeCodeAdapter implements EngramAdapter {
     // MCP session ID (standard MCP header, server-assigned)
     const mcpSessionId = headerValue(context.headers, "mcp-session-id");
 
-    // Principal: explicit header > default
-    const principal = headerValue(context.headers, "x-engram-principal")
-      || "claude-code";
-
     // Namespace: explicit header > default
     const namespace = headerValue(context.headers, "x-engram-namespace")
       || "claude-code";
 
     return {
       namespace,
-      principal,
+      principal: "claude-code",
       sessionKey: mcpSessionId ?? context.sessionKey,
       adapterId: this.id,
     };
   }
 }
-

package/src/adapters/codex.ts

@@ -11,7 +11,11 @@ import { headerValue, type AdapterContext, type EngramAdapter, type ResolvedIden
  * http_headers in ~/.codex/config.toml:
  *   [mcp_servers.engram]
  *   url = "http://localhost:4318/mcp"
- *   http_headers = { "X-Engram-Namespace" = "my-project", "X-Engram-Principal" = "codex-agent" }
+ *   http_headers = { "X-Engram-Namespace" = "my-project" }
+ *
+ * Principal overrides are intentionally handled only by the HTTP server's
+ * trustPrincipalHeader gate. Adapters must not independently trust
+ * X-Engram-Principal.
  *
  * Codex also sends a custom "sandbox_state" RPC notification after
  * init with sandbox policy info (read-only/writable paths).
@@ -38,20 +42,15 @@ export class CodexAdapter implements EngramAdapter {
     // MCP session ID (standard MCP header, server-assigned)
     const mcpSessionId = headerValue(context.headers, "mcp-session-id");
 
-    // Principal: explicit header > default
-    const principal = headerValue(context.headers, "x-engram-principal")
-      || "codex";
-
     // Namespace: explicit header > default
     const namespace = headerValue(context.headers, "x-engram-namespace")
       || "codex";
 
     return {
       namespace,
-      principal,
+      principal: "codex",
       sessionKey: mcpSessionId ?? context.sessionKey,
       adapterId: this.id,
     };
   }
 }
-

package/src/adapters/hermes.ts

@@ -47,18 +47,14 @@ export class HermesAdapter implements EngramAdapter {
   resolveIdentity(context: AdapterContext): ResolvedIdentity {
     const sessionId = headerValue(context.headers, "x-hermes-session-id");
 
-    const principal = headerValue(context.headers, "x-engram-principal")
-      || "hermes-agent";
-
     const namespace = headerValue(context.headers, "x-engram-namespace")
       || "hermes";
 
     return {
       namespace,
-      principal,
+      principal: "hermes-agent",
       sessionKey: sessionId ?? context.sessionKey,
       adapterId: this.id,
     };
   }
 }
-

package/src/adapters/registry.test.ts

@@ -0,0 +1,63 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { AdapterRegistry } from "./registry.js";
+import type { AdapterContext, EngramAdapter } from "./types.js";
+
+test("adapter registry falls back to explicit request identity when no adapter matches", () => {
+  const registry = new AdapterRegistry([]);
+
+  assert.deepEqual(
+    registry.resolve({
+      headers: {},
+      namespace: " project-a ",
+      principal: " user-1 ",
+      sessionKey: "session-1",
+    }),
+    {
+      namespace: "project-a",
+      principal: "user-1",
+      sessionKey: "session-1",
+      adapterId: "explicit",
+    },
+  );
+});
+
+test("adapter registry requires complete explicit identity fallback", () => {
+  const registry = new AdapterRegistry([]);
+
+  assert.equal(registry.resolve({ headers: {}, sessionKey: "session-1" }), null);
+  assert.equal(registry.resolve({ headers: {}, namespace: "project-a" }), null);
+  assert.equal(registry.resolve({ headers: {}, principal: "user-1" }), null);
+});
+
+test("adapter registry prefers matching adapters over explicit fallback", () => {
+  const adapter: EngramAdapter = {
+    id: "test-adapter",
+    matches(context: AdapterContext) {
+      return context.headers["x-test"] === "yes";
+    },
+    resolveIdentity() {
+      return {
+        namespace: "adapter-namespace",
+        principal: "adapter-principal",
+        adapterId: "test-adapter",
+      };
+    },
+  };
+
+  const registry = new AdapterRegistry([adapter]);
+
+  assert.deepEqual(
+    registry.resolve({
+      headers: { "x-test": "yes" },
+      namespace: "explicit-namespace",
+      principal: "explicit-principal",
+    }),
+    {
+      namespace: "adapter-namespace",
+      principal: "adapter-principal",
+      adapterId: "test-adapter",
+    },
+  );
+});

package/src/adapters/registry.ts

@@ -31,6 +31,16 @@ export class AdapterRegistry {
         return adapter.resolveIdentity(context);
       }
     }
+    const namespace = context.namespace?.trim();
+    const principal = context.principal?.trim();
+    if (namespace && principal) {
+      return {
+        namespace,
+        principal,
+        sessionKey: context.sessionKey,
+        adapterId: "explicit",
+      };
+    }
     return null;
   }
 

package/src/adapters/replit.ts

@@ -16,8 +16,10 @@ import { headerValue, type AdapterContext, type EngramAdapter, type ResolvedIden
  *   Header Name: X-Engram-Client-Id
  *   Header Value: replit
  *
- * Optionally also set X-Engram-Namespace and X-Engram-Principal for
- * project/user scoping.
+ * Optionally also set X-Engram-Namespace for project scoping. Principal
+ * overrides are intentionally handled only by the HTTP server's
+ * trustPrincipalHeader gate. Adapters must not independently trust
+ * X-Engram-Principal.
  */
 export class ReplitAdapter implements EngramAdapter {
   readonly id = "replit";
@@ -38,18 +40,14 @@ export class ReplitAdapter implements EngramAdapter {
   resolveIdentity(context: AdapterContext): ResolvedIdentity {
     const mcpSessionId = headerValue(context.headers, "mcp-session-id");
 
-    const principal = headerValue(context.headers, "x-engram-principal")
-      || "replit-agent";
-
     const namespace = headerValue(context.headers, "x-engram-namespace")
       || "replit";
 
     return {
       namespace,
-      principal,
+      principal: "replit-agent",
       sessionKey: mcpSessionId ?? context.sessionKey,
       adapterId: this.id,
     };
   }
 }
-

package/src/adapters/types.ts

@@ -13,6 +13,10 @@ export interface AdapterContext {
   clientInfo?: { name: string; version?: string };
   /** Explicit session key from request args */
   sessionKey?: string;
+  /** Explicit namespace from already-validated request args */
+  namespace?: string;
+  /** Explicit principal from already-validated request args */
+  principal?: string;
 }
 
 export interface ResolvedIdentity {
@@ -45,7 +49,26 @@ export function headerValue(
   headers: Record<string, string | string[] | undefined>,
   key: string,
 ): string | undefined {
-  const raw = headers[key];
+  const exactValue = normalizeHeaderValue(headers[key]);
+  if (exactValue !== undefined) {
+    return exactValue;
+  }
+
+  const normalizedKey = key.toLowerCase();
+  for (const [headerKey, raw] of Object.entries(headers)) {
+    if (headerKey.toLowerCase() !== normalizedKey) {
+      continue;
+    }
+    const value = normalizeHeaderValue(raw);
+    if (value !== undefined) {
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
+function normalizeHeaderValue(raw: string | string[] | undefined): string | undefined {
   const value = Array.isArray(raw) ? raw[0] : raw;
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
 }

package/src/behavior-signals.ts

@@ -64,7 +64,7 @@ export function dedupeBehaviorSignalsByMemoryAndHash(
   const seen = new Set<string>();
   const out: BehaviorSignalEvent[] = [];
   for (const signal of signals) {
-    const key = `${signal.memoryId}:${signal.signalHash}`;
+    const key = `${signal.namespace}:${signal.memoryId}:${signal.signalHash}`;
     if (seen.has(key)) continue;
     seen.add(key);
     out.push(signal);

package/src/binary-lifecycle/backend.ts

@@ -41,11 +41,23 @@ export class FilesystemBackend implements BinaryStorageBackend {
     if (!basePath || basePath.trim().length === 0) {
       throw new Error("FilesystemBackend requires a non-empty basePath");
     }
-    this.basePath = basePath;
+    this.basePath = path.resolve(basePath);
+  }
+
+  private resolveRemotePath(remotePath: string): string {
+    if (path.isAbsolute(remotePath)) {
+      throw new Error(`FilesystemBackend remotePath must be relative: ${JSON.stringify(remotePath)}`);
+    }
+    const resolved = path.resolve(this.basePath, remotePath);
+    const relative = path.relative(this.basePath, resolved);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+      throw new Error(`FilesystemBackend remotePath escapes basePath: ${JSON.stringify(remotePath)}`);
+    }
+    return resolved;
   }
 
   async upload(localPath: string, remotePath: string): Promise<string> {
-    const dest = path.join(this.basePath, remotePath);
+    const dest = this.resolveRemotePath(remotePath);
     const destDir = path.dirname(dest);
     await fsp.mkdir(destDir, { recursive: true });
     await fsp.copyFile(localPath, dest);
@@ -53,7 +65,7 @@ export class FilesystemBackend implements BinaryStorageBackend {
   }
 
   async exists(remotePath: string): Promise<boolean> {
-    const dest = path.join(this.basePath, remotePath);
+    const dest = this.resolveRemotePath(remotePath);
     try {
       await fsp.access(dest, fs.constants.F_OK);
       return true;
@@ -63,7 +75,7 @@ export class FilesystemBackend implements BinaryStorageBackend {
   }
 
   async delete(remotePath: string): Promise<void> {
-    const dest = path.join(this.basePath, remotePath);
+    const dest = this.resolveRemotePath(remotePath);
     try {
       await fsp.unlink(dest);
     } catch (err: unknown) {

package/src/binary-lifecycle/pipeline.test.ts

@@ -0,0 +1,149 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import crypto from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { runBinaryLifecyclePipeline } from "./pipeline.js";
+import { writeManifest } from "./manifest.js";
+import type { BinaryLifecycleConfig } from "./types.js";
+import type { BinaryStorageBackend } from "./backend.js";
+
+const baseConfig: BinaryLifecycleConfig = {
+  enabled: true,
+  gracePeriodDays: 0,
+  maxBinarySizeBytes: 1024 * 1024,
+  scanPatterns: ["*.png"],
+  backend: { type: "none" },
+};
+
+test("binary lifecycle pipeline is a no-op when disabled", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-binary-disabled-"));
+  let uploaded = false;
+  try {
+    await writeFile(path.join(memoryDir, "image.png"), "bytes", "utf8");
+    const backend = {
+      type: "test",
+      upload: async () => {
+        uploaded = true;
+        return "remote";
+      },
+      exists: async () => false,
+      delete: async () => {},
+    } satisfies BinaryStorageBackend;
+
+    const result = await runBinaryLifecyclePipeline(
+      memoryDir,
+      { ...baseConfig, enabled: false },
+      backend,
+      noopLogger,
+    );
+
+    assert.deepEqual(result, {
+      scanned: 0,
+      mirrored: 0,
+      redirected: 0,
+      cleaned: 0,
+      errors: [],
+      dryRun: false,
+    });
+    assert.equal(uploaded, false);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("binary lifecycle remirrors changed tracked binaries", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-binary-remirror-"));
+  const uploaded: string[] = [];
+  try {
+    await writeFile(path.join(memoryDir, "image.png"), "new-content", "utf8");
+    await writeManifest(memoryDir, {
+      version: 1,
+      assets: [
+        {
+          originalPath: "image.png",
+          mirroredPath: "image.png",
+          contentHash: sha256("old-content"),
+          sizeBytes: "old-content".length,
+          mimeType: "image/png",
+          mirroredAt: "2026-01-01T00:00:00.000Z",
+          status: "mirrored",
+        },
+      ],
+    });
+    const backend = {
+      type: "test",
+      upload: async (_localPath: string, remotePath: string) => {
+        uploaded.push(remotePath);
+        return `remote/${remotePath}`;
+      },
+      exists: async () => false,
+      delete: async () => {},
+    } satisfies BinaryStorageBackend;
+
+    const result = await runBinaryLifecyclePipeline(memoryDir, baseConfig, backend, noopLogger);
+    const manifest = JSON.parse(
+      await readFile(path.join(memoryDir, ".binary-lifecycle", "manifest.json"), "utf8"),
+    ) as { assets: Array<{ originalPath: string; contentHash: string; mirroredPath: string }> };
+
+    assert.equal(result.mirrored, 1);
+    assert.deepEqual(uploaded, ["image.png"]);
+    assert.equal(manifest.assets.length, 1);
+    assert.equal(manifest.assets[0]?.contentHash, sha256("new-content"));
+    assert.equal(manifest.assets[0]?.mirroredPath, "remote/image.png");
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("binary lifecycle blocks cleanup when local hash no longer matches manifest", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-binary-clean-"));
+  try {
+    await writeFile(path.join(memoryDir, "image.png"), "changed", "utf8");
+    await writeFile(path.join(memoryDir, "note.md"), "![img](image.png)", "utf8");
+    await writeManifest(memoryDir, {
+      version: 1,
+      assets: [
+        {
+          originalPath: "image.png",
+          mirroredPath: "remote/image.png",
+          contentHash: sha256("original"),
+          sizeBytes: "original".length,
+          mimeType: "image/png",
+          mirroredAt: "2026-01-01T00:00:00.000Z",
+          redirectedAt: "2026-01-01T00:00:00.000Z",
+          status: "redirected",
+        },
+      ],
+    });
+
+    const result = await runBinaryLifecyclePipeline(memoryDir, baseConfig, noUploadBackend, noopLogger);
+
+    assert.equal(result.cleaned, 0);
+    assert.match(result.errors.join("\n"), /local content hash does not match manifest/);
+    assert.equal(await readFile(path.join(memoryDir, "image.png"), "utf8"), "changed");
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+const noopLogger = {
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+};
+
+const noUploadBackend = {
+  type: "test",
+  upload: async () => {
+    throw new Error("upload should not run");
+  },
+  exists: async () => false,
+  delete: async () => {},
+} satisfies BinaryStorageBackend;
+
+function sha256(value: string): string {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}