@mnemom/mnemom 0.17.4-next.3 → 0.17.4-next.5

package/dist/turn-origin.mjs

@@ -0,0 +1,330 @@
+// turn-origin.mjs — states where each recent user turn came from, read from Claude Code's OWN
+// transcript, as the `x-mnemom-turn` request header (implicit goal mode, provenance design B).
+//
+// WHY. On the wire a cron / loop tick, a skill body, hook text, a channel relay and a peer message
+// all go out as plain user text. Claude Code records the difference locally: every user entry in
+// `<config>/projects/<cwd-slug>/<session-id>.jsonl` carries `promptId`, `promptSource`
+// (typed / queued / system / sdk), `turnOrigin` (human / scheduled / peer / task_notification /
+// system / sdk), `origin.kind` (human / task-notification / peer / channel), `isMeta` and
+// `isCompactSummary`. The local proxy in front of Claude Code (rc-proxy.mjs under Remote Control,
+// base-url-proxy.mjs in terminal mode) takes a request's `x-claude-code-prompt-id`, waits until
+// the transcript holds an entry with that promptId (Claude Code writes it ~90 ms before the
+// request leaves; we retry for up to WAIT_MS), and sends the recent prompt entries' facts:
+//
+//   x-mnemom-turn: origin=scheduled; source=system; pastes=0; h=<sha256 hex of the text>, …
+//
+// One entry per text part (oldest first, at most TURN_PARTS_MAX). The gateway
+// (gateway/src/goal-turn-claims.ts) uses it restrict-only: text whose hash matches a NON-human
+// entry is never the user's words; nothing is ever promoted. No header (no prompt id, a transcript
+// that is missing, unreadable or late, a schema without these fields) = the gateway's step-A
+// behaviour. Only facts Claude Code itself recorded decide an origin: no text is inspected for
+// meaning (the paste count reads Claude Code's own `<pasted_content id=…>` wrapper).
+//
+// Node >= 18, no dependencies. Never logs transcript text.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+
+export const TURN_HEADER = "x-mnemom-turn";
+/** Text parts sent per request (the gateway accepts up to 32). */
+export const TURN_PARTS_MAX = 16;
+/** How long a request waits for its prompt's transcript entry. */
+export const WAIT_MS = 500;
+const POLL_MS = 20;
+/** Prompt entries kept in memory per transcript (only the newest TURN_PARTS_MAX parts are sent). */
+const ENTRIES_KEPT = 64;
+/** Prompt ids remembered per transcript before the set is reset. */
+const PROMPT_IDS_MAX = 4096;
+const READ_CHUNK = 256 * 1024;
+const ID_RE = /^[A-Za-z0-9-]{8,64}$/;
+
+/** The configured Claude Code home: CLAUDE_CONFIG_DIR, else ~/.claude. */
+export function claudeConfigDir(env = process.env) {
+  return env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+}
+
+/** Claude Code's project directory name for a cwd: every non-alphanumeric byte becomes "-". */
+export function cwdSlug(cwd) {
+  return String(cwd).replace(/[^A-Za-z0-9]/g, "-");
+}
+
+function contentOf(entry) {
+  return entry && entry.message ? entry.message.content : undefined;
+}
+
+/**
+ * A prompt entry: a user entry that is not a tool result and not a sidechain (a subagent's own
+ * transcript lives in its own file). Tool results carry the prompt id too, but they are the
+ * tools' output, never a turn.
+ */
+export function isPromptEntry(entry) {
+  if (!entry || entry.type !== "user" || entry.isSidechain === true) return false;
+  const c = contentOf(entry);
+  if (typeof c === "string") return true;
+  if (!Array.isArray(c)) return false;
+  return !c.some((b) => b && b.type === "tool_result");
+}
+
+/**
+ * The origin Claude Code recorded for a prompt entry, or null when it recorded none we know
+ * (then the entry is not stated at all, and the gateway reads that text as before).
+ * Precedence: summary / transcript-only → meta; channel; scheduled; peer; task; isMeta → meta;
+ * a human origin or a typed / queued prompt → human.
+ */
+export function entryOrigin(entry) {
+  if (!entry) return null;
+  const turn = entry.turnOrigin;
+  const kind = entry.origin && typeof entry.origin === "object" ? entry.origin.kind : undefined;
+  if (entry.isCompactSummary === true || entry.isVisibleInTranscriptOnly === true) return "meta";
+  if (kind === "channel") return "channel";
+  if (turn === "scheduled" || (typeof entry.scheduledTaskId === "string" && entry.scheduledTaskId))
+    return "scheduled";
+  if (turn === "peer" || kind === "peer") return "peer";
+  if (turn === "task_notification" || kind === "task-notification") return "task";
+  if (entry.isMeta === true || turn === "system") return "meta";
+  if (turn === "human" || kind === "human") return "human";
+  if (entry.promptSource === "typed" || entry.promptSource === "queued") return "human";
+  return null;
+}
+
+const SOURCES = new Set(["typed", "queued", "system", "sdk"]);
+
+/** `promptSource` when it is one of the four Claude Code records, else undefined. */
+export function entrySource(entry) {
+  return entry && SOURCES.has(entry.promptSource) ? entry.promptSource : undefined;
+}
+
+/** The entry's text parts as Claude Code sends them: the string, or each text block's text. */
+export function entryTexts(entry) {
+  const c = contentOf(entry);
+  if (typeof c === "string") return c ? [c] : [];
+  if (!Array.isArray(c)) return [];
+  return c
+    .filter((b) => b && b.type === "text" && typeof b.text === "string" && b.text)
+    .map((b) => b.text);
+}
+
+/**
+ * Pastes in an entry: Claude Code's `<pasted_content id="X">…</pasted_content id="X">` wrappers
+ * whose open and close ids match, plus pasted images (`imagePasteIds`).
+ */
+export function countPastes(entry) {
+  let n = Array.isArray(entry && entry.imagePasteIds) ? entry.imagePasteIds.length : 0;
+  for (const text of entryTexts(entry)) {
+    let i = 0;
+    for (;;) {
+      const open = text.indexOf('<pasted_content id="', i);
+      if (open < 0) break;
+      const idFrom = open + '<pasted_content id="'.length;
+      const idEnd = text.indexOf('">', idFrom);
+      if (idEnd < 0) break;
+      const id = text.slice(idFrom, idEnd);
+      const close = `</pasted_content id="${id}">`;
+      const at = text.indexOf(close, idEnd + 2);
+      if (at < 0) {
+        i = idEnd + 2;
+        continue;
+      }
+      n++;
+      i = at + close.length;
+    }
+  }
+  return n;
+}
+
+export const sha256Hex = (text) => crypto.createHash("sha256").update(text, "utf8").digest("hex");
+
+/** The header value for a list of prompt entries (oldest first). "" when nothing is stated. */
+export function buildTurnHeader(entries, max = TURN_PARTS_MAX) {
+  const parts = [];
+  for (const e of entries) {
+    const origin = entryOrigin(e);
+    if (!origin) continue;
+    const source = entrySource(e);
+    const pastes = Math.min(countPastes(e), 9999);
+    for (const text of entryTexts(e)) {
+      parts.push(
+        `origin=${origin}; ${source ? `source=${source}; ` : ""}pastes=${pastes}; h=${sha256Hex(text)}`,
+      );
+    }
+  }
+  return parts.slice(-max).join(", ");
+}
+
+/** Incremental reader of one transcript file: parses only the bytes appended since last time. */
+export class TranscriptIndex {
+  constructor(file) {
+    this.file = file;
+    this.offset = 0;
+    this.partial = "";
+    this.entries = [];
+    this.promptIds = new Set();
+  }
+
+  reset() {
+    this.offset = 0;
+    this.partial = "";
+    this.entries = [];
+    this.promptIds = new Set();
+  }
+
+  /** Read whatever was appended. Returns false when the file cannot be read. */
+  refresh() {
+    let fd;
+    try {
+      fd = fs.openSync(this.file, "r");
+      const size = fs.fstatSync(fd).size;
+      if (size < this.offset) this.reset(); // rewritten / truncated: start over
+      // Read to EOF (a 0-byte read), not to the size above: Claude Code may append meanwhile.
+      const buf = Buffer.alloc(READ_CHUNK);
+      for (let n; (n = fs.readSync(fd, buf, 0, buf.length, this.offset)) > 0; ) {
+        this.offset += n;
+        this.ingest(buf.subarray(0, n).toString("utf8"));
+      }
+      return true;
+    } catch {
+      return false;
+    } finally {
+      if (fd !== undefined) fs.closeSync(fd);
+    }
+  }
+
+  ingest(chunk) {
+    const text = this.partial + chunk;
+    const lines = text.split("\n");
+    this.partial = lines.pop() ?? "";
+    for (const line of lines) this.ingestLine(line);
+  }
+
+  ingestLine(line) {
+    if (!line || line.indexOf('"promptId"') < 0) return;
+    let e;
+    try {
+      e = JSON.parse(line);
+    } catch {
+      return;
+    }
+    if (!isPromptEntry(e) || typeof e.promptId !== "string") return;
+    if (this.promptIds.size >= PROMPT_IDS_MAX) this.promptIds.clear();
+    this.promptIds.add(e.promptId);
+    this.entries.push(e);
+    if (this.entries.length > ENTRIES_KEPT)
+      this.entries.splice(0, this.entries.length - ENTRIES_KEPT);
+  }
+
+  has(promptId) {
+    return this.promptIds.has(promptId);
+  }
+
+  header() {
+    return buildTurnHeader(this.entries);
+  }
+}
+
+const one = (v) => (Array.isArray(v) ? v[0] : v);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Builds `x-mnemom-turn` values for requests. One instance per proxy process; it caches each
+ * session's transcript location and incremental index.
+ */
+export class TurnOrigins {
+  constructor(opts = {}) {
+    this.configDir = opts.configDir || claudeConfigDir();
+    this.cwd = opts.cwd || process.cwd();
+    this.waitMs = opts.waitMs ?? WAIT_MS;
+    this.indexes = new Map();
+    this.misses = new Map();
+  }
+
+  /** The transcript file for a session id: the cwd's project dir first, then every project dir. */
+  locate(sessionId) {
+    const projects = path.join(this.configDir, "projects");
+    const name = `${sessionId}.jsonl`;
+    const first = path.join(projects, cwdSlug(this.cwd), name);
+    if (fs.existsSync(first)) return first;
+    const missAt = this.misses.get(sessionId);
+    if (missAt !== undefined && Date.now() - missAt < 1000) return null;
+    try {
+      for (const d of fs.readdirSync(projects)) {
+        const cand = path.join(projects, d, name);
+        if (fs.existsSync(cand)) {
+          this.misses.delete(sessionId);
+          return cand;
+        }
+      }
+    } catch {
+      /* no projects dir */
+    }
+    if (this.misses.size > 256) this.misses.clear();
+    this.misses.set(sessionId, Date.now());
+    return null;
+  }
+
+  index(sessionId) {
+    let ix = this.indexes.get(sessionId);
+    if (ix && fs.existsSync(ix.file)) return ix;
+    const file = this.locate(sessionId);
+    if (!file) return null;
+    if (this.indexes.size > 64) this.indexes.clear();
+    ix = new TranscriptIndex(file);
+    this.indexes.set(sessionId, ix);
+    return ix;
+  }
+
+  /**
+   * The header for a request, from its (lower-cased) headers: `{ value, note }`. `value` is ""
+   * when nothing is stated; `note` is a log word (never transcript text).
+   *
+   * Main requests only. The prompt id is the SYNC point: with one, wait (up to waitMs) until the
+   * transcript holds that prompt, so the newest turn is stated too. Claude Code sends no prompt id
+   * on some main requests (a slash command / skill turn, measured on 2.1.285): those get the
+   * transcript as it stands, no wait. Either way every entry sent is a recorded fact, and an entry
+   * that is not in the transcript yet is simply not stated (the gateway reads that text as before).
+   * Notes: `skip` (not main / no session id), `n=<parts>` (synced), `nosync n=<parts>` (no prompt
+   * id), `late n=<parts>` (the prompt never appeared in time), `none` (no transcript entries).
+   */
+  async forRequest(headers) {
+    const cls = String(one(headers["x-claude-code-request-class"]) ?? "");
+    const promptId = String(one(headers["x-claude-code-prompt-id"]) ?? "").trim();
+    const sessionId = String(one(headers["x-claude-code-session-id"]) ?? "").trim();
+    if (cls !== "main" || !ID_RE.test(sessionId)) return { value: "", note: "skip" };
+    const synced = ID_RE.test(promptId);
+    const deadline = Date.now() + (synced ? this.waitMs : 0);
+    let ix;
+    let tag = synced ? "" : "nosync ";
+    for (;;) {
+      ix = this.index(sessionId);
+      const ok = ix ? ix.refresh() : false;
+      if (ok && (!synced || ix.has(promptId))) break;
+      if (Date.now() >= deadline) {
+        if (synced) tag = "late ";
+        break;
+      }
+      await sleep(POLL_MS);
+    }
+    const value = ix ? ix.header() : "";
+    return { value, note: value ? `${tag}n=${value.split(", ").length}` : "none" };
+  }
+}
+
+/**
+ * `turns.forRequest(headers)`, but never rejects: an unexpected error reads as `{ value: "",
+ * note: "error" }`, so a proxy forwards the request without the header instead of failing it.
+ */
+export async function turnHeaderFor(turns, headers) {
+  try {
+    return await turns.forRequest(headers);
+  } catch {
+    return { value: "", note: "error" };
+  }
+}
+
+/** Whether a launch asked for the header (on unless MNEMOM_AGENT_TURN_HEADER is 0/off/false/no). */
+export function turnHeaderEnabled(env = process.env) {
+  const raw = String(env.MNEMOM_AGENT_TURN_HEADER ?? "")
+    .trim()
+    .toLowerCase();
+  return !(raw === "0" || raw === "off" || raw === "false" || raw === "no");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.17.4-next.3",
+  "version": "0.17.4-next.5",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {