@agentex/agent 0.0.30 → 0.0.32

package/src/history/types.ts

@@ -1,4 +1,93 @@
-import type { BaseStreamEventFields, StreamEvent } from "../types.js";
+import type {
+  BaseStreamEventFields,
+  HistoryCheckpoint,
+  ProviderRuntimeContext,
+  StreamEvent,
+} from "../types.js";
+
+/**
+ * Provider-neutral discovery options for persisted sessions. Unlike
+ * `LocalHistoryDiscoverOptions`, these options do not assume a filesystem
+ * source. Providers may satisfy them through a local authenticated service.
+ */
+export interface SavedHistoryDiscoverOptions extends ProviderRuntimeContext {
+  /** Optional provider-session directory filter. `cwd` is runtime context only. */
+  directory?: string;
+  includeArchived?: boolean;
+  mainSessionsOnly?: boolean;
+  requireUserMessage?: boolean;
+  limit?: number;
+}
+
+export interface SavedHistoryProbeOptions extends ProviderRuntimeContext {
+  limit?: number;
+}
+
+export interface SavedHistoryProbeResult {
+  providerType: string;
+  /** The provider-owned history source could be reached. */
+  sourceAvailable: boolean;
+  historyAvailable: boolean;
+  /** A bounded source count, not necessarily an eligible-session count. */
+  approximateCount?: number;
+}
+
+export type SavedHistoryArchiveState = "active" | "archived" | "unknown";
+
+/**
+ * Serializable metadata for a provider-owned persisted session. Storage
+ * details such as transcript paths, byte offsets, and database layouts are
+ * deliberately absent.
+ */
+export interface SavedHistorySession {
+  version: 1;
+  providerType: string;
+  externalSessionId: string;
+  cwd: string | null;
+  title: string | null;
+  startedAt: string | null;
+  updatedAt: string;
+  branch: string | null;
+  gitOriginUrl: string | null;
+  archiveState: SavedHistoryArchiveState;
+  hasUserMessage: boolean;
+}
+
+export type SavedHistoryUserEvent = {
+  type: "user";
+  text: string;
+} & BaseStreamEventFields;
+
+export type SavedHistoryEvent = StreamEvent | SavedHistoryUserEvent;
+
+export interface SavedHistoryYield {
+  event: SavedHistoryEvent & { eventId: string };
+  /** Opaque provider-owned bookmark. Persist only after the event commits. */
+  checkpoint: HistoryCheckpoint;
+  eventId: string;
+  /** Disambiguates normalized events that share one provider source part. */
+  partIndex: number;
+}
+
+export interface SavedHistoryReadOptions extends ProviderRuntimeContext {
+  after?: HistoryCheckpoint;
+  mode?: "incremental" | "bounded_full_resync";
+}
+
+/**
+ * Discover and read provider-owned saved sessions when their ids are not yet
+ * known. This is the provider-neutral import/synchronization surface. It is
+ * separate from `attachHistory`, which starts from a known `SessionRecord`,
+ * and from the file-specific `LocalHistoryOps` compatibility API.
+ */
+export interface SavedHistoryOps {
+  probe(options?: SavedHistoryProbeOptions): Promise<SavedHistoryProbeResult>;
+  discover(options?: SavedHistoryDiscoverOptions): AsyncIterable<SavedHistorySession>;
+  read(
+    session: SavedHistorySession,
+    options?: SavedHistoryReadOptions,
+  ): AsyncIterable<SavedHistoryYield>;
+}
 
 export interface LocalHistoryDiscoverOptions {
   includeArchived?: boolean;

package/src/index.ts

@@ -206,9 +206,19 @@ export type {
   GoalSentinelContext,
 } from "./types.js";
 
-// Local persisted session discovery. Runtime errors are exported from the
+// Persisted session discovery. Runtime errors are exported from the
 // `@agentex/agent/history` subpath to keep the root barrel lazy.
 export type {
+  SavedHistoryArchiveState,
+  SavedHistoryDiscoverOptions,
+  SavedHistoryEvent,
+  SavedHistoryOps,
+  SavedHistoryProbeOptions,
+  SavedHistoryProbeResult,
+  SavedHistoryReadOptions,
+  SavedHistorySession,
+  SavedHistoryUserEvent,
+  SavedHistoryYield,
   LocalHistoryArchiveState,
   LocalHistoryDiscoverOptions,
   LocalHistoryErrorCode,

package/src/providers/codex/history.ts

@@ -246,7 +246,9 @@ function legacyCodexEvents(
   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 }] : [];
+    const rawPhase = line.raw["phase"];
+    const phase = rawPhase === "commentary" || rawPhase === "final_answer" ? rawPhase : undefined;
+    return text ? [{ type: "assistant", text, ...(phase ? { phase } : {}), ...base }] : [];
   }
   if (line.type === "reasoning") {
     const text = textFromContent(line.raw["summary"] ?? line.raw["content"], new Set(["text", "summary_text"]));

package/src/providers/codex/parse.ts

@@ -53,6 +53,10 @@ function asNullableNumber(value: unknown): number | null {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
 
+function asMessagePhase(value: unknown): "commentary" | "final_answer" | undefined {
+  return value === "commentary" || value === "final_answer" ? value : undefined;
+}
+
 function parseObject(value: unknown): Record<string, unknown> {
   if (typeof value === "object" && value !== null && !Array.isArray(value)) {
     return value as Record<string, unknown>;
@@ -333,10 +337,11 @@ function parseV2Notification(event: Record<string, unknown>): StreamEvent | null
       asNullableString(item["id"]) ??
       asNullableString(item["call_id"]);
     const base = makeBase(itemId);
+    const isCommandExecution = itemType === "command_execution" || itemType === "commandExecution";
 
     // Tool starts — emit tool_call on item/started only.
     if (method === "item/started") {
-      if (itemType === "command_execution") {
+      if (isCommandExecution) {
         return {
           type: "tool_call",
           toolCallId: itemId,
@@ -359,14 +364,15 @@ function parseV2Notification(event: Record<string, unknown>): StreamEvent | null
     }
 
     // item/completed — emit the terminal event for each item type.
-    if (itemType === "command_execution") {
-      const exitCode = asNullableNumber(item["exit_code"]);
+    if (isCommandExecution) {
+      const exitCode = asNullableNumber(item["exit_code"] ?? item["exitCode"]);
+      const status = asString(item["status"], "");
       return {
         type: "tool_result",
         toolCallId: itemId,
         toolName: "command_execution",
-        content: asString(item["aggregated_output"], ""),
-        isError: exitCode !== null && exitCode !== 0,
+        content: asString(item["aggregated_output"], asString(item["aggregatedOutput"], "")),
+        isError: status === "failed" || status === "declined" || (exitCode !== null && exitCode !== 0),
         exitCode,
         ...base,
       };
@@ -386,9 +392,11 @@ function parseV2Notification(event: Record<string, unknown>): StreamEvent | null
     if (itemType === "agentMessage") {
       const directText = asString(item["text"], "");
       if (directText || directText === "") {
+        const phase = asMessagePhase(item["phase"]);
         return {
           type: "assistant",
           text: directText,
+          ...(phase ? { phase } : {}),
           ...base,
         };
       }
@@ -575,11 +583,13 @@ function parseNdjsonEvent(
       };
     }
     if (itemType === "agent_message") {
+      const phase = asMessagePhase(item["phase"]);
       const directText = asString(item["text"], "");
       if (directText) {
         return {
           type: "assistant",
           text: directText,
+          ...(phase ? { phase } : {}),
           ...base,
         };
       }
@@ -591,6 +601,7 @@ function parseNdjsonEvent(
           return {
             type: "assistant",
             text: asString(block["text"], ""),
+            ...(phase ? { phase } : {}),
             ...base,
           };
         }

package/src/providers/codex/session.ts

@@ -307,9 +307,16 @@ export { codexGoalCapability } from "./goal-capability.js";
 
 export class CodexSessionImpl implements AgentSession {
   private _state: SessionState = "idle";
+  /**
+   * The root thread represented by this AgentSession. Codex app-server also
+   * reports child-agent threads on the same stdout connection, so this id is
+   * pinned once discovered and must never be promoted to a child thread.
+   */
   private _threadId: string | null = null;
   /** Thread id to resume (from ctx.sessionParams); null starts a fresh thread. */
   private readonly _resumeThreadId: string | null;
+  /** Expected root during handshake, cleared when resume falls back to fresh. */
+  private _expectedThreadId: string | null;
   private _lineBuffer = "";
   private _nextId = 1;
 
@@ -366,6 +373,7 @@ export class CodexSessionImpl implements AgentSession {
     private readonly instructions: string | null,
   ) {
     this._resumeThreadId = readCodexResumeId(ctx.sessionParams);
+    this._expectedThreadId = this._resumeThreadId;
 
     this._goals = new GoalController({
       providerType: "codex",
@@ -527,12 +535,18 @@ export class CodexSessionImpl implements AgentSession {
         // thread/resume may echo the thread back or return {}; fall back to the
         // id we resumed with so `sessionId` is always populated.
         this._threadId = str(thread, "id") || str(thread, "sessionId") || this._resumeThreadId;
+        this._expectedThreadId = this._threadId;
         // Rehydrate a durable Codex goal so getGoal() reflects it immediately
         // (goals live in SQLite, not the transcript, so a resumed thread would
         // otherwise report null until the next goal notification).
         await this.hydrateGoalFromThread();
         return;
       } catch (err) {
+        // A failed resume can emit thread/started before its error response.
+        // Clear that provisional identity so the fresh thread's init event is
+        // accepted instead of being mistaken for a foreign child thread.
+        if (this._threadId === this._expectedThreadId) this._threadId = null;
+        this._expectedThreadId = null;
         // The thread is unknown to this codex install (different machine, pruned
         // history). Don't fail the whole session — fall back to a fresh thread
         // and surface the downgrade on stderr. The new id flows back out via
@@ -586,6 +600,7 @@ export class CodexSessionImpl implements AgentSession {
     // codex-cli 0.130.0+ shape: { thread: { id, sessionId, ... }, model, ... }
     const thread = asObj(res, "thread");
     this._threadId = str(thread, "id") || str(thread, "sessionId") || null;
+    this._expectedThreadId = this._threadId;
   }
 
   // -------------------------------------------------------------------------
@@ -971,6 +986,23 @@ export class CodexSessionImpl implements AgentSession {
   // Notification handling (v2 format)
   // -------------------------------------------------------------------------
 
+  /** Extract the thread scope carried by a v2 app-server notification. */
+  private notificationThreadId(params: Record<string, unknown>): string | null {
+    const thread = asObj(params, "thread");
+    return str(params, "threadId") || str(thread, "id") || str(thread, "sessionId") || null;
+  }
+
+  /**
+   * Whether an explicitly-scoped event belongs to another app-server thread.
+   * `_expectedThreadId` protects the resume handshake window before `_threadId`
+   * has been populated and is cleared if resume falls back to a fresh thread.
+   * Unscoped global notifications remain eligible.
+   */
+  private isForeignThread(threadId: string | null): boolean {
+    const rootThreadId = this._threadId ?? this._expectedThreadId;
+    return !!threadId && !!rootThreadId && threadId !== rootThreadId;
+  }
+
   private handleNotification(method: string, params: Record<string, unknown>, rawLine: string): void {
     // codex/event — legacy wrapper
     if (method === "codex/event") {
@@ -983,11 +1015,17 @@ export class CodexSessionImpl implements AgentSession {
       return;
     }
 
+    // One Codex app-server connection multiplexes notifications for the root
+    // thread and any child agents it spawns. An AgentSession represents only
+    // its root thread, so foreign items must not change root state/summary and,
+    // most importantly, a child turn/completed must not resolve the root send.
+    const notificationThreadId = this.notificationThreadId(params);
+    if (this.isForeignThread(notificationThreadId)) return;
+
     // Map v2 notification methods to processing
     if (method === "thread/started") {
       // codex-cli 0.130.0+ shape: { thread: { id, sessionId, ... } }
-      const thread = asObj(params, "thread");
-      this._threadId = str(thread, "id") || str(thread, "sessionId") || this._threadId;
+      if (!this._threadId) this._threadId = notificationThreadId;
       this.emitStreamEvent(rawLine);
       return;
     }
@@ -1041,9 +1079,15 @@ export class CodexSessionImpl implements AgentSession {
 
   private handleLegacyEvent(event: Record<string, unknown>, rawLine: string): void {
     const type = str(event, "type");
+    const eventThreadId =
+      str(event, "thread_id") || str(event, "threadId") || str(event, "session_id") || null;
+
+    // Older NDJSON-shaped events can also carry explicit thread scope. Keep
+    // the same root-only invariant when that scope is available.
+    if (this.isForeignThread(eventThreadId)) return;
 
     if (type === "thread.started") {
-      this._threadId = str(event, "thread_id") || this._threadId;
+      if (!this._threadId) this._threadId = eventThreadId;
       this.emitStreamEvent(rawLine);
       return;
     }
@@ -1093,6 +1137,11 @@ export class CodexSessionImpl implements AgentSession {
     const itemType = str(item, "type");
     if (itemType !== "agent_message" && itemType !== "agentMessage") return;
 
+    // Commentary is progress, not the terminal answer. Keep phase-absent
+    // legacy events as a compatibility fallback, while known final_answer
+    // items remain eligible for TurnResult.summary.
+    if (str(item, "phase") === "commentary") return;
+
     // Direct text (Codex 0.30+)
     const directText = str(item, "text");
     if (directText) {
@@ -1280,8 +1329,9 @@ export class CodexSessionImpl implements AgentSession {
     // share an id; the last write wins. It also does NOT match the transcript
     // reader's `codex:<sessionId>:<offset>` scheme (different wire vocabulary
     // on disk) — cross-shape dedup remains a host concern.
-    if (!event.eventId && this._threadId && event.turnId && event.messageId) {
-      event.eventId = `codex:${this._threadId}:${event.turnId}:${event.messageId}:${event.type}`;
+    const eventThreadId = event.sessionId ?? this._threadId;
+    if (!event.eventId && eventThreadId && event.turnId && event.messageId) {
+      event.eventId = `codex:${eventThreadId}:${event.turnId}:${event.messageId}:${event.type}`;
     }
     // Enrich synchronously (in stream order) so tool_result events carry the
     // name of the tool_call they answer.

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

@@ -61,7 +61,13 @@ function mapLine(line: CodexTranscriptLine, sessionId: string | null): StreamEve
       // Only assistant messages surface; developer/user messages are
       // system-prompt material we don't replay.
       if (payload["role"] !== "assistant") return [];
-      return [{ type: "assistant", text: extractMessageText(payload["content"]) ?? "", ...base }];
+      const phase = messagePhase(payload["phase"]);
+      return [{
+        type: "assistant",
+        text: extractMessageText(payload["content"]) ?? "",
+        ...(phase ? { phase } : {}),
+        ...base,
+      }];
     }
 
     if (innerType === "reasoning") {
@@ -129,6 +135,10 @@ function str(v: unknown): string | null {
   return typeof v === "string" && v.length > 0 ? v : null;
 }
 
+function messagePhase(v: unknown): "commentary" | "final_answer" | undefined {
+  return v === "commentary" || v === "final_answer" ? v : undefined;
+}
+
 /**
  * `response_item/message.content` is an array of typed parts (`output_text`
  * for assistant replies). Concat the text parts with a blank-line separator.

package/src/providers/opencode/history.ts

@@ -1,3 +1,5 @@
+import { createHash } from "node:crypto";
+
 import type {
   AttachOptions,
   HistoryAttachment,
@@ -6,8 +8,9 @@ import type {
   HistoryCheckpoint,
   LastTurnStatus,
   SessionRecord,
-  StreamEvent,
 } from "../../types.js";
+import type { SavedHistoryEvent, SavedHistoryUserEvent } from "../../history/types.js";
+import { meaningfulHumanText } from "../../history/fs.js";
 import { assertSessionRecord, createSessionRecord, MalformedSessionRecordError } from "../../sessions/record.js";
 import { acquireOpenCodeRuntime } from "./runtime.js";
 import { opencodeSessionCodec } from "./codec.js";
@@ -18,7 +21,7 @@ const PAGE_SIZE = 100;
 const MAX_PAGES = 100;
 const MAX_MESSAGES = 10_000;
 const MAX_BYTES = 25 * 1024 * 1024;
-const CHECKPOINT_KIND = "opencode:message-part:v1";
+const CHECKPOINT_KIND = "opencode:message-part:v2";
 
 export class OpenCodeHistoryCheckpointNotFoundError extends Error {
   readonly code = "history_checkpoint_not_found";
@@ -36,17 +39,39 @@ export class OpenCodeHistoryResyncLimitError extends Error {
   }
 }
 
+export class OpenCodeHistorySourceMissingError extends Error {
+  readonly code = "source_missing";
+
+  constructor(sessionId: string) {
+    super(`OpenCode saved session ${JSON.stringify(sessionId)} no longer exists`);
+    this.name = "OpenCodeHistorySourceMissingError";
+  }
+}
+
 interface DecodedCheckpoint {
   messageId: string;
   partId: string;
   ordinal: number | null;
+  messageRevision: string;
 }
 
-export interface MessageEnvelope {
+export interface MessageEnvelope extends Record<string, unknown> {
   info?: Record<string, unknown>;
   parts?: unknown[];
 }
 
+interface HistoricalEvent {
+  event: SavedHistoryEvent;
+  partId: string;
+}
+
+export interface CollectedHistoryEvent {
+  event: SavedHistoryEvent;
+  checkpoint: HistoryCheckpoint;
+  eventId: string | null;
+  partIndex: number;
+}
+
 function rec(value: unknown): Record<string, unknown> | null {
   return value && typeof value === "object" && !Array.isArray(value)
     ? value as Record<string, unknown>
@@ -57,35 +82,118 @@ function string(value: unknown): string | null {
   return typeof value === "string" && value.length > 0 ? value : null;
 }
 
+function historicalTimestamp(info: Record<string, unknown>): string {
+  const created = rec(info["time"])?.["created"];
+  if (typeof created === "number" && Number.isFinite(created)) {
+    const timestamp = new Date(created);
+    if (!Number.isNaN(timestamp.getTime())) return timestamp.toISOString();
+  }
+  return new Date(0).toISOString();
+}
+
 function decodeCheckpoint(checkpoint: HistoryCheckpoint | undefined): DecodedCheckpoint | null {
   if (!checkpoint) return null;
   if (checkpoint.kind !== CHECKPOINT_KIND) throw new OpenCodeHistoryCheckpointNotFoundError();
   const value = rec(checkpoint.value);
   const messageId = string(value?.["messageId"]);
   const partId = string(value?.["partId"]);
-  if (!messageId || !partId) throw new OpenCodeHistoryCheckpointNotFoundError();
+  const messageRevision = string(value?.["messageRevision"]);
+  if (!messageId || !partId || !messageRevision) throw new OpenCodeHistoryCheckpointNotFoundError();
   const ordinal = typeof value?.["ordinal"] === "number" && Number.isInteger(value["ordinal"])
     ? value["ordinal"] as number
     : null;
-  return { messageId, partId, ordinal };
+  return { messageId, partId, ordinal, messageRevision };
+}
+
+function checkpoint(
+  messageId: string,
+  partId: string,
+  ordinal: number,
+  messageRevision: string,
+): HistoryCheckpoint {
+  return {
+    kind: CHECKPOINT_KIND,
+    value: { messageId, partId, ordinal, messageRevision },
+  };
+}
+
+function canonicalJson(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalJson);
+  const record = rec(value);
+  if (record) {
+    return Object.fromEntries(
+      Object.keys(record).sort().map((key) => [key, canonicalJson(record[key])]),
+    );
+  }
+  return value;
 }
 
-function checkpoint(messageId: string, partId: string, ordinal: number): HistoryCheckpoint {
-  return { kind: CHECKPOINT_KIND, value: { messageId, partId, ordinal } };
+function messageRevision(message: MessageEnvelope): string {
+  return createHash("sha256")
+    .update(JSON.stringify(canonicalJson(message)))
+    .digest("hex");
 }
 
-export function historicalEvents(message: MessageEnvelope, sessionId: string): Array<{ event: StreamEvent; partId: string }> {
+function userTextPart(part: Record<string, unknown>): string | null {
+  if (part["synthetic"] === true || part["ignored"] === true) return null;
+  if (part["type"] === "text") return string(part["text"]);
+  if (part["type"] === "subtask") return string(part["prompt"]);
+  return null;
+}
+
+function historicalUserEvent(
+  message: MessageEnvelope,
+  sessionId: string,
+  timestamp: string,
+): HistoricalEvent | null {
   const info = message.info ?? {};
-  if (info["role"] !== "assistant") return [];
   const messageId = string(info["id"]);
-  const timestamp = new Date(
-    typeof rec(info["time"])?.["created"] === "number"
-      ? rec(info["time"])!["created"] as number
-      : Date.now(),
-  ).toISOString();
+  const texts: string[] = [];
+  let partId: string | null = null;
+  for (const rawPart of Array.isArray(message.parts) ? message.parts : []) {
+    const part = rec(rawPart);
+    const text = part ? userTextPart(part) : null;
+    if (!part || !text) continue;
+    const candidatePartId = string(part["id"]);
+    if (!candidatePartId) continue;
+    texts.push(text);
+    partId = candidatePartId;
+  }
+  const text = meaningfulHumanText(texts.join("\n\n"));
+  if (!text || !partId) return null;
+  const eventId = messageId ?? partId;
+  const event: SavedHistoryUserEvent = {
+    type: "user",
+    text,
+    timestamp,
+    providerType: "opencode",
+    sessionId,
+    messageId,
+    eventId,
+    turnId: null,
+    parentToolCallId: null,
+    raw: message,
+  };
+  return { event, partId };
+}
+
+export function historicalEvents(
+  message: MessageEnvelope,
+  sessionId: string,
+  options: { includeUserMessages?: boolean } = {},
+): HistoricalEvent[] {
+  const info = rec(message.info) ?? {};
+  const messageId = string(info["id"]);
+  const timestamp = historicalTimestamp(info);
+  if (info["role"] === "user") {
+    if (!options.includeUserMessages) return [];
+    const user = historicalUserEvent(message, sessionId, timestamp);
+    return user ? [user] : [];
+  }
+  if (info["role"] !== "assistant") return [];
   const base: OcBaseInfo = { provider: "opencode", sessionId, timestamp };
-  const events: Array<{ event: StreamEvent; partId: string }> = [];
-  for (const rawPart of message.parts ?? []) {
+  const events: HistoricalEvent[] = [];
+  for (const rawPart of Array.isArray(message.parts) ? message.parts : []) {
     const part = rec(rawPart);
     const partId = string(part?.["id"]);
     if (!part || !partId) continue;
@@ -99,7 +207,8 @@ export function historicalEvents(message: MessageEnvelope, sessionId: string): A
     if (event) events.push({ event, partId });
   }
   const lastPartId = events.at(-1)?.partId;
-  if (messageId && lastPartId) {
+  const finished = string(info["finish"]) !== null || info["error"] != null;
+  if (messageId && lastPartId && finished) {
     const error = info["error"] != null;
     events.push({
       partId: lastPartId,
@@ -130,7 +239,11 @@ export async function collectHistory(
   client: import("./client.js").OpenCodeClient,
   sessionId: string,
   options: HistoryCatchUpOptions | undefined,
-): Promise<Array<{ event: StreamEvent; checkpoint: HistoryCheckpoint; eventId: string | null }>> {
+  mapping: {
+    includeUserMessages?: boolean;
+    missingSession?: "empty" | "error";
+  } = {},
+): Promise<CollectedHistoryEvent[]> {
   const after = options?.mode === "bounded_full_resync" ? null : decodeCheckpoint(options?.after);
   const pages: MessageEnvelope[][] = [];
   let before: string | null = null;
@@ -142,7 +255,12 @@ export async function collectHistory(
     const query = new URLSearchParams({ limit: String(PAGE_SIZE) });
     if (before) query.set("before", before);
     const response = await client.request(`/session/${encodeURIComponent(sessionId)}/message?${query}`);
-    if (response.status === 404) return [];
+    if (response.status === 404) {
+      if (mapping.missingSession === "error") {
+        throw new OpenCodeHistorySourceMissingError(sessionId);
+      }
+      return [];
+    }
     if (!response.ok) throw new Error(`OpenCode history request failed (${response.status})`);
     const text = await response.text();
     collectedBytes += Buffer.byteLength(text);
@@ -171,13 +289,21 @@ export async function collectHistory(
   }
 
   const messages = pages.reverse().flat();
-  const output: Array<{ event: StreamEvent; checkpoint: HistoryCheckpoint; eventId: string | null }> = [];
+  const output: CollectedHistoryEvent[] = [];
   let passedCheckpoint = after === null;
   let foundPart = after === null;
   for (const message of messages) {
     const messageId = string(message.info?.["id"]);
     if (!messageId) continue;
-    const events = historicalEvents(message, sessionId);
+    const revision = messageRevision(message);
+    if (
+      after
+      && messageId === after.messageId
+      && revision !== after.messageRevision
+    ) {
+      throw new OpenCodeHistoryCheckpointNotFoundError();
+    }
+    const events = historicalEvents(message, sessionId, mapping);
     const partOrdinals = new Map<string, number>();
     for (const item of events) {
       const ordinal = partOrdinals.get(item.partId) ?? 0;
@@ -204,8 +330,9 @@ export async function collectHistory(
       }
       output.push({
         event: item.event,
-        checkpoint: checkpoint(messageId, item.partId, ordinal),
+        checkpoint: checkpoint(messageId, item.partId, ordinal, revision),
         eventId: item.event.eventId,
+        partIndex: ordinal,
       });
     }
     if (foundPart && messageId === after?.messageId) passedCheckpoint = true;
@@ -256,7 +383,13 @@ export async function attachOpenCodeHistory(
     catchUp(options) {
       return {
         async *[Symbol.asyncIterator](): AsyncIterator<HistoryCatchUpYield> {
-          for (const yielded of await collectHistory(runtime.server.client, sessionId, options)) yield yielded;
+          for (const yielded of await collectHistory(runtime.server.client, sessionId, options)) {
+            // Known-session catch-up deliberately excludes user prompts. The
+            // host already owns them. `savedHistory.read()` opts in to users
+            // when importing a conversation the host did not create.
+            const event = yielded.event;
+            if (event.type !== "user") yield { ...yielded, event };
+          }
         },
       };
     },

package/src/providers/opencode/index.ts

@@ -20,6 +20,7 @@ export const opencodeProvider: ProviderModule = {
     modes: true,
     goals: EMULATED_GOAL_CAPABILITY,
     durableHistory: true,
+    savedHistory: true,
     resume: true,
     modelVariants: true,
     permissionRequests: true,
@@ -50,4 +51,20 @@ export const opencodeProvider: ProviderModule = {
     disconnect: (providerId, ctx) => import("./manager.js").then((m) => m.openCodeUpstreamProviders.disconnect(providerId, ctx)),
   },
   attachHistory: (record, options) => import("./history.js").then((m) => m.attachOpenCodeHistory(record, options)),
+  savedHistory: {
+    probe: (options) => import("./saved-history.js")
+      .then((module) => module.openCodeSavedHistory.probe(options)),
+    discover: (options) => ({
+      async *[Symbol.asyncIterator]() {
+        const module = await import("./saved-history.js");
+        yield* module.openCodeSavedHistory.discover(options);
+      },
+    }),
+    read: (session, options) => ({
+      async *[Symbol.asyncIterator]() {
+        const module = await import("./saved-history.js");
+        yield* module.openCodeSavedHistory.read(session, options);
+      },
+    }),
+  },
 };