agents 0.12.4 → 0.13.1

package/dist/experimental/memory/session/index.d.ts

@@ -19,29 +19,56 @@ import {
   w as SqlProvider,
   x as SearchProvider,
   y as isSkillProvider
-} from "../../../compaction-helpers-bYvP1o2S.js";
+} from "../../../compaction-helpers-DAe-xiVY.js";
 import { ToolSet } from "ai";
 
 //#region src/experimental/memory/session/session.d.ts
 type SessionContextOptions = Omit<ContextConfig, "label">;
+type InternalMessageChangeEvent =
+  | {
+      type: "append";
+      message: SessionMessage;
+      parentId?: string | null;
+      inserted: boolean;
+    }
+  | {
+      type: "update";
+      message: SessionMessage;
+    }
+  | {
+      type: "delete";
+      messageIds: string[];
+    }
+  | {
+      type: "clear";
+    }
+  | {
+      type: "compact";
+    };
 declare class Session {
   private storage;
   private context;
   private _agent?;
   private _broadcaster?;
+  private _storageProvider?;
   private _sessionId?;
   private _pending?;
   private _cachedPrompt?;
   private _compactionFn?;
   private _tokenThreshold?;
   private _ready;
+  private _restorePromise?;
+  private _messageChangeListener?;
   constructor(storage: SessionProvider, options?: SessionOptions);
   /**
-   * Chainable session creation with auto-wired SQLite providers.
-   * Chain methods in any order — providers are resolved lazily on first use.
+   * Chainable session creation with auto-wired providers.
+   *
+   * Pass a `SqlProvider` (Agent with `sql` method) for auto-wired SQLite,
+   * or a `SessionProvider` directly for custom storage (Postgres, etc.).
    *
    * @example
    * ```ts
+   * // Auto-wired SQLite (DO Agent)
    * const session = Session.create(this)
    *   .withContext("soul", { provider: { get: async () => "You are helpful." } })
    *   .withContext("memory", { description: "Learned facts", maxTokens: 1100 })
@@ -53,9 +80,17 @@ declare class Session {
    *     provider: new R2SkillProvider(env.SKILLS_BUCKET, { prefix: "skills/" })
    *   })
    *   .withCachedPrompt();
+   *
+   * // Custom storage provider (Postgres, etc.)
+   * const session = Session.create(postgresProvider)
+   *   .withContext("memory", {
+   *     maxTokens: 1100,
+   *     provider: new PostgresContextProvider(conn, "memory")
+   *   })
+   *   .withCachedPrompt(new PostgresContextProvider(conn, "_prompt"));
    * ```
    */
-  static create(agent: SqlProvider): Session;
+  static create(provider: SqlProvider | SessionProvider): Session;
   forSession(sessionId: string): this;
   withContext(label: string, options?: SessionContextOptions): this;
   withCachedPrompt(provider?: WritableContextProvider): this;
@@ -71,23 +106,52 @@ declare class Session {
    * Checked after each `appendMessage`. Requires `onCompaction()`.
    */
   compactAfter(tokenThreshold: number): this;
+  /**
+   * @internal
+   * Framework hook for cache-owning callers that need to mirror message
+   * storage changes. Application code should use the normal Session methods.
+   */
+  internal_onMessagesChanged(
+    listener:
+      | ((event: InternalMessageChangeEvent) => void | Promise<void>)
+      | null
+  ): this;
   private _ensureReady;
+  /**
+   * Await the background skill-restore kicked off by `_ensureReady()`.
+   * Idempotent and cheap — every async public method calls this so that
+   * `_loadedSkills` reflects conversation history before any read or write.
+   */
+  private _ensureRestored;
+  private _notifyMessagesChanged;
   /**
    * Reconstruct which skills are loaded by scanning conversation history
    * for load_context tool results that haven't been unloaded.
-   * Called during init to survive hibernation/eviction.
+   * Runs once per init to survive hibernation / eviction, including for
+   * async SessionProviders (e.g. Postgres) where we must `await` history.
    */
   private _restoreLoadedSkills;
   /**
-   * Replace a load_context tool result in conversation history
-   * with a short marker to reclaim context space.
+   * Reclaim context-window tokens consumed by a previously loaded skill.
+   *
+   * When a skill is loaded via the `load_context` tool, its full body is
+   * embedded as that tool call's `output-available` result inside the
+   * assistant message — which means every subsequent turn replays the
+   * entire skill as part of the conversation history and pays for it in
+   * input tokens.
+   *
+   * This method walks back through history, finds the matching
+   * `load_context` tool result for `(label, key)`, and replaces its bulky
+   * `output` with a short marker `[skill unloaded: <key>]`. The skill
+   * content is dropped from future turns and the tokens are reclaimed.
+   * The skill itself stays available to reload via `load_context`.
    */
   private _reclaimLoadedSkill;
-  getHistory(leafId?: string | null): SessionMessage[];
-  getMessage(id: string): SessionMessage | null;
-  getLatestLeaf(): SessionMessage | null;
-  getBranches(messageId: string): SessionMessage[];
-  getPathLength(leafId?: string | null): number;
+  getHistory(leafId?: string | null): Promise<SessionMessage[]>;
+  getMessage(id: string): Promise<SessionMessage | null>;
+  getLatestLeaf(): Promise<SessionMessage | null>;
+  getBranches(messageId: string): Promise<SessionMessage[]>;
+  getPathLength(leafId?: string | null): Promise<number>;
   private _broadcast;
   private _emitStatus;
   private _emitError;
@@ -95,15 +159,16 @@ declare class Session {
     message: SessionMessage,
     parentId?: string | null
   ): Promise<void>;
-  updateMessage(message: SessionMessage): void;
-  deleteMessages(messageIds: string[]): void;
-  clearMessages(): void;
+  private _appendMessage;
+  updateMessage(message: SessionMessage): Promise<void>;
+  deleteMessages(messageIds: string[]): Promise<void>;
+  clearMessages(): Promise<void>;
   addCompaction(
     summary: string,
     fromMessageId: string,
     toMessageId: string
-  ): StoredCompaction;
-  getCompactions(): StoredCompaction[];
+  ): Promise<StoredCompaction>;
+  getCompactions(): Promise<StoredCompaction[]>;
   /**
    * Run the registered compaction function and store the result as an overlay.
    * Requires `onCompaction()` to be called first.
@@ -115,7 +180,12 @@ declare class Session {
   appendContextBlock(label: string, content: string): Promise<ContextBlock>;
   /**
    * Dynamically register a new context block after session initialization.
-   * Used by extensions to contribute context blocks at runtime.
+   *
+   * This is a **builder / runtime API**, not an LLM tool. The LLM writes
+   * into existing context blocks via the `set_context` tool (see
+   * `ContextBlocks.tools()`); it cannot declare new blocks itself. This
+   * method is how extension / host code contributes blocks at runtime
+   * (e.g. an extension's `onLoad` handler registering its own memory block).
    *
    * The block's provider is initialized and loaded immediately.
    * Call `refreshSystemPrompt()` afterward to include the new block
@@ -141,12 +211,18 @@ declare class Session {
   /**
    * Unload a previously loaded skill, reclaiming context space.
    * The tool result in conversation history is replaced with a short marker.
+   *
+   * Async so that the session's background skill-state restore (which
+   * reads conversation history) is awaited first — otherwise a freshly
+   * rehydrated DO could report "not loaded" for a skill that's actually
+   * present in history.
    */
-  unloadSkill(label: string, key: string): boolean;
+  unloadSkill(label: string, key: string): Promise<boolean>;
   /**
    * Get currently loaded skill keys (as "label:key" strings).
+   * Async for the same reason as `unloadSkill` — must wait for restore.
    */
-  getLoadedSkillKeys(): Set<string>;
+  getLoadedSkillKeys(): Promise<Set<string>>;
   freezeSystemPrompt(): Promise<string>;
   refreshSystemPrompt(): Promise<string>;
   search(
@@ -154,12 +230,14 @@ declare class Session {
     options?: {
       limit?: number;
     }
-  ): Array<{
-    id: string;
-    role: string;
-    content: string;
-    createdAt?: string;
-  }>;
+  ): Promise<
+    Array<{
+      id: string;
+      role: string;
+      content: string;
+      createdAt?: string;
+    }>
+  >;
   /** Returns set_context and load_context tools. */
   tools(): Promise<ToolSet>;
 }
@@ -253,7 +331,7 @@ declare class SessionManager {
   ): SessionInfo;
   get(sessionId: string): SessionInfo | null;
   list(): SessionInfo[];
-  delete(sessionId: string): void;
+  delete(sessionId: string): Promise<void>;
   rename(sessionId: string, name: string): void;
   append(
     sessionId: string,
@@ -270,11 +348,11 @@ declare class SessionManager {
     messages: SessionMessage[],
     parentId?: string
   ): Promise<string | null>;
-  getHistory(sessionId: string, leafId?: string): SessionMessage[];
-  getMessageCount(sessionId: string): number;
-  clearMessages(sessionId: string): void;
-  deleteMessages(sessionId: string, messageIds: string[]): void;
-  getBranches(sessionId: string, messageId: string): SessionMessage[];
+  getHistory(sessionId: string, leafId?: string): Promise<SessionMessage[]>;
+  getMessageCount(sessionId: string): Promise<number>;
+  clearMessages(sessionId: string): Promise<void>;
+  deleteMessages(sessionId: string, messageIds: string[]): Promise<void>;
+  getBranches(sessionId: string, messageId: string): Promise<SessionMessage[]>;
   /**
    * Fork a session at a specific message, creating a new session
    * with the history up to that point copied over.
@@ -289,8 +367,8 @@ declare class SessionManager {
     summary: string,
     fromId: string,
     toId: string
-  ): StoredCompaction;
-  getCompactions(sessionId: string): StoredCompaction[];
+  ): Promise<StoredCompaction>;
+  getCompactions(sessionId: string): Promise<StoredCompaction[]>;
   compactAndSplit(
     sessionId: string,
     summary: string,
@@ -329,6 +407,135 @@ declare class AgentContextProvider implements WritableContextProvider {
   set(content: string): Promise<void>;
 }
 //#endregion
+//#region src/experimental/memory/session/providers/postgres-adapter.d.ts
+/**
+ * Postgres connection adapter.
+ *
+ * Lets the Postgres-backed providers accept either:
+ *   - a raw `pg.Client` (or any client with a compatible `query` method), or
+ *   - the internal `PostgresConnection` interface used by tests and custom drivers.
+ *
+ * When a `pg`-style client is passed, `?` placeholders are rewritten to
+ * `$1, $2, ...` on the way through, so the providers can keep using the
+ * portable `?` syntax internally without users having to write a wrapper.
+ */
+/**
+ * Minimal connection interface used internally by the Postgres providers.
+ * Tests and custom drivers can implement this directly.
+ */
+interface PostgresConnection {
+  execute(
+    query: string,
+    args?: (string | number | boolean | null)[]
+  ): Promise<{
+    rows: Record<string, unknown>[];
+  }>;
+}
+/**
+ * Structural type matching `pg.Client` (and most `pg`-compatible pools).
+ * Accepts the subset of the real client that the providers need, so users
+ * can pass `new pg.Client({ connectionString: env.HYPERDRIVE.connectionString })`
+ * directly without a wrapper.
+ */
+interface PgClientLike {
+  query(
+    queryText: string,
+    values?: readonly unknown[]
+  ): Promise<{
+    rows: Record<string, unknown>[];
+  }>;
+}
+/**
+ * Accepted client type across the Postgres providers.
+ *
+ * Use `pg.Client` (the recommended path for Hyperdrive):
+ * ```ts
+ * const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
+ * await client.connect();
+ * new PostgresSessionProvider(client, sessionId);
+ * ```
+ *
+ * Or implement `PostgresConnection` for tests / bespoke drivers.
+ */
+type PostgresClient = PostgresConnection | PgClientLike;
+//#endregion
+//#region src/experimental/memory/session/providers/postgres.d.ts
+declare class PostgresSessionProvider implements SessionProvider {
+  private conn;
+  private sessionId;
+  /**
+   * @param client A raw `pg.Client` (recommended) or any `PostgresConnection`.
+   *   Must already be connected — this provider never opens or closes the
+   *   underlying client.
+   * @param sessionId Session identifier. Different ids are fully isolated
+   *   rows within the shared tables. Defaults to `""`.
+   */
+  constructor(client: PostgresClient, sessionId?: string);
+  getMessage(id: string): Promise<SessionMessage | null>;
+  getHistory(leafId?: string | null): Promise<SessionMessage[]>;
+  getLatestLeaf(): Promise<SessionMessage | null>;
+  getBranches(messageId: string): Promise<SessionMessage[]>;
+  getPathLength(leafId?: string | null): Promise<number>;
+  appendMessage(
+    message: SessionMessage,
+    parentId?: string | null
+  ): Promise<void>;
+  updateMessage(message: SessionMessage): Promise<void>;
+  deleteMessages(messageIds: string[]): Promise<void>;
+  clearMessages(): Promise<void>;
+  addCompaction(
+    summary: string,
+    fromMessageId: string,
+    toMessageId: string
+  ): Promise<StoredCompaction>;
+  getCompactions(): Promise<StoredCompaction[]>;
+  searchMessages(query: string, limit?: number): Promise<SearchResult[]>;
+  private latestLeafRow;
+  private applyCompactions;
+  private parse;
+  private parseRows;
+  /**
+   * Extract just the human-readable text from a message's JSON blob
+   * and store it in `text_content`, which feeds the generated `content_tsv`
+   * column used for FTS. The full structured message (parts, tool calls,
+   * metadata) is still stored verbatim in `content` — this is the source
+   * of truth. Indexing the raw JSON would return FTS hits on keys like
+   * `"role"`, `"parts"`, `"dynamic-tool"`, etc.
+   */
+  private extractSearchableText;
+}
+//#endregion
+//#region src/experimental/memory/session/providers/postgres-context.d.ts
+declare class PostgresContextProvider implements WritableContextProvider {
+  private conn;
+  private label;
+  /**
+   * @param client A raw `pg.Client` (recommended) or any `PostgresConnection`.
+   *   Must already be connected.
+   * @param label Block label used as the primary key row in
+   *   `cf_agents_context_blocks`. Pass a session-scoped label (e.g.
+   *   `` `memory_${sessionId}` ``) for per-session state.
+   */
+  constructor(client: PostgresClient, label: string);
+  get(): Promise<string | null>;
+  set(content: string): Promise<void>;
+}
+//#endregion
+//#region src/experimental/memory/session/providers/postgres-search.d.ts
+declare class PostgresSearchProvider implements SearchProvider {
+  private conn;
+  private label;
+  /**
+   * @param client A raw `pg.Client` (recommended) or any `PostgresConnection`.
+   *   Must already be connected.
+   */
+  constructor(client: PostgresClient);
+  init(label: string): void;
+  get(): Promise<string | null>;
+  search(query: string): Promise<string | null>;
+  set(key: string, content: string): Promise<void>;
+}
+//#endregion
 export {
   AgentContextProvider,
   AgentSearchProvider,
@@ -336,6 +543,12 @@ export {
   type ContextBlock,
   type ContextConfig,
   type ContextProvider,
+  type PgClientLike,
+  type PostgresClient,
+  type PostgresConnection,
+  PostgresContextProvider,
+  PostgresSearchProvider,
+  PostgresSessionProvider,
   R2SkillProvider,
   type SearchProvider,
   type SearchResult,