@agentex/agent 0.0.10 → 0.0.11

package/dist/providers/claude/transcript.js

@@ -0,0 +1,434 @@
+/**
+ * Claude Code writes a durable JSONL transcript for every session under
+ * `<claudeHome>/projects/<sanitized-cwd>/<sessionId>.jsonl`. The on-disk lines
+ * use the same JSON shape Claude streams over stdout, so {@link parseStreamLine}
+ * handles them unchanged. These helpers cover the two parts the consuming
+ * host can't easily derive itself: where the file lives, and how to stream
+ * it back as `StreamEvent`s.
+ *
+ * Encoding rules are verified against Claude Code's open-source source
+ * (`sessionStoragePortable.ts:sanitizePath`):
+ *   1. Replace EVERY non-alphanumeric character with `-`
+ *      (not just `/` and `.` — also `_`, space, `:`, etc.)
+ *   2. If the sanitized name exceeds {@link MAX_SANITIZED_LENGTH} (200),
+ *      truncate and append a hash suffix
+ *   3. Canonicalize the cwd via `realpath` + NFC first so symlinks
+ *      (e.g. macOS `/tmp` → `/private/tmp`) resolve to the same project dir
+ *
+ * The CLI does not expose a flag for the transcript path; the only source of
+ * truth is the open-source `sessionStoragePortable.ts`.
+ */
+import { createReadStream } from "node:fs";
+import { readdir, realpath, stat, open as fsOpen } from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as readline from "node:readline";
+import { getDefaultRuntimeHome, getRuntimeHomeEnvVar } from "../../utils/runtime-homes.js";
+import { parseStreamLine } from "./parse.js";
+/**
+ * Maximum length of a sanitized project-directory name before truncation +
+ * hash suffix kicks in. Mirrors Claude Code's `MAX_SANITIZED_LENGTH`. Most
+ * filesystems cap individual filename segments at 255 bytes; the gap leaves
+ * room for the hash suffix.
+ */
+export const MAX_SANITIZED_LENGTH = 200;
+/** Bytes scanned from the tail of the file in {@link peekClaudeTranscript}. */
+const PEEK_TAIL_BYTES = 16 * 1024;
+/** Filter rule: skip these Claude wrapper-event types when streaming a transcript. */
+const SKIP_ON_DISK_TYPES = new Set([
+    // Internal enqueue/dequeue bookkeeping that Claude writes for its own
+    // scheduler; the on-disk file is the only place these surface. They carry
+    // no user-visible content and shouldn't be replayed.
+    "queue-operation",
+]);
+/**
+ * djb2 string hash returning an unsigned base-36 string. Deterministic across
+ * runtimes — Claude Code's source uses `Bun.hash` under Bun (a different
+ * algorithm), so for cwd paths longer than {@link MAX_SANITIZED_LENGTH} the
+ * exact directory name will differ between Bun and Node. {@link getClaudeTranscriptPath}
+ * compensates with a prefix-match fallback when the exact path is missing.
+ */
+function djb2Base36(input) {
+    let hash = 0;
+    for (let i = 0; i < input.length; i++) {
+        hash = ((hash << 5) - hash + input.charCodeAt(i)) | 0;
+    }
+    return Math.abs(hash).toString(36);
+}
+/**
+ * Encode an absolute path into Claude's project-directory name. Mirrors
+ * `sanitizePath` in Claude Code's open-source `sessionStoragePortable.ts`.
+ *
+ * @example
+ * sanitizeProjectPath("/Users/foo/bar")     // → "-Users-foo-bar"
+ * sanitizeProjectPath("/Users/foo/.config") // → "-Users-foo--config"
+ * sanitizeProjectPath("/Users/foo/my_app")  // → "-Users-foo-my-app"
+ *                                           //   (underscore is non-alphanumeric)
+ */
+export function sanitizeProjectPath(name) {
+    const sanitized = name.replace(/[^a-zA-Z0-9]/g, "-");
+    if (sanitized.length <= MAX_SANITIZED_LENGTH)
+        return sanitized;
+    return `${sanitized.slice(0, MAX_SANITIZED_LENGTH)}-${djb2Base36(name)}`;
+}
+/**
+ * Resolve Claude's config home directory. Mirrors `getClaudeConfigHomeDir` in
+ * Claude Code, including the NFC normalization needed to keep paths consistent
+ * with macOS HFS+/APFS Unicode handling.
+ */
+export function resolveClaudeHome(override) {
+    if (override)
+        return override.normalize("NFC");
+    const envVar = getRuntimeHomeEnvVar("claude");
+    const fromEnv = envVar ? process.env[envVar] : undefined;
+    const base = fromEnv ?? getDefaultRuntimeHome("claude") ?? path.join(os.homedir(), ".claude");
+    return base.normalize("NFC");
+}
+/**
+ * Canonicalize a cwd path to match what Claude Code stores. `realpath`
+ * resolves symlinks (`/tmp` → `/private/tmp` on macOS) and NFC unifies the
+ * two Unicode normalizations macOS accepts for filenames with accents.
+ *
+ * Returns the NFC-normalized input on `realpath` failure (e.g., directory
+ * was deleted after the session ran), since the directory name on disk was
+ * computed against whatever the cwd was at session start.
+ */
+export async function canonicalizeCwd(cwd) {
+    try {
+        return (await realpath(cwd)).normalize("NFC");
+    }
+    catch {
+        return cwd.normalize("NFC");
+    }
+}
+/**
+ * Compute the on-disk JSONL path for a Claude session. Performs `realpath`
+ * canonicalization on the cwd and applies the same encoding rules Claude
+ * Code uses internally.
+ *
+ * For cwd paths sanitized longer than {@link MAX_SANITIZED_LENGTH}, the
+ * deterministic djb2 hash suffix may not match what Claude wrote (Claude Code
+ * uses `Bun.hash` under Bun). If the exact path doesn't exist and the
+ * sanitized name was truncated, this function falls back to a prefix scan
+ * under `<claudeHome>/projects/` and returns the first matching directory.
+ */
+export async function getClaudeTranscriptPath(opts) {
+    if (!opts.sessionId)
+        throw new Error("getClaudeTranscriptPath: sessionId is required");
+    if (!opts.cwd)
+        throw new Error("getClaudeTranscriptPath: cwd is required");
+    const claudeHome = resolveClaudeHome(opts.claudeHome);
+    const canonicalCwd = await canonicalizeCwd(opts.cwd);
+    const sanitized = sanitizeProjectPath(canonicalCwd);
+    const fileName = `${opts.sessionId}.jsonl`;
+    const projectsRoot = path.join(claudeHome, "projects");
+    // Primary: exact match. Covers the common case (short paths, same hash algorithm).
+    const exactPath = path.join(projectsRoot, sanitized, fileName);
+    if (await pathExists(exactPath)) {
+        return { filePath: exactPath, projectDir: sanitized, canonicalCwd, claudeHome };
+    }
+    // Long-path fallback: Claude under Bun uses `Bun.hash` for the suffix;
+    // we use djb2. The truncated prefix is identical, so prefix-scan to find
+    // the actual on-disk directory. Mirrors open-source `findProjectDir`.
+    if (sanitized.length > MAX_SANITIZED_LENGTH) {
+        const prefix = sanitized.slice(0, MAX_SANITIZED_LENGTH);
+        try {
+            const entries = await readdir(projectsRoot, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                if (!entry.name.startsWith(`${prefix}-`))
+                    continue;
+                const candidate = path.join(projectsRoot, entry.name, fileName);
+                if (await pathExists(candidate)) {
+                    return { filePath: candidate, projectDir: entry.name, canonicalCwd, claudeHome };
+                }
+            }
+        }
+        catch {
+            // projectsRoot missing or unreadable — fall through to deterministic path.
+        }
+    }
+    return { filePath: exactPath, projectDir: sanitized, canonicalCwd, claudeHome };
+}
+/**
+ * Scan `<claudeHome>/projects/*` looking for `<sessionId>.jsonl`. Use this
+ * when you have a session ID but don't know which cwd Claude was launched
+ * in — typical for resume-by-id flows.
+ *
+ * Session IDs are unique across project directories, so the first match is
+ * authoritative. The original cwd is recovered from the transcript's first
+ * `system.init` event (Claude writes one at session start carrying `cwd`).
+ *
+ * Returns `null` if no project directory contains the session file.
+ */
+export async function findClaudeTranscriptBySessionId(opts) {
+    if (!opts.sessionId) {
+        throw new Error("findClaudeTranscriptBySessionId: sessionId is required");
+    }
+    const claudeHome = resolveClaudeHome(opts.claudeHome);
+    const projectsRoot = path.join(claudeHome, "projects");
+    const fileName = `${opts.sessionId}.jsonl`;
+    let entries;
+    try {
+        entries = await readdir(projectsRoot, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const candidate = path.join(projectsRoot, entry.name, fileName);
+        if (!(await pathExists(candidate)))
+            continue;
+        const cwd = await readCwdFromTranscript(candidate);
+        return { filePath: candidate, projectDir: entry.name, cwd };
+    }
+    return null;
+}
+/**
+ * Read the cwd field from the first transcript line that carries one.
+ *
+ * Claude's on-disk format does NOT emit a `system.init` event the way the
+ * stream wire format does. Instead, every event line (`user`, `assistant`,
+ * etc.) carries its own `cwd`, `sessionId`, `gitBranch`, `version` envelope.
+ * Read the first few lines raw, extract the first `cwd` we find.
+ *
+ * Returns `null` if no line in the first ~50 carries a `cwd` field.
+ */
+async function readCwdFromTranscript(filePath) {
+    const fh = await fsOpen(filePath, "r").catch(() => null);
+    if (!fh)
+        return null;
+    try {
+        const stream = fh.createReadStream({ encoding: "utf8", autoClose: false });
+        const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+        let count = 0;
+        try {
+            for await (const raw of rl) {
+                if (++count > 50)
+                    break;
+                const trimmed = raw.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    const obj = JSON.parse(trimmed);
+                    // Outer envelope: every Claude line carries `cwd` at the top level.
+                    if (typeof obj["cwd"] === "string" && obj["cwd"]) {
+                        return obj["cwd"];
+                    }
+                    // Forward-compat: streaming-style init events also have cwd.
+                    if (obj["type"] === "system" &&
+                        obj["subtype"] === "init" &&
+                        typeof obj["cwd"] === "string") {
+                        return obj["cwd"];
+                    }
+                }
+                catch {
+                    // skip malformed
+                }
+            }
+        }
+        finally {
+            rl.close();
+            stream.destroy();
+        }
+    }
+    finally {
+        await fh.close();
+    }
+    return null;
+}
+async function pathExists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Stream-read a Claude transcript JSONL, yielding parsed `StreamEvent`s.
+ *
+ * Behavior:
+ * - Returns an empty async iterable if the file doesn't exist (no throw).
+ * - Skips wrapper types in {@link SKIP_ON_DISK_TYPES} (currently `queue-operation`).
+ * - Skips lines that fail to parse as JSON (`parseStreamLine` returns []).
+ * - Seeks into the file with `createReadStream` so multi-megabyte transcripts
+ *   don't load fully into memory.
+ *
+ * The yielded `offset` lets the caller checkpoint after each event and
+ * resume from that offset on the next call.
+ */
+export async function* readClaudeTranscript(opts) {
+    const { filePath, fromOffset = 0, sinceEventId } = opts;
+    // Fast-path: file missing → empty iterable, no throw.
+    if (!(await pathExists(filePath)))
+        return;
+    const stream = createReadStream(filePath, { start: fromOffset, encoding: undefined });
+    // Suppress stray ENOENT (file deleted between stat and open) — readline
+    // raises the same condition through its own iterator, which we catch below.
+    stream.on("error", () => { });
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    let pos = fromOffset;
+    let stillSkippingPastSince = !!sinceEventId;
+    try {
+        for await (const line of rl) {
+            // readline strips the trailing `\n` (and the `\r` from `\r\n`). Claude
+            // writes Unix line endings, so we account for `\n` only. A `\r\n` file
+            // would yield offsets 1 byte short per line — accepted as a corner
+            // case; resume from such an offset would skip one stray `\r`.
+            const lineByteLen = Buffer.byteLength(line, "utf8");
+            pos += lineByteLen + 1;
+            if (!line)
+                continue;
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            if (looksLikeSkippedType(trimmed))
+                continue;
+            const events = parseStreamLine(trimmed);
+            if (events.length === 0)
+                continue;
+            if (stillSkippingPastSince) {
+                if (events.some((e) => e.eventId === sinceEventId)) {
+                    // Found the boundary line — skip ALL events on it and resume from the next.
+                    stillSkippingPastSince = false;
+                }
+                continue;
+            }
+            for (const event of events) {
+                yield { event, offset: pos };
+            }
+        }
+    }
+    catch (err) {
+        // Swallow ENOENT (race: file deleted after the existence check); rethrow others.
+        const e = err;
+        if (e?.code !== "ENOENT")
+            throw err;
+    }
+    finally {
+        rl.close();
+        stream.destroy();
+    }
+}
+/**
+ * Quick pre-parse check for wrapper types we want to skip. Cheaper than a
+ * full `JSON.parse`; falls through to the parser if uncertain.
+ */
+function looksLikeSkippedType(line) {
+    for (const t of SKIP_ON_DISK_TYPES) {
+        if (line.includes(`"type":"${t}"`) || line.includes(`"type": "${t}"`)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Drift-check primitive. Reads up to {@link PEEK_TAIL_BYTES} from the end of
+ * the file, parses the last complete line, and returns the last event plus
+ * total file size.
+ *
+ * Does NOT stream the whole file — designed to be called frequently as a
+ * cheap "has this changed since I last checked?" probe. Walks back through
+ * the buffer if the last line is a skipped wrapper type or fails to parse.
+ *
+ * Returns `{ lastEvent: null, size }` if the tail buffer holds no parseable
+ * line — caller should fall back to a full read if it needs guaranteed data.
+ */
+export async function peekClaudeTranscript(filePath) {
+    let size;
+    try {
+        const s = await stat(filePath);
+        size = s.size;
+    }
+    catch {
+        return { lastEvent: null, size: null };
+    }
+    if (size === 0)
+        return { lastEvent: null, size: 0 };
+    const readBytes = Math.min(PEEK_TAIL_BYTES, size);
+    const start = size - readBytes;
+    const startedMidFile = start > 0;
+    let handle;
+    try {
+        handle = await fsOpen(filePath, "r");
+    }
+    catch {
+        return { lastEvent: null, size };
+    }
+    try {
+        const buf = Buffer.alloc(readBytes);
+        await handle.read(buf, 0, readBytes, start);
+        const text = buf.toString("utf8");
+        // Split on `\n`, drop the trailing empty entry from a final newline.
+        const lines = text.split("\n");
+        if (lines.length > 0 && lines[lines.length - 1] === "")
+            lines.pop();
+        // If we started mid-file, line[0] is partial — never trust it.
+        const minIdx = startedMidFile ? 1 : 0;
+        for (let i = lines.length - 1; i >= minIdx; i--) {
+            const raw = lines[i];
+            if (raw === undefined)
+                continue;
+            const trimmed = raw.trim();
+            if (!trimmed)
+                continue;
+            if (looksLikeSkippedType(trimmed))
+                continue;
+            const events = parseStreamLine(trimmed);
+            const last = events[events.length - 1];
+            if (!last)
+                continue;
+            return { lastEvent: last, size };
+        }
+        return { lastEvent: null, size };
+    }
+    finally {
+        await handle.close();
+    }
+}
+// ---------------------------------------------------------------------------
+// Polymorphic facade
+// ---------------------------------------------------------------------------
+/**
+ * Polymorphic transcript ops for Claude. Delegates to the named functions
+ * above; mounted as `claudeProvider.transcript` so apps doing runtime-
+ * dispatched recovery can call `getProvider(name).transcript.find(...)`
+ * without a switch statement.
+ *
+ * Apps that know they're on Claude at compile time should prefer the named
+ * helpers (`getClaudeTranscriptPath`, `findClaudeTranscriptBySessionId`) —
+ * they return richer types (`canonicalCwd`, `projectDir`, `claudeHome`) that
+ * the polymorphic interface flattens away.
+ */
+export const claudeTranscriptOps = {
+    async find(opts) {
+        // Fast path: cwd hint provided → direct O(1) lookup.
+        if (opts.cwd) {
+            const loc = await getClaudeTranscriptPath({
+                sessionId: opts.sessionId,
+                cwd: opts.cwd,
+            });
+            if (await pathExists(loc.filePath)) {
+                return { filePath: loc.filePath, cwd: loc.canonicalCwd };
+            }
+            // cwd was wrong (e.g. session was launched in a different worktree);
+            // fall through to scan.
+        }
+        const found = await findClaudeTranscriptBySessionId({ sessionId: opts.sessionId });
+        if (!found)
+            return null;
+        return { filePath: found.filePath, cwd: found.cwd };
+    },
+    read(opts) {
+        return readClaudeTranscript(opts);
+    },
+    peek(filePath) {
+        return peekClaudeTranscript(filePath);
+    },
+};
+//# sourceMappingURL=transcript.js.map

package/dist/providers/claude/transcript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript.js","sourceRoot":"","sources":["../../../src/providers/claude/transcript.ts"],"names":[],"mappings":"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"}

package/dist/providers/codex/index.d.ts

@@ -1,3 +1,5 @@
 import type { ProviderModule } from "../../types.js";
 export declare const codexProvider: ProviderModule;
+export { getCodexTranscriptPath, readCodexTranscript, peekCodexTranscript, readCodexCwd, codexTranscriptOps, parseCodexLine, resolveCodexHome, } from "./transcript.js";
+export type { GetCodexTranscriptPathOptions, CodexTranscriptLocation, ReadCodexTranscriptOptions, CodexTranscriptYield, CodexTranscriptLine, CodexPeekResult, } from "./transcript.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/providers/codex/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/codex/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAgC,MAAM,gBAAgB,CAAC;AAMnF,eAAO,MAAM,aAAa,EAAE,cAgB3B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/codex/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAgC,MAAM,gBAAgB,CAAC;AAOnF,eAAO,MAAM,aAAa,EAAE,cAiB3B,CAAC;AAEF,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,6BAA6B,EAC7B,uBAAuB,EACvB,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,GAChB,MAAM,iBAAiB,CAAC"}

package/dist/providers/codex/index.js

@@ -2,6 +2,7 @@ import { executeCodexProvider } from "./execute.js";
 import { createCodexSession } from "./session.js";
 import { codexSessionCodec } from "./codec.js";
 import { resolveAuthForProvider } from "../../utils/auth.js";
+import { codexTranscriptOps } from "./transcript.js";
 export const codexProvider = {
     type: "codex",
     capabilities: {
@@ -18,5 +19,7 @@ export const codexProvider = {
     createSession: (ctx) => createCodexSession(ctx),
     resolveAuth: (ctx) => resolveAuthForProvider("codex", ctx),
     sessionCodec: codexSessionCodec,
+    transcript: codexTranscriptOps,
 };
+export { getCodexTranscriptPath, readCodexTranscript, peekCodexTranscript, readCodexCwd, codexTranscriptOps, parseCodexLine, resolveCodexHome, } from "./transcript.js";
 //# sourceMappingURL=index.js.map

package/dist/providers/codex/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/providers/codex/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,MAAM,CAAC,MAAM,aAAa,GAAmB;IAC3C,IAAI,EAAE,OAAO;IACb,YAAY,EAAE;QACZ,QAAQ,EAAE,IAAI;QACd,cAAc,EAAE,KAAK;QACrB,YAAY,EAAE,KAAK;QACnB,GAAG,EAAE,KAAK;QACV,MAAM,EAAE,IAAI;QACZ,YAAY,EAAE,IAAI;QAClB,SAAS,EAAE,IAAI;QACf,QAAQ,EAAE,IAAI;KACf;IACD,OAAO,EAAE,oBAAoB;IAC7B,aAAa,EAAE,CAAC,GAAmB,EAAyB,EAAE,CAAC,kBAAkB,CAAC,GAAG,CAAC;IACtF,WAAW,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,sBAAsB,CAAC,OAAO,EAAE,GAAG,CAAC;IAC1D,YAAY,EAAE,iBAAiB;CAChC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/providers/codex/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,CAAC,MAAM,aAAa,GAAmB;IAC3C,IAAI,EAAE,OAAO;IACb,YAAY,EAAE;QACZ,QAAQ,EAAE,IAAI;QACd,cAAc,EAAE,KAAK;QACrB,YAAY,EAAE,KAAK;QACnB,GAAG,EAAE,KAAK;QACV,MAAM,EAAE,IAAI;QACZ,YAAY,EAAE,IAAI;QAClB,SAAS,EAAE,IAAI;QACf,QAAQ,EAAE,IAAI;KACf;IACD,OAAO,EAAE,oBAAoB;IAC7B,aAAa,EAAE,CAAC,GAAmB,EAAyB,EAAE,CAAC,kBAAkB,CAAC,GAAG,CAAC;IACtF,WAAW,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,sBAAsB,CAAC,OAAO,EAAE,GAAG,CAAC;IAC1D,YAAY,EAAE,iBAAiB;IAC/B,UAAU,EAAE,kBAAkB;CAC/B,CAAC;AAEF,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,gBAAgB,GACjB,MAAM,iBAAiB,CAAC"}

package/dist/providers/codex/transcript.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Codex writes a durable JSONL rollout for every session under
+ * `<codexHome>/sessions/YYYY/MM/DD/rollout-<TIMESTAMP>-<sessionId>.jsonl`.
+ *
+ * Unlike Claude's project-keyed layout, Codex organizes rollouts by start
+ * date. The session ID is encoded at the end of the filename, after the
+ * launch timestamp. Locating a rollout by sessionId therefore requires a
+ * filename scan; there is no deterministic single-path-from-sessionId
+ * computation.
+ *
+ * On-disk format diverges from Codex's stream wire format. The wire format
+ * (handled by {@link parseCodexStreamLine}) emits either JSON-RPC
+ * notifications (`{method, params}`) or NDJSON events (`{type: "thread.started", ...}`).
+ * The on-disk format uses one of two shapes depending on Codex version:
+ *
+ *   1. Newer (≥0.10): `{timestamp, type: "session_meta"|"event_msg"|"response_item", payload: {...}}`
+ *   2. Older (pre-0.10): unwrapped — first line is `{id, timestamp, instructions}`,
+ *      subsequent lines are `{type: "message"|"reasoning"|..., ...}` directly
+ *
+ * These helpers expose path discovery + raw-line streaming. Translating the
+ * on-disk types into `StreamEvent`s requires knowing the full Codex internal
+ * event vocabulary (which differs across versions and is not externally
+ * documented), so that work is left to consumers — they read structured raw
+ * lines and interpret payloads against the version they care about.
+ */
+import type { TranscriptOps } from "../../types.js";
+/**
+ * Resolve Codex's config home directory. Honors `$CODEX_HOME` first, falls
+ * back to `~/.codex`.
+ */
+export declare function resolveCodexHome(override?: string): string;
+export interface GetCodexTranscriptPathOptions {
+    /** Codex session ID (UUID). Matches the `id` field in the session_meta line. */
+    sessionId: string;
+    /** Override the Codex home. Defaults to `$CODEX_HOME` or `~/.codex`. */
+    codexHome?: string;
+    /**
+     * Also search `<codexHome>/archived_sessions/`. Default `true`. Codex moves
+     * old rollouts here during cleanup; without this fallback, recovery of
+     * older sessions would fail.
+     */
+    searchArchived?: boolean;
+}
+export interface CodexTranscriptLocation {
+    /** Absolute path to the rollout JSONL. */
+    filePath: string;
+    /** Which subtree it was found in. */
+    source: "active" | "archived";
+    /** The codex home that was searched. */
+    codexHome: string;
+}
+/**
+ * Read the literal cwd Codex was launched with, recovered from the first
+ * `session_meta` line in a rollout (or the legacy unwrapped first line for
+ * pre-0.10 transcripts).
+ *
+ * Returns `null` if the file has no recoverable cwd (truncated transcript,
+ * unrecognized format, etc.). Stops scanning after the first ~50 lines —
+ * `session_meta` is always the first line, but the older format may need a
+ * few lines to find the `environment_context` user_message with the cwd.
+ */
+export declare function readCodexCwd(filePath: string): Promise<string | null>;
+/**
+ * Locate a Codex rollout file by session ID. Scans the date-organized tree
+ * under `<codexHome>/sessions/` in reverse-chronological order (newest first,
+ * since recent sessions are the common lookup target), then optionally
+ * `<codexHome>/archived_sessions/`.
+ *
+ * Returns `null` if no matching rollout is found. The session ID must be
+ * the exact UUID Codex assigned — partial matches are not accepted.
+ */
+export declare function getCodexTranscriptPath(opts: GetCodexTranscriptPathOptions): Promise<CodexTranscriptLocation | null>;
+/**
+ * Best-effort parsed view of a single Codex transcript line, normalized
+ * across the wrapped (≥0.10) and unwrapped (pre-0.10) on-disk formats.
+ */
+export interface CodexTranscriptLine {
+    /** Raw JSON-parsed object verbatim from the file. */
+    raw: Record<string, unknown>;
+    /**
+     * Outer wrapper type when present:
+     *   - "session_meta", "event_msg", "response_item" — wrapped (≥0.10) lines
+     *   - For unwrapped lines, falls back to the line's own `type` field
+     *     (e.g., "message", "reasoning", "function_call_output").
+     *   - `null` for lines with no `type` field (e.g., the older
+     *     `{record_type: "state"}` markers or the bare-meta first line).
+     */
+    type: string | null;
+    /** ISO timestamp from the line's `timestamp` field, or null if absent. */
+    timestamp: string | null;
+    /**
+     * Inner payload as a parsed object, when the wrapped format is used.
+     * `null` for unwrapped lines — in that case the meaningful fields are on
+     * {@link raw} directly.
+     */
+    payload: Record<string, unknown> | null;
+}
+export interface ReadCodexTranscriptOptions {
+    /** Absolute path to the rollout JSONL. */
+    filePath: string;
+    /**
+     * Byte offset to resume from. Must be line-aligned. Use an offset previously
+     * yielded by this function. Defaults to 0 (start of file).
+     */
+    fromOffset?: number;
+}
+export interface CodexTranscriptYield {
+    /**
+     * Parsed line, normalized for the consumer. Named `event` for symmetry
+     * with Claude's `readClaudeTranscript` and the polymorphic
+     * `provider.transcript.read` interface — both yield `{event, offset}`.
+     * The underlying type is provider-specific (`CodexTranscriptLine` here,
+     * `StreamEvent` for Claude).
+     */
+    event: CodexTranscriptLine;
+    /**
+     * Byte offset immediately AFTER the trailing `\n` of this line. Pass back
+     * as {@link ReadCodexTranscriptOptions.fromOffset} to resume on the next line.
+     */
+    offset: number;
+}
+/**
+ * Stream-read a Codex rollout JSONL, yielding parsed lines.
+ *
+ * Behavior:
+ * - Empty async iterable if the file doesn't exist (no throw).
+ * - Silently skips lines that fail to JSON.parse.
+ * - Does not interpret payloads — that's the consumer's responsibility,
+ *   since the on-disk event vocabulary is version-specific.
+ */
+export declare function readCodexTranscript(opts: ReadCodexTranscriptOptions): AsyncIterable<CodexTranscriptYield>;
+/**
+ * Parse a single Codex transcript line into a normalized view. Returns
+ * `null` for lines that don't parse as JSON objects.
+ *
+ * Exported because consumers reading the file by other means (e.g. tailing
+ * a write stream) can use it to get the same shape this module yields.
+ */
+export declare function parseCodexLine(line: string): CodexTranscriptLine | null;
+export interface CodexPeekResult {
+    /**
+     * Last successfully parsed line, or null if the file is empty/missing/unparseable.
+     * Named `lastEvent` for symmetry with Claude's `peekClaudeTranscript` and
+     * the polymorphic `provider.transcript.peek` interface.
+     */
+    lastEvent: CodexTranscriptLine | null;
+    /** Total size of the file in bytes, or null if missing. */
+    size: number | null;
+}
+/**
+ * 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 declare function peekCodexTranscript(filePath: string): Promise<CodexPeekResult>;
+/**
+ * Polymorphic transcript ops for Codex. Delegates to the named functions
+ * above; mounted as `codexProvider.transcript`. The `cwd` hint to `find` is
+ * accepted for interface symmetry with Claude but is ignored — Codex
+ * rollouts are organized by date, not by cwd.
+ */
+export declare const codexTranscriptOps: TranscriptOps<CodexTranscriptLine>;
+//# sourceMappingURL=transcript.d.ts.map

package/dist/providers/codex/transcript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../../src/providers/codex/transcript.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AASH,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAKrE;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAK1D;AAMD,MAAM,WAAW,6BAA6B;IAC5C,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,uBAAuB;IACtC,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,MAAM,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC9B,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAmC3E;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,6BAA6B,GAClC,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAkBzC;AAmFD;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B;;;;;;;OAOG;IACH,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,0EAA0E;IAC1E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,0BAA0B;IACzC,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,KAAK,EAAE,mBAAmB,CAAC;IAC3B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAuB,mBAAmB,CACxC,IAAI,EAAE,0BAA0B,GAC/B,aAAa,CAAC,oBAAoB,CAAC,CA6BrC;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAoBvE;AAeD,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,SAAS,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACtC,2DAA2D;IAC3D,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CA4CpF;AAMD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,aAAa,CAAC,mBAAmB,CAajE,CAAC"}