@remnic/core 9.69.33 → 9.69.34

package/src/activity/timeline/regenerate.ts

@@ -0,0 +1,373 @@
+/**
+ * Production timeline/activity regenerate flow (issue #2050).
+ *
+ * Builds deterministic cards, optionally runs analysis once, and persists
+ * the day. Analysis failure keeps the deterministic cards. Concurrent
+ * callers share one in-flight run. Surfaces (sync, CLI) call this function.
+ */
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import { FallbackLlmClient, fallbackLlmRuntimeContextFromConfig } from "../../fallback-llm.js";
+import { LocalLlmClient } from "../../local-llm.js";
+import type { PluginConfig } from "../../types.js";
+import {
+  activityDateInTimezone,
+  activityDayWindow,
+  hashActivityBody,
+  isValidActivityDate,
+} from "../digest.js";
+import type { ActivitySnapshot, ActivityTimelineAnalysisConfig } from "../types.js";
+import { applyTimelineCorrections, correctionsForCards, TimelineCorrectionStore } from "./corrections.js";
+import { buildTimelineDay } from "./build.js";
+import { runTimelineCardAnalysis, type TimelineAnalysisRunResult } from "./analysis-run.js";
+import type {
+  TimelineAnalysisLocalLlm,
+  TimelineAnalysisRemoteLlm,
+} from "./analysis-provider.js";
+import type { AnalysisFailure } from "./analysis-failure.js";
+import type { AnalysisRunMetadata } from "./analysis-metadata.js";
+import type { TimelineAnalysisStatus } from "./analysis.js";
+import type { TimelineCard, TimelineCorrection, TimelineObservation } from "./types.js";
+
+export const TIMELINE_DAY_FORMAT_VERSION = 1;
+export const TIMELINE_DAY_DIR = path.join("activity", "timeline");
+
+export interface TimelineAnalysisClients {
+  localLlm?: TimelineAnalysisLocalLlm | null;
+  remoteLlm?: TimelineAnalysisRemoteLlm | null;
+}
+
+export interface RegenerateTimelineDayInput {
+  date: string;
+  timezone: string;
+  memoryDir: string;
+  store: { listSnapshotsForDay: (machine: string | null, startUtc: string, endUtc: string) => ActivitySnapshot[] };
+  timelineEnabled: boolean;
+  analysis: ActivityTimelineAnalysisConfig;
+  deps?: TimelineAnalysisClients;
+  pluginConfig?: PluginConfig;
+  signal?: AbortSignal;
+  corrections?: readonly TimelineCorrection[];
+}
+
+/**
+ * Persisted day status. "pending" is the prewrite marker for an enabled run
+ * whose analysis has not completed: a crash after the deterministic prewrite
+ * must not read as terminal on the next run.
+ */
+export type PersistedTimelineDayStatus = TimelineAnalysisStatus | "pending" | "timeline_disabled";
+
+export interface PersistedTimelineDay {
+  formatVersion: number;
+  date: string;
+  timezone: string;
+  sourceHash: string;
+  status: PersistedTimelineDayStatus;
+  cards: TimelineCard[];
+  metadata?: AnalysisRunMetadata;
+  failure?: AnalysisFailure;
+}
+
+export interface RegenerateTimelineDayResult {
+  status: PersistedTimelineDayStatus;
+  cards: TimelineCard[];
+  path: string;
+  written: boolean;
+  analyzed: boolean;
+  metadata?: AnalysisRunMetadata;
+  failure?: AnalysisFailure;
+}
+
+const inflight = new Map<string, Promise<RegenerateTimelineDayResult>>();
+
+function requireToken(value: string, name: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+export function timelineDayPath(memoryDir: string, date: string): string {
+  const root = requireToken(memoryDir, "memoryDir");
+  if (!isValidActivityDate(date)) {
+    throw new RangeError("date must be a real YYYY-MM-DD day");
+  }
+  return path.join(path.resolve(root), TIMELINE_DAY_DIR, `${date}.json`);
+}
+
+export function snapshotToObservation(snapshot: ActivitySnapshot): TimelineObservation | null {
+  if (typeof snapshot.id !== "number") return null;
+  return {
+    id: snapshot.id,
+    machine: snapshot.machine,
+    capturedAtUtc: snapshot.capturedAtUtc,
+    app: snapshot.app,
+    windowTitle: snapshot.windowTitle,
+    ...(snapshot.browserUrl === undefined ? {} : { browserUrl: snapshot.browserUrl }),
+    contentHash: snapshot.contentHash,
+  };
+}
+
+/** Local calendar days covering [fromMs, toMs), oldest first. Capped at 3660 days. */
+export function localDatesForUtcRange(fromMs: number, toMs: number, timezone: string): string[] {
+  if (!Number.isFinite(fromMs) || !Number.isFinite(toMs) || toMs <= fromMs) return [];
+  const dates: string[] = [];
+  let date = activityDateInTimezone(new Date(fromMs), timezone);
+  const last = activityDateInTimezone(new Date(toMs - 1), timezone);
+  while (dates.length < 3660) {
+    dates.push(date);
+    if (date === last) break;
+    const { endUtc } = activityDayWindow(date, timezone);
+    date = activityDateInTimezone(new Date(Date.parse(endUtc)), timezone);
+  }
+  return dates;
+}
+
+/** Persisted local days already on disk (YYYY-MM-DD), regardless of store state. */
+export function listPersistedTimelineDates(memoryDir: string): string[] {
+  let entries: readonly string[];
+  try {
+    entries = readdirSync(path.join(path.resolve(requireToken(memoryDir, "memoryDir")), TIMELINE_DAY_DIR));
+  } catch {
+    return [];
+  }
+  const dates: string[] = [];
+  for (const entry of entries) {
+    const day = entry.endsWith(".json") ? entry.slice(0, -".json".length) : entry;
+    if (isValidActivityDate(day)) dates.push(day);
+  }
+  return dates.sort();
+}
+
+/**
+ * Local days a CLI window must load. Bounded windows keep the explicit
+ * from/to span. An unbounded search loads every day the snapshot store or a
+ * persisted day file covers (plus today), so historical cards enter the
+ * search pool instead of only the current day.
+ */
+export function resolveTimelineLoadDates(input: {
+  window: { from?: string; to?: string };
+  timezone: string;
+  today: string;
+  store: { snapshotCaptureExtent(): { firstUtc: string; lastUtc: string } | null };
+  persistedDates: readonly string[];
+}): string[] {
+  const { window, timezone, today, store, persistedDates } = input;
+  if (window.from !== undefined || window.to !== undefined) {
+    const fromMs = window.from === undefined ? Date.now() : Date.parse(window.from);
+    const toMs = window.to === undefined ? fromMs + 1 : Date.parse(window.to);
+    if (!Number.isFinite(fromMs) || !Number.isFinite(toMs)) return [];
+    return localDatesForUtcRange(fromMs, toMs > fromMs ? toMs : fromMs + 1, timezone);
+  }
+  const days = new Set<string>(persistedDates);
+  days.add(today);
+  const extent = store.snapshotCaptureExtent();
+  if (extent !== null) {
+    const firstMs = Date.parse(extent.firstUtc);
+    const lastMs = Date.parse(extent.lastUtc);
+    if (Number.isFinite(firstMs) && Number.isFinite(lastMs) && lastMs >= firstMs) {
+      for (const day of localDatesForUtcRange(firstMs, lastMs + 1, timezone)) days.add(day);
+    }
+  }
+  return [...days].sort();
+}
+
+export function timelineAnalysisClientsFromConfig(config: PluginConfig): TimelineAnalysisClients {
+  return {
+    localLlm: new LocalLlmClient(config),
+    remoteLlm: new FallbackLlmClient(
+      config.gatewayConfig,
+      fallbackLlmRuntimeContextFromConfig(config),
+    ),
+  };
+}
+
+function resolveClients(input: RegenerateTimelineDayInput): TimelineAnalysisClients {
+  if (input.deps !== undefined) return input.deps;
+  if (input.pluginConfig !== undefined) return timelineAnalysisClientsFromConfig(input.pluginConfig);
+  return {};
+}
+
+function sourceHash(input: {
+  observations: readonly TimelineObservation[];
+  analysis: ActivityTimelineAnalysisConfig;
+  corrections: readonly TimelineCorrection[];
+}): string {
+  return hashActivityBody(
+    JSON.stringify({
+      observations: input.observations.map((observation) => ({
+        id: observation.id,
+        contentHash: observation.contentHash,
+        capturedAtUtc: observation.capturedAtUtc,
+      })),
+      analysis: {
+        enabled: input.analysis.enabled,
+        provider: input.analysis.provider ?? null,
+        model: input.analysis.model ?? null,
+        timeoutMs: input.analysis.timeoutMs ?? null,
+        preferences: input.analysis.preferences ?? null,
+      },
+      corrections: input.corrections,
+    }),
+  );
+}
+
+function readPersisted(filePath: string): PersistedTimelineDay | null {
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, "utf8")) as PersistedTimelineDay;
+    if (parsed?.formatVersion !== TIMELINE_DAY_FORMAT_VERSION || !Array.isArray(parsed.cards)) {
+      return null;
+    }
+    return parsed;
+  } catch (error) {
+    if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+      return null;
+    }
+    return null;
+  }
+}
+
+function persistDay(filePath: string, payload: PersistedTimelineDay): boolean {
+  const text = `${JSON.stringify(payload)}\n`;
+  try {
+    if (readFileSync(filePath, "utf8") === text) return false;
+  } catch (error) {
+    if (!(typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT")) {
+      throw error;
+    }
+  }
+  mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  const tmpPath = `${filePath}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+  writeFileSync(tmpPath, text, { encoding: "utf8", mode: 0o600 });
+  try {
+    renameSync(tmpPath, filePath);
+  } catch (error) {
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+      // Best-effort cleanup of the temp file.
+    }
+    throw error;
+  }
+  return true;
+}
+
+function toResult(
+  filePath: string,
+  written: boolean,
+  analyzed: boolean,
+  day: Pick<PersistedTimelineDay, "status" | "cards" | "metadata" | "failure">,
+): RegenerateTimelineDayResult {
+  return {
+    status: day.status,
+    cards: day.cards,
+    path: filePath,
+    written,
+    analyzed,
+    ...(day.metadata === undefined ? {} : { metadata: day.metadata }),
+    ...(day.failure === undefined ? {} : { failure: day.failure }),
+  };
+}
+
+/**
+ * A cached day is final when its persisted status matches the request:
+ * completed results (ok, or an explicit provider/output failure) are terminal
+ * for the same source hash, so unchanged scheduled syncs and CLI reads never
+ * repeat provider spend. A "pending" prewrite, or a "disabled" file under an
+ * enabled request (legacy prewrite or interrupted run), is rebuilt so a later
+ * enabled config can still analyze.
+ */
+function isCachedDayFinal(status: PersistedTimelineDayStatus, analysisEnabled: boolean): boolean {
+  if (analysisEnabled) {
+    return status === "ok" || status === "provider_failed" || status === "invalid_output";
+  }
+  return status === "disabled";
+}
+
+async function regenerateUncached(input: RegenerateTimelineDayInput): Promise<RegenerateTimelineDayResult> {
+  const date = requireToken(input.date, "date");
+  const timezone = requireToken(input.timezone, "timezone");
+  const filePath = timelineDayPath(input.memoryDir, date);
+  if (!input.timelineEnabled) {
+    return toResult(filePath, false, false, { status: "timeline_disabled", cards: [] });
+  }
+
+  const { startUtc, endUtc } = activityDayWindow(date, timezone);
+  const observations = input.store
+    .listSnapshotsForDay(null, startUtc, endUtc)
+    .map(snapshotToObservation)
+    .filter((observation): observation is TimelineObservation => observation !== null);
+
+  let corrections = input.corrections;
+  let opened: TimelineCorrectionStore | undefined;
+  if (corrections === undefined) {
+    opened = TimelineCorrectionStore.open(input.memoryDir);
+    corrections = opened.list();
+  }
+  try {
+    const rawCards = buildTimelineDay({ date, timezone, observations }).cards;
+    corrections = correctionsForCards(rawCards, corrections);
+    const built = applyTimelineCorrections(rawCards, corrections);
+    const hash = sourceHash({ observations, analysis: input.analysis, corrections });
+    const prior = readPersisted(filePath);
+    if (prior !== null && prior.sourceHash === hash && isCachedDayFinal(prior.status, input.analysis.enabled)) {
+      return toResult(filePath, false, false, prior);
+    }
+
+    const deterministic: PersistedTimelineDay = {
+      formatVersion: TIMELINE_DAY_FORMAT_VERSION,
+      date,
+      timezone,
+      sourceHash: hash,
+      status: input.analysis.enabled ? "pending" : "disabled",
+      cards: built,
+    };
+    persistDay(filePath, deterministic);
+
+    if (!input.analysis.enabled) {
+      return toResult(filePath, true, false, deterministic);
+    }
+
+    const deps = resolveClients(input);
+    const analyzed: TimelineAnalysisRunResult = await runTimelineCardAnalysis({
+      date,
+      timezone,
+      cards: built,
+      observations,
+      corrections,
+      config: input.analysis,
+      deps,
+      ...(input.signal === undefined ? {} : { signal: input.signal }),
+    });
+    const next: PersistedTimelineDay = {
+      formatVersion: TIMELINE_DAY_FORMAT_VERSION,
+      date,
+      timezone,
+      sourceHash: hash,
+      status: analyzed.status,
+      cards: analyzed.cards,
+      ...(analyzed.metadata === undefined ? {} : { metadata: analyzed.metadata }),
+      ...(analyzed.failure === undefined ? {} : { failure: analyzed.failure }),
+    };
+    persistDay(filePath, next);
+    return toResult(filePath, true, analyzed.status === "ok", next);
+  } finally {
+    opened?.close();
+  }
+}
+
+/** Build, optionally analyze once, and persist one local day of timeline cards. */
+export async function regenerateTimelineDay(
+  input: RegenerateTimelineDayInput,
+): Promise<RegenerateTimelineDayResult> {
+  const key = `${path.resolve(requireToken(input.memoryDir, "memoryDir"))}\0${input.date}`;
+  const pending = inflight.get(key);
+  if (pending !== undefined) return pending;
+  const run = regenerateUncached(input).finally(() => {
+    if (inflight.get(key) === run) inflight.delete(key);
+  });
+  inflight.set(key, run);
+  return run;
+}

package/src/activity/types.ts

@@ -12,6 +12,7 @@
  */
 
 import type { ImportanceLevel } from "../types.js";
+import type { JournalSource } from "./journal-source.js";
 
 export type ActivityExtractionMode = "off" | "smart";
 
@@ -96,13 +97,22 @@ export interface ActivitySourceConfig {
   token?: string;
 }
 
-/** Opt-in daily journal settings (issue #1984). Default off. */
+/** Opt-in daily journal settings (issue #1984; vault read-back #1987). Default off. */
 export interface ActivityTimelineJournalConfig {
   enabled: boolean;
-  /** Where the journal text is read from (issue #1987). */
-  source: "file" | "vault";
-  /** Vault section heading, trimmed. Required when `source` is `"vault"`; not stored in `"file"` mode. */
-  heading?: string;
+  /** Where the journal text is read from: the memoryDir day file (default) or the vault daily note. */
+  source: JournalSource;
+  /** Review-only journal extraction gate (issue #1987): "off" | "review". No auto mode by design. */
+  extractionMode: ActivityJournalExtractionMode;
+}
+
+/** Journal extraction is review-only by design (#1984 decision): no "auto". */
+export type ActivityJournalExtractionMode = "off" | "review";
+
+/** Vault daily-note read-back settings (issue #1987). */
+export interface ActivityTimelineVaultReadbackConfig {
+  /** Heading whose section is the user's journal; arbitrary user-chosen text. */
+  journalSection: string;
 }
 
 /** Section ownership strategy for vault publishing (issue #1985). */
@@ -144,6 +154,7 @@ export interface ActivityTimelineVaultConfig {
   };
   /** Markers strategy: heading under which missing marker pairs are inserted; empty = never insert. */
   insertUnderHeading: string;
+  readback: ActivityTimelineVaultReadbackConfig;
   wikilinks: { places: boolean; placesFolder: string };
   properties: { mode: VaultPropertiesMode; prefix: string };
   autoPublish: boolean;
@@ -156,9 +167,33 @@ export interface ActivityTimelineQaConfig {
   maxRangeDays: number;
 }
 
+/**
+ * Opt-in AI analysis over deterministic timeline cards (issue #2050).
+ * Default off; gated independently of `activity.timeline.enabled`, capture,
+ * and memory creation. When disabled, zero provider calls and zero analysis
+ * artifacts occur.
+ */
+export interface ActivityTimelineAnalysisConfig {
+  enabled: boolean;
+  /**
+   * Explicit provider id: `"local"` routes to the local LLM client; any other
+   * identifier routes to the configured remote provider registry. Required
+   * when enabled. A single provider segment only — `/` is rejected at parse.
+   * At most 120 characters so accepted config cannot fail metadata validation.
+   */
+  provider?: string;
+  /** Model id. Required when enabled. May include `/`. At most 120 characters. */
+  model?: string;
+  /** Per-request timeout in ms. Positive integer. */
+  timeoutMs?: number;
+  /** Free-form user preferences passed to the prompt (no secrets). */
+  preferences?: string[];
+}
+
 /** Opt-in timeline-card derivation settings (issue #2049). Default off. */
 export interface ActivityTimelineConfig {
   enabled: boolean;
+  analysis: ActivityTimelineAnalysisConfig;
   journal: ActivityTimelineJournalConfig;
   qa: ActivityTimelineQaConfig;
   vault: ActivityTimelineVaultConfig;

package/src/adapters/grok-opencode.test.ts

@@ -0,0 +1,146 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { AdapterRegistry } from "./registry.js";
+import { GrokAdapter } from "./grok.js";
+import { OpenCodeAdapter } from "./opencode.js";
+import type { AdapterContext } from "./types.js";
+
+function context(overrides: Partial<AdapterContext> = {}): AdapterContext {
+  return { headers: {}, ...overrides };
+}
+
+test("GrokAdapter matches clientInfo names containing grok", () => {
+  const adapter = new GrokAdapter();
+  assert.equal(adapter.matches(context({ clientInfo: { name: "grok" } })), true);
+  assert.equal(adapter.matches(context({ clientInfo: { name: "grok-cli" } })), true);
+  assert.equal(adapter.matches(context({ clientInfo: { name: "Grok-Desktop" } })), true);
+});
+
+test("GrokAdapter matches User-Agent and configured client-id headers", () => {
+  const adapter = new GrokAdapter();
+  assert.equal(adapter.matches(context({ headers: { "user-agent": "grok/4.6" } })), true);
+  assert.equal(
+    adapter.matches(context({ headers: { "X-Engram-Client-Id": "grok" } })),
+    true,
+  );
+});
+
+test("GrokAdapter rejects unrelated clients", () => {
+  const adapter = new GrokAdapter();
+  assert.equal(adapter.matches(context()), false);
+  assert.equal(adapter.matches(context({ clientInfo: { name: "claude-code" } })), false);
+  assert.equal(adapter.matches(context({ clientInfo: { name: "codex-mcp-client" } })), false);
+  assert.equal(adapter.matches(context({ clientInfo: { name: "opencode" } })), false);
+  assert.equal(
+    adapter.matches(context({ headers: { "X-Engram-Client-Id": "codex" } })),
+    false,
+  );
+});
+
+test("GrokAdapter resolves identity with adapter-owned principal and header namespace", () => {
+  const adapter = new GrokAdapter();
+  assert.deepEqual(
+    adapter.resolveIdentity(context({
+      headers: {
+        "mcp-session-id": "sess-grok-1",
+        "x-engram-namespace": "my-project",
+      },
+    })),
+    {
+      namespace: "my-project",
+      principal: "grok",
+      sessionKey: "sess-grok-1",
+      adapterId: "grok",
+    },
+  );
+  assert.deepEqual(
+    adapter.resolveIdentity(context({ sessionKey: "session-1" })).principal,
+    "grok",
+  );
+  // Default namespace when no explicit header is present.
+  assert.equal(
+    adapter.resolveIdentity(context()).namespace,
+    "grok",
+  );
+});
+
+test("OpenCodeAdapter matches clientInfo, User-Agent, and configured client-id headers", () => {
+  const adapter = new OpenCodeAdapter();
+  assert.equal(adapter.matches(context({ clientInfo: { name: "opencode" } })), true);
+  assert.equal(adapter.matches(context({ clientInfo: { name: "OpenCode/1.0" } })), true);
+  assert.equal(adapter.matches(context({ headers: { "user-agent": "opencode/2.3.0" } })), true);
+  assert.equal(
+    adapter.matches(context({ headers: { "X-Engram-Client-Id": "opencode" } })),
+    true,
+  );
+});
+
+test("OpenCodeAdapter rejects unrelated clients", () => {
+  const adapter = new OpenCodeAdapter();
+  assert.equal(adapter.matches(context()), false);
+  assert.equal(adapter.matches(context({ clientInfo: { name: "claude-code" } })), false);
+  assert.equal(adapter.matches(context({ clientInfo: { name: "codex-mcp-client" } })), false);
+  assert.equal(adapter.matches(context({ clientInfo: { name: "grok" } })), false);
+});
+
+test("OpenCodeAdapter resolves identity with adapter-owned principal", () => {
+  const adapter = new OpenCodeAdapter();
+  const resolved = adapter.resolveIdentity(context({
+    headers: { "mcp-session-id": "sess-oc-1" },
+  }));
+  assert.deepEqual(resolved, {
+    namespace: "opencode",
+    principal: "opencode",
+    sessionKey: "sess-oc-1",
+    adapterId: "opencode",
+  });
+});
+
+test("default registry registers grok and opencode adapters in order", () => {
+  const registry = new AdapterRegistry();
+  assert.deepEqual(registry.list(), [
+    "hermes",
+    "replit",
+    "codex",
+    "claude-code",
+    "grok",
+    "opencode",
+  ]);
+});
+
+test("issue #2782 reproduction: Grok headers resolve a transport principal without a session key", () => {
+  const registry = new AdapterRegistry();
+  const resolved = registry.resolve({
+    headers: {
+      "x-engram-client-id": "grok",
+      "x-engram-principal": "grok",
+    },
+  });
+  assert.ok(resolved, "expected the Grok adapter to resolve the request");
+  assert.equal(resolved.principal, "grok");
+  assert.equal(resolved.adapterId, "grok");
+  assert.equal(resolved.sessionKey, undefined);
+});
+
+test("issue #2782 reproduction: OpenCode headers resolve a transport principal without a session key", () => {
+  const registry = new AdapterRegistry();
+  const resolved = registry.resolve({
+    headers: { "x-engram-client-id": "opencode" },
+    clientInfo: { name: "opencode" },
+  });
+  assert.ok(resolved, "expected the OpenCode adapter to resolve the request");
+  assert.equal(resolved.principal, "opencode");
+});
+
+test("adapters never adopt X-Engram-Principal as their own resolution source", () => {
+  const registry = new AdapterRegistry();
+  for (const clientId of ["grok", "opencode"]) {
+    const resolved = registry.resolve({
+      headers: { "x-engram-client-id": clientId, "x-engram-principal": "spoofed-principal" },
+    });
+    assert.ok(resolved);
+    assert.equal(resolved.principal, clientId);
+    assert.notEqual(resolved.principal, "spoofed-principal");
+  }
+});

package/src/adapters/grok.ts

@@ -0,0 +1,53 @@
+import { headerValue, type AdapterContext, type EngramAdapter, type ResolvedIdentity } from "./types.js";
+
+/**
+ * Grok adapter.
+ *
+ * Detection: Grok clients identify themselves with a clientInfo name
+ * containing "grok" in the MCP initialize handshake, and send
+ * User-Agent: grok/<version> on HTTP requests. The exact clientInfo
+ * name is not yet stable across Grok surfaces (desktop app, CLI), so
+ * detection uses a contains-match for forward compatibility.
+ *
+ * User-configured identification is also supported via headers:
+ *      "headers": { "X-Engram-Client-Id": "grok" }
+ *
+ * Principal overrides are intentionally handled only by the HTTP server's
+ * trustPrincipalHeader gate. Adapters must not independently trust
+ * X-Engram-Principal.
+ */
+export class GrokAdapter implements EngramAdapter {
+  readonly id = "grok";
+
+  matches(context: AdapterContext): boolean {
+    // Primary: MCP clientInfo from initialize handshake
+    const clientName = context.clientInfo?.name?.toLowerCase() ?? "";
+    if (clientName.includes("grok")) return true;
+
+    // Fallback: User-Agent header ("grok/<version>")
+    const ua = headerValue(context.headers, "user-agent");
+    if (ua && ua.toLowerCase().startsWith("grok/")) return true;
+
+    // Fallback: user-configured client identifier header
+    const clientId = headerValue(context.headers, "x-engram-client-id");
+    if (clientId?.toLowerCase() === "grok") return true;
+
+    return false;
+  }
+
+  resolveIdentity(context: AdapterContext): ResolvedIdentity {
+    // MCP session ID (standard MCP header, server-assigned)
+    const mcpSessionId = headerValue(context.headers, "mcp-session-id");
+
+    // Namespace: explicit header > default
+    const namespace = headerValue(context.headers, "x-engram-namespace")
+      || "grok";
+
+    return {
+      namespace,
+      principal: "grok",
+      sessionKey: mcpSessionId ?? context.sessionKey,
+      adapterId: this.id,
+    };
+  }
+}

package/src/adapters/index.ts

@@ -1,6 +1,8 @@
 export type { AdapterContext, EngramAdapter, ResolvedIdentity } from "./types.js";
 export { ClaudeCodeAdapter } from "./claude-code.js";
 export { CodexAdapter } from "./codex.js";
+export { GrokAdapter } from "./grok.js";
+export { OpenCodeAdapter } from "./opencode.js";
 export { ReplitAdapter } from "./replit.js";
 export { HermesAdapter } from "./hermes.js";
 export { AdapterRegistry } from "./registry.js";