@poncho-ai/harness 0.55.0 → 0.58.0

package/src/orchestrator/run-conversation-turn.ts

@@ -36,6 +36,15 @@ import {
   executeConversationTurn,
   flushTurnDraft,
 } from "./turn.js";
+import {
+  appendEntriesSafe,
+  assistantMessageEntry,
+  compactionEntry,
+  harnessMessageEntries,
+  newHarnessMessagesThisTurn,
+  userMessageEntry,
+  verifyEntriesParity,
+} from "./entries-dual-write.js";
 
 const log = createLogger("orchestrator");
 
@@ -185,6 +194,14 @@ export const runConversationTurn = async (
     await opts.conversationStore.update(conversation);
   };
 
+  // Snapshot the harness-message array as it stood BEFORE this turn so the
+  // finalize path can diff out the messages this turn appended (dual-write).
+  const preTurnHarnessMessages = conversation._harnessMessages
+    ? [...conversation._harnessMessages]
+    : undefined;
+  // The stable per-turn id used to group dual-write entries.
+  const turnId = assistantId;
+
   // Persist the user turn immediately so a crash mid-run still records what
   // the user said. Fire-and-forget — don't block the run.
   conversation.messages = [...historyMessages, userMessage];
@@ -197,6 +214,15 @@ export const runConversationTurn = async (
     );
   });
 
+  // DUAL-WRITE (additive, mirrors the user-turn blob write above): append a
+  // user_message entry. Fire-and-forget — never blocks or breaks the turn.
+  void appendEntriesSafe(
+    opts.conversationStore,
+    conversation,
+    [userMessageEntry(userMessage, turnId)],
+    log,
+  );
+
   try {
     const execution = await executeConversationTurn({
       harness: opts.harness,
@@ -247,6 +273,48 @@ export const runConversationTurn = async (
               ...existingHistory,
               ...preRunMessages.slice(0, removedCount),
             ];
+
+            // DUAL-WRITE (mirrors the compactedHistory blob write above): the
+            // compacted array is [summaryMessage, ...keptMessages]. BEST-EFFORT
+            // firstKeptSeq: the entry-log seqs of the kept harness messages
+            // aren't known here, so we derive a sentinel from the kept-count by
+            // reading the current max harness_message seq and pointing at the
+            // tail. We read the existing entries to compute it.
+            const summaryMessage = event.compactedMessages[0];
+            const keptCount = Math.max(0, event.compactedMessages.length - 1);
+            if (summaryMessage) {
+              void (async () => {
+                try {
+                  const existing = await opts.conversationStore.readEntries(
+                    opts.conversationId,
+                    { types: ["harness_message"] },
+                  );
+                  // firstKeptSeq = seq of the (keptCount)-th-from-last existing
+                  // harness message, so rebuild keeps exactly that many.
+                  const harnessSeqs = existing.map((e) => e.seq);
+                  const firstKeptSeq =
+                    harnessSeqs.length >= keptCount && keptCount > 0
+                      ? harnessSeqs[harnessSeqs.length - keptCount]!
+                      : (harnessSeqs[harnessSeqs.length - 1] ?? 0) + 1;
+                  await appendEntriesSafe(
+                    opts.conversationStore,
+                    conversation,
+                    [
+                      compactionEntry(summaryMessage, firstKeptSeq, {
+                        tokensBefore: conversation.contextTokens,
+                      }),
+                    ],
+                    log,
+                  );
+                } catch (err) {
+                  log.error(
+                    `[entries-dual-write] compaction append failed: ${
+                      err instanceof Error ? err.message : String(err)
+                    }`,
+                  );
+                }
+              })();
+            }
           }
         }
         if (event.type === "step:completed") {
@@ -387,6 +455,46 @@ export const runConversationTurn = async (
         { shouldRebuildCanonical },
       );
       await opts.conversationStore.update(conversation);
+
+      // DUAL-WRITE at finalize (mirrors applyTurnMetadata's _harnessMessages
+      // write + the final assistant bubble in conversation.messages):
+      //   1. harness_message entries for the messages this turn appended,
+      //   2. the final assistant_message entry.
+      // Best-effort + fire-and-forget; never blocks the return.
+      const finalAssistant =
+        conversation.messages[conversation.messages.length - 1];
+      const { messages: newHarness, approximate } = newHarnessMessagesThisTurn(
+        preTurnHarnessMessages,
+        conversation._harnessMessages,
+      );
+      if (approximate) {
+        log.warn(
+          `[entries-dual-write] ${opts.conversationId} harness-message diff approximate ` +
+            `(blob array shrank this turn — likely compaction); appended full context`,
+        );
+      }
+      const finalizeEntries = [
+        ...harnessMessageEntries(newHarness, turnId),
+        ...(finalAssistant && finalAssistant.role === "assistant"
+          ? [assistantMessageEntry(finalAssistant, turnId, latestRunId)]
+          : []),
+      ];
+      void appendEntriesSafe(
+        opts.conversationStore,
+        conversation,
+        finalizeEntries,
+        log,
+      ).then(() =>
+        verifyEntriesParity(
+          opts.conversationStore,
+          opts.conversationId,
+          {
+            harnessMessages: conversation._harnessMessages,
+            displayMessages: conversation.messages,
+          },
+          log,
+        ),
+      );
     }
 
     return {

package/src/state.ts

@@ -1,4 +1,9 @@
 import type { Message } from "@poncho-ai/sdk";
+import {
+  type ConversationEntry,
+  type NewConversationEntry,
+  rebuildConversationFromEntries,
+} from "./storage/entries.js";
 
 export interface ConversationState {
   runId: string;
@@ -142,6 +147,23 @@ export interface ConversationStore {
   clearCallbackLock(conversationId: string): Promise<Conversation | undefined>;
   /** List thread conversations anchored under `parentConversationId`. */
   listThreads(parentConversationId: string): Promise<ConversationSummary[]>;
+  /**
+   * Append entries to a conversation's append-only log (Phase 3 substrate).
+   * Assigns a per-conversation monotonic `seq` and a `createdAt` to each
+   * entry, persists them in order, and returns the stored entries with those
+   * fields filled in. Additive — no existing read path consumes these yet.
+   */
+  appendEntries(
+    conversationId: string,
+    agentId: string,
+    tenantId: string | null,
+    entries: NewConversationEntry[],
+  ): Promise<ConversationEntry[]>;
+  /** Read a conversation's entries ordered by `seq` ascending. */
+  readEntries(
+    conversationId: string,
+    opts?: { types?: string[]; afterSeq?: number; limit?: number },
+  ): Promise<ConversationEntry[]>;
 }
 
 export type StateProviderName =
@@ -201,6 +223,7 @@ export class InMemoryStateStore implements StateStore {
 
 export class InMemoryConversationStore implements ConversationStore {
   private readonly conversations = new Map<string, Conversation>();
+  private readonly entries = new Map<string, ConversationEntry[]>();
   private readonly ttlMs?: number;
 
   constructor(ttlSeconds?: number) {
@@ -250,7 +273,12 @@ export class InMemoryConversationStore implements ConversationStore {
 
   async get(conversationId: string): Promise<Conversation | undefined> {
     this.purgeExpired();
-    return this.conversations.get(conversationId);
+    const c = this.conversations.get(conversationId);
+    if (!c) return undefined;
+    // Phase 3c read cutover: rebuild reader-facing fields from the entry log
+    // (blob fallback for un-migrated conversations). Clone first — the map
+    // holds a live mutable reference and the rebuild overrides fields.
+    return rebuildConversationFromEntries({ ...c }, (id) => this.readEntries(id));
   }
 
   // In-memory stores already hold the full conversation object, so there's
@@ -372,6 +400,43 @@ export class InMemoryConversationStore implements ConversationStore {
         channelMeta: c.channelMeta,
       }));
   }
+
+  async appendEntries(
+    conversationId: string,
+    _agentId: string,
+    _tenantId: string | null,
+    entries: NewConversationEntry[],
+  ): Promise<ConversationEntry[]> {
+    const list = this.entries.get(conversationId) ?? [];
+    // seq is per-conversation: max existing seq + 1, then consecutive.
+    let nextSeq = list.reduce((max, e) => (e.seq > max ? e.seq : max), 0) + 1;
+    const now = Date.now();
+    const stored: ConversationEntry[] = entries.map(
+      (e) => ({ ...e, seq: nextSeq++, createdAt: now }) as ConversationEntry,
+    );
+    this.entries.set(conversationId, [...list, ...stored]);
+    return stored;
+  }
+
+  async readEntries(
+    conversationId: string,
+    opts?: { types?: string[]; afterSeq?: number; limit?: number },
+  ): Promise<ConversationEntry[]> {
+    let list = (this.entries.get(conversationId) ?? [])
+      .slice()
+      .sort((a, b) => a.seq - b.seq);
+    if (opts?.types && opts.types.length > 0) {
+      const allowed = new Set(opts.types);
+      list = list.filter((e) => allowed.has(e.type));
+    }
+    if (typeof opts?.afterSeq === "number") {
+      list = list.filter((e) => e.seq > opts.afterSeq!);
+    }
+    if (typeof opts?.limit === "number") {
+      list = list.slice(0, opts.limit);
+    }
+    return list;
+  }
 }
 
 export type ConversationSummary = {

package/src/storage/engine.ts

@@ -5,6 +5,7 @@ import type {
   ConversationSummary,
   PendingSubagentResult,
 } from "../state.js";
+import type { ConversationEntry, NewConversationEntry } from "./entries.js";
 import type { MainMemory } from "../memory.js";
 import type { TodoItem } from "../todo-tools.js";
 import type { Reminder, ReminderCreateInput, ReminderStatus } from "../reminder-store.js";
@@ -77,6 +78,23 @@ export interface StorageEngine {
     clearCallbackLock(conversationId: string): Promise<Conversation | undefined>;
     /** List thread conversations anchored under `parentConversationId`. */
     listThreads(parentConversationId: string): Promise<ConversationSummary[]>;
+    /**
+     * Append entries to a conversation's append-only log (Phase 3 substrate).
+     * Assigns a per-conversation monotonic `seq` and `createdAt` to each entry,
+     * persists them in order, and returns the stored entries. Additive — no
+     * read path consumes these yet.
+     */
+    appendEntries(
+      conversationId: string,
+      agentId: string,
+      tenantId: string | null,
+      entries: NewConversationEntry[],
+    ): Promise<ConversationEntry[]>;
+    /** Read a conversation's entries ordered by `seq` ascending. */
+    readEntries(
+      conversationId: string,
+      opts?: { types?: string[]; afterSeq?: number; limit?: number },
+    ): Promise<ConversationEntry[]>;
   };
 
   // --- Memory (replaces MemoryStore) ---

package/src/storage/entries.ts

@@ -1,5 +1,7 @@
-import type { Message } from "@poncho-ai/sdk";
-import type { PendingSubagentResult } from "../state.js";
+import { createLogger, type Message } from "@poncho-ai/sdk";
+import type { Conversation, PendingSubagentResult } from "../state.js";
+
+const entriesReadLog = createLogger("entries-read");
 
 /**
  * Append-only conversation entries (Phase 3 substrate).
@@ -100,6 +102,19 @@ export type ConversationEntry =
   | SubagentResultEntry
   | CallbackStartedEntry;
 
+/**
+ * An entry to append, before the engine assigns `seq` and `createdAt`. This
+ * is a DISTRIBUTIVE omit — `Omit<ConversationEntry, K>` over a union would
+ * collapse to only the keys common to every member (dropping `message`,
+ * `summaryMessage`, etc.), so we distribute over the union with a
+ * conditional type to omit those fields from each member individually.
+ */
+export type NewConversationEntry = ConversationEntry extends infer T
+  ? T extends ConversationEntry
+    ? Omit<T, "seq" | "createdAt">
+    : never
+  : never;
+
 /**
  * Rebuild the LLM-visible message context from the entry log.
  *
@@ -202,3 +217,56 @@ export function getPendingSubagentResults(
     .filter((e) => !consumed.has(e.seq))
     .map((e) => e.result);
 }
+
+// A very large tail so the rebuilt display snapshot is the full transcript.
+// Display callers slice to whatever window they actually render.
+const FULL_TRANSCRIPT_TAIL = 100_000;
+
+/**
+ * Phase 3c read cutover: rebuild a conversation's reader-facing fields from
+ * the append-only entry log, with a blob fallback for conversations that
+ * predate dual-write.
+ *
+ * Call this in every conversation `get`/`getWithArchive` path AFTER the
+ * Conversation has been constructed from the stored row/blob. It:
+ *   - reads the entry log via `readEntries`,
+ *   - if NON-EMPTY, overrides `_harnessMessages`, `messages`, and
+ *     `pendingSubagentResults` with entry-derived values,
+ *   - if EMPTY (un-migrated conversation), leaves the blob-derived fields
+ *     untouched (fallback),
+ *   - on ANY error, logs and falls back to the blob (never throws — this is
+ *     a hot read path).
+ *
+ * `_continuationMessages` and `pendingApprovals` are NOT modeled as entries
+ * yet and are intentionally left as blob fields.
+ *
+ * Kill-switch: set `PONCHO_READ_ENTRIES=0` to instantly revert to pure blob
+ * reads without a deploy (rebuild is ON by default).
+ *
+ * NOTE: mutates `conversation` in place and returns it. Callers that hand
+ * back a shared/mutable Conversation reference (the in-memory stores) MUST
+ * pass a clone, or the override will corrupt their stored object.
+ */
+export async function rebuildConversationFromEntries(
+  conversation: Conversation,
+  readEntries: (conversationId: string) => Promise<ConversationEntry[]>,
+): Promise<Conversation> {
+  // Kill-switch: ON by default; PONCHO_READ_ENTRIES="0" reverts to blob reads.
+  if (process.env.PONCHO_READ_ENTRIES === "0") return conversation;
+
+  try {
+    const entries = await readEntries(conversation.conversationId);
+    if (entries.length === 0) return conversation; // fallback: pre-dual-write
+    conversation._harnessMessages = buildLlmContext(entries);
+    conversation.messages = buildDisplaySnapshot(entries, FULL_TRANSCRIPT_TAIL).messages;
+    conversation.pendingSubagentResults = getPendingSubagentResults(entries);
+    return conversation;
+  } catch (err) {
+    entriesReadLog.warn(
+      `[entries-read] ${conversation.conversationId} rebuild failed, using blob: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    return conversation;
+  }
+}

package/src/storage/memory-engine.ts

@@ -14,6 +14,11 @@ import type { MainMemory } from "../memory.js";
 import type { TodoItem } from "../todo-tools.js";
 import type { Reminder, ReminderCreateInput, ReminderStatus } from "../reminder-store.js";
 import type { StorageEngine, VfsDirEntry, VfsStat } from "./engine.js";
+import {
+  type ConversationEntry,
+  type NewConversationEntry,
+  rebuildConversationFromEntries,
+} from "./entries.js";
 
 // ---------------------------------------------------------------------------
 // Internal VFS entry type
@@ -59,6 +64,8 @@ export class InMemoryEngine implements StorageEngine {
 
   // Conversation data
   private convs = new Map<string, Conversation>();
+  // Append-only conversation entries (Phase 3 substrate)
+  private entries = new Map<string, ConversationEntry[]>();
   // Memory data
   private mem = new Map<string, MainMemory>();
   // Todos data
@@ -100,13 +107,24 @@ export class InMemoryEngine implements StorageEngine {
     },
 
     get: async (conversationId: string): Promise<Conversation | undefined> => {
-      return this.convs.get(conversationId);
+      const c = this.convs.get(conversationId);
+      if (!c) return undefined;
+      // Phase 3c read cutover: rebuild reader-facing fields from the entry
+      // log (blob fallback for un-migrated conversations). Clone first — the
+      // map holds a live mutable reference and the rebuild overrides fields.
+      return rebuildConversationFromEntries({ ...c }, (id) =>
+        this.conversations.readEntries(id),
+      );
     },
 
     // In-memory storage has no separate archive blob, so both variants
     // return the same conversation object.
     getWithArchive: async (conversationId: string): Promise<Conversation | undefined> => {
-      return this.convs.get(conversationId);
+      const c = this.convs.get(conversationId);
+      if (!c) return undefined;
+      return rebuildConversationFromEntries({ ...c }, (id) =>
+        this.conversations.readEntries(id),
+      );
     },
 
     getStatusSnapshot: async (
@@ -239,6 +257,43 @@ export class InMemoryEngine implements StorageEngine {
       results.sort((a, b) => b.updatedAt - a.updatedAt);
       return results;
     },
+
+    appendEntries: async (
+      conversationId: string,
+      _agentId: string,
+      _tenantId: string | null,
+      entries: NewConversationEntry[],
+    ): Promise<ConversationEntry[]> => {
+      const list = this.entries.get(conversationId) ?? [];
+      // seq is per-conversation: max existing seq + 1, then consecutive.
+      let nextSeq = list.reduce((max, e) => (e.seq > max ? e.seq : max), 0) + 1;
+      const now = Date.now();
+      const stored: ConversationEntry[] = entries.map(
+        (e) => ({ ...e, seq: nextSeq++, createdAt: now }) as ConversationEntry,
+      );
+      this.entries.set(conversationId, [...list, ...stored]);
+      return stored;
+    },
+
+    readEntries: async (
+      conversationId: string,
+      opts?: { types?: string[]; afterSeq?: number; limit?: number },
+    ): Promise<ConversationEntry[]> => {
+      let list = (this.entries.get(conversationId) ?? [])
+        .slice()
+        .sort((a, b) => a.seq - b.seq);
+      if (opts?.types && opts.types.length > 0) {
+        const allowed = new Set(opts.types);
+        list = list.filter((e) => allowed.has(e.type));
+      }
+      if (typeof opts?.afterSeq === "number") {
+        list = list.filter((e) => e.seq > opts.afterSeq!);
+      }
+      if (typeof opts?.limit === "number") {
+        list = list.slice(0, opts.limit);
+      }
+      return list;
+    },
   };
 
   // -----------------------------------------------------------------------

package/src/storage/schema.ts

@@ -214,4 +214,34 @@ export const migrations: Migration[] = [
       ];
     },
   },
+  {
+    version: 8,
+    name: "conversation_entries",
+    // Append-only conversation log (Phase 3 substrate). Additive: no
+    // existing table or behavior changes. `seq` is a per-conversation
+    // monotonic order assigned by the application (NOT an autoincrement
+    // serial), so the same seq space restarts at 1 for every conversation.
+    // The UNIQUE (conversation_id, seq) constraint backstops the
+    // app-assigned ordering against concurrent writers.
+    up: (d) => {
+      const jsonType = d === "sqlite" ? "TEXT" : "JSONB";
+      const tsDefault = d === "sqlite" ? "datetime('now')" : "NOW()";
+      const autoTs = `DEFAULT (${tsDefault})`;
+      return [
+        `CREATE TABLE IF NOT EXISTS conversation_entries (
+          seq INTEGER NOT NULL,
+          id TEXT NOT NULL UNIQUE,
+          agent_id TEXT NOT NULL,
+          tenant_id TEXT NOT NULL DEFAULT '__default__',
+          conversation_id TEXT NOT NULL,
+          type TEXT NOT NULL,
+          payload ${jsonType} NOT NULL,
+          created_at TIMESTAMP ${autoTs},
+          UNIQUE (conversation_id, seq)
+        )`,
+        `CREATE INDEX IF NOT EXISTS idx_conversation_entries_seq
+          ON conversation_entries (conversation_id, seq)`,
+      ];
+    },
+  },
 ];

package/src/storage/sql-dialect.ts

@@ -22,6 +22,11 @@ import type { MainMemory } from "../memory.js";
 import type { TodoItem } from "../todo-tools.js";
 import type { Reminder, ReminderCreateInput, ReminderStatus } from "../reminder-store.js";
 import type { StorageEngine, VfsDirEntry, VfsStat } from "./engine.js";
+import {
+  type ConversationEntry,
+  type NewConversationEntry,
+  rebuildConversationFromEntries,
+} from "./entries.js";
 import { type DialectTag, migrations } from "./schema.js";
 
 // ---------------------------------------------------------------------------
@@ -324,7 +329,12 @@ export abstract class SqlStorageEngine implements StorageEngine {
             ? JSON.parse(row.continuation_messages)
             : row.continuation_messages;
       }
-      return conv;
+      // Phase 3c read cutover: rebuild reader-facing fields from the
+      // append-only entry log, falling back to the blob for un-migrated
+      // conversations. parseConversation returns a fresh object, so no clone.
+      return rebuildConversationFromEntries(conv, (id) =>
+        this.conversations.readEntries(id),
+      );
     },
 
     getStatusSnapshot: async (
@@ -407,7 +417,11 @@ export abstract class SqlStorageEngine implements StorageEngine {
             ? JSON.parse(row.continuation_messages)
             : row.continuation_messages;
       }
-      return conv;
+      // Phase 3c read cutover: rebuild reader-facing fields from the entry
+      // log (blob fallback for un-migrated conversations).
+      return rebuildConversationFromEntries(conv, (id) =>
+        this.conversations.readEntries(id),
+      );
     },
 
     create: async (
@@ -628,6 +642,117 @@ export abstract class SqlStorageEngine implements StorageEngine {
       ]);
       return rows.map((r) => this.rowToSummary(r));
     },
+
+    appendEntries: async (
+      conversationId: string,
+      agentId: string,
+      tenantId: string | null,
+      entries: NewConversationEntry[],
+    ): Promise<ConversationEntry[]> => {
+      if (entries.length === 0) return [];
+      const tid = normalizeTenant(tenantId);
+
+      // CONCURRENCY: seq is assigned by the app as COALESCE(MAX(seq),0)+1 per
+      // conversation, inside a transaction. Two concurrent writers can read
+      // the same MAX and collide on the UNIQUE (conversation_id, seq)
+      // constraint; we let the loser's transaction fail and retry the whole
+      // compute-and-insert up to 3 times. This MAX+1+retry scheme is correct
+      // for the modest concurrency here (a single conversation rarely has
+      // simultaneous appenders). A later hardening — a per-conversation
+      // advisory lock — can replace it before any read path depends on these
+      // entries.
+      const maxAttempts = 3;
+      let lastErr: unknown;
+      for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const stored: ConversationEntry[] = [];
+        try {
+          await this.executor.transaction(async () => {
+            stored.length = 0; // reset on retry within the same closure
+            const row = await this.executor.get<{ max_seq: number | null }>(
+              rewrite(
+                "SELECT MAX(seq) AS max_seq FROM conversation_entries WHERE conversation_id = $1",
+                this.dialect,
+              ),
+              [conversationId],
+            );
+            let nextSeq = Number(row?.max_seq ?? 0) + 1;
+            const now = Date.now();
+            for (const entry of entries) {
+              const seq = nextSeq++;
+              const createdAt = now;
+              // Persist the full entry object (minus seq/createdAt, which are
+              // columns) as the JSON payload. seq, id, created_at are columns.
+              const payload = JSON.stringify(entry);
+              await this.executor.run(
+                rewrite(
+                  `INSERT INTO conversation_entries
+                     (seq, id, agent_id, tenant_id, conversation_id, type, payload, created_at)
+                   VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
+                  this.dialect,
+                ),
+                [
+                  seq,
+                  entry.id,
+                  agentId,
+                  tid,
+                  conversationId,
+                  entry.type,
+                  payload,
+                  new Date(createdAt).toISOString(),
+                ],
+              );
+              stored.push({ ...entry, seq, createdAt } as ConversationEntry);
+            }
+          });
+          return stored;
+        } catch (err) {
+          lastErr = err;
+          // Retry on any failure (the likely cause is a UNIQUE collision from
+          // a concurrent writer); the next attempt re-reads MAX(seq).
+        }
+      }
+      throw lastErr;
+    },
+
+    readEntries: async (
+      conversationId: string,
+      opts?: { types?: string[]; afterSeq?: number; limit?: number },
+    ): Promise<ConversationEntry[]> => {
+      const params: unknown[] = [conversationId];
+      let sql = "SELECT seq, id, payload, created_at FROM conversation_entries WHERE conversation_id = $1";
+      if (opts?.types && opts.types.length > 0) {
+        const placeholders = opts.types.map(
+          (_t, i) => `$${params.length + 1 + i}`,
+        );
+        sql += ` AND type IN (${placeholders.join(", ")})`;
+        params.push(...opts.types);
+      }
+      if (typeof opts?.afterSeq === "number") {
+        sql += ` AND seq > $${params.length + 1}`;
+        params.push(opts.afterSeq);
+      }
+      sql += " ORDER BY seq ASC";
+      if (typeof opts?.limit === "number") {
+        sql += ` LIMIT $${params.length + 1}`;
+        params.push(opts.limit);
+      }
+      const rows = await this.executor.all<{
+        seq: number;
+        id: string;
+        payload: unknown;
+        created_at: string;
+      }>(rewrite(sql, this.dialect), params);
+      return rows.map((r) => {
+        const parsed =
+          typeof r.payload === "string" ? JSON.parse(r.payload) : r.payload;
+        return {
+          ...parsed,
+          id: r.id,
+          seq: Number(r.seq),
+          createdAt: new Date(r.created_at).getTime(),
+        } as ConversationEntry;
+      });
+    },
   };
 
   // -----------------------------------------------------------------------

package/src/storage/store-adapters.ts

@@ -58,6 +58,14 @@ export function createConversationStoreFromEngine(
       engine.conversations.clearCallbackLock(conversationId),
     listThreads: (parentConversationId: string) =>
       engine.conversations.listThreads(parentConversationId),
+    appendEntries: (
+      conversationId: string,
+      agentId: string,
+      tenantId: string | null,
+      entries,
+    ) => engine.conversations.appendEntries(conversationId, agentId, tenantId, entries),
+    readEntries: (conversationId: string, opts) =>
+      engine.conversations.readEntries(conversationId, opts),
   };
 }