@gmickel/gno 2.5.1 → 2.7.0

package/src/sessions/parsers/codex.ts

@@ -0,0 +1,303 @@
+/**
+ * Codex rollout JSONL parser.
+ *
+ * Prompts of `codex exec` runs (`session_meta.source = "exec"`) come from a
+ * program or script (often another agent) and are not archived as human
+ * speech; interactive CLI and editor sessions are.
+ *
+ * Verified layouts (2026-09): every line is `{timestamp, ordinal?, type,
+ * payload}` and the first line is `session_meta`.
+ * - CLI >= 0.151: speech arrives as `event_msg` `item_completed` with
+ *   `item.type` `UserMessage` / `AgentMessage`.
+ * - CLI <= 0.150: speech arrives as `event_msg` `user_message` /
+ *   `agent_message`.
+ * `response_item` messages duplicate that speech and mix injected context
+ * (environment, instructions, skills) into `role=user`, so they are never
+ * used as a human signal. Reasoning and tool records are excluded.
+ *
+ * Forks and spawned subagents carry `forked_from_id` /
+ * `subagent_history_start_ordinal`; records before that ordinal (including a
+ * second `session_meta`) are copied parent history and are skipped. In a
+ * spawned subagent thread the "user" message is the parent agent's task, not
+ * human speech.
+ *
+ * @module src/sessions/parsers/codex
+ */
+
+import {
+  emptyDiagnostics,
+  normalizeTimestamp,
+  noteUnknownKind,
+  type ParsedThread,
+  type ParsedTurn,
+  type ParseUnitResult,
+  type SessionThreadKind,
+} from "../types";
+import {
+  missingHumanTurns,
+  isRecord,
+  joinTextBlocks,
+  pushTurn,
+  readJsonlRecords,
+  stringField,
+} from "./shared";
+
+export const CODEX_PARSER = "codex/1";
+
+const SKIPPED_TOP_LEVEL = new Set([
+  "response_item",
+  "inter_agent_communication_metadata",
+  "turn_context",
+  "world_state",
+  "token_usage_record",
+  "compacted",
+]);
+
+const SKIPPED_EVENTS = new Set([
+  "token_count",
+  "task_started",
+  "task_complete",
+  "turn_started",
+  "turn_complete",
+  "turn_aborted",
+  "agent_reasoning",
+  "agent_reasoning_raw_content",
+  "agent_reasoning_section_break",
+  "thread_settings_applied",
+  "thread_goal_updated",
+  "exec_command_begin",
+  "exec_command_end",
+  "exec_command_output_delta",
+  "patch_apply_begin",
+  "patch_apply_end",
+  "mcp_tool_call_begin",
+  "mcp_tool_call_end",
+  "web_search_begin",
+  "web_search_end",
+  "item_started",
+  "item_updated",
+  "context_compacted",
+  "entered_review_mode",
+  "exited_review_mode",
+  "stream_error",
+  "error",
+  "warning",
+  "background_event",
+  "session_configured",
+  "plan_update",
+  "turn_diff",
+  "get_history_entry_response",
+  "view_image_tool_call",
+]);
+
+const SKIPPED_ITEMS = new Set([
+  "CommandExecution",
+  "Reasoning",
+  "FileChange",
+  "McpToolCall",
+  "WebSearch",
+  "TodoList",
+  "ImageView",
+  "CustomToolCall",
+  "FunctionCall",
+  "ContextCompaction",
+  "Plan",
+  "Extension",
+  "SubAgentActivity",
+  "CollabAgentToolCall",
+]);
+
+/** Text block types seen in completed items across CLI versions. */
+const ITEM_TEXT_TYPES = ["text", "Text", "input_text", "output_text"];
+
+interface Candidate extends ParsedTurn {
+  shape: "item" | "legacy";
+}
+
+const itemText = (item: Record<string, unknown>): string | undefined =>
+  joinTextBlocks(item.content, ITEM_TEXT_TYPES);
+
+/** Report speech items whose content blocks no longer match (format drift). */
+function noteUntextedItem(
+  diagnostics: ReturnType<typeof emptyDiagnostics>,
+  item: Record<string, unknown>
+): void {
+  const blocks = Array.isArray(item.content) ? item.content : [];
+  const first = blocks.find(isRecord);
+  noteUnknownKind(
+    diagnostics,
+    `${typeof item.type === "string" ? item.type : "unknown"}/content:${typeof first?.type === "string" ? first.type : "none"}`
+  );
+}
+
+export async function parseCodexRollout(
+  path: string
+): Promise<ParseUnitResult> {
+  const diagnostics = emptyDiagnostics();
+  const candidates: Candidate[] = [];
+  let meta: Record<string, unknown> | undefined;
+  let historyStart: number | undefined;
+  let cwd: string | undefined;
+  let agentInstructionThread = false;
+  let programmaticEntry = false;
+  let copiedParentMeta = false;
+
+  for await (const { lineNumber, record } of readJsonlRecords(
+    path,
+    diagnostics
+  )) {
+    const ordinal =
+      typeof record.ordinal === "number" ? record.ordinal : lineNumber - 1;
+    const type = record.type;
+    const payload = isRecord(record.payload) ? record.payload : {};
+
+    if (type === "session_meta") {
+      if (!meta) {
+        meta = payload;
+        cwd = stringField(payload.cwd);
+        const start = payload.subagent_history_start_ordinal;
+        if (typeof start === "number" && start > 0) historyStart = start;
+        const source = payload.source;
+        const spawnParent =
+          isRecord(source) &&
+          isRecord(source.subagent) &&
+          isRecord(source.subagent.thread_spawn)
+            ? stringField(source.subagent.thread_spawn.parent_thread_id)
+            : undefined;
+        agentInstructionThread =
+          payload.thread_source === "subagent" ||
+          Boolean(stringField(payload.parent_thread_id) ?? spawnParent);
+        // `codex exec` prompts are issued by a program or script, which may
+        // be another agent; they are not attributed to a person.
+        programmaticEntry = payload.source === "exec";
+      } else {
+        diagnostics.copiedHistorySkipped += 1;
+        copiedParentMeta = true;
+      }
+      continue;
+    }
+
+    if (historyStart !== undefined && ordinal < historyStart) {
+      diagnostics.copiedHistorySkipped += 1;
+      continue;
+    }
+
+    if (type === "turn_context") {
+      cwd = stringField(payload.cwd) ?? cwd;
+      continue;
+    }
+    if (typeof type === "string" && SKIPPED_TOP_LEVEL.has(type)) continue;
+    if (type !== "event_msg") {
+      noteUnknownKind(diagnostics, type);
+      continue;
+    }
+
+    const eventType = payload.type;
+    const timestamp = normalizeTimestamp(record.timestamp);
+    const locator = `line:${lineNumber}`;
+    if (eventType === "item_completed") {
+      const item = isRecord(payload.item) ? payload.item : {};
+      const itemType = item.type;
+      if (itemType !== "UserMessage" && itemType !== "AgentMessage") {
+        if (typeof itemType !== "string" || !SKIPPED_ITEMS.has(itemType)) {
+          noteUnknownKind(diagnostics, `item_completed/${String(itemType)}`);
+        }
+        continue;
+      }
+      const text = itemText(item);
+      if (text === undefined) {
+        noteUntextedItem(diagnostics, item);
+        continue;
+      }
+      candidates.push({
+        shape: "item",
+        turnId: stringField(item.id) ?? `ordinal:${ordinal}`,
+        role: itemType === "UserMessage" ? "human" : "assistant",
+        text,
+        timestamp,
+        locator,
+        cwd,
+      });
+      continue;
+    }
+    if (eventType === "user_message" || eventType === "agent_message") {
+      const text = stringField(payload.message);
+      if (text === undefined) continue;
+      candidates.push({
+        shape: "legacy",
+        turnId: `ordinal:${ordinal}`,
+        role: eventType === "user_message" ? "human" : "assistant",
+        text,
+        timestamp,
+        locator,
+        cwd,
+      });
+      continue;
+    }
+    if (typeof eventType !== "string" || !SKIPPED_EVENTS.has(eventType)) {
+      noteUnknownKind(diagnostics, `event_msg/${String(eventType)}`);
+    }
+  }
+
+  // A fork carries copied parent history. Without the recorded start
+  // ordinal its boundary is unknown: archive nothing rather than duplicate
+  // the parent, and keep the unit incomplete as format drift.
+  const forkBoundaryUnknown =
+    meta !== undefined &&
+    historyStart === undefined &&
+    (copiedParentMeta || stringField(meta.forked_from_id) !== undefined);
+  if (forkBoundaryUnknown)
+    noteUnknownKind(diagnostics, "fork_without_history_start");
+  if (!meta || forkBoundaryUnknown) {
+    return {
+      threads: [],
+      diagnostics,
+      complete: !diagnostics.truncatedTail && !forkBoundaryUnknown,
+      parser: CODEX_PARSER,
+    };
+  }
+
+  // A file never mixes shapes in practice; if it did, the item shape wins so
+  // the same speech is not archived twice.
+  const hasItemShape = candidates.some((turn) => turn.shape === "item");
+  const turns: ParsedTurn[] = [];
+  for (const candidate of candidates) {
+    if (hasItemShape && candidate.shape === "legacy") continue;
+    const { shape: _shape, ...turn } = candidate;
+    if (
+      turn.role === "human" &&
+      (agentInstructionThread || programmaticEntry)
+    ) {
+      diagnostics.injectedSkipped += 1;
+      continue;
+    }
+    if (!pushTurn(turns, turn, diagnostics)) break;
+  }
+
+  const threadId = stringField(meta.id) ?? "unknown";
+  const parentThreadId =
+    stringField(meta.parent_thread_id) ?? stringField(meta.forked_from_id);
+  let kind: SessionThreadKind = "main";
+  if (agentInstructionThread) kind = "subagent";
+  else if (stringField(meta.forked_from_id)) kind = "fork";
+  if (kind === "main" && !programmaticEntry) {
+    diagnostics.humanTurnsMissing = missingHumanTurns(turns);
+  }
+  diagnostics.formatVersion = stringField(meta.cli_version);
+
+  const thread: ParsedThread = {
+    harness: "codex",
+    threadId,
+    sessionId: stringField(meta.session_id) ?? threadId,
+    parentThreadId,
+    kind,
+    cwd: stringField(meta.cwd),
+    turns,
+  };
+  return {
+    threads: [thread],
+    diagnostics,
+    complete: !diagnostics.truncatedTail && !diagnostics.humanTurnsMissing,
+    parser: CODEX_PARSER,
+  };
+}

package/src/sessions/parsers/hermes.ts

@@ -0,0 +1,248 @@
+/**
+ * Hermes `state.db` parser.
+ *
+ * Built from the Hermes v0.19 schema (`SCHEMA_VERSION = 22`); no populated
+ * store was available locally, so fixtures are synthetic.
+ *
+ * - `sessions(id, source, parent_session_id, started_at, cwd, model_config,
+ *   end_reason, ...)` and `messages(id, session_id, role, content,
+ *   timestamp, active, compacted, ...)`.
+ * - Every session is one thread. `parent_session_id` is overloaded: a
+ *   delegated subagent (`model_config.$._delegate_from`, or a child that is
+ *   neither a branch nor a compression continuation) receives the parent's
+ *   task as its `role=user` message, so its user messages are not human.
+ * - In-place compaction soft-archives the original rows (`active=0,
+ *   compacted=1`) and inserts a summary plus copied tail rows. Original rows
+ *   are archived; inserted copies of an archived row are skipped, and
+ *   compaction summaries are recognised by their fixed prefix. Rewound rows
+ *   (`active=0, compacted=0`) were retracted and are skipped. Continuation
+ *   sessions skip rows copied from the parent the same way.
+ * - Tool, system and reasoning content are excluded.
+ *
+ * @module src/sessions/parsers/hermes
+ */
+
+import type { Database } from "bun:sqlite";
+
+import {
+  emptyDiagnostics,
+  normalizeTimestamp,
+  type ParsedThread,
+  type ParsedTurn,
+  type ParseUnitResult,
+  SESSION_LIMITS,
+  type SessionThreadKind,
+} from "../types";
+import {
+  copiedPrefixLength,
+  missingHumanTurns,
+  hasTables,
+  pushTurn,
+  tableColumns,
+  withReadOnlySnapshot,
+} from "./shared";
+
+export const HERMES_PARSER = "hermes/1";
+
+const SUMMARY_PREFIXES = ["[CONTEXT COMPACTION", "[CONTEXT SUMMARY]:"];
+
+interface SessionRow {
+  id: string;
+  parent_session_id: string | null;
+  started_at: number | null;
+  cwd: string | null;
+  model_config: string | null;
+  end_reason: string | null;
+  parent_end_reason: string | null;
+  parent_ended_at: number | null;
+}
+
+interface MessageRow {
+  id: number;
+  role: string;
+  content: string | null;
+  timestamp: number | null;
+  active: number | null;
+  compacted: number | null;
+}
+
+export function isHermesDatabase(db: Database): boolean {
+  return (
+    hasTables(db, ["sessions", "messages"]) &&
+    tableColumns(db, "messages").has("session_id")
+  );
+}
+
+function configFlag(raw: string | null, key: string): boolean {
+  if (!raw) return false;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return Boolean(
+      parsed &&
+      typeof parsed === "object" &&
+      (parsed as Record<string, unknown>)[key]
+    );
+  } catch {
+    return false;
+  }
+}
+
+function classifyChild(row: SessionRow): SessionThreadKind {
+  if (!row.parent_session_id) return "main";
+  if (configFlag(row.model_config, "_delegate_from")) return "subagent";
+  if (configFlag(row.model_config, "_branched_from")) return "fork";
+  if (row.parent_end_reason === "compression") return "continuation";
+  if (
+    row.parent_end_reason === "branched" &&
+    (row.started_at ?? 0) >= (row.parent_ended_at ?? 0)
+  ) {
+    return "fork";
+  }
+  return "subagent";
+}
+
+const contentKey = (role: string, content: string): string =>
+  `${role}\0${content}`;
+
+const isSummary = (content: string): boolean => {
+  const trimmed = content.trimStart();
+  return SUMMARY_PREFIXES.some((prefix) => trimmed.startsWith(prefix));
+};
+
+/**
+ * Rows a harness copied from earlier history: the contiguous block right
+ * after each in-place compaction point that repeats the tail of the
+ * compacted originals, and the block at a continuation's start that repeats
+ * the tail of its parent. A later genuine repeat ("yes") is kept.
+ */
+function copiedRowIds(
+  rows: readonly MessageRow[],
+  parentSpeech: readonly string[]
+): Set<number> {
+  const copied = new Set<number>();
+  const skipBlock = (startIndex: number, source: readonly string[]): void => {
+    // Rewound rows and summaries are dropped anyway; they do not break a block.
+    const candidates: MessageRow[] = [];
+    for (let cursor = startIndex; cursor < rows.length; cursor += 1) {
+      const row = rows[cursor]!;
+      if (row.compacted === 1) break;
+      if (row.active === 0 || isSummary(row.content ?? "")) continue;
+      candidates.push(row);
+    }
+    const length = copiedPrefixLength(
+      candidates.map((row) => contentKey(row.role, row.content ?? "")),
+      source
+    );
+    for (const row of candidates.slice(0, length)) copied.add(row.id);
+  };
+  if (parentSpeech.length > 0) skipBlock(0, parentSpeech);
+  const originals: string[] = [];
+  for (let index = 0; index < rows.length; index += 1) {
+    const row = rows[index]!;
+    if (row.compacted === 1) {
+      originals.push(contentKey(row.role, row.content ?? ""));
+      const next = rows[index + 1];
+      if (next && next.compacted !== 1) skipBlock(index + 1, originals);
+    }
+  }
+  return copied;
+}
+
+export function parseHermesDatabase(path: string): ParseUnitResult {
+  const diagnostics = emptyDiagnostics();
+  const threads = withReadOnlySnapshot(path, (db) => {
+    if (!isHermesDatabase(db)) return [];
+    const sessionColumns = tableColumns(db, "sessions");
+    const messageColumns = tableColumns(db, "messages");
+    const col = (columns: Set<string>, name: string, alias = name) =>
+      columns.has(name) ? `s.${name} AS ${alias}` : `NULL AS ${alias}`;
+    const sessions = db
+      .query<SessionRow, []>(
+        `SELECT s.id AS id, ${col(sessionColumns, "parent_session_id")}, ${col(sessionColumns, "started_at")}, ${col(sessionColumns, "cwd")}, ${col(sessionColumns, "model_config")}, ${col(sessionColumns, "end_reason")},
+           ${sessionColumns.has("parent_session_id") && sessionColumns.has("end_reason") ? "p.end_reason" : "NULL"} AS parent_end_reason,
+           ${sessionColumns.has("parent_session_id") && sessionColumns.has("ended_at") ? "p.ended_at" : "NULL"} AS parent_ended_at
+         FROM sessions s
+         ${sessionColumns.has("parent_session_id") ? "LEFT JOIN sessions p ON p.id = s.parent_session_id" : ""}
+         ORDER BY ${sessionColumns.has("started_at") ? "s.started_at," : ""} s.id`
+      )
+      .all();
+    const pickMessage = (name: string) =>
+      messageColumns.has(name) ? name : `NULL AS ${name}`;
+    // Insertion order (id) keeps a copied block contiguous with its origin.
+    const messageQuery = db.query<MessageRow, [string]>(
+      `SELECT id, role, content, ${pickMessage("timestamp")}, ${pickMessage("active")}, ${pickMessage("compacted")} FROM messages WHERE session_id = ? ORDER BY id`
+    );
+    const speechBySession = new Map<string, string[]>();
+    const result: ParsedThread[] = [];
+    diagnostics.threadsOverLimit = Math.max(
+      0,
+      sessions.length - SESSION_LIMITS.maxThreadsPerUnit
+    );
+    for (const session of sessions.slice(0, SESSION_LIMITS.maxThreadsPerUnit)) {
+      const kind = classifyChild(session);
+      const rows = messageQuery
+        .all(session.id)
+        .filter(
+          (row) =>
+            (row.role === "user" || row.role === "assistant") &&
+            (row.content ?? "").trim() !== ""
+        );
+      const copied = copiedRowIds(
+        rows,
+        kind === "continuation" && session.parent_session_id
+          ? (speechBySession.get(session.parent_session_id) ?? [])
+          : []
+      );
+      diagnostics.copiedHistorySkipped += copied.size;
+      const speech: string[] = [];
+      const turns: ParsedTurn[] = [];
+      for (const row of rows) {
+        const content = row.content ?? "";
+        const rewound = row.active === 0 && row.compacted !== 1;
+        if (rewound || copied.has(row.id)) continue;
+        if (isSummary(content)) {
+          diagnostics.injectedSkipped += 1;
+          continue;
+        }
+        speech.push(contentKey(row.role, content));
+        if (row.role === "user" && kind === "subagent") {
+          diagnostics.injectedSkipped += 1;
+          continue;
+        }
+        const pushed = pushTurn(
+          turns,
+          {
+            turnId: `message:${row.id}`,
+            role: row.role === "user" ? "human" : "assistant",
+            text: content,
+            timestamp: normalizeTimestamp(row.timestamp),
+            locator: `messages/${row.id}`,
+            cwd: session.cwd ?? undefined,
+          },
+          diagnostics
+        );
+        if (!pushed) break;
+      }
+      speechBySession.set(session.id, speech);
+      if (kind === "main" && missingHumanTurns(turns)) {
+        diagnostics.threadsWithoutHuman += 1;
+      }
+      result.push({
+        harness: "hermes",
+        threadId: session.id,
+        sessionId: session.parent_session_id ?? session.id,
+        parentThreadId: session.parent_session_id ?? undefined,
+        kind,
+        cwd: session.cwd ?? undefined,
+        turns,
+      });
+    }
+    return result;
+  });
+  return {
+    threads,
+    diagnostics,
+    complete: diagnostics.threadsOverLimit === 0,
+    parser: HERMES_PARSER,
+  };
+}