opencode-episodic-memory 0.1.0 → 0.1.1

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "opencode-episodic-memory",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Semantic search over past OpenCode conversations. Port of obra/episodic-memory to OpenCode primitives.",
   "type": "module",
   "license": "MIT",
   "author": "robertn702",
   "repository": {
     "type": "git",
-    "url": "https://github.com/robertn702/opencode-episodic-memory"
+    "url": "git+https://github.com/robertn702/opencode-episodic-memory.git"
   },
   "keywords": [
     "opencode",
@@ -27,7 +27,7 @@
     "skills"
   ],
   "bin": {
-    "opencode-episodic": "./src/cli.ts"
+    "opencode-episodic": "src/cli.ts"
   },
   "scripts": {
     "spike": "bun run spikes/spike.ts",
@@ -37,7 +37,8 @@
   },
   "dependencies": {
     "@huggingface/transformers": "^4.2.0",
-    "@opencode-ai/plugin": "^1.18.4"
+    "@opencode-ai/plugin": "^1.18.4",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/reader.test.ts

@@ -0,0 +1,139 @@
+import { describe, test, expect } from "bun:test";
+import { Database } from "bun:sqlite";
+import { listSessions, getSession, getTranscript } from "./reader";
+
+// A minimal opencode.db mirroring only the columns reader.ts SELECTs. Writable
+// here so we can seed rows; the reader functions take a Database and never write.
+function makeSource(): Database {
+  const db = new Database(":memory:");
+  db.run(`CREATE TABLE session (
+    id TEXT, project_id TEXT, parent_id TEXT, title TEXT, directory TEXT,
+    time_created INTEGER, time_updated INTEGER, time_archived INTEGER
+  )`);
+  db.run(`CREATE TABLE message (
+    id TEXT, session_id TEXT, time_created INTEGER, data TEXT
+  )`);
+  db.run(`CREATE TABLE part (
+    id TEXT, message_id TEXT, session_id TEXT, time_created INTEGER, data TEXT
+  )`);
+  return db;
+}
+
+function addSession(db: Database, s: {
+  id: string; parent_id?: string | null; title?: string;
+  time_created?: number; time_updated?: number; time_archived?: number | null;
+}): void {
+  db.run(
+    `INSERT INTO session (id, project_id, parent_id, title, directory, time_created, time_updated, time_archived)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    [s.id, "proj", s.parent_id ?? null, s.title ?? "Title", "/dir",
+     s.time_created ?? 1000, s.time_updated ?? 1000, s.time_archived ?? null]
+  );
+}
+function addMessage(db: Database, id: string, sessionId: string, time: number, data: string): void {
+  db.run("INSERT INTO message (id, session_id, time_created, data) VALUES (?, ?, ?, ?)",
+    [id, sessionId, time, data]);
+}
+function addPart(db: Database, id: string, messageId: string, sessionId: string, time: number, data: string): void {
+  db.run("INSERT INTO part (id, message_id, session_id, time_created, data) VALUES (?, ?, ?, ?, ?)",
+    [id, messageId, sessionId, time, data]);
+}
+
+describe("listSessions / getSession (structural rows)", () => {
+  test("lists active sessions ordered by time_created, excludes archived", () => {
+    const db = makeSource();
+    addSession(db, { id: "ses_b", time_created: 2000 });
+    addSession(db, { id: "ses_a", time_created: 1000, parent_id: "ses_b" });
+    addSession(db, { id: "ses_arch", time_created: 1500, time_archived: 9999 });
+    const sessions = listSessions(db);
+    expect(sessions.map((s) => s.id)).toEqual(["ses_a", "ses_b"]);
+    expect(sessions[0].parent_id).toBe("ses_b");
+    expect(sessions[1].parent_id).toBeNull();
+  });
+
+  test("getSession returns a row, or null for an unknown id", () => {
+    const db = makeSource();
+    addSession(db, { id: "ses_a", title: "Hello" });
+    expect(getSession(db, "ses_a")?.title).toBe("Hello");
+    expect(getSession(db, "nope")).toBeNull();
+  });
+
+  test("throws (does not silently mis-read) when a structural column drifts", () => {
+    const db = makeSource();
+    // time_created NULL violates z.number() — simulates OpenCode schema drift.
+    db.run(
+      `INSERT INTO session (id, project_id, parent_id, title, directory, time_created, time_updated, time_archived)
+       VALUES ('ses_x', 'p', NULL, 't', '/d', NULL, 1000, NULL)`
+    );
+    expect(() => listSessions(db)).toThrow();
+  });
+
+  test("getSession throws on a drifted session row for an existing id", () => {
+    const db = makeSource();
+    // title NULL violates z.string() — simulates OpenCode schema drift.
+    db.run(
+      `INSERT INTO session (id, project_id, parent_id, title, directory, time_created, time_updated, time_archived)
+       VALUES ('ses_y', 'p', NULL, NULL, '/d', 1000, 1000, NULL)`
+    );
+    expect(() => getSession(db, "ses_y")).toThrow();
+  });
+});
+
+describe("getTranscript (JSON blob degradation)", () => {
+  test("parses roles and part fields; degrades malformed blobs per-row", () => {
+    const db = makeSource();
+    addSession(db, { id: "ses_a" });
+    addMessage(db, "m1", "ses_a", 1, `{"role":"user"}`);
+    addMessage(db, "m2", "ses_a", 2, `{"role":"assistant"}`);
+    addMessage(db, "m3", "ses_a", 3, `{not valid json`);   // role -> "unknown"
+    addMessage(db, "m4", "ses_a", 4, `{"noRole":true}`);    // role -> "unknown"
+
+    addPart(db, "p1", "m1", "ses_a", 1, `{"type":"text","text":"hello"}`);
+    addPart(db, "p2", "m1", "ses_a", 2, `{"type":"tool","tool":"edit"}`);
+    addPart(db, "p3", "m2", "ses_a", 3, `{oops not json`);          // -> {type:"unknown"}
+    addPart(db, "p4", "m2", "ses_a", 4, `{"type":123,"text":"keep"}`); // type->unknown, text kept
+    addPart(db, "p5", "m4", "ses_a", 5, `42`);                       // non-object -> {type:"unknown"}
+
+    const t = getTranscript(db, "ses_a");
+    expect(t.map((m) => m.role)).toEqual(["user", "assistant", "unknown", "unknown"]);
+
+    expect(t[0].parts).toEqual([
+      { type: "text", text: "hello" },
+      { type: "tool", tool: "edit" },
+    ]);
+    expect(t[1].parts).toEqual([
+      { type: "unknown" },
+      { type: "unknown", text: "keep" },
+    ]);
+    expect(t[3].parts).toEqual([{ type: "unknown" }]);
+  });
+
+  test("per-field catch: bad text/tool fields are dropped, type is preserved", () => {
+    const db = makeSource();
+    addSession(db, { id: "ses_a" });
+    addMessage(db, "m1", "ses_a", 1, `{"role":"user"}`);
+    addPart(db, "p1", "m1", "ses_a", 1, `{"type":"text","text":123}`); // bad text dropped
+    addPart(db, "p2", "m1", "ses_a", 2, `{"type":"tool","tool":123}`); // bad tool dropped
+
+    const t = getTranscript(db, "ses_a");
+    expect(t[0].parts).toEqual([{ type: "text" }, { type: "tool" }]);
+  });
+
+  test("throws when a part row's data column is non-string (structural drift)", () => {
+    const db = makeSource();
+    addSession(db, { id: "ses_a" });
+    // Valid message first so the message-row parse passes and the throw comes
+    // from the part row below.
+    addMessage(db, "m1", "ses_a", 1, `{"role":"user"}`);
+    db.run("INSERT INTO part (id, message_id, session_id, time_created, data) VALUES ('p1', 'm1', 'ses_a', 1, NULL)");
+    expect(() => getTranscript(db, "ses_a")).toThrow();
+  });
+
+  test("throws when a message row's data column is non-string (structural drift)", () => {
+    const db = makeSource();
+    addSession(db, { id: "ses_a" });
+    // data NULL violates the row schema's z.string(); structural, so it throws.
+    db.run("INSERT INTO message (id, session_id, time_created, data) VALUES ('m1', 'ses_a', 1, NULL)");
+    expect(() => getTranscript(db, "ses_a")).toThrow();
+  });
+});

package/src/reader.ts

@@ -3,24 +3,59 @@
 import { Database } from "bun:sqlite";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { z } from "zod";
 
 export const DEFAULT_SOURCE_DB = join(homedir(), ".local/share/opencode/opencode.db");
 
-export interface SourceSession {
-  id: string;
-  project_id: string;
-  parent_id: string | null;
-  title: string;
-  directory: string;
-  time_created: number;
-  time_updated: number;
-}
-
-export interface SourcePart {
-  type: string;
-  text?: string;
-  tool?: string;
-}
+// --- Validation strategy ----------------------------------------------------
+// Two surfaces, two failure modes (see AGENTS.md):
+//   1. Structural rows we SELECT from opencode.db (columns: id, time_created,
+//      data, ...). These are a uniform contract; if a column's type/nullability
+//      drifts it drifts for every row, so we THROW (`.parse`) to surface
+//      OpenCode schema changes loudly instead of silently mis-reading them.
+//   2. The JSON blob inside each `data` column (message role, part contents).
+//      This format evolves and carries many part shapes we don't model, so we
+//      DEGRADE per-row to "unknown"/undefined (`.catch`): one corrupt or
+//      unfamiliar blob can never abort a whole transcript read, and the parser
+//      already filters unknown types/roles downstream.
+// No `as` assertions: schemas narrow via `.parse()`.
+
+// --- Structural row schemas (throw on drift) --------------------------------
+const SessionRowSchema = z.object({
+  id: z.string(),
+  project_id: z.string(),
+  parent_id: z.string().nullable(),
+  title: z.string(),
+  directory: z.string(),
+  time_created: z.number(),
+  time_updated: z.number(),
+});
+export type SourceSession = z.infer<typeof SessionRowSchema>;
+
+const MessageRowSchema = z.object({
+  id: z.string(),
+  time_created: z.number(),
+  data: z.string(),
+});
+
+const PartRowSchema = z.object({
+  message_id: z.string(),
+  data: z.string(),
+});
+
+// --- JSON blob schemas (degrade to "unknown" on mismatch) -------------------
+const PartDataSchema = z
+  .object({
+    type: z.string().catch("unknown"),
+    text: z.string().optional().catch(undefined),
+    tool: z.string().optional().catch(undefined),
+  })
+  .catch({ type: "unknown" });
+export type SourcePart = z.infer<typeof PartDataSchema>;
+
+const MessageDataSchema = z
+  .object({ role: z.string().catch("unknown") })
+  .catch({ role: "unknown" });
 
 export interface SourceMessage {
   id: string;
@@ -37,35 +72,9 @@ export function sourceDbPath(): string {
   return process.env.EPISODIC_SOURCE_DB ?? DEFAULT_SOURCE_DB;
 }
 
-export function listSessions(db: Database): SourceSession[] {
-  return db
-    .prepare<SourceSession, []>(
-      `SELECT id, project_id, parent_id, title, directory, time_created, time_updated
-       FROM session WHERE time_archived IS NULL ORDER BY time_created`
-    )
-    .all();
-}
-
-export function getSession(db: Database, sessionId: string): SourceSession | null {
-  return (
-    db
-      .prepare<SourceSession, [string]>(
-        `SELECT id, project_id, parent_id, title, directory, time_created, time_updated
-         FROM session WHERE id = ?`
-      )
-      .get(sessionId) ?? null
-  );
-}
-
-// JSON.parse returns `any`; these guards validate shape at runtime so no type
-// assertion is needed. Malformed rows degrade gracefully (unknown type/role) —
-// including a corrupt `data` blob whose JSON.parse throws, so one bad row can't
-// abort the whole transcript read.
-function isRecord(v: unknown): v is Record<string, unknown> {
-  return typeof v === "object" && v !== null;
-}
-
-function safeParse(data: string): unknown {
+// JSON.parse throws on malformed input; return undefined so the blob schema's
+// `.catch` fallback applies (one bad blob can't abort a transcript read).
+function safeJsonParse(data: string): unknown {
   try {
     return JSON.parse(data);
   } catch {
@@ -73,39 +82,48 @@ function safeParse(data: string): unknown {
   }
 }
 
-function parsePart(data: string): SourcePart {
-  const raw = safeParse(data);
-  if (!isRecord(raw)) return { type: "unknown" };
-  return {
-    type: typeof raw.type === "string" ? raw.type : "unknown",
-    text: typeof raw.text === "string" ? raw.text : undefined,
-    tool: typeof raw.tool === "string" ? raw.tool : undefined,
-  };
+export function listSessions(db: Database): SourceSession[] {
+  const rows = db
+    .prepare(
+      `SELECT id, project_id, parent_id, title, directory, time_created, time_updated
+       FROM session WHERE time_archived IS NULL ORDER BY time_created`
+    )
+    .all();
+  return SessionRowSchema.array().parse(rows);
 }
 
-function parseRole(data: string): string {
-  const raw = safeParse(data);
-  return isRecord(raw) && typeof raw.role === "string" ? raw.role : "unknown";
+export function getSession(db: Database, sessionId: string): SourceSession | null {
+  const row = db
+    .prepare(
+      `SELECT id, project_id, parent_id, title, directory, time_created, time_updated
+       FROM session WHERE id = ?`
+    )
+    .get(sessionId);
+  return row === null || row === undefined ? null : SessionRowSchema.parse(row);
 }
 
 export function getTranscript(db: Database, sessionId: string): SourceMessage[] {
-  const messages = db
-    .prepare<{ id: string; time_created: number; data: string }, [string]>(
-      `SELECT id, time_created, data FROM message
-       WHERE session_id = ? ORDER BY time_created, id`
-    )
-    .all(sessionId);
+  const messages = MessageRowSchema.array().parse(
+    db
+      .prepare(
+        `SELECT id, time_created, data FROM message
+         WHERE session_id = ? ORDER BY time_created, id`
+      )
+      .all(sessionId)
+  );
 
-  const parts = db
-    .prepare<{ message_id: string; data: string }, [string]>(
-      `SELECT message_id, data FROM part
-       WHERE session_id = ? ORDER BY time_created, id`
-    )
-    .all(sessionId);
+  const parts = PartRowSchema.array().parse(
+    db
+      .prepare(
+        `SELECT message_id, data FROM part
+         WHERE session_id = ? ORDER BY time_created, id`
+      )
+      .all(sessionId)
+  );
 
   const partsByMsg = new Map<string, SourcePart[]>();
   for (const p of parts) {
-    const d = parsePart(p.data);
+    const d = PartDataSchema.parse(safeJsonParse(p.data));
     let list = partsByMsg.get(p.message_id);
     if (!list) partsByMsg.set(p.message_id, (list = []));
     list.push(d);
@@ -113,7 +131,7 @@ export function getTranscript(db: Database, sessionId: string): SourceMessage[]
 
   return messages.map((m) => ({
     id: m.id,
-    role: parseRole(m.data),
+    role: MessageDataSchema.parse(safeJsonParse(m.data)).role,
     timeCreated: m.time_created,
     parts: partsByMsg.get(m.id) ?? [],
   }));