agents 0.25.0 → 0.27.0

package/dist/sessions/index.d.ts

@@ -1,4 +1,4 @@
-import { s as LifecycleCapability } from "../capability-runner-DBAnGr6L.js";
+import { s as LifecycleCapability } from "../capability-runner-O5VbQzqg.js";
 import {
   a as RecentHistoryResult,
   c as SessionChangeListener,
@@ -15,440 +15,17 @@ import {
   t as AppendOptions,
   u as SessionMessagePart
 } from "../types-B7LojTe4.js";
+import {
+  a as CompactOptions,
+  c as isCompactionMessage,
+  i as COMPACTION_PREFIX,
+  n as Session,
+  o as CompactResult,
+  r as SessionMirrorOptions,
+  s as createCompactFunction,
+  t as CompactionFunction
+} from "../handle-zAzh0UW2.js";
 
-//#region src/sessions/compaction-helpers.d.ts
-/** Prefix for all compaction messages (overlays and summaries) */
-declare const COMPACTION_PREFIX = "compaction_";
-/** Check if a message is a compaction message */
-declare function isCompactionMessage(msg: SessionMessage): boolean;
-/**
- * Result of a compaction function — describes the overlay to store.
- */
-interface CompactResult {
-  /** First message ID in the compacted range */
-  fromMessageId: string;
-  /** Last message ID in the compacted range */
-  toMessageId: string;
-  /** Summary text to store as the overlay */
-  summary: string;
-}
-interface CompactOptions {
-  /** Calls the model to summarize; receives a prompt, returns its text. */
-  summarize: (prompt: string) => Promise<string>;
-  /**
-   * Token budget for the recent tail kept verbatim. Older messages above the
-   * protected head are summarized into one overlay. Default 20,000.
-   */
-  keepRecentTokens?: number;
-}
-/**
- * Reference compaction implementation.
- *
- * Implements the full hermes-style compaction algorithm:
- * 1. Protect head messages (first N)
- * 2. Protect tail by token budget (walk backward)
- * 3. Align boundaries to tool call groups
- * 4. Summarize middle section with LLM (structured format)
- * 5. Iterative summary updates on subsequent compactions
- *
- * @example
- * ```typescript
- * import { createCompactFunction } from "agents/sessions";
- *
- * sessions
- *   .session()
- *   .onCompaction(
- *     createCompactFunction({
- *       summarize: (prompt) => generateText({ model, prompt }).then((r) => r.text)
- *     })
- *   )
- *   .compactAfter(100_000);
- * ```
- */
-declare function createCompactFunction(
-  opts: CompactOptions
-): (messages: SessionMessage[]) => Promise<CompactResult | null>;
-//#endregion
-//#region src/sessions/io.d.ts
-/** @internal SQLite and telemetry supplied by the Sessions capability. */
-type SqlParam = ArrayBuffer | string | number | null;
-interface SessionsIo {
-  /** Run a read and return every row. */
-  sql<T>(query: string, params: SqlParam[]): T[];
-  /** Run a write (or DDL) and return the rows it wrote. */
-  sqlWrite(query: string, params: SqlParam[]): number;
-  /** One synchronous SQLite transaction. */
-  transaction<T>(fn: () => T): T;
-  /** Capability telemetry event. */
-  emit(type: string, payload: Record<string, unknown>): void;
-}
-//#endregion
-//#region src/sessions/core.d.ts
-type UpdateOutcome = "missing" | "unchanged" | "updated";
-declare class SessionsCore {
-  #private;
-  readonly io: SessionsIo;
-  constructor(options: SessionsOptions, io: SessionsIo);
-  ensureTables(): void;
-  /**
-   * Lift the legacy `assistant_*` message and compaction tables.
-   *
-   * The copy is pure SQL, so SQLite streams it rather than materializing rows
-   * in the isolate. Each source is then verified row by row against its
-   * destination and DROPPED: keeping tombstones would leave every upgraded
-   * object holding its history twice inside the same 10 GB. A table whose
-   * verification fails is left in place with a `session:migration:incomplete`
-   * event, and the method returns false so the caller leaves the schema
-   * version unstamped and retries on a later start. `assistant_config`
-   * belongs to Think, which lifts and drops it itself.
-   */
-  migrateLegacy(): boolean;
-  subscribe(listener: SessionChangeListener): () => void;
-  /**
-   * Dispatch after a durable write. A listener that throws must not turn a
-   * committed write into a rejected call, so failures are reported through
-   * telemetry and dispatch continues.
-   */
-  notify(event: SessionChangeEvent): Promise<void>;
-  exists(sessionId: string, id: string): boolean;
-  getMessage(sessionId: string, id: string): SessionMessage | null;
-  /**
-   * Drop the in-memory tail and token-total caches for a session. For a
-   * caller whose enclosing transaction rolled back after an append or update
-   * ran inside it: the rows are gone but the caches already moved. The next
-   * read re-derives both from storage.
-   */
-  forgetCaches(sessionId: string): void;
-  latestLeafId(sessionId: string): string | null;
-  getLatestLeaf(sessionId: string): SessionMessage | null;
-  getBranches(sessionId: string, messageId: string): SessionMessage[];
-  /**
-   * The active branch path as content-free rows, root → leaf. Recurses over
-   * (id, parent_id) only — carrying content through the recursive queue
-   * materializes the transcript several times inside SQLite (#1710).
-   * `bytes` counts the message row, its continuation rows, AND the payloads
-   * it points at, charged at the size they take once inlined, so a byte
-   * budget over these rows bounds real hydrated memory.
-   */
-  pathRowStats(sessionId: string, leafId?: string | null): SessionRowStat[];
-  /**
-   * Stream the path ending at `leafId` (default: active leaf), root → leaf
-   * (or leaf → root with `newestFirst`), compaction overlays collapsed. Peak
-   * memory is one bounded content window — never the whole transcript.
-   */
-  streamHistory(
-    sessionId: string,
-    options: HistoryReadOptions
-  ): AsyncGenerator<SessionMessage, void, undefined>;
-  getHistory(
-    sessionId: string,
-    options: HistoryReadOptions
-  ): Promise<SessionMessage[]>;
-  /**
-   * Byte-budgeted read of the most recent messages on the active branch
-   * path — the longest suffix whose stored size fits `maxContentBytes`.
-   *
-   * There is no message-count floor: one used to exist, and it admitted
-   * rows regardless of size, so a window of media-heavy messages could
-   * hydrate far past the limit meant to bound it. The newest message is
-   * always returned even if it alone exceeds the budget, since returning
-   * nothing is worse. Overlays whose anchors fall outside the window are
-   * skipped, showing the raw recent messages.
-   */
-  getRecentHistory(
-    sessionId: string,
-    maxContentBytes: number,
-    leafId?: string | null
-  ): Promise<RecentHistoryResult>;
-  /**
-   * Heuristic token estimate for the active path with compaction overlays
-   * applied: stamped per-row estimates, minus compacted spans, plus their
-   * summaries. Derived from content-free rows on each call; it gates cheap
-   * triggers only, and model-reported usage stays authoritative.
-   */
-  tokenEstimate(sessionId: string): number;
-  stripReservedMetadata(message: SessionMessage): SessionMessage;
-  /**
-   * Stamped row estimate: the part heuristic over the message as written,
-   * plus a weight per inline file payload so media never counts as zero.
-   */
-  estimateRowTokens(message: SessionMessage): number;
-  /**
-   * Durable append. The caller has already sanitized the message. Message,
-   * continuation, attachment, and FTS rows commit in one synchronous SQLite
-   * transaction. Returns the stored message: the input itself when it was
-   * inserted (extraction is lossless, so the two are identical), or the row
-   * already holding the id when it was not.
-   */
-  append(
-    sessionId: string,
-    message: SessionMessage,
-    parentId: string | null | undefined,
-    tokenEstimate: number
-  ): {
-    inserted: boolean;
-    message: SessionMessage;
-  };
-  /**
-   * Durable update of an existing row. An identical row writes nothing: no
-   * row, no continuation, no FTS, no event. The no-op guard compares the
-   * FULL content, through the digest the last write stamped, so neither the
-   * payload nor a continuation row is read. A row without a digest compares
-   * the reassembled content once and is stamped.
-   */
-  update(
-    sessionId: string,
-    message: SessionMessage,
-    tokenEstimate: number
-  ): UpdateOutcome;
-  /**
-   * Delete rows, SPLICING children to their grandparent so a mid-chain
-   * delete never decapitates older history. Only surviving boundary children
-   * are rewired: a prefix delete writes one boundary child, not one child
-   * per deleted message.
-   */
-  deleteMessages(sessionId: string, messageIds: string[]): void;
-  clearMessages(sessionId: string): void;
-  addCompaction(
-    sessionId: string,
-    summary: string,
-    fromMessageId: string,
-    toMessageId: string
-  ): StoredCompaction;
-  getCompactions(sessionId: string): StoredCompaction[];
-  search(sessionId: string, query: string, limit: number): SearchResult[];
-  /**
-   * Import one historical message verbatim (migrations, cross-DO moves):
-   * explicit parent and timestamp, stamped estimate, no change-feed events.
-   */
-  /** Returns `false` when the id already exists and nothing was written. */
-  importMessage(
-    sessionId: string,
-    message: SessionMessage,
-    options: {
-      parentId: string | null;
-      createdAt: number;
-    }
-  ): boolean;
-}
-//#endregion
-//#region src/sessions/mirror.d.ts
-/**
- * How a host keeps an in-memory transcript in step with one session's change
- * feed. The mirror applies the reduction every such cache needs; the hooks
- * carry the decisions only the host can make.
- */
-interface SessionMirrorOptions<
-  M extends {
-    id: string;
-  }
-> {
-  /**
-   * The cached transcript. Read on every event, so a host that reassigns its
-   * array (a public `messages` field, say) is followed rather than
-   * shadowed.
-   */
-  get(): M[];
-  /** Install a new array: after a delete, or emptied by a clear. */
-  set(messages: M[]): void;
-  /** The cached form of a stored message. Defaults to the stored message. */
-  transform?(message: SessionMessage): M;
-  /**
-   * Handle an event instead of the default reduction, returning `true` when
-   * it did. A host whose cache cannot express a change in place — a branch
-   * append, a compaction — re-reads storage here.
-   */
-  intercept?(event: SessionChangeEvent): boolean | Promise<boolean>;
-  /**
-   * After the default reduction wrote `message` for an append or update.
-   * `previous` is the cached entry it replaced, if there was one.
-   */
-  onApplied?(
-    event: Extract<
-      SessionChangeEvent,
-      {
-        type: "append" | "update";
-      }
-    >,
-    message: M,
-    previous: M | undefined
-  ): void;
-}
-//#endregion
-//#region src/sessions/handle.d.ts
-/** Summarizes a branch into an overlay. */
-type CompactionFunction = (
-  messages: SessionMessage[]
-) => Promise<CompactResult | null>;
-declare class Session {
-  #private;
-  readonly sessionId: string;
-  /** @internal Constructed by the Sessions capability only. */
-  constructor(
-    sessionId: string,
-    core: SessionsCore,
-    ready: () => Promise<void>
-  );
-  /** Register the function `compact()` calls to summarize a branch. */
-  onCompaction(fn: CompactionFunction): this;
-  /**
-   * Auto-compact after an append once the estimated token count crosses the
-   * threshold. Requires `onCompaction()`. The estimate is derived from the
-   * stamped per-row estimates, never from the transcript.
-   */
-  compactAfter(tokenThreshold: number): this;
-  /**
-   * Keep an in-memory transcript in step with this session's change feed,
-   * so write sites never hand-patch it. Returns the unsubscribe function.
-   */
-  mirror<
-    M extends {
-      id: string;
-    }
-  >(options: SessionMirrorOptions<M>): () => void;
-  /**
-   * Stream the active branch path root → leaf (leaf → root with
-   * `newestFirst`) with compaction overlays applied. Peak memory is one
-   * bounded content window, never the whole transcript, and a consumer that
-   * breaks out early leaves the rows it never reached unread.
-   */
-  history(
-    options?: HistoryReadOptions
-  ): AsyncGenerator<SessionMessage, void, undefined>;
-  /**
-   * Stream history in bounded non-empty batches. Both message count and
-   * serialized bytes bound each batch; a single large message is yielded by
-   * itself.
-   */
-  historyBatches(
-    options?: HistoryBatchReadOptions
-  ): AsyncGenerator<SessionMessage[], void, undefined>;
-  /**
-   * Materialize the whole selected path. Prefer `history()` or
-   * `getRecentHistory()` inside a Durable Object: this holds every message
-   * of the branch in memory at once.
-   */
-  getHistory(options?: HistoryReadOptions): Promise<SessionMessage[]>;
-  /**
-   * Byte-budgeted read of the most recent messages on the active branch path
-   * (always at least the leaf). The budget counts each row, its continuation
-   * rows, and the payloads it points at, so it bounds hydrated memory (#1710).
-   */
-  getRecentHistory(
-    maxContentBytes: number,
-    options?: Pick<HistoryReadOptions, "leafId">
-  ): Promise<RecentHistoryResult>;
-  /**
-   * Per-row stored sizes (row plus continuation rows and attachments) and
-   * stamped token estimates for the active branch path (root → leaf)
-   * WITHOUT loading message content.
-   */
-  getHistoryRowStats(leafId?: string | null): Promise<SessionRowStat[]>;
-  getMessage(id: string): Promise<SessionMessage | null>;
-  getLatestLeaf(): Promise<SessionMessage | null>;
-  getBranches(messageId: string): Promise<SessionMessage[]>;
-  /**
-   * Full-text search over this session's text parts. The index is built on
-   * the first call and maintained from then on.
-   */
-  search(
-    query: string,
-    options?: {
-      limit?: number;
-    }
-  ): Promise<SearchResult[]>;
-  /**
-   * Append one message. Idempotent on id: a repeated append returns the row
-   * already stored and dispatches an `append` event with `inserted: false`.
-   *
-   * A compaction overlay (a `compaction_` id) is derived on read and is never
-   * stored. Clients post their transcript back after every compaction, so
-   * this and every other write drops one silently: nothing is written and no
-   * event is dispatched.
-   */
-  appendMessage(
-    message: SessionMessage,
-    options?: AppendOptions
-  ): Promise<AppendResult>;
-  /**
-   * Update one stored row. Returns the stored form, or `null` when the id is
-   * not in this session. An unchanged message writes nothing and dispatches
-   * no event. A compaction overlay is never a stored row, so it reports
-   * `null`.
-   */
-  updateMessage(
-    message: SessionMessage,
-    options?: WriteOptions
-  ): Promise<SessionMessage | null>;
-  /**
-   * @internal Synchronous write aperture for same-isolate first-party
-   * machinery that must commit a message inside a caller-owned SQLite
-   * transaction — the stream cutover, where the finished message and the
-   * discard of its stream rows land together. Bypasses readiness (the
-   * caller owns startup ordering) and defers everything that follows a
-   * write — the change-feed dispatch and auto-compaction: call the returned
-   * `after()` once the transaction commits, or subscribers (the host's
-   * message mirror) never hear about the write. If the transaction rolls
-   * back after an `upsert` ran inside it, call `abandon()`: the write is
-   * gone but the in-memory tail and token-total caches already moved.
-   * Will break without notice; never use from application code.
-   */
-  __DO_NOT_USE_WILL_BREAK__sync(): {
-    upsert(
-      message: SessionMessage,
-      options?: AppendOptions
-    ): {
-      result: AppendResult;
-      after: () => Promise<void>;
-    };
-    abandon(): void;
-  };
-  upsertMessage(
-    message: SessionMessage,
-    options?: AppendOptions
-  ): Promise<AppendResult>;
-  /**
-   * Import one historical message verbatim (migrations, cross-object moves):
-   * explicit parent and timestamp. A row actually written dispatches an
-   * `import` change event so a host cache can mark itself stale; it is not
-   * an `append`, so a cache does not patch itself per imported row, and an
-   * id that already exists writes nothing and dispatches nothing.
-   *
-   * Unlike the other writes, a `compaction_` id is imported as given: a
-   * summary copied from another session's `history()` is the only record of
-   * the context it replaced, and later rows may be parented to it. History
-   * reads hide such a row only when it duplicates one of this session's own
-   * compaction overlays.
-   */
-  importMessage(
-    message: SessionMessage,
-    options: {
-      parentId: string | null;
-      createdAt: number;
-    }
-  ): Promise<void>;
-  deleteMessages(messageIds: string[]): Promise<void>;
-  clearMessages(): Promise<void>;
-  /**
-   * Store an overlay directly. Dispatches a `compaction` change event: the
-   * rows are untouched, but what a path read returns has changed.
-   */
-  addCompaction(
-    summary: string,
-    fromMessageId: string,
-    toMessageId: string
-  ): Promise<StoredCompaction>;
-  getCompactions(): Promise<StoredCompaction[]>;
-  /**
-   * Run the registered compaction function and store the result as an
-   * overlay. When `leafId` is given, compact that root-to-leaf branch instead
-   * of the active branch. Requires `onCompaction()`. A compaction function
-   * that throws is reported through the `session:error` capability event and
-   * the call returns `null`.
-   */
-  compact(leafId?: string | null): Promise<CompactResult | null>;
-}
-//#endregion
 //#region src/sessions/sessions.d.ts
 /**
  * Durable conversation history for a Lifecycle Object.