@agentex/agent 0.0.26 → 0.0.28

package/src/derived.ts

@@ -1,11 +1,18 @@
 import type {
+  AgentSession,
+  AttachOptions,
+  HistoryAttachment,
   ProviderCapabilities,
   ProviderConfig,
   ProviderModel,
   ProviderModule,
+  ProviderRuntimeContext,
+  SessionAttachment,
+  SessionRecord,
 } from "./types.js";
 import { getProvider, registerProvider } from "./registry.js";
 import { acpProvider } from "./providers/acp/index.js";
+import { MalformedSessionRecordError } from "./sessions/record.js";
 
 /**
  * Declarative configuration for a *derived* provider — a new provider id that
@@ -76,6 +83,38 @@ export function getAcpFactory(): AcpFactory | null {
   return acpFactory;
 }
 
+function withProviderType(record: SessionRecord | null, providerType: string): SessionRecord | null {
+  return record ? { ...record, providerType } : null;
+}
+
+function wrapDerivedSession(session: AgentSession, providerType: string): AgentSession {
+  return new Proxy(session, {
+    get(target, property) {
+      if (property === "describe") {
+        return target.describe
+          ? () => withProviderType(target.describe!(), providerType)
+          : undefined;
+      }
+      if (property === "describeHistory") {
+        return target.describeHistory
+          ? () => withProviderType(target.describeHistory!(), providerType)
+          : undefined;
+      }
+      const value = Reflect.get(target, property, target) as unknown;
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+}
+
+function assertDerivedRecord(record: SessionRecord, providerType: string): void {
+  if (record.providerType !== providerType) {
+    throw new MalformedSessionRecordError(
+      `${providerType} attach requires providerType ${JSON.stringify(providerType)}; got ${JSON.stringify(record.providerType)}`,
+      "providerType",
+    );
+  }
+}
+
 /**
  * Build a derived `ProviderModule` from a base provider plus an overlay. The
  * returned module is NOT auto-registered — pass it to `registerProvider`, or
@@ -124,15 +163,21 @@ export function defineDerivedProvider(cfg: DerivedProviderConfig): ProviderModul
 
   if (base.createSession) {
     const baseCreate = base.createSession.bind(base);
-    derived.createSession = (ctx) =>
-      baseCreate({ ...ctx, env: overlayEnv(ctx.env), config: overlayConfig(ctx.config) });
+    derived.createSession = async (ctx) => wrapDerivedSession(
+      await baseCreate({ ...ctx, env: overlayEnv(ctx.env), config: overlayConfig(ctx.config) }),
+      cfg.id,
+    );
   }
   if (cfg.models) {
     const models = cfg.models;
     derived.listModels = async () => models;
   } else if (base.listModels) {
     const baseList = base.listModels.bind(base);
-    derived.listModels = (opts) => baseList(opts);
+    derived.listModels = (opts) => baseList({
+      ...opts,
+      env: overlayEnv(opts?.env),
+      config: overlayConfig(opts?.config),
+    });
   }
   if (base.listModes) {
     const baseModes = base.listModes.bind(base);
@@ -144,10 +189,88 @@ export function defineDerivedProvider(cfg: DerivedProviderConfig): ProviderModul
     derived.checkQuota = (qctx) =>
       baseQuota({ ...qctx, env: overlayEnv(qctx?.env), config: overlayConfig(qctx?.config) });
   }
+  if (base.probeCapabilities) {
+    const baseProbe = base.probeCapabilities.bind(base);
+    derived.probeCapabilities = (ctx) => baseProbe({
+      ...ctx,
+      env: overlayEnv(ctx?.env),
+      config: overlayConfig(ctx?.config),
+    });
+  }
+  if (base.upstreamProviders) {
+    const manager = base.upstreamProviders;
+    const runtime = (ctx?: ProviderRuntimeContext): ProviderRuntimeContext => ({
+      ...ctx,
+      env: overlayEnv(ctx?.env),
+      config: overlayConfig(ctx?.config),
+    });
+    derived.upstreamProviders = {
+      list: (ctx) => manager.list(runtime(ctx)),
+      authMethods: (providerId, ctx) => manager.authMethods(providerId, runtime(ctx)),
+      setApiKey: (providerId, key, ctx) => manager.setApiKey(providerId, key, runtime(ctx)),
+      beginOAuth: (providerId, methodId, inputs, ctx) =>
+        manager.beginOAuth(providerId, methodId, inputs, runtime(ctx)),
+      completeOAuth: (flowId, code, ctx) => manager.completeOAuth(flowId, code, runtime(ctx)),
+      canDisconnect: (providerId, ctx) => manager.canDisconnect(providerId, runtime(ctx)),
+      disconnect: (providerId, ctx) => manager.disconnect(providerId, runtime(ctx)),
+    };
+  }
+  if (base.attachSession && derived.createSession) {
+    const baseAttach = base.attachSession.bind(base);
+    derived.attachSession = async (record, opts): Promise<SessionAttachment> => {
+      assertDerivedRecord(record, cfg.id);
+      const attachment = await baseAttach(
+        { ...record, providerType: base.type },
+        overlayAttachOptions(opts, overlayEnv, overlayConfig),
+      );
+      const derivedRecord = withProviderType(attachment.record, cfg.id)!;
+      return {
+        ...attachment,
+        record: derivedRecord,
+        resume: (ctx) => derived.createSession!({
+          ...ctx,
+          cwd: ctx?.cwd ?? derivedRecord.cwd ?? undefined,
+          sessionParams: derivedRecord.params,
+        }),
+      };
+    };
+  }
+  if (base.attachHistory && derived.createSession) {
+    const baseAttachHistory = base.attachHistory.bind(base);
+    derived.attachHistory = async (record, opts): Promise<HistoryAttachment> => {
+      assertDerivedRecord(record, cfg.id);
+      const attachment = await baseAttachHistory(
+        { ...record, providerType: base.type },
+        overlayAttachOptions(opts, overlayEnv, overlayConfig),
+      );
+      const derivedRecord = withProviderType(attachment.record, cfg.id)!;
+      return {
+        ...attachment,
+        record: derivedRecord,
+        resume: (ctx) => derived.createSession!({
+          ...ctx,
+          cwd: ctx?.cwd ?? derivedRecord.cwd ?? undefined,
+          sessionParams: derivedRecord.params,
+        }),
+      };
+    };
+  }
 
   return derived;
 }
 
+function overlayAttachOptions(
+  opts: AttachOptions | undefined,
+  overlayEnv: (env?: Record<string, string>) => Record<string, string>,
+  overlayConfig: (config?: ProviderConfig) => ProviderConfig,
+): AttachOptions {
+  return {
+    ...opts,
+    env: overlayEnv(opts?.env),
+    config: overlayConfig(opts?.config),
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Config-file loader
 // ---------------------------------------------------------------------------

package/src/goals/controller.ts

@@ -139,6 +139,9 @@ export class GoalController {
    * sentinel/loop), call `setGoal` again; hydrate does not restart the loop.
    */
   hydrate(state: GoalState): void {
+    // Hydration is historical initialization, never an overwrite. A live
+    // parser event or caller-set goal that won the race remains authoritative.
+    if (this.state !== null) return;
     this.state = state;
     this.mode = "idle";
   }
@@ -387,6 +390,19 @@ export class GoalController {
       // re-enters onTurnSettled and continues the loop.
       const nudge = verdict.nudge ?? defaultNudge(objective, this.iterations);
       void this.deps.send(nudge).catch(() => {});
+    } catch (error) {
+      if (gen !== this.generation) return;
+      this.transition({
+        objective,
+        status: "blocked",
+        met: false,
+        enforced: true,
+        source: "agentex",
+        blockedReason: "sentinel_error",
+        errorMessage: error instanceof Error ? error.message : String(error),
+      });
+      this.mode = "idle";
+      this.sentinel = null;
     } finally {
       this.evaluating = false;
     }
@@ -433,6 +449,7 @@ export class GoalController {
       raw: { synthetic: "goal", ...fields },
     };
     if (fields.blockedReason !== undefined) event.blockedReason = fields.blockedReason;
+    if (fields.errorMessage !== undefined) event.errorMessage = fields.errorMessage;
     if (fields.tokensUsed !== undefined) event.tokensUsed = fields.tokensUsed;
     if (fields.timeUsedSeconds !== undefined) event.timeUsedSeconds = fields.timeUsedSeconds;
     if (fields.tokenBudget !== undefined) event.tokenBudget = fields.tokenBudget;

package/src/goals/normalize.ts

@@ -33,6 +33,7 @@ export interface NormalizedGoalFields {
   enforced: boolean;
   source: GoalSource;
   blockedReason?: GoalBlockedReason;
+  errorMessage?: string;
   tokensUsed?: number;
   timeUsedSeconds?: number;
   tokenBudget?: number;
@@ -90,6 +91,9 @@ export function normalizeCodexGoalStatus(raw: string | null | undefined): {
     case "budget-limited":
     case "budget_limited":
     case "budgetlimited": // camelCase `budgetLimited`, lowercased
+    case "usage-limited":
+    case "usage_limited":
+    case "usagelimited": // camelCase `usageLimited`, lowercased
       return { status: "blocked", met: false, blockedReason: "budget" };
     case "blocked":
       return { status: "blocked", met: false, blockedReason: "needs_input" };
@@ -165,6 +169,7 @@ export function goalStateFromEvent(event: GoalStatusEvent): GoalState {
     updatedAt: event.timestamp,
   };
   if (event.blockedReason !== undefined) state.blockedReason = event.blockedReason;
+  if (event.errorMessage !== undefined) state.errorMessage = event.errorMessage;
   if (event.tokensUsed !== undefined) state.tokensUsed = event.tokensUsed;
   if (event.timeUsedSeconds !== undefined) state.timeUsedSeconds = event.timeUsedSeconds;
   if (event.tokenBudget !== undefined) state.tokenBudget = event.tokenBudget;

package/src/index.ts

@@ -141,6 +141,9 @@ export {
 export type {
   ProviderModule,
   ProviderCapabilities,
+  ProviderRuntimeContext,
+  ProviderRuntimeReport,
+  CapabilityStatus,
   AgentMode,
   ListModesOptions,
   ExecutionContext,
@@ -168,6 +171,11 @@ export type {
   AuthRequiredReason,
   BinaryStatus,
   ProviderModel,
+  ListModelsOptions,
+  ProviderAuthMethod,
+  ProviderAuthFlow,
+  UpstreamProvider,
+  UpstreamProviderManager,
   SessionContext,
   AgentSession,
   SendHandle,
@@ -235,6 +243,11 @@ export type {
   CatchUpOptions,
   AttachOptions,
   SessionAttachment,
+  HistoryCheckpoint,
+  HistorySource,
+  HistoryCatchUpYield,
+  HistoryCatchUpOptions,
+  HistoryAttachment,
 } from "./types.js";
 
 export type {

package/src/providers/claude/attach.ts

@@ -1,4 +1,6 @@
+import { createReadStream } from "node:fs";
 import { stat } from "node:fs/promises";
+import * as readline from "node:readline";
 import type {
   AttachOptions,
   CatchUpOptions,
@@ -19,7 +21,6 @@ import { claudeSessionCodec } from "./codec.js";
 import {
   findClaudeTranscriptBySessionId,
   getClaudeTranscriptPath,
-  peekClaudeTranscript,
   readClaudeTranscript,
 } from "./transcript.js";
 // Heavy-on-heavy is fine: this whole module loads lazily via
@@ -77,6 +78,44 @@ const EMPTY: AsyncIterable<CatchUpYield> = {
   },
 };
 
+/**
+ * Classify lifecycle boundaries from the raw transcript rather than replay's
+ * normalized events. Ordinary Claude `user` prompt records intentionally
+ * normalize to no StreamEvent, but still start a new turn. Looking only at
+ * normalized output can therefore mistake an interrupted new turn for the
+ * preceding completed one.
+ */
+async function classifyLastTurn(filePath: string): Promise<LastTurnStatus> {
+  const stream = createReadStream(filePath, { encoding: "utf8" });
+  stream.on("error", () => {});
+  const lines = readline.createInterface({ input: stream, crlfDelay: Infinity });
+  let lastTurn: LastTurnStatus = "unknown";
+
+  try {
+    for await (const line of lines) {
+      let raw: unknown;
+      try {
+        raw = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (typeof raw !== "object" || raw === null || Array.isArray(raw)) continue;
+      const type = (raw as Record<string, unknown>)["type"];
+      if (type === "result") lastTurn = "completed";
+      else if (type === "user" || type === "assistant") lastTurn = "interrupted";
+    }
+  } catch (error) {
+    const fsError = error as NodeJS.ErrnoException;
+    if (fsError?.code !== "ENOENT") throw error;
+    return "unknown";
+  } finally {
+    lines.close();
+    stream.destroy();
+  }
+
+  return lastTurn;
+}
+
 /**
  * Read-only reattachment to a durable Claude session. Composition of existing
  * primitives (codec + transcript ops + `createClaudeSession` resume) — spawns
@@ -87,6 +126,12 @@ export async function attachClaudeSession(
   opts?: AttachOptions,
 ): Promise<SessionAttachment> {
   assertSessionRecord(record);
+  if (record.providerType !== "claude") {
+    throw new MalformedSessionRecordError(
+      `claude attach requires providerType "claude"; got ${JSON.stringify(record.providerType)}`,
+      "providerType",
+    );
+  }
 
   // 1. Normalize params through the codec.
   const params = claudeSessionCodec.deserialize(record.params);
@@ -113,10 +158,7 @@ export async function attachClaudeSession(
   // 3. Classify how the last persisted turn ended.
   let lastTurn: LastTurnStatus = "unknown";
   if (transcript) {
-    const { lastEvent } = await peekClaudeTranscript(transcript.filePath);
-    if (lastEvent === null) lastTurn = "unknown";
-    else if (lastEvent.type === "result") lastTurn = "completed";
-    else lastTurn = "interrupted";
+    lastTurn = await classifyLastTurn(transcript.filePath);
   }
 
   return {
@@ -141,7 +183,7 @@ export async function attachClaudeSession(
     },
     // 5. Continue live — exactly `createSession` with the record's params.
     resume(ctx?: SessionContext) {
-      return createClaudeSession({ ...ctx, sessionParams: params });
+      return createClaudeSession({ ...ctx, cwd: ctx?.cwd ?? cwd ?? undefined, sessionParams: params });
     },
   };
 }

package/src/providers/claude/index.ts

@@ -35,6 +35,7 @@ export const claudeProvider: ProviderModule = {
     modes: false,
     goals: claudeGoalCapability,
     durableSessions: true,
+    durableHistory: true,
   },
   // Heavy machinery (execute.ts, session.ts, attach.ts) loads lazily on first
   // use — every ProviderModule method is already async, so this is invisible to
@@ -48,6 +49,13 @@ export const claudeProvider: ProviderModule = {
   transcript: claudeTranscriptOps,
   attachSession: async (record, opts) =>
     (await import("./attach.js")).attachClaudeSession(record, opts),
+  attachHistory: async (record, opts) => {
+    const [{ attachClaudeSession }, { historyFromSessionAttachment }] = await Promise.all([
+      import("./attach.js"),
+      import("../../sessions/history.js"),
+    ]);
+    return historyFromSessionAttachment("claude", await attachClaudeSession(record, opts));
+  },
 };
 
 export {

package/src/providers/claude/session.ts

@@ -216,11 +216,7 @@ export async function createClaudeSession(ctx: SessionContext): Promise<AgentSes
     throw new Error("Failed to open stdio on Claude process");
   }
 
-  const session = new ClaudeSessionImpl(proc, ctx, skillsDir, mcpConfigPath);
-
-  // On resume, restore an unmet native goal from the transcript (best-effort,
-  // non-blocking so session creation isn't delayed by a transcript read).
-  if (resumeId) void session.hydrateGoalFromTranscript(resumeId);
+  const session = new ClaudeSessionImpl(proc, { ...ctx, cwd }, skillsDir, mcpConfigPath);
 
   // Wire up AbortSignal to close the session
   if (ctx.signal) {
@@ -231,6 +227,10 @@ export async function createClaudeSession(ctx: SessionContext): Promise<AgentSes
     }
   }
 
+  // Finish historical hydration before exposing the session. This prevents a
+  // late transcript read from overwriting a goal the caller sets immediately.
+  if (resumeId && session.state !== "closed") await session.hydrateGoalFromTranscript(resumeId);
+
   return session;
 }
 
@@ -307,6 +307,7 @@ export class ClaudeSessionImpl implements AgentSession {
   /** Tail state for observing native goal_status (transcript-only, not on stdout). */
   private _goalScanOffset = 0;
   private _goalPoll: ReturnType<typeof setInterval> | null = null;
+  private readonly cwd: string;
 
   constructor(
     private readonly proc: ChildProcess,
@@ -314,6 +315,7 @@ export class ClaudeSessionImpl implements AgentSession {
     private readonly skillsDir: string | null,
     private readonly mcpConfigPath: string | null = null,
   ) {
+    this.cwd = ctx.cwd ?? process.cwd();
     this._goals = new GoalController({
       providerType: "claude",
       capability: claudeGoalCapability,
@@ -384,6 +386,7 @@ export class ClaudeSessionImpl implements AgentSession {
 
   get sessionId(): string | null { return this._sessionId; }
   get state(): SessionState { return this._state; }
+  private isClosed(): boolean { return this._state === "closed"; }
 
   /**
    * Durable identity for persistence + later `attachSession`. Null until Claude
@@ -392,7 +395,7 @@ export class ClaudeSessionImpl implements AgentSession {
    */
   describe(): SessionRecord | null {
     if (!this._sessionId) return null;
-    const cwd = this.ctx.cwd ?? null;
+    const cwd = this.cwd;
     const params = claudeSessionCodec.serialize({
       sessionId: this._sessionId,
       ...(cwd ? { cwd } : {}),
@@ -1144,7 +1147,7 @@ export class ClaudeSessionImpl implements AgentSession {
     try {
       const found = await claudeTranscriptOps.find({
         sessionId,
-        cwd: this.ctx.cwd ?? process.cwd(),
+        cwd: this.cwd,
       });
       if (found) this._transcriptPath = found.filePath;
     } catch { /* best effort */ } finally {
@@ -1166,20 +1169,22 @@ export class ClaudeSessionImpl implements AgentSession {
    */
   async hydrateGoalFromTranscript(sessionId: string): Promise<void> {
     try {
+      if (this.isClosed()) return;
       const found = await claudeTranscriptOps.find({
         sessionId,
-        cwd: this.ctx.cwd ?? process.cwd(),
+        cwd: this.cwd,
       });
-      if (!found) return;
+      if (!found || this.isClosed()) return;
       this._transcriptPath = found.filePath;
       const events: StreamEvent[] = [];
       let endOffset = 0;
       for await (const { event, offset } of claudeTranscriptOps.read({ filePath: found.filePath })) {
+        if (this.isClosed()) return;
         endOffset = offset;
         if (event.type === "goal_status") events.push(event);
       }
       const last = latestGoalFromEvents(events);
-      if (last && !isTerminalGoalStatus(last.status)) {
+      if (!this.isClosed() && last && !isTerminalGoalStatus(last.status)) {
         // Start observing from the END of the historical transcript so the poller
         // surfaces only post-resume transitions (we already hydrated the state).
         this._goalScanOffset = endOffset;

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,6 +38,44 @@ 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
@@ -48,6 +87,12 @@ export async function attachCodexSession(
   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";
   }
@@ -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/index.ts

@@ -23,6 +23,7 @@ export const codexProvider: ProviderModule = {
     modes: true,
     goals: codexGoalCapability,
     durableSessions: true,
+    durableHistory: true,
   },
   // Heavy machinery (execute.ts, session.ts, modes.ts, attach.ts) loads lazily
   // on first use — every ProviderModule method is already async.
@@ -35,6 +36,13 @@ 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));
+  },
 };
 
 export {

package/src/providers/codex/session.ts

@@ -619,6 +619,11 @@ export class CodexSessionImpl implements AgentSession {
       input: [{ type: "text", text: message }],
     };
     if (this._threadId) turnParams["threadId"] = this._threadId;
+    // Codex app-server accepts reasoning effort as a turn/start override. The
+    // selected value becomes the default for later turns on this thread, so
+    // forwarding the session config here works for both fresh and resumed
+    // sessions without mutating the user's global config.toml.
+    if (this.ctx.config?.effort) turnParams["effort"] = this.ctx.config.effort;
 
     let resolveFn!: (r: TurnResult) => void;
     let rejectFn!: (e: Error) => void;

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 };
     }