opencode-episodic-memory 0.1.2 → 0.2.0

package/src/embed-sidecar.mjs

@@ -0,0 +1,110 @@
+// Persistent Node-side embedding server. stdout is reserved for NDJSON protocol
+// messages; all diagnostics (including dependency chatter) go to stderr.
+const originalConsole = globalThis.console;
+globalThis.console = {
+  ...originalConsole,
+  log: (...args) => originalConsole.error(...args),
+  info: (...args) => originalConsole.error(...args),
+  debug: (...args) => originalConsole.error(...args),
+  warn: (...args) => originalConsole.error(...args),
+};
+
+// Keep this fallback synchronized with DEFAULT_MODEL in embed.ts; embed.test.ts
+// guards against accidental drift between the Bun host and Node sidecar.
+const model = process.env.EPISODIC_EMBED_MODEL ?? "Snowflake/snowflake-arctic-embed-m-v1.5";
+const MAX_REQUEST_TEXTS = 64;
+const batchSize = positiveIntegerEnv("EPISODIC_EMBED_BATCH_SIZE", 32, MAX_REQUEST_TEXTS);
+let embedder;
+let queue = Promise.resolve();
+
+function positiveIntegerEnv(name, defaultValue, maximum) {
+  const value = process.env[name];
+  if (value === undefined) return defaultValue;
+  if (!/^[1-9]\d*$/.test(value)) throw new Error(`Invalid ${name} ${JSON.stringify(value)}; expected an integer from 1 to ${maximum}.`);
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed > maximum) {
+    throw new Error(`Invalid ${name} ${JSON.stringify(value)}; expected an integer from 1 to ${maximum}.`);
+  }
+  return parsed;
+}
+
+function send(response) {
+  process.stdout.write(`${JSON.stringify(response)}\n`);
+}
+
+function requestError(id, error) {
+  send({ id, error: error instanceof Error ? error.message : String(error) });
+}
+
+function validRequest(value) {
+  return value && typeof value === "object" && Number.isSafeInteger(value.id)
+    && Array.isArray(value.texts) && value.texts.length <= MAX_REQUEST_TEXTS
+    && value.texts.every((text) => typeof text === "string");
+}
+
+async function embed(texts) {
+  const vectors = [];
+  for (let offset = 0; offset < texts.length; offset += batchSize) {
+    const batch = texts.slice(offset, offset + batchSize);
+    const output = await embedder(batch, { pooling: "cls", normalize: true });
+    const dimensions = output.dims.at(-1);
+    if (!Number.isSafeInteger(dimensions) || dimensions <= 0) throw new Error("model returned invalid embedding dimensions");
+    const data = output.data;
+    if (data.length !== batch.length * dimensions) throw new Error("model returned an invalid embedding batch");
+    for (let index = 0; index < batch.length; index++) {
+      vectors.push(Array.from(data.slice(index * dimensions, (index + 1) * dimensions)));
+    }
+  }
+  return vectors;
+}
+
+async function initialize() {
+  try {
+    const { pipeline } = await import("@huggingface/transformers");
+    embedder = await pipeline("feature-extraction", model, { dtype: "q8" });
+    send({ ready: true });
+  } catch (error) {
+    send({ ready: false, error: error instanceof Error ? error.message : String(error) });
+    process.exitCode = 1;
+    process.stdin.destroy();
+    throw error;
+  }
+}
+
+const initialization = initialize();
+let remainder = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  remainder += chunk;
+  let newline;
+  while ((newline = remainder.indexOf("\n")) >= 0) {
+    const line = remainder.slice(0, newline);
+    remainder = remainder.slice(newline + 1);
+    if (!line) continue;
+    let request;
+    try {
+      request = JSON.parse(line);
+    } catch {
+      requestError(null, "request must be valid JSON");
+      continue;
+    }
+    if (!validRequest(request)) {
+      requestError(request && typeof request === "object" && "id" in request ? request.id : null, `request must have an integer id and at most ${MAX_REQUEST_TEXTS} string texts`);
+      continue;
+    }
+    queue = queue.then(async () => {
+      try {
+        await initialization;
+        send({ id: request.id, vectors: await embed(request.texts) });
+      } catch (error) {
+        requestError(request.id, error);
+      }
+    });
+  }
+});
+process.stdin.on("error", () => process.exit());
+process.stdin.on("end", () => process.exit());
+process.on("SIGTERM", () => process.exit());
+process.on("SIGINT", () => process.exit());
+
+await initialization.catch(() => {});

package/src/embed.ts

@@ -1,14 +1,7 @@
-// Local, offline embeddings via Transformers.js. CLS-pooled + L2-normalized,
-// so cosine similarity is a plain dot product.
-//
-// Model: Snowflake/snowflake-arctic-embed-m-v1.5 (q8) — 768 dims, Apache-2.0,
-// official ONNX export in the model repo. Chosen over Xenova/bge-small-en-v1.5
-// by empirical eval on our real corpus (2026-07-22, see
-// docs/embedding-model-eval.md): equal top-1, better top-3, and far better
-// score separation (negatives max ~0.33 vs bge's ~0.66), so minScore
-// thresholding is meaningful. Asymmetric retriever: queries get a task
-// prefix, documents go through unmodified.
-import { pipeline, type FeatureExtractionPipeline } from "@huggingface/transformers";
+// Local, offline embeddings. The default backend lives in a system-Node
+// sidecar so importing the OpenCode plugin never loads ML native addons into
+// its embedded Bun process.
+import { fileURLToPath } from "node:url";
 
 export const DEFAULT_MODEL = "Snowflake/snowflake-arctic-embed-m-v1.5";
 
@@ -20,34 +13,295 @@ export const QUERY_PREFIX = "Represent this sentence for searching relevant pass
 // degrade embeddings (and this model's window is 512 tokens anyway).
 export const MAX_CHARS = 2000;
 
-let cached: Promise<FeatureExtractionPipeline> | null = null;
+const DEFAULT_BATCH_SIZE = 32;
+const MAX_BATCH_SIZE = 64;
+const DEFAULT_READY_TIMEOUT_MS = 10 * 60 * 1000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 2 * 60 * 1000;
+const MAX_TIMEOUT_MS = 2_147_483_647;
 
-export function getEmbedder(): Promise<FeatureExtractionPipeline> {
-  if (!cached) {
-    // transformers.js declares pipeline<"feature-extraction"> as its task-metadata
-    // record, not the FeatureExtractionPipeline instance it returns at runtime, so
-    // this cast restores the documented return type (matches HuggingFace's examples).
-    cached = pipeline("feature-extraction", process.env.EPISODIC_EMBED_MODEL ?? DEFAULT_MODEL, {
-      dtype: "q8",
-    }) as Promise<FeatureExtractionPipeline>;
-    // A rejected promise (e.g. failed model download) would poison the cache
-    // for the lifetime of the process; reset so the next call retries.
-    cached.catch(() => { if (cached) cached = null; });
+export type EmbedMode = "sidecar" | "inline";
+
+type PendingRequest = {
+  resolve: (vectors: Float32Array[]) => void;
+  reject: (error: Error) => void;
+  count: number;
+};
+
+type Sidecar = {
+  process: Bun.Subprocess<"pipe", "pipe", "pipe">;
+  pending: Map<number, PendingRequest>;
+  ready: Promise<void>;
+  resolveReady: () => void;
+  rejectReady: (error: Error) => void;
+  stderr: string;
+  stdout: string;
+  dimensions: number | null;
+};
+
+class SidecarUnavailableError extends Error {}
+
+let sidecar: Sidecar | null = null;
+let nextRequestId = 1;
+
+export function getEmbedMode(): EmbedMode {
+  const mode = process.env.EPISODIC_EMBED_MODE ?? "sidecar";
+  if (mode === "sidecar" || mode === "inline") return mode;
+  throw new Error(`Invalid EPISODIC_EMBED_MODE ${JSON.stringify(mode)}; expected "sidecar" or "inline".`);
+}
+
+function tail(value: string, addition: string): string {
+  return (value + addition).slice(-8_192);
+}
+
+function positiveIntegerEnv(name: string, defaultValue: number, maximum: number): number {
+  const value = process.env[name];
+  if (value === undefined) return defaultValue;
+  if (!/^[1-9]\d*$/.test(value)) throw new Error(`Invalid ${name} ${JSON.stringify(value)}; expected an integer from 1 to ${maximum}.`);
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed > maximum) {
+    throw new Error(`Invalid ${name} ${JSON.stringify(value)}; expected an integer from 1 to ${maximum}.`);
+  }
+  return parsed;
+}
+
+function sidecarError(message: string, child: Sidecar): Error {
+  const details = child.stderr.trim();
+  return new SidecarUnavailableError(details ? `${message}: ${details}` : message);
+}
+
+function rejectAll(child: Sidecar, error: Error): void {
+  for (const { reject } of child.pending.values()) reject(error);
+  child.pending.clear();
+  child.rejectReady(error);
+}
+
+function sidecarGone(child: Sidecar, error: Error): void {
+  if (sidecar === child) sidecar = null;
+  rejectAll(child, error);
+  child.process.kill();
+}
+
+function protocolFailure(child: Sidecar, message: string): void {
+  const error = new Error(`Embedding sidecar protocol error: ${message}`);
+  sidecarGone(child, error);
+}
+
+function vectorsFromResponse(value: unknown, expectedCount: number, child: Sidecar): Float32Array[] {
+  if (!Array.isArray(value) || value.length !== expectedCount) {
+    throw new Error(`expected ${expectedCount} vectors, got ${Array.isArray(value) ? value.length : "a non-array"}`);
+  }
+
+  const vectors = value.map((vector) => {
+    if (!Array.isArray(vector) || vector.length === 0 || !vector.every((n) => typeof n === "number" && Number.isFinite(n))) {
+      throw new Error("vectors must be non-empty arrays of finite numbers");
+    }
+    if (child.dimensions !== null && vector.length !== child.dimensions) {
+      throw new Error(`expected ${child.dimensions} dimensions, got ${vector.length}`);
+    }
+    return new Float32Array(vector);
+  });
+
+  const dimensions = vectors[0]?.length;
+  if (vectors.some((vector) => vector.length !== dimensions)) throw new Error("vectors have inconsistent dimensions");
+  child.dimensions ??= dimensions ?? null;
+  return vectors;
+}
+
+function handleLine(child: Sidecar, line: string): void {
+  let response: unknown;
+  try {
+    response = JSON.parse(line);
+  } catch {
+    protocolFailure(child, "stdout contained invalid JSON");
+    return;
+  }
+  if (!response || typeof response !== "object" || Array.isArray(response)) {
+    protocolFailure(child, "response must be an object");
+    return;
+  }
+
+  const record = response as Record<string, unknown>;
+  if ("ready" in record) {
+    if (record.ready === true) child.resolveReady();
+    else {
+      sidecarGone(child, new SidecarUnavailableError(`Embedding sidecar failed to start: ${typeof record.error === "string" ? record.error : "unknown error"}`));
+    }
+    return;
+  }
+  if (typeof record.id !== "number" || !Number.isSafeInteger(record.id)) {
+    protocolFailure(child, "response has no valid request id");
+    return;
+  }
+  const pending = child.pending.get(record.id);
+  if (!pending) {
+    protocolFailure(child, `response has unknown request id ${record.id}`);
+    return;
+  }
+  child.pending.delete(record.id);
+  if (typeof record.error === "string") {
+    pending.reject(new Error(`Embedding sidecar request failed: ${record.error}`));
+    return;
+  }
+  try {
+    pending.resolve(vectorsFromResponse(record.vectors, pending.count, child));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    pending.reject(new Error(`Embedding sidecar protocol error: ${message}`));
+    protocolFailure(child, message);
+  }
+}
+
+async function drainStdout(child: Sidecar): Promise<void> {
+  const reader = child.process.stdout.getReader();
+  const decoder = new TextDecoder();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      child.stdout += decoder.decode(value, { stream: true });
+      let newline: number;
+      while ((newline = child.stdout.indexOf("\n")) >= 0) {
+        const line = child.stdout.slice(0, newline);
+        child.stdout = child.stdout.slice(newline + 1);
+        if (line) handleLine(child, line);
+      }
+    }
+    if (child.stdout.trim()) protocolFailure(child, "stdout ended with an incomplete response");
+  } catch (error) {
+    if (sidecar === child) sidecarGone(child, sidecarError(`Could not read embedding sidecar output (${String(error)})`, child));
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+async function drainStderr(child: Sidecar): Promise<void> {
+  const reader = child.process.stderr.getReader();
+  const decoder = new TextDecoder();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      child.stderr = tail(child.stderr, decoder.decode(value, { stream: true }));
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function startSidecar(): Sidecar {
+  if (sidecar) return sidecar;
+  const nodeBinary = process.env.EPISODIC_NODE_BINARY ?? "node";
+  const sidecarPath = fileURLToPath(new URL("./embed-sidecar.mjs", import.meta.url));
+  let resolveReady!: () => void;
+  let rejectReady!: (error: Error) => void;
+  const ready = new Promise<void>((resolve, reject) => {
+    resolveReady = resolve;
+    rejectReady = reject;
+  });
+  // The rejected ready promise is also observed by each request; suppress a
+  // transient unhandled-rejection warning while the first request is starting.
+  ready.catch(() => {});
+
+  let childProcess: Bun.Subprocess<"pipe", "pipe", "pipe">;
+  try {
+    childProcess = Bun.spawn([nodeBinary, sidecarPath], {
+      env: process.env,
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+      detached: true,
+    });
+  } catch (error) {
+    throw new Error(`Could not start embedding sidecar using ${JSON.stringify(nodeBinary)}. Install Node 20+ or set EPISODIC_NODE_BINARY: ${String(error)}`);
+  }
+  childProcess.unref();
+  const child: Sidecar = { process: childProcess, pending: new Map(), ready, resolveReady, rejectReady, stderr: "", stdout: "", dimensions: null };
+  sidecar = child;
+  void drainStdout(child);
+  void drainStderr(child);
+  void childProcess.exited.then(() => {
+    if (sidecar === child) {
+      sidecar = null;
+      rejectAll(child, sidecarError("Embedding sidecar exited unexpectedly", child));
+    }
+  });
+  return child;
+}
+
+function awaitReady(child: Sidecar, timeoutMs: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      const error = new SidecarUnavailableError(`Embedding sidecar did not become ready within ${timeoutMs}ms`);
+      sidecarGone(child, error);
+      reject(error);
+    }, timeoutMs);
+    child.ready.then(
+      () => {
+        clearTimeout(timeout);
+        resolve();
+      },
+      (error) => {
+        clearTimeout(timeout);
+        reject(error);
+      },
+    );
+  });
+}
+
+async function requestSidecar(texts: string[], readyTimeoutMs: number, requestTimeoutMs: number, retried = false): Promise<Float32Array[]> {
+  let child: Sidecar;
+  try {
+    child = startSidecar();
+    await awaitReady(child, readyTimeoutMs);
+    const id = nextRequestId++;
+    return await new Promise<Float32Array[]>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        sidecarGone(child, new SidecarUnavailableError(`Embedding sidecar request timed out after ${requestTimeoutMs}ms`));
+      }, requestTimeoutMs);
+      const resolveRequest = (vectors: Float32Array[]) => {
+        clearTimeout(timeout);
+        resolve(vectors);
+      };
+      const rejectRequest = (error: Error) => {
+        clearTimeout(timeout);
+        reject(error);
+      };
+      child.pending.set(id, { resolve: resolveRequest, reject: rejectRequest, count: texts.length });
+      if (sidecar !== child) {
+        child.pending.delete(id);
+        rejectRequest(new SidecarUnavailableError("Embedding sidecar became unavailable before the request was sent"));
+        return;
+      }
+      try {
+        child.process.stdin.write(`${JSON.stringify({ id, texts })}\n`);
+      } catch (error) {
+        child.pending.delete(id);
+        const unavailable = new SidecarUnavailableError(`Could not write to embedding sidecar: ${String(error)}`);
+        sidecarGone(child, unavailable);
+        rejectRequest(unavailable);
+      }
+    });
+  } catch (error) {
+    if (!retried && error instanceof SidecarUnavailableError) return requestSidecar(texts, readyTimeoutMs, requestTimeoutMs, true);
+    throw error;
   }
-  return cached;
 }
 
 async function embedRaw(texts: string[]): Promise<Float32Array[]> {
   if (texts.length === 0) return [];
-  const e = await getEmbedder();
-  const out = await e(texts.map((t) => t.slice(0, MAX_CHARS)), { pooling: "cls", normalize: true });
-  const dims: number = out.dims[out.dims.length - 1];
-  // out.data is DataArray (a union incl. bigint typed arrays); a feature-extraction
-  // tensor with normalize:true is a Float32Array at runtime, so this cast is safe.
-  const flat = new Float32Array(out.data as Float32Array);
+  const prepared = texts.map((text) => text.slice(0, MAX_CHARS));
+  if (getEmbedMode() === "inline") {
+    // Unsafe under affected OpenCode/Bun versions: this intentionally loads
+    // Transformers.js only when the caller explicitly opts in.
+    const { embedInline } = await import("./embed-inline.ts");
+    return embedInline(prepared);
+  }
+  const batchSize = positiveIntegerEnv("EPISODIC_EMBED_BATCH_SIZE", DEFAULT_BATCH_SIZE, MAX_BATCH_SIZE);
+  const readyTimeoutMs = positiveIntegerEnv("EPISODIC_EMBED_READY_TIMEOUT_MS", DEFAULT_READY_TIMEOUT_MS, MAX_TIMEOUT_MS);
+  const requestTimeoutMs = positiveIntegerEnv("EPISODIC_EMBED_REQUEST_TIMEOUT_MS", DEFAULT_REQUEST_TIMEOUT_MS, MAX_TIMEOUT_MS);
   const vectors: Float32Array[] = [];
-  for (let i = 0; i < texts.length; i++) {
-    vectors.push(flat.subarray(i * dims, (i + 1) * dims));
+  for (let index = 0; index < prepared.length; index += batchSize) {
+    vectors.push(...await requestSidecar(prepared.slice(index, index + batchSize), readyTimeoutMs, requestTimeoutMs));
   }
   return vectors;
 }
@@ -57,6 +311,5 @@ export const embed = embedRaw;
 
 /** Embed a search query. Prepends the retrieval prefix. */
 export function embedQuery(query: string): Promise<Float32Array[]> {
-  const q = query.startsWith(QUERY_PREFIX) ? query : QUERY_PREFIX + query;
-  return embedRaw([q]);
+  return embedRaw([query.startsWith(QUERY_PREFIX) ? query : QUERY_PREFIX + query]);
 }

package/src/format.ts

@@ -0,0 +1,70 @@
+// Shared presentation layer for the CLI and the plugin. Both stay thin: date
+// parsing, date formatting, transcript→markdown, and search-hit formatting live
+// here so the two front-ends can't drift apart.
+import type { SourceMessage } from "./reader";
+import type { SearchHit } from "./store";
+
+// Discriminated result so callers handle the parse error explicitly (no cast to
+// strip the error arm off a union). `ms` is undefined when no date was given.
+export type ParsedDate = { ok: true; ms?: number } | { ok: false; error: string };
+
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+// Require strict YYYY-MM-DD, then round-trip to reject impossible calendar dates
+// (`new Date("2024-02-31")` silently normalizes to March 2 rather than failing).
+export function parseDateArg(s?: string): ParsedDate {
+  if (!s) return { ok: true };
+  const ms = new Date(s).getTime();
+  if (!DATE_RE.test(s) || Number.isNaN(ms) || new Date(ms).toISOString().slice(0, 10) !== s) {
+    return { ok: false, error: `Invalid date "${s}" (expected YYYY-MM-DD).` };
+  }
+  return { ok: true, ms };
+}
+
+export function fmtDate(ms: number): string {
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+// Render a full transcript as markdown:
+//   # title
+//   date — directory — id
+//
+//   ## role
+//   text
+//   *(tools: …)*
+//
+// A blank line follows every rendered message. Callers decide truncation (the
+// plugin caps at 50k chars; the CLI prints in full).
+export function renderTranscript(
+  meta: { title: string; time_created: number; directory: string; id: string },
+  messages: SourceMessage[]
+): string {
+  const lines: string[] = [
+    `# ${meta.title}`,
+    `${fmtDate(meta.time_created)} — ${meta.directory} — ${meta.id}`,
+    "",
+  ];
+  for (const m of messages) {
+    const text = m.parts.filter((p) => p.type === "text" && p.text).map((p) => p.text).join("\n");
+    const tools = m.parts.filter((p) => p.type === "tool" && p.tool).map((p) => p.tool);
+    if (!text && tools.length === 0) continue;
+    lines.push(`## ${m.role}`);
+    if (text) lines.push(text);
+    if (tools.length) lines.push(`*(tools: ${tools.join(", ")})*`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+// One search hit as a markdown block. snippetLength defaults to 400 (plugin
+// tool output); the CLI passes 220 to keep terminal output brief. scoreLabel
+// names the score field: "score" for vector (cosine ~0.4–0.7) and BM25, "rrf"
+// for hybrid (fused reciprocal-rank scores ~0.03, a different scale — see
+// AGENTS.md) so the number isn't misread against the cosine thresholds.
+export function formatHit(h: SearchHit, snippetLength = 400, scoreLabel = "score"): string {
+  const snippet = h.text.replace(/\s+/g, " ").slice(0, snippetLength);
+  return `## ${fmtDate(h.time_created)} — ${h.title}\nsession: ${h.session_id}  ${scoreLabel}: ${h.score.toFixed(3)}\n${h.directory}\n> ${snippet}`;
+}
+
+export function formatHits(hits: SearchHit[], snippetLength = 400, scoreLabel = "score"): string {
+  return hits.map((h) => formatHit(h, snippetLength, scoreLabel)).join("\n\n");
+}

package/src/indexer.ts

@@ -1,7 +1,7 @@
 // Incremental, idempotent indexer. Watermark = session.time_updated; a session
 // is re-embedded only when the source changed since we last indexed it.
 import type { Database } from "bun:sqlite";
-import { getTranscript, listSessions, transcriptHasMarker, type SourceSession } from "./reader";
+import { getTranscriptChecked, listSessions, type SourceSession } from "./reader";
 import { parseTranscript, exchangeText } from "./parser";
 import { embed } from "./embed";
 import { getIndexedSession, replaceSessionChunks } from "./store";
@@ -24,12 +24,13 @@ export async function syncSession(
   const prior = getIndexedSession(index, s.id);
   if (!force && prior && prior.source_time_updated >= s.time_updated) return "fresh";
 
-  // Authoritative opt-out gate: raw part blobs. The parsed-text scan inside
-  // parseTranscript would miss a marker in an unparseable blob.
-  const excludedRaw = transcriptHasMarker(source, s.id);
-  const { exchanges, excluded } = excludedRaw
+  // Authoritative opt-out gate lives inside getTranscriptChecked (raw-blob
+  // scan before any read); parseTranscript's own parsed-text check is a
+  // harmless redundant fast path for the non-excluded branch.
+  const checked = getTranscriptChecked(source, s.id);
+  const { exchanges, excluded } = checked.excluded
     ? { exchanges: [], excluded: true }
-    : parseTranscript(getTranscript(source, s.id));
+    : parseTranscript(checked.messages);
   const meta = {
     id: s.id, project_id: s.project_id, parent_id: s.parent_id,
     title: s.title, directory: s.directory,

package/src/parser.ts

@@ -29,8 +29,9 @@ export interface Exchange {
   time: number;
 }
 
-const SKIP_PART_TYPES = new Set(["reasoning", "step-start", "step-finish", "file", "patch", "snapshot"]);
-
+// reasoning blobs, step markers, and every other non-text/-tool part type are
+// excluded implicitly: textOf keeps only type === "text" and toolNames only
+// type === "tool", so nothing else can slip through.
 function textOf(parts: SourcePart[]): string {
   return parts
     .filter((p) => p.type === "text" && p.text)
@@ -41,7 +42,7 @@ function textOf(parts: SourcePart[]): string {
 
 function toolNames(parts: SourcePart[]): string[] {
   return parts
-    .filter((p) => p.type === "tool" && p.tool && !SKIP_PART_TYPES.has(p.type))
+    .filter((p) => p.type === "tool" && p.tool)
     .map((p) => p.tool!);
 }
 

package/src/reader.ts

@@ -128,7 +128,10 @@ export function transcriptHasMarker(db: Database, sessionId: string): boolean {
   return row.n > 0;
 }
 
-export function getTranscript(db: Database, sessionId: string): SourceMessage[] {
+// Module-internal: the raw read with no privacy gate. Production code must go
+// through getTranscriptChecked so the exclusion marker can never be bypassed by
+// forgetting a manual transcriptHasMarker() call. Not exported.
+function getTranscript(db: Database, sessionId: string): SourceMessage[] {
   const messages = MessageRowSchema.array().parse(
     db
       .prepare(
@@ -162,3 +165,18 @@ export function getTranscript(db: Database, sessionId: string): SourceMessage[]
     parts: partsByMsg.get(m.id) ?? [],
   }));
 }
+
+// Discriminated result: excluded conversations never yield a transcript.
+export type CheckedTranscript =
+  | { excluded: true }
+  | { excluded: false; messages: SourceMessage[] };
+
+// The single privacy-gated entry point for reading a transcript. Runs the
+// AUTHORITATIVE raw-blob exclusion check (transcriptHasMarker) BEFORE reading,
+// so the opt-out marker cannot be bypassed by a caller forgetting to check.
+// All production call sites (CLI read, plugin episodic_read, indexer) use this;
+// the raw getTranscript is module-internal.
+export function getTranscriptChecked(db: Database, sessionId: string): CheckedTranscript {
+  if (transcriptHasMarker(db, sessionId)) return { excluded: true };
+  return { excluded: false, messages: getTranscript(db, sessionId) };
+}