@agentex/agent 0.0.27 → 0.0.29

package/src/providers/codex/attach.ts

@@ -16,6 +16,7 @@ import {
 import { getRuntimeHomeEnvVar } from "../../utils/runtime-homes.js";
 import { codexSessionCodec } from "./codec.js";
 import {
+  type CodexTranscriptLine,
   getCodexTranscriptPath,
   peekCodexTranscript,
   readCodexCwd,
@@ -37,17 +38,61 @@ const EMPTY: AsyncIterable<CatchUpYield> = {
   },
 };
 
+function isTurnBoundary(line: CodexTranscriptLine, sessionId: string): boolean {
+  const payloadType = typeof line.payload?.["type"] === "string" ? line.payload["type"] : null;
+
+  // These raw records start a turn but intentionally normalize to no replay
+  // event. They must still supersede an earlier task_complete when deciding
+  // whether the latest persisted turn was interrupted.
+  if (line.type === "event_msg" && (payloadType === "task_started" || payloadType === "user_message")) {
+    return true;
+  }
+  if (line.type === "response_item" && payloadType === "message" && line.payload?.["role"] === "user") {
+    return true;
+  }
+  if (line.type === "message" && line.raw["role"] === "user") return true;
+
+  return codexLineToStreamEvents(line, { sessionId }).some((event) => ![
+    "system",
+    "permission_mode",
+    "rate_limit",
+    "goal_status",
+    "unknown",
+  ].includes(event.type));
+}
+
+async function latestTurnBoundary(
+  filePath: string,
+  sessionId: string,
+): Promise<CodexTranscriptLine | null> {
+  const { lastEvent } = await peekCodexTranscript(filePath, {
+    accept: (line) => isTurnBoundary(line, sessionId),
+  });
+  if (lastEvent) return lastEvent;
+  let latest: CodexTranscriptLine | null = null;
+  for await (const { event } of readCodexTranscript({ filePath })) {
+    if (isTurnBoundary(event, sessionId)) latest = event;
+  }
+  return latest;
+}
+
 /**
  * Read-only reattachment to a durable Codex session. Same skeleton as Claude,
  * with two deltas: classify via the rollout's last line, and replay through
- * `codexLineToStreamEvents` (Codex has no wire ids, so `eventId` is always null
- * — hosts gate replay dedup on their own running flag, per spec §9.7).
+ * `codexLineToStreamEvents`. File-backed transcript lines carry deterministic
+ * synthetic event ids so replay can be deduplicated across process restarts.
  */
 export async function attachCodexSession(
   record: SessionRecord,
   opts?: AttachOptions,
 ): Promise<SessionAttachment> {
   assertSessionRecord(record);
+  if (record.providerType !== "codex") {
+    throw new MalformedSessionRecordError(
+      `codex attach requires providerType "codex"; got ${JSON.stringify(record.providerType)}`,
+      "providerType",
+    );
+  }
 
   // 1. Normalize params through the codec.
   const params = codexSessionCodec.deserialize(record.params);
@@ -85,9 +130,9 @@ export async function attachCodexSession(
   // 3. Classify how the last persisted turn ended.
   let lastTurn: LastTurnStatus = "unknown";
   if (transcript) {
-    const { lastEvent } = await peekCodexTranscript(transcript.filePath);
+    const lastEvent = await latestTurnBoundary(transcript.filePath, sessionId);
     if (lastEvent === null) lastTurn = "unknown";
-    else if (lastEvent.type === "event_msg" && lastEvent.payload?.["type"] === "task_complete")
+    else if (codexLineToStreamEvents(lastEvent, { sessionId }).some((event) => event.type === "result"))
       lastTurn = "completed";
     else lastTurn = "interrupted";
   }
@@ -97,7 +142,7 @@ export async function attachCodexSession(
     transcript,
     lastTurn,
     // 4. Replay: map each rollout line through the normalizer; one yield per
-    //    produced event, all sharing the line's offset, eventId always null.
+    //    produced event, all sharing the line's offset and source event id.
     catchUp(catchOpts?: CatchUpOptions): AsyncIterable<CatchUpYield> {
       if (!transcript) return EMPTY;
       const filePath = transcript.filePath;
@@ -109,7 +154,7 @@ export async function attachCodexSession(
             ...(catchOpts?.fromOffset !== undefined ? { fromOffset: catchOpts.fromOffset } : {}),
           })) {
             for (const event of codexLineToStreamEvents(line, { sessionId: sid })) {
-              yield { event, offset, eventId: null };
+              yield { event, offset, eventId: event.eventId };
             }
           }
         },
@@ -117,7 +162,7 @@ export async function attachCodexSession(
     },
     // 5. Continue live — exactly `createSession` with the record's params.
     resume(ctx?: SessionContext) {
-      return createCodexSession({ ...ctx, sessionParams: params });
+      return createCodexSession({ ...ctx, cwd: ctx?.cwd ?? cwd ?? undefined, sessionParams: params });
     },
   };
 }

package/src/providers/codex/history.ts

@@ -0,0 +1,399 @@
+import * as path from "node:path";
+import { readdir } from "node:fs/promises";
+
+import type { BaseStreamEventFields, StreamEvent } from "../../types.js";
+import type {
+  LocalHistoryDiscoverOptions,
+  LocalHistoryOps,
+  LocalHistoryProbeOptions,
+  LocalHistorySession,
+  LocalHistoryYield,
+} from "../../history/types.js";
+import {
+  ROLLOUT_UUID_RE,
+  asRecord,
+  asString,
+  cleanTitle,
+  isDirectory,
+  isoDate,
+  listJsonlFiles,
+  meaningfulHumanText,
+  readJsonlRecords,
+  recentEligible,
+  sourceFingerprint,
+  textFromContent,
+} from "../../history/fs.js";
+import { codexLineToStreamEvents } from "./transcript-normalize.js";
+import { parseCodexLine, resolveCodexHome, type CodexTranscriptLine } from "./transcript.js";
+
+const MAX_DISCOVERY_SCAN_BYTES = 4 * 1024 * 1024;
+const DEFAULT_PROBE_LIMIT = 100;
+const DISCOVERY_CONCURRENCY = 16;
+
+function codexHome(options?: { env?: Record<string, string> }): string {
+  return resolveCodexHome(options?.env?.["CODEX_HOME"]);
+}
+
+async function listCodexSessionFiles(
+  home: string,
+  options: { includeArchived: boolean; limit?: number },
+): Promise<string[]> {
+  const cap = Math.max(1, options.limit ?? Number.MAX_SAFE_INTEGER);
+  const active = await listJsonlFiles(path.join(home, "sessions"), {
+    maxDepth: 5,
+    limit: cap,
+    accept: (name) => ROLLOUT_UUID_RE.test(name),
+  });
+  if (!options.includeArchived || active.length >= cap) return active;
+  const archived = await listJsonlFiles(path.join(home, "archived_sessions"), {
+    maxDepth: 2,
+    limit: cap - active.length,
+    accept: (name) => ROLLOUT_UUID_RE.test(name),
+  });
+  return [...active, ...archived];
+}
+
+function codexUserText(line: CodexTranscriptLine): string | null {
+  if (line.type === "event_msg" && line.payload?.["type"] === "user_message") {
+    return meaningfulHumanText(asString(line.payload["message"]));
+  }
+  // Older unwrapped rollouts have no event_msg mirror.
+  if (line.type === "message" && line.raw["role"] === "user") {
+    return meaningfulHumanText(textFromContent(
+      line.raw["content"],
+      new Set(["text", "input_text"]),
+    ));
+  }
+  return null;
+}
+
+function isSubagentMeta(payload: Record<string, unknown>): boolean {
+  if (asString(payload["parent_thread_id"])) return true;
+  if (payload["thread_source"] === "subagent") return true;
+  const source = asRecord(payload["source"]);
+  return !!source && source["subagent"] !== undefined;
+}
+
+function legacyCwd(record: Record<string, unknown>): string | null {
+  if (record["type"] !== "message" || record["role"] !== "user") return null;
+  const text = textFromContent(record["content"], new Set(["text", "input_text"]));
+  const xml = text?.match(/<cwd>([^<]+)<\/cwd>/)?.[1];
+  const plain = text?.match(/Current working directory:\s*([^\n\r]+)/)?.[1];
+  const candidate = (xml ?? plain)?.trim();
+  return candidate && path.isAbsolute(candidate) ? candidate : null;
+}
+
+async function loadSessionIndexTitles(home: string): Promise<Map<string, string>> {
+  const titles = new Map<string, string>();
+  try {
+    for await (const line of readJsonlRecords(path.join(home, "session_index.jsonl"))) {
+      const id = asString(line.raw["id"]);
+      const title = cleanTitle(asString(line.raw["thread_name"]));
+      if (id && title) titles.set(id, title);
+    }
+  } catch {
+    // The index is optional and absent on older Codex versions.
+  }
+  return titles;
+}
+
+interface SqliteDatabase {
+  prepare(sql: string): { all(): unknown[] };
+  close(): void;
+}
+
+async function stateDatabasePaths(home: string): Promise<string[]> {
+  const paths: string[] = [];
+  for (const dir of [home, path.join(home, "sqlite")]) {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.isFile() && /^state_\d+\.sqlite$/.test(entry.name)) paths.push(path.join(dir, entry.name));
+    }
+  }
+  return paths.sort().reverse();
+}
+
+async function loadSqliteTitles(home: string): Promise<Map<string, string>> {
+  const titles = new Map<string, string>();
+  try {
+    // Keep Node 20 compatibility. node:sqlite is used opportunistically on
+    // runtimes that provide it and is always opened read-only.
+    const moduleName = "node:sqlite";
+    const sqlite = await import(moduleName) as unknown as {
+      DatabaseSync: new (filePath: string, options: { readOnly: boolean }) => SqliteDatabase;
+    };
+    for (const filePath of await stateDatabasePaths(home)) {
+      let database: SqliteDatabase | null = null;
+      try {
+        database = new sqlite.DatabaseSync(filePath, { readOnly: true });
+        for (const value of database.prepare("SELECT id, title FROM threads WHERE title <> ''").all()) {
+          const row = asRecord(value);
+          const id = asString(row?.["id"]);
+          const title = cleanTitle(asString(row?.["title"]));
+          if (id && title && !titles.has(id)) titles.set(id, title);
+        }
+        if (titles.size > 0) break;
+      } catch {
+        // Missing, locked, or schema-incompatible indexes are non-fatal.
+      } finally {
+        database?.close();
+      }
+    }
+  } catch {
+    // node:sqlite is unavailable on Node 20.
+  }
+  return titles;
+}
+
+async function loadCodexTitles(home: string): Promise<Map<string, string>> {
+  const index = await loadSessionIndexTitles(home);
+  // session_index is the least invasive and most portable source. SQLite is
+  // a fallback for installations that do not maintain the JSONL index.
+  return index.size > 0 ? index : loadSqliteTitles(home);
+}
+
+async function inspectCodexSession(
+  transcriptPath: string,
+  titles: ReadonlyMap<string, string>,
+  options: LocalHistoryDiscoverOptions,
+): Promise<LocalHistorySession | null> {
+  let meta: Record<string, unknown> | null = null;
+  let legacyMeta: Record<string, unknown> | null = null;
+  let metaTimestamp: string | null = null;
+  let firstPrompt: string | null = null;
+  let fallbackCwd: string | null = null;
+
+  for await (const record of readJsonlRecords(transcriptPath)) {
+    const line = parseCodexLine(record.text);
+    if (!line) continue;
+    if (line.type === "session_meta" && line.payload) {
+      meta ??= line.payload;
+      metaTimestamp ??= line.timestamp;
+    }
+    if (line.type === null && asString(line.raw["id"])) legacyMeta ??= line.raw;
+    firstPrompt ??= codexUserText(line);
+    fallbackCwd ??= legacyCwd(line.raw);
+    if (meta && firstPrompt) break;
+    if (record.nextOffset >= MAX_DISCOVERY_SCAN_BYTES) break;
+  }
+
+  const fileId = path.basename(transcriptPath).match(ROLLOUT_UUID_RE)?.[1] ?? null;
+  const externalSessionId = asString(meta?.["id"])
+    ?? asString(meta?.["session_id"])
+    ?? asString(legacyMeta?.["id"])
+    ?? fileId;
+  if (!externalSessionId) return null;
+  if ((options.mainSessionsOnly ?? true) && meta && isSubagentMeta(meta)) return null;
+
+  const metaCwd = asString(meta?.["cwd"]);
+  const cwd = metaCwd && path.isAbsolute(metaCwd) ? metaCwd : fallbackCwd;
+  if (!cwd || (options.cwd && path.normalize(cwd) !== path.normalize(options.cwd))) return null;
+  const hasUserMessage = firstPrompt !== null;
+  if ((options.requireUserMessage ?? true) && !hasUserMessage) return null;
+
+  const git = asRecord(meta?.["git"]);
+  const source = await sourceFingerprint(transcriptPath);
+  const archiveState = transcriptPath.split(path.sep).includes("archived_sessions")
+    ? "archived" as const
+    : "active" as const;
+  return {
+    version: 1,
+    providerType: "codex",
+    externalSessionId,
+    transcriptPath,
+    cwd,
+    title: titles.get(externalSessionId) ?? cleanTitle(firstPrompt),
+    startedAt: isoDate(meta?.["timestamp"] ?? metaTimestamp ?? legacyMeta?.["timestamp"]),
+    updatedAt: new Date(Number(BigInt(source.modifiedAtNs) / 1_000_000n)).toISOString(),
+    branch: asString(git?.["branch"]) ?? asString(meta?.["git_branch"]),
+    gitOriginUrl: asString(git?.["repository_url"])
+      ?? asString(git?.["origin_url"])
+      ?? asString(meta?.["git_origin_url"]),
+    archiveState,
+    hasUserMessage,
+    source,
+  };
+}
+
+function baseFields(
+  session: LocalHistorySession,
+  line: CodexTranscriptLine,
+  eventId: string,
+): BaseStreamEventFields & { eventId: string } {
+  return {
+    timestamp: isoDate(line.timestamp, session.startedAt ?? new Date(0).toISOString())!,
+    providerType: "codex",
+    sessionId: session.externalSessionId,
+    messageId: null,
+    eventId,
+    turnId: null,
+    parentToolCallId: null,
+    raw: line.raw,
+  };
+}
+
+function legacyCodexEvents(
+  session: LocalHistorySession,
+  line: CodexTranscriptLine,
+  eventId: string,
+): Array<StreamEvent & { eventId: string }> {
+  if (line.payload) return [];
+  const base = baseFields(session, line, eventId);
+  if (line.type === "message" && line.raw["role"] === "assistant") {
+    const text = textFromContent(line.raw["content"], new Set(["text", "output_text"]));
+    return text ? [{ type: "assistant", text, ...base }] : [];
+  }
+  if (line.type === "reasoning") {
+    const text = textFromContent(line.raw["summary"] ?? line.raw["content"], new Set(["text", "summary_text"]));
+    return text ? [{ type: "thinking", text, ...base }] : [];
+  }
+  if (line.type === "function_call") {
+    const toolCallId = asString(line.raw["call_id"]) ?? asString(line.raw["id"]);
+    const name = asString(line.raw["name"]) ?? "function_call";
+    const rawArguments = line.raw["arguments"];
+    let input: Record<string, unknown> | string | null = asString(rawArguments);
+    if (typeof rawArguments === "string") {
+      try {
+        const parsed = JSON.parse(rawArguments);
+        if (asRecord(parsed)) input = parsed as Record<string, unknown>;
+      } catch {
+        // Preserve malformed arguments as their original string.
+      }
+    } else if (asRecord(rawArguments)) {
+      input = rawArguments as Record<string, unknown>;
+    }
+    return [{ type: "tool_call", toolCallId, name, input, ...base }];
+  }
+  if (line.type === "function_call_output") {
+    const output = line.raw["output"];
+    let content = typeof output === "string" ? output : "";
+    if (!content && output !== undefined) {
+      try {
+        content = JSON.stringify(output);
+      } catch {
+        content = "";
+      }
+    }
+    return [{
+      type: "tool_result",
+      toolCallId: asString(line.raw["call_id"]),
+      toolName: null,
+      content,
+      isError: line.raw["is_error"] === true,
+      exitCode: typeof line.raw["exit_code"] === "number" ? line.raw["exit_code"] : null,
+      ...base,
+    }];
+  }
+  return [];
+}
+
+function dedupeCodexSessionFiles(filePaths: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const output: string[] = [];
+  // listCodexSessionFiles returns active files first, so an active copy wins
+  // over a briefly duplicated archive copy before transcript inspection.
+  for (const filePath of filePaths) {
+    const id = path.basename(filePath).match(ROLLOUT_UUID_RE)?.[1] ?? filePath;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    output.push(filePath);
+  }
+  return output;
+}
+
+function normalizedCodexEvents(
+  session: LocalHistorySession,
+  line: CodexTranscriptLine,
+  eventId: string,
+): Array<StreamEvent & { eventId: string }> {
+  const events = line.payload
+    ? codexLineToStreamEvents(line, { sessionId: session.externalSessionId })
+    : legacyCodexEvents(session, line, eventId);
+  return events
+    .filter((event) => !((event.type === "assistant" || event.type === "thinking") && !event.text.trim()))
+    .map((event) => ({
+      ...event,
+      timestamp: isoDate(line.timestamp, event.timestamp)!,
+      providerType: "codex",
+      sessionId: session.externalSessionId,
+      eventId,
+      raw: line.raw,
+    } as StreamEvent & { eventId: string }));
+}
+
+export const codexLocalHistory: LocalHistoryOps = {
+  async probe(options?: LocalHistoryProbeOptions) {
+    const home = codexHome(options);
+    const homeAvailable = await isDirectory(home);
+    const files = homeAvailable
+      ? await listCodexSessionFiles(home, {
+        includeArchived: true,
+        limit: options?.limit ?? DEFAULT_PROBE_LIMIT,
+      })
+      : [];
+    return {
+      providerType: "codex",
+      homeAvailable,
+      historyAvailable: files.length > 0,
+      approximateCount: files.length,
+    };
+  },
+
+  async *discover(options: LocalHistoryDiscoverOptions = {}) {
+    const home = codexHome(options);
+    const [files, titles] = await Promise.all([
+      listCodexSessionFiles(home, { includeArchived: options.includeArchived ?? true }),
+      loadCodexTitles(home),
+    ]);
+    const sessions = await recentEligible(
+      dedupeCodexSessionFiles(files),
+      { limit: options.limit, concurrency: DISCOVERY_CONCURRENCY },
+      async (filePath) => {
+        try {
+          return await inspectCodexSession(filePath, titles, options);
+        } catch {
+          return null;
+        }
+      },
+    );
+    for (const session of sessions) yield session;
+  },
+
+  async *read(session, options = {}): AsyncIterable<LocalHistoryYield> {
+    if (session.providerType !== "codex" || !path.isAbsolute(session.transcriptPath)) {
+      throw new Error("Invalid Codex local history session");
+    }
+    for await (const record of readJsonlRecords(
+      session.transcriptPath,
+      options.fromOffset ?? 0,
+      { rejectChanges: true },
+    )) {
+      const line = parseCodexLine(record.text);
+      if (!line) continue;
+      const eventId = `codex:${session.externalSessionId}:${record.lineStartOffset}`;
+      line.eventId = eventId;
+      const events: LocalHistoryYield["event"][] = [];
+      const userText = codexUserText(line);
+      if (userText) events.push({ type: "user", text: userText, ...baseFields(session, line, eventId) });
+      events.push(...normalizedCodexEvents(session, line, eventId));
+      for (let partIndex = 0; partIndex < events.length; partIndex++) {
+        yield {
+          event: events[partIndex]!,
+          lineStartOffset: record.lineStartOffset,
+          nextOffset: record.nextOffset,
+          partIndex,
+        };
+      }
+    }
+  },
+
+  fingerprint(session, options) {
+    if (session.providerType !== "codex") throw new Error("Invalid Codex local history session");
+    return sourceFingerprint(session.transcriptPath, options?.sha256 ?? false);
+  },
+};

package/src/providers/codex/index.ts

@@ -23,6 +23,8 @@ export const codexProvider: ProviderModule = {
     modes: true,
     goals: codexGoalCapability,
     durableSessions: true,
+    durableHistory: true,
+    localHistory: true,
   },
   // Heavy machinery (execute.ts, session.ts, modes.ts, attach.ts) loads lazily
   // on first use — every ProviderModule method is already async.
@@ -35,6 +37,30 @@ export const codexProvider: ProviderModule = {
   listModes: async (opts) => (await import("./modes.js")).listCodexModes(opts),
   attachSession: async (record, opts) =>
     (await import("./attach.js")).attachCodexSession(record, opts),
+  attachHistory: async (record, opts) => {
+    const [{ attachCodexSession }, { historyFromSessionAttachment }] = await Promise.all([
+      import("./attach.js"),
+      import("../../sessions/history.js"),
+    ]);
+    return historyFromSessionAttachment("codex", await attachCodexSession(record, opts));
+  },
+  localHistory: {
+    probe: (options) => import("./history.js").then((module) => module.codexLocalHistory.probe(options)),
+    discover: (options) => ({
+      async *[Symbol.asyncIterator]() {
+        const module = await import("./history.js");
+        yield* module.codexLocalHistory.discover(options);
+      },
+    }),
+    read: (session, options) => ({
+      async *[Symbol.asyncIterator]() {
+        const module = await import("./history.js");
+        yield* module.codexLocalHistory.read(session, options);
+      },
+    }),
+    fingerprint: (session, options) => import("./history.js")
+      .then((module) => module.codexLocalHistory.fingerprint(session, options)),
+  },
 };
 
 export {

package/src/providers/codex/transcript-normalize.ts

@@ -20,8 +20,9 @@ import type { CodexTranscriptLine } from "./transcript.js";
  *
  * The on-disk vocabulary is Codex-internal and version-shifting, so every field
  * is read defensively and a weird line NEVER throws — it returns `[]`. Codex
- * emits no per-line wire id, so `eventId`/`turnId` are null (hosts gate replay
- * dedup on their own "not currently running" flag; see spec §9.7).
+ * emits no native per-line wire id. File readers attach a deterministic
+ * synthetic `line.eventId`, which this normalizer preserves. Standalone line
+ * parsing still produces a null event id.
  */
 export function codexLineToStreamEvents(
   line: CodexTranscriptLine,
@@ -47,7 +48,7 @@ function mapLine(line: CodexTranscriptLine, sessionId: string | null): StreamEve
     providerType: "codex",
     sessionId,
     messageId: null,
-    eventId: null,
+    eventId: line.eventId,
     turnId: null,
     parentToolCallId: null,
     raw: line.raw,

package/src/providers/codex/transcript.ts

@@ -415,7 +415,10 @@ export interface CodexPeekResult {
  * Cheap drift-check: reads up to {@link PEEK_TAIL_BYTES} from the tail,
  * walks back to the last parseable line, returns it plus the file size.
  */
-export async function peekCodexTranscript(filePath: string): Promise<CodexPeekResult> {
+export async function peekCodexTranscript(
+  filePath: string,
+  options: { accept?: (event: CodexTranscriptLine) => boolean } = {},
+): Promise<CodexPeekResult> {
   let size: number;
   try {
     const s = await stat(filePath);
@@ -452,6 +455,7 @@ export async function peekCodexTranscript(filePath: string): Promise<CodexPeekRe
       if (!trimmed) continue;
       const parsed = parseCodexLine(trimmed);
       if (!parsed) continue;
+      if (options.accept && !options.accept(parsed)) continue;
       return { lastEvent: parsed, size };
     }