@jeffober/thatch 0.1.35 → 0.1.36

package/src/index.ts

@@ -21,6 +21,8 @@ import { installSkills, SHARED_SKILLS, OPENCODE_ONLY_SKILLS } from "./skills";
 import { hygieneReport } from "./hygiene";
 import { seedDefaultBehaviors } from "./seed-behaviors";
 import { startVersionChecker, stopVersionChecker, getVersionChecker, readOnDiskVersion, compareSemver } from "./version-check";
+import { WatcherRegistry, ghApiRun, ghAvailable } from "./watchers";
+import { watcherNotificationNudge } from "./prompts";
 import pkg from "../package.json";
 
 // ---------------------------------------------------------------------------
@@ -83,6 +85,43 @@ export const server: Plugin = async ({ client, worktree }) => {
   // non-restart.
   const runningVersion = pkg.version;
 
+  // Latest observed opencode session status per session ("busy" | "idle" |
+  // "retry"). The event hook records these; the watcher registry's
+  // canDeliver gate reads them so proactive notification prompts only fire
+  // into idle sessions - never into a turn that is already running.
+  const sessionStatus = new Map<string, string>();
+
+  // In-memory watcher registry for proactive event notifications (GitHub PR
+  // watching today). Deliberately process-scoped: no SQLite, no cross-restart
+  // state. See src/watchers.ts for the rationale.
+  //
+  // Delivery prompts the session with a synthetic part - the same mechanism
+  // opencode uses for background task completions - so a watched event
+  // triggers a model turn even when the user is away. Events only carry
+  // pointer data; the model fetches details itself with gh.
+  const watchers = new WatcherRegistry({
+    deliver: async (sessionID, events) => {
+      const target = events[0]?.url.match(/github\.com\/([^/]+\/[^/]+)\/pull\/(\d+)/)?.[0]
+        ?.replace(/github\.com\//, "")
+        .replace(/\/pull\//, "#") ?? "watched PR";
+      await client.session.promptAsync({
+        path: { id: sessionID },
+        body: {
+          parts: [{ type: "text", text: watcherNotificationNudge(target, events), synthetic: true }],
+        },
+      });
+    },
+    canDeliver: (sessionID) =>
+      !compacting.has(sessionID) && sessionStatus.get(sessionID) === "idle",
+    ghRunner: ghApiRun,
+  });
+  // gh presence decides whether watch_create works; checked lazily by the
+  // tool, but log once at startup so misconfiguration is visible in debug logs.
+  void ghAvailable().then((ok) => {
+    if (!ok) console.error("[thatch] gh CLI not found - watch tools will report unavailable");
+  });
+  watchers.start();
+
   // Sessions currently being compacted. chat.message nudges are skipped while
   // a session is in this set - the agent can't call tools during summary
   // generation, so a recall or extraction nudge would cause a blocked-tool
@@ -242,6 +281,7 @@ export const server: Plugin = async ({ client, worktree }) => {
         if (all.length === 0) return null;
         return extraction.buildPayload(all, repo);
       },
+      watcherRegistry: watchers,
     }),
 
     // 1. System prompt - always in context.
@@ -600,8 +640,13 @@ export const server: Plugin = async ({ client, worktree }) => {
         }
         return;
       }
-      if (event.type === "session.status" && event.properties.status?.type === "idle") {
+      if (event.type === "session.status") {
         const sessionID = event.properties.sessionID;
+        const statusType = event.properties.status?.type;
+        // Record the latest status so the watcher registry can gate
+        // proactive prompt delivery on idle sessions.
+        if (sessionID && statusType) sessionStatus.set(sessionID, statusType);
+        if (statusType !== "idle") return;
         const parentID = sessionID ? childToParent.get(sessionID) : undefined;
         if (parentID && sessionID) {
           // A child session went idle. Two cases:
@@ -685,6 +730,15 @@ export const server: Plugin = async ({ client, worktree }) => {
             extracting.delete(sessionID);
           }
         }
+        // The session just became idle, so watcher events queued while it
+        // was busy can be delivered now - the poll interval may otherwise
+        // hold them for up to a full cycle. Best-effort; failures stay
+        // pending and retry on the next poll.
+        try {
+          await watchers.deliverPending();
+        } catch (err) {
+          console.error(`[thatch] watcher delivery on idle failed: ${err}`);
+        }
         return;
       }
       if (event.type === "session.deleted") {
@@ -699,9 +753,13 @@ export const server: Plugin = async ({ client, worktree }) => {
         parentSnapshots.delete(id);
         childMetrics.delete(id);
         extractionChildren.delete(id);
-        // A deleted parent takes its accepted entries with it.
+        // A deleted parent takes its accepted entries with it, and its
+        // watchers die with it - the session that would receive their
+        // notifications no longer exists.
         extraction.completeAccepted(id);
         extracting.delete(id);
+        sessionStatus.delete(id);
+        watchers.cancelSession(id);
         return;
       }
 
@@ -739,6 +797,7 @@ export const server: Plugin = async ({ client, worktree }) => {
 
     dispose: async () => {
       stopVersionChecker();
+      watchers.dispose();
       db.close();
     },
   };

package/src/mcp.ts

@@ -60,9 +60,12 @@ interface CompiledTool {
   inputSchema: Record<string, unknown>;
 }
 
-function compileTools(): Map<string, CompiledTool> {
+export function compileTools(): Map<string, CompiledTool> {
   const map = new Map<string, CompiledTool>();
   for (const def of TOOL_DEFS) {
+    // opencode-only tools depend on host capabilities MCP servers don't
+    // have (e.g. session identity via HostToolContext) - never expose them.
+    if (def.opencodeOnly) continue;
     const schema = z.object(def.args);
     map.set(def.name, {
       def,

package/src/prompts.ts

@@ -17,13 +17,15 @@ Thatch provides persistent memory across opencode sessions. Use it to persist
 knowledge so future sessions can build on what you've already learned.
 
 Tools: thatch_memory_remember, thatch_memory_recall, thatch_memory_list,
-       thatch_memory_show, thatch_memory_forget, thatch_store_list,
-       thatch_find_duplicates, thatch_dedup_mark_checked,
-       thatch_extraction_done, thatch_get_extraction_payload,
-       thatch_prediction_query, thatch_prediction_update, thatch_prediction_list,
-       thatch_prediction_delete,
-       thatch_behavior_codify, thatch_behavior_feedback, thatch_behavior_list,
-       thatch_behavior_delete
+        thatch_memory_show, thatch_memory_forget, thatch_store_list,
+        thatch_find_duplicates, thatch_dedup_mark_checked,
+        thatch_extraction_done, thatch_get_extraction_payload,
+        thatch_prediction_query, thatch_prediction_update, thatch_prediction_list,
+        thatch_prediction_delete,
+        thatch_behavior_codify, thatch_behavior_feedback, thatch_behavior_list,
+        thatch_behavior_delete, thatch_get_session_info,
+        thatch_session_search, thatch_session_get,
+        thatch_watch_create, thatch_watch_list, thatch_watch_cancel
 
 ## Stores
 
@@ -107,6 +109,20 @@ the same prompt. If the re-dispatch also fails or times out, note the gap and
 move on. Do not retry more than once - repeated failures indicate an
 intractable prompt, not a transient hang.
 
+## Watchers
+
+Use thatch_watch_create to watch a GitHub PR for events (comments, review
+comments and replies, commits, status changes, description edits, CI check
+completions). thatch polls the PR in the background and injects a
+notification into this session when a watched event happens. The
+notification carries pointer data only (author, URL); fetch details with
+the gh CLI when you decide to act. When the user asks you to watch
+something, state your handling policy for notifications out loud first
+("I'll report human comments and handle bugbot replies myself") so the
+notification turn knows what to do. Treat watcher notifications like
+background task completions: they are system events, not user input, and
+not approval to advance other pending work.
+
 ## User Decision Model
 
 A statistical model of the user's decision-making preferences is maintained by
@@ -270,6 +286,10 @@ Tools are prefixed in ${host}: \`mcp__thatch__memory_remember\`,
 \`mcp__thatch__prediction_list\`, \`mcp__thatch__prediction_delete\`,
 \`mcp__thatch__behavior_codify\`, \`mcp__thatch__behavior_feedback\`,
 \`mcp__thatch__behavior_list\`, \`mcp__thatch__behavior_delete\`. Bare names used below for readability.
+get_session_info, session_search, session_get, watch_create, watch_list,
+and watch_cancel are intentionally absent: they are opencode-only (MCP
+hosts have no session concept, session database, or proactive-prompt
+channel), so do not expect them here.
 
 ## Stores
 
@@ -668,3 +688,19 @@ export function behaviorNudge(items: BehaviorNudgeItem[]): string {
   });
   return `[thatch] Situational behaviors\n${lines.join("\n")}`;
 }
+
+/**
+ * Watcher notification for the poller's promptAsync delivery. Injected as a
+ * synthetic part that triggers a model turn. Events carry pointer data only
+ * (author, URL) - never external content - so the model fetches details on
+ * demand with the gh CLI. The wrapper text borrows the background-task
+ * completion framing: a system event, not user input, not approval to
+ * advance other pending work.
+ */
+export function watcherNotificationNudge(target: string, events: { type: string; summary: string; url: string }[]): string {
+  const lines = events.map((e) => `- ${e.type}: ${e.summary} ${e.url}`);
+  return `[thatch] Watcher notification for ${target}
+${lines.join("\n")}
+
+This is a system notification, not user input. Decide whether to act now or keep waiting - the user's instructions from when the watch was created govern how to handle it. Fetch details with the gh CLI if you need them. Do not treat this notification as approval to advance other pending work. If you act, tell the user what you did and why; if not, stop and wait.`;
+}

package/src/session-db.ts

@@ -0,0 +1,452 @@
+import { Database } from "bun:sqlite";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Read-only access to the opencode session database (opencode.db). opencode
+ * stores its conversation transcripts in three tables: `session` (one row per
+ * conversation), `message` (one row per user/assistant turn; `data` carries
+ * the role), and `part` (one row per content piece of a message; `data` is a
+ * JSON blob whose `type` field distinguishes text, tool, reasoning, patch,
+ * and step boundaries). This module is host-agnostic: the CLI subcommands use
+ * it directly, and the opencode-only session tools reach the same db from
+ * inside the plugin process.
+ *
+ * The database is opened read-only so a thatch bug can never corrupt the
+ * host's session history. Concurrent reads are safe - the daemon holds the
+ * write lock, readers never block.
+ */
+
+/** The piece types emitted by list/search. step-start/step-finish are
+ *  bookkeeping boundaries opencode writes between model calls. */
+export type PartType = "text" | "tool" | "reasoning" | "patch" | "step-start" | "step-finish" | "other";
+
+/** Decoded role from the message row's data blob ("user" or "assistant"). */
+export type MessageRole = "user" | "assistant" | string;
+
+/** One content piece of a conversation, decoded from the part table. */
+export interface SessionPart {
+  partId: string;
+  messageId: string;
+  sessionId: string;
+  /** Millisecond epoch from the part row. */
+  timeCreated: number;
+  role: MessageRole;
+  type: PartType;
+  /** Raw decoded data blob - shape varies by type (see listEntries docs). */
+  data: Record<string, unknown>;
+}
+
+/**
+ * Resolves the opencode session database path. Precedence mirrors opencode
+ * itself: OPENCODE_DB (its documented override, read at opencode startup)
+ * wins, then the XDG_DATA_HOME-derived default. Returns null when no
+ * database file exists - the CLI turns this into a useful error and the
+ * session tools report unavailability.
+ */
+export function resolveOpencodeDbPath(): string | null {
+  if (process.env.OPENCODE_DB) {
+    return existsSync(process.env.OPENCODE_DB) ? process.env.OPENCODE_DB : null;
+  }
+  const dataHome = process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share");
+  const path = join(dataHome, "opencode", "opencode.db");
+  return existsSync(path) ? path : null;
+}
+
+export interface SessionRow {
+  id: string;
+  title: string;
+  directory: string;
+  agent: string | null;
+  model: string | null;
+  timeCreated: number;
+  timeUpdated: number;
+}
+
+/** Truncate for list/search preview fields. Kept modest so a full screen of
+ *  timeline stays scannable; `session get` returns untruncated content. */
+const PREVIEW_LEN = 200;
+
+function truncate(text: string, maxLen = PREVIEW_LEN): string {
+  return text.length <= maxLen ? text : text.slice(0, maxLen) + "...";
+}
+
+function toIso(ms: number): string {
+  return new Date(ms).toISOString();
+}
+
+/** Extract every human-readable string from a decoded part blob. Used by
+ *  search so patterns match real content, not JSON field names or escaped
+ *  syntax in the raw blob. */
+function searchableStrings(data: Record<string, unknown>): string[] {
+  const out: string[] = [];
+  const walk = (value: unknown, depth: number): void => {
+    if (depth > 6) return;
+    if (typeof value === "string") {
+      out.push(value);
+    } else if (Array.isArray(value)) {
+      for (const item of value) walk(item, depth + 1);
+    } else if (value && typeof value === "object") {
+      for (const item of Object.values(value)) walk(item, depth + 1);
+    }
+  };
+  walk(data, 0);
+  return out;
+}
+
+/**
+ * Read-only facade over opencode.db. All methods throw when the underlying
+ * file is missing or has an unexpected schema - callers surface the error.
+ */
+export class SessionDB {
+  readonly path: string;
+  #db: Database;
+
+  constructor(path: string) {
+    this.path = path;
+    this.#db = new Database(path, { readonly: true });
+  }
+
+  close(): void {
+    this.#db.close();
+  }
+
+  /** Fetches one session row, or null for an unknown id. */
+  getSession(sessionID: string): SessionRow | null {
+    const row = this.#db
+      .query(
+        "SELECT id, title, directory, agent, model, time_created, time_updated FROM session WHERE id = ?",
+      )
+      .get(sessionID) as
+      | { id: string; title: string; directory: string; agent: string | null; model: string | null; time_created: number; time_updated: number }
+      | undefined;
+    if (!row) return null;
+    return {
+      id: row.id,
+      title: row.title,
+      directory: row.directory,
+      agent: row.agent,
+      model: row.model,
+      timeCreated: row.time_created,
+      timeUpdated: row.time_updated,
+    };
+  }
+
+  /**
+   * Lists a session's parts in conversation order (message time, then part
+   * order within the message), each joined with its message role.
+   * afterMs/beforeMs bound the part time window (epoch ms, inclusive).
+   */
+  listParts(sessionID: string, afterMs?: number, beforeMs?: number): SessionPart[] {
+    const rows = this.#db
+      .query(
+        `SELECT p.id AS part_id, p.message_id, p.session_id, p.time_created, p.data AS part_data,
+                m.data AS message_data
+         FROM part p
+         JOIN message m ON m.id = p.message_id
+         WHERE p.session_id = ?
+           AND (? IS NULL OR p.time_created >= ?)
+           AND (? IS NULL OR p.time_created <= ?)
+         ORDER BY m.time_created, p.time_created, p.id`,
+      )
+      .all(sessionID, afterMs ?? null, afterMs ?? null, beforeMs ?? null, beforeMs ?? null) as {
+      part_id: string;
+      message_id: string;
+      session_id: string;
+      time_created: number;
+      part_data: string;
+      message_data: string;
+    }[];
+
+    return rows.map((row) => {
+      const partData = JSON.parse(row.part_data) as Record<string, unknown>;
+      const messageData = JSON.parse(row.message_data) as Record<string, unknown>;
+      return {
+        partId: row.part_id,
+        messageId: row.message_id,
+        sessionId: row.session_id,
+        timeCreated: row.time_created,
+        role: (messageData.role as MessageRole) ?? "unknown",
+        type: (partData.type as PartType) ?? "other",
+        data: partData,
+      };
+    });
+  }
+
+  /**
+   * Fetches one part by its part id. No session filter - part ids are
+   * globally unique primary keys, so a bare --id works without -s.
+   */
+  getPart(partID: string): SessionPart | null {
+    const row = this.#db
+      .query(
+        `SELECT p.id AS part_id, p.message_id, p.session_id, p.time_created, p.data AS part_data,
+                m.data AS message_data
+         FROM part p
+         JOIN message m ON m.id = p.message_id
+         WHERE p.id = ?`,
+      )
+      .get(partID) as
+      | { part_id: string; message_id: string; session_id: string; time_created: number; part_data: string; message_data: string }
+      | undefined;
+    if (!row) return null;
+    const partData = JSON.parse(row.part_data) as Record<string, unknown>;
+    const messageData = JSON.parse(row.message_data) as Record<string, unknown>;
+    return {
+      partId: row.part_id,
+      messageId: row.message_id,
+      sessionId: row.session_id,
+      timeCreated: row.time_created,
+      role: (messageData.role as MessageRole) ?? "unknown",
+      type: (partData.type as PartType) ?? "other",
+      data: partData,
+    };
+  }
+
+  /** Fetches one message row (decoded) with all of its parts in order. */
+  getMessage(messageID: string): { messageId: string; sessionId: string; timeCreated: number; role: MessageRole; data: Record<string, unknown>; parts: SessionPart[] } | null {
+    const row = this.#db
+      .query("SELECT id, session_id, time_created, data FROM message WHERE id = ?")
+      .get(messageID) as { id: string; session_id: string; time_created: number; data: string } | undefined;
+    if (!row) return null;
+    const decoded = JSON.parse(row.data) as Record<string, unknown>;
+    const parts = this.listParts(row.session_id).filter((p) => p.messageId === messageID);
+    return {
+      messageId: messageID,
+      sessionId: row.session_id,
+      timeCreated: row.time_created,
+      role: (decoded.role as MessageRole) ?? "unknown",
+      data: decoded,
+      parts,
+    };
+  }
+
+  /** Lists a session's messages in order, each with its parts. Used by the
+   *  transcript builder, which needs per-message grouping rather than the
+   *  flat part stream listParts produces. */
+  listMessages(sessionID: string): { messageId: string; sessionId: string; timeCreated: number; role: MessageRole; data: Record<string, unknown>; parts: SessionPart[] }[] {
+    const messages = this.#db
+      .query("SELECT id, session_id, time_created, data FROM message WHERE session_id = ? ORDER BY time_created, id")
+      .all(sessionID) as { id: string; session_id: string; time_created: number; data: string }[];
+    const parts = this.listParts(sessionID);
+    return messages.map((row) => {
+      const decoded = JSON.parse(row.data) as Record<string, unknown>;
+      return {
+        messageId: row.id,
+        sessionId: row.session_id,
+        timeCreated: row.time_created,
+        role: (decoded.role as MessageRole) ?? "unknown",
+        data: decoded,
+        parts: parts.filter((p) => p.messageId === row.id),
+      };
+    });
+  }
+
+  /**
+   * Searches decoded part content across sessions. Plain queries are
+   * case-insensitive substrings; regex queries use the pattern as-is.
+   * Scans the part table in conversation order, so results come back in
+   * chronological order grouped by session. sessionID narrows to one
+   * session; limit caps matches (applied after the scan completes, oldest
+   * first).
+   */
+  search(query: string, opts?: { regex?: boolean; sessionID?: string; limit?: number }): SessionPart[] {
+    let matcher: (s: string) => boolean;
+    if (opts?.regex) {
+      const re = new RegExp(query);
+      matcher = (s) => re.test(s);
+    } else {
+      const needle = query.toLowerCase();
+      matcher = (s) => s.toLowerCase().includes(needle);
+    }
+
+    const rows = (opts?.sessionID
+      ? this.#db
+          .query(
+            `SELECT p.id AS part_id, p.message_id, p.session_id, p.time_created, p.data AS part_data,
+                    m.data AS message_data
+             FROM part p JOIN message m ON m.id = p.message_id
+             WHERE p.session_id = ?
+             ORDER BY m.time_created, p.id`,
+          )
+          .all(opts.sessionID)
+      : this.#db
+          .query(
+            `SELECT p.id AS part_id, p.message_id, p.session_id, p.time_created, p.data AS part_data,
+                    m.data AS message_data
+             FROM part p JOIN message m ON m.id = p.message_id
+             ORDER BY p.session_id, m.time_created, p.time_created, p.id`,
+          )
+          .all()) as {
+      part_id: string;
+      message_id: string;
+      session_id: string;
+      time_created: number;
+      part_data: string;
+      message_data: string;
+    }[];
+
+    const limit = opts?.limit ?? 200;
+    const matches: SessionPart[] = [];
+    for (const row of rows) {
+      let decoded: Record<string, unknown>;
+      let role: MessageRole;
+      try {
+        decoded = JSON.parse(row.part_data) as Record<string, unknown>;
+        role = (JSON.parse(row.message_data) as Record<string, unknown>).role as MessageRole;
+      } catch {
+        continue;
+      }
+      if (searchableStrings(decoded).some(matcher)) {
+        matches.push({
+          partId: row.part_id,
+          messageId: row.message_id,
+          sessionId: row.session_id,
+          timeCreated: row.time_created,
+          role: role ?? "unknown",
+          type: (decoded.type as PartType) ?? "other",
+          data: decoded,
+        });
+        if (matches.length >= limit) break;
+      }
+    }
+    return matches;
+  }
+}
+
+/** Human-recognizable epoch-ms timestamp for JSONL output. */
+export function iso(ms: number): string {
+  return toIso(ms);
+}
+
+/**
+ * Full-content serialization of one part (the `session get` shape). Uses the
+ * same snake_case field names as the timeline entries so consumers pipe
+ * list/search output into get without renaming. `data` is the complete
+ * decoded part blob - tool parts carry their full input and output here,
+ * untruncated.
+ */
+export function partToFullJson(part: SessionPart): Record<string, unknown> {
+  return {
+    part_id: part.partId,
+    message_id: part.messageId,
+    session_id: part.sessionId,
+    timestamp: iso(part.timeCreated),
+    role: part.role,
+    type: part.type,
+    data: part.data,
+  };
+}
+
+/** Full-content serialization of one message with all of its parts. */
+export function messageToFullJson(message: {
+  messageId: string;
+  sessionId: string;
+  timeCreated: number;
+  role: MessageRole;
+  data: Record<string, unknown>;
+  parts: SessionPart[];
+}): Record<string, unknown> {
+  return {
+    message_id: message.messageId,
+    session_id: message.sessionId,
+    timestamp: iso(message.timeCreated),
+    role: message.role,
+    data: message.data,
+    parts: message.parts.map(partToFullJson),
+  };
+}
+
+/**
+ * Builds the `session list` timeline entry for one part: a flat object with
+ * common identity fields plus type-specific preview fields. Tool parts keep
+ * their callID so callers can trace a call back to its transcript row.
+ */
+export function partToTimelineEntry(part: SessionPart): Record<string, unknown> {
+  const base: Record<string, unknown> = {
+    timestamp: iso(part.timeCreated),
+    msg_id: part.messageId,
+    part_id: part.partId,
+    role: part.role,
+    type: part.type,
+  };
+  switch (part.type) {
+    case "text":
+    case "reasoning":
+      base.detail = truncate(String(part.data.text ?? ""));
+      break;
+    case "tool": {
+      const state = (part.data.state ?? {}) as Record<string, unknown>;
+      const toolName = String(part.data.tool ?? "");
+      base.call_id = part.data.callID;
+      base.tool = toolName;
+      base.detail = toolName;
+      base.args_preview = truncate(JSON.stringify(state.input ?? {}));
+      base.output = truncate(String(state.output ?? ""));
+      break;
+    }
+    case "patch":
+      base.detail = ((part.data.files as string[]) ?? []).map((f) => f.split("/").pop()).join(", ");
+      break;
+    case "step-finish": {
+      const tokens = (part.data.tokens ?? {}) as Record<string, unknown>;
+      base.detail = `tokens: ${tokens.total ?? "?"} cost: ${part.data.cost ?? "?"}`;
+      break;
+    }
+    default:
+      base.detail = "";
+  }
+  return base;
+}
+
+/**
+ * Builds the `session transcript` OpenAI chat-completions entry set for one
+ * message. Returns 0..n lines: user messages become one {role:"user"} line;
+ * assistant messages become one {role:"assistant"} line (with a tool_calls
+ * array when the step made tool calls) followed by one {role:"tool"} line
+ * per tool result. Reasoning and step boundaries have no chat-completions
+ * equivalent and are dropped.
+ */
+export function partToTranscriptEntries(
+  messageRole: MessageRole,
+  parts: SessionPart[],
+): Record<string, unknown>[] {
+  const entries: Record<string, unknown>[] = [];
+  if (messageRole === "user") {
+    const text = parts
+      .filter((p) => p.type === "text")
+      .map((p) => String(p.data.text ?? ""))
+      .join("\n");
+    if (text) entries.push({ role: "user", content: text });
+    return entries;
+  }
+  if (messageRole !== "assistant") return entries;
+
+  const textParts = parts.filter((p) => p.type === "text");
+  const toolParts = parts.filter((p) => p.type === "tool");
+  const content = textParts.map((p) => String(p.data.text ?? "")).join("\n");
+  // A message with neither text nor tool calls (e.g. reasoning-only) has no
+  // chat-completions representation - emit nothing rather than an empty line.
+  if (!content && toolParts.length === 0) return entries;
+  const assistant: Record<string, unknown> = { role: "assistant", content };
+  if (toolParts.length > 0) {
+    assistant.tool_calls = toolParts.map((p) => ({
+      id: p.data.callID,
+      type: "function",
+      function: {
+        name: p.data.tool,
+        arguments: JSON.stringify((p.data.state as Record<string, unknown>)?.input ?? {}),
+      },
+    }));
+  }
+  entries.push(assistant);
+  for (const p of toolParts) {
+    entries.push({
+      role: "tool",
+      tool_call_id: p.data.callID,
+      content: String((p.data.state as Record<string, unknown>)?.output ?? ""),
+    });
+  }
+  return entries;
+}