agents 0.24.0 → 0.26.0

package/dist/sessions/index.d.ts

@@ -1,4 +1,4 @@
-import { s as LifecycleCapability } from "../capability-runner-BUBa6Ake.js";
+import { s as LifecycleCapability } from "../capability-runner-DBAnGr6L.js";
 import {
   a as RecentHistoryResult,
   c as SessionChangeListener,
@@ -192,7 +192,9 @@ declare class SessionsCore {
   /**
    * 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 reassembled content, not just the slice the message row holds.
+   * 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,
@@ -230,6 +232,49 @@ declare class SessionsCore {
   ): 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 = (
@@ -252,6 +297,15 @@ declare class Session {
    * 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
@@ -306,6 +360,11 @@ declare class Session {
   /**
    * 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,
@@ -314,7 +373,8 @@ declare class Session {
   /**
    * 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.
+   * no event. A compaction overlay is never a stored row, so it reports
+   * `null`.
    */
   updateMessage(
     message: SessionMessage,
@@ -353,6 +413,12 @@ declare class Session {
    * `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,
@@ -430,6 +496,7 @@ export {
   type SessionChangeListener,
   type SessionMessage,
   type SessionMessagePart,
+  type SessionMirrorOptions,
   type SessionRowStat,
   Sessions,
   type SessionsOptions,