agents 0.12.3 → 0.13.0

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

@@ -1,26 +1,74 @@
-import { A as SessionOptions, C as AgentSessionProvider, D as StoredCompaction, E as SessionProvider, O as SessionMessage, S as isSearchProvider, T as SearchResult, _ as R2SkillProvider, b as AgentSearchProvider, f as ContextBlock, g as isWritableProvider, h as WritableContextProvider, k as SessionMessagePart, m as ContextProvider, p as ContextConfig, r as CompactResult, v as SkillProvider, w as SqlProvider, x as SearchProvider, y as isSkillProvider } from "../../../compaction-helpers-CzCq1-fF.js";
+import {
+  A as SessionOptions,
+  C as AgentSessionProvider,
+  D as StoredCompaction,
+  E as SessionProvider,
+  O as SessionMessage,
+  S as isSearchProvider,
+  T as SearchResult,
+  _ as R2SkillProvider,
+  b as AgentSearchProvider,
+  f as ContextBlock,
+  g as isWritableProvider,
+  h as WritableContextProvider,
+  k as SessionMessagePart,
+  m as ContextProvider,
+  p as ContextConfig,
+  r as CompactResult,
+  v as SkillProvider,
+  w as SqlProvider,
+  x as SearchProvider,
+  y as isSkillProvider
+} 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 })
@@ -32,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;
@@ -42,38 +98,77 @@ declare class Session {
    * Register a compaction function. Called by `compact()` to compress
    * message history into a summary overlay.
    */
-  onCompaction(fn: (messages: SessionMessage[]) => Promise<CompactResult | null>): this;
+  onCompaction(
+    fn: (messages: SessionMessage[]) => Promise<CompactResult | null>
+  ): this;
   /**
    * Auto-compact when estimated token count exceeds the threshold.
    * 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;
-  appendMessage(message: SessionMessage, parentId?: string | null): Promise<void>;
-  updateMessage(message: SessionMessage): void;
-  deleteMessages(messageIds: string[]): void;
-  clearMessages(): void;
-  addCompaction(summary: string, fromMessageId: string, toMessageId: string): StoredCompaction;
-  getCompactions(): StoredCompaction[];
+  appendMessage(
+    message: SessionMessage,
+    parentId?: string | null
+  ): Promise<void>;
+  private _appendMessage;
+  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[]>;
   /**
    * Run the registered compaction function and store the result as an overlay.
    * Requires `onCompaction()` to be called first.
@@ -85,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
@@ -95,7 +195,10 @@ declare class Session {
    * AgentContextProvider. Requires the session to have been created
    * via `Session.create(agent)` (not the direct constructor).
    */
-  addContext(label: string, options?: SessionContextOptions): Promise<ContextBlock>;
+  addContext(
+    label: string,
+    options?: SessionContextOptions
+  ): Promise<ContextBlock>;
   /**
    * Remove a dynamically registered context block.
    * Used during extension unload cleanup.
@@ -108,22 +211,33 @@ 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(query: string, options?: {
-    limit?: number;
-  }): Array<{
-    id: string;
-    role: string;
-    content: string;
-    createdAt?: string;
-  }>;
+  search(
+    query: string,
+    options?: {
+      limit?: number;
+    }
+  ): Promise<
+    Array<{
+      id: string;
+      role: string;
+      content: string;
+      createdAt?: string;
+    }>
+  >;
   /** Returns set_context and load_context tools. */
   tools(): Promise<ToolSet>;
 }
@@ -178,7 +292,9 @@ declare class SessionManager {
    * Register a compaction function propagated to all sessions.
    * Called by `Session.compact()` to compress message history.
    */
-  onCompaction(fn: (messages: SessionMessage[]) => Promise<CompactResult | null>): this;
+  onCompaction(
+    fn: (messages: SessionMessage[]) => Promise<CompactResult | null>
+  ): this;
   /**
    * Auto-compact when estimated token count exceeds the threshold.
    * Propagated to all sessions. Requires `onCompaction()`.
@@ -205,35 +321,71 @@ declare class SessionManager {
   private _createHistoryProvider;
   /** Get or create the Session instance for a session ID. */
   getSession(sessionId: string): Session;
-  create(name: string, opts?: {
-    parentSessionId?: string;
-    model?: string;
-    source?: string;
-  }): SessionInfo;
+  create(
+    name: string,
+    opts?: {
+      parentSessionId?: string;
+      model?: string;
+      source?: string;
+    }
+  ): 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, message: SessionMessage, parentId?: string): Promise<string>;
-  upsert(sessionId: string, message: SessionMessage, parentId?: string): Promise<string>;
-  appendAll(sessionId: string, 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[];
+  append(
+    sessionId: string,
+    message: SessionMessage,
+    parentId?: string
+  ): Promise<string>;
+  upsert(
+    sessionId: string,
+    message: SessionMessage,
+    parentId?: string
+  ): Promise<string>;
+  appendAll(
+    sessionId: string,
+    messages: SessionMessage[],
+    parentId?: string
+  ): Promise<string | null>;
+  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.
    */
-  fork(sessionId: string, atMessageId: string, newName: string): Promise<SessionInfo>;
-  addCompaction(sessionId: string, summary: string, fromId: string, toId: string): StoredCompaction;
-  getCompactions(sessionId: string): StoredCompaction[];
-  compactAndSplit(sessionId: string, summary: string, newName?: string): Promise<SessionInfo>;
-  addUsage(sessionId: string, inputTokens: number, outputTokens: number, cost: number): void;
-  search(query: string, options?: {
-    limit?: number;
-  }): {
+  fork(
+    sessionId: string,
+    atMessageId: string,
+    newName: string
+  ): Promise<SessionInfo>;
+  addCompaction(
+    sessionId: string,
+    summary: string,
+    fromId: string,
+    toId: string
+  ): Promise<StoredCompaction>;
+  getCompactions(sessionId: string): Promise<StoredCompaction[]>;
+  compactAndSplit(
+    sessionId: string,
+    summary: string,
+    newName?: string
+  ): Promise<SessionInfo>;
+  addUsage(
+    sessionId: string,
+    inputTokens: number,
+    outputTokens: number,
+    cost: number
+  ): void;
+  search(
+    query: string,
+    options?: {
+      limit?: number;
+    }
+  ): {
     id: string;
     role: string;
     content: string;
@@ -255,5 +407,166 @@ declare class AgentContextProvider implements WritableContextProvider {
   set(content: string): Promise<void>;
 }
 //#endregion
-export { AgentContextProvider, AgentSearchProvider, AgentSessionProvider, type ContextBlock, type ContextConfig, type ContextProvider, R2SkillProvider, type SearchProvider, type SearchResult, Session, type SessionContextOptions, type SessionInfo, SessionManager, type SessionManagerOptions, type SessionMessage, type SessionMessagePart, type SessionOptions, type SessionProvider, type SkillProvider, type SqlProvider, type StoredCompaction, type WritableContextProvider, isSearchProvider, isSkillProvider, isWritableProvider };
-//# sourceMappingURL=index.d.ts.map
+//#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,
+  AgentSessionProvider,
+  type ContextBlock,
+  type ContextConfig,
+  type ContextProvider,
+  type PgClientLike,
+  type PostgresClient,
+  type PostgresConnection,
+  PostgresContextProvider,
+  PostgresSearchProvider,
+  PostgresSessionProvider,
+  R2SkillProvider,
+  type SearchProvider,
+  type SearchResult,
+  Session,
+  type SessionContextOptions,
+  type SessionInfo,
+  SessionManager,
+  type SessionManagerOptions,
+  type SessionMessage,
+  type SessionMessagePart,
+  type SessionOptions,
+  type SessionProvider,
+  type SkillProvider,
+  type SqlProvider,
+  type StoredCompaction,
+  type WritableContextProvider,
+  isSearchProvider,
+  isSkillProvider,
+  isWritableProvider
+};
+//# sourceMappingURL=index.d.ts.map