@agentex/agent 0.0.30 → 0.0.31

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/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);
+      },
+    }),
+  },
 };

package/src/providers/opencode/probe.ts

@@ -74,6 +74,10 @@ export async function probeOpenCodeCapabilities(
         questionRequests: capability(has("/question", "get") && has("/question/{requestID}/reply", "post")),
         upstreamProviderDisconnect: capability(supportsDisconnect),
         durableHistory: capability(has("/session/{sessionID}/message", "get")),
+        savedHistory: capability(
+          (has("/experimental/session", "get") || has("/session", "get"))
+          && has("/session/{sessionID}/message", "get"),
+        ),
         planMode: capability(agents.some((value) => {
           const agent = rec(value);
           return agent["name"] === "plan" || agent["id"] === "plan";