agents 0.21.0 → 0.23.0

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

@@ -1,670 +0,0 @@
-import {
-  A as StoredCompaction,
-  C as isSearchProvider,
-  D as RecentHistoryResult,
-  E as HistoryRowStat,
-  F as SessionMessagePart,
-  I as SessionOptions,
-  L as SessionTokenCounter,
-  M as CompactContext,
-  N as CompactionErrorHandler,
-  O as SearchResult,
-  P as SessionMessage,
-  R as SessionTokenCounterInput,
-  S as SearchProvider,
-  T as SqlProvider,
-  _ as isWritableProvider,
-  b as isSkillProvider,
-  g as WritableContextProvider,
-  h as ContextProvider,
-  j as CompactAfterOptions,
-  k as SessionProvider,
-  m as ContextConfig,
-  p as ContextBlock,
-  r as CompactResult,
-  v as R2SkillProvider,
-  w as AgentSessionProvider,
-  x as AgentSearchProvider,
-  y as SkillProvider
-} from "../../../compaction-helpers-wUz6M3us.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 _warnedCompactionNoOp;
-  private _tokenThreshold?;
-  private _tokenCounter?;
-  private _compactionErrorHandler?;
-  private _ready;
-  private _restorePromise?;
-  private _messageChangeListener?;
-  constructor(storage: SessionProvider, options?: SessionOptions);
-  /**
-   * 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 })
-   *   .withCachedPrompt();
-   *
-   * // Skills from R2 (on-demand loading via load_context tool)
-   * const session = Session.create(this)
-   *   .withContext("skills", {
-   *     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(provider: SqlProvider | SessionProvider): Session;
-  forSession(sessionId: string): this;
-  withContext(label: string, options?: SessionContextOptions): this;
-  withCachedPrompt(provider?: WritableContextProvider): this;
-  /**
-   * Register a compaction function. Called by `compact()` to compress
-   * message history into a summary overlay.
-   */
-  onCompaction(
-    fn: (
-      messages: SessionMessage[],
-      context?: CompactContext
-    ) => Promise<CompactResult | null>
-  ): this;
-  /**
-   * Auto-compact when estimated token count exceeds the threshold.
-   * Checked after each `appendMessage`. Requires `onCompaction()`.
-   *
-   * By default this uses a Workers-safe heuristic over stored messages plus
-   * the Session-managed frozen system prompt. Provide `tokenCounter` when you
-   * have model-reported usage or a tokenizer and need a stricter budget.
-   */
-  compactAfter(tokenThreshold: number, options?: CompactAfterOptions): this;
-  /**
-   * Handle failures from the automatic `compactAfter()` trigger.
-   *
-   * Manual `compact()` still reports errors through the existing session error
-   * broadcast path.
-   */
-  onCompactionError(handler: CompactionErrorHandler): 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.
-   * Runs once per init to survive hibernation / eviction, including for
-   * async SessionProviders (e.g. Postgres) where we must `await` history.
-   *
-   * Skipped entirely when no skill-capable provider is configured —
-   * `load_context` results can only exist when a skill block was registered,
-   * and the scan would otherwise read the whole transcript on every wake,
-   * bypassing byte-budgeted hydration (#1710). A skill block added later via
-   * `addContext()` triggers the scan at that point instead.
-   */
-  private _restoreLoadedSkills;
-  private _skillScanRan;
-  /**
-   * Scan stored history for load/unload_context tool results and restore
-   * the loaded-skill tracking set.
-   *
-   * Memory-bounded when the provider supports `getHistoryRowStats`: rows
-   * are enumerated without content, then only assistant rows are fetched
-   * and scanned ONE AT A TIME — peak memory is a single message instead of
-   * the whole transcript. Falls back to a full `getHistory()` read for
-   * providers without row stats (e.g. Postgres).
-   *
-   * Note: the bounded path scans raw path rows, so `load_context` results
-   * inside compacted ranges are still seen (the full-read path hides them
-   * behind compaction overlays). That superset is intentional — the stored
-   * tool result still exists and can be reclaimed by `unloadSkill`.
-   */
-  private _scanHistoryForLoadedSkills;
-  /**
-   * 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): Promise<SessionMessage[]>;
-  private _warnedNoRecentHistorySupport;
-  /**
-   * Byte-budgeted read of the most recent messages on the active branch
-   * path (always at least the leaf message, and at least
-   * `minRecentMessages` when the path is long enough). Lets hosts hydrate
-   * a bounded window instead of the full transcript so wake-time memory
-   * scales with the budget rather than total session history (#1710).
-   *
-   * Falls back to a full (untruncated) read when the provider doesn't
-   * implement `getRecentHistory`. The fallback reports honest metadata
-   * (`truncated: false` and the real serialized size) and warns once so a
-   * host relying on the budget knows it is not being enforced.
-   */
-  getRecentHistory(
-    maxContentBytes: number,
-    minRecentMessages?: number
-  ): Promise<RecentHistoryResult>;
-  /**
-   * Per-row stored sizes for the active branch path (root → leaf) WITHOUT
-   * loading message content, or `null` when the provider doesn't support it.
-   * Lets hosts find oversized rows (e.g. inline base64 media) and process
-   * them one at a time with bounded memory.
-   */
-  getHistoryRowStats(): Promise<HistoryRowStat[] | null>;
-  getMessage(id: string): Promise<SessionMessage | null>;
-  getLatestLeaf(): Promise<SessionMessage | null>;
-  getBranches(messageId: string): Promise<SessionMessage[]>;
-  getPathLength(leafId?: string | null): Promise<number>;
-  private _broadcast;
-  private _shouldEstimateTokens;
-  private _estimateTokenCount;
-  private _handleAutoCompactionError;
-  private _emitStatus;
-  private _emitError;
-  appendMessage(
-    message: SessionMessage,
-    parentId?: string | null
-  ): Promise<void>;
-  private _appendMessage;
-  updateMessage(message: SessionMessage): Promise<void>;
-  /**
-   * @internal
-   * Rewrite a stored message WITHOUT the public-write side effects: no
-   * token-estimate status broadcast (which reads the FULL history) and no
-   * auto-compaction check. For framework maintenance passes that rewrite
-   * many rows with bounded memory — e.g. media eviction (#1710) — where the
-   * per-row full-history estimate would reintroduce the memory pressure the
-   * pass exists to remove. The message-change listener still fires so a
-   * cache-owning host stays coherent. Application code should use
-   * `updateMessage`.
-   */
-  internal_rewriteMessage(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.
-   */
-  compact(): Promise<CompactResult | null>;
-  getContextBlock(label: string): ContextBlock | null;
-  getContextBlocks(): ContextBlock[];
-  replaceContextBlock(label: string, content: string): Promise<ContextBlock>;
-  appendContextBlock(label: string, content: string): Promise<ContextBlock>;
-  /**
-   * Dynamically register a new context block after session initialization.
-   *
-   * 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
-   * in the system prompt.
-   *
-   * Note: When called without a provider, auto-wires to SQLite via
-   * AgentContextProvider. Requires the session to have been created
-   * via `Session.create(agent)` (not the direct constructor).
-   */
-  addContext(
-    label: string,
-    options?: SessionContextOptions
-  ): Promise<ContextBlock>;
-  /**
-   * Remove a dynamically registered context block.
-   * Used during extension unload cleanup.
-   *
-   * Returns true if the block existed and was removed.
-   * Call `refreshSystemPrompt()` afterward to rebuild the prompt
-   * without the removed block.
-   */
-  removeContext(label: string): boolean;
-  /**
-   * 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): Promise<boolean>;
-  /**
-   * Get currently loaded skill keys (as "label:key" strings).
-   * Async for the same reason as `unloadSkill` — must wait for restore.
-   */
-  getLoadedSkillKeys(): Promise<Set<string>>;
-  freezeSystemPrompt(): Promise<string>;
-  refreshSystemPrompt(): Promise<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>;
-}
-//#endregion
-//#region src/experimental/memory/session/manager.d.ts
-interface SessionInfo {
-  id: string;
-  name: string;
-  parent_session_id: string | null;
-  model: string | null;
-  source: string | null;
-  input_tokens: number;
-  output_tokens: number;
-  estimated_cost: number;
-  end_reason: string | null;
-  created_at: string;
-  updated_at: string;
-}
-interface SessionManagerOptions {}
-declare class SessionManager {
-  private agent;
-  private _pending;
-  private _cachedPrompt?;
-  private _compactionFn?;
-  private _tokenThreshold?;
-  private _tokenCounter?;
-  private _compactionErrorHandler?;
-  private _sessions;
-  private _historyLabel?;
-  private _tableReady;
-  private _ready;
-  constructor(agent: SqlProvider, _options?: SessionManagerOptions);
-  /**
-   * Chainable SessionManager creation with auto-wired context for all sessions.
-   *
-   * @example
-   * ```ts
-   * const manager = SessionManager.create(this)
-   *   .withContext("soul", { provider: { get: async () => "You are helpful." } })
-   *   .withContext("memory", { description: "Learned facts", maxTokens: 1100 })
-   *   .withCachedPrompt()
-   *   .compactAfter(100_000);
-   *
-   * // Each getSession(id) auto-creates namespaced providers:
-   * //   memory key: "memory_<sessionId>"
-   * //   prompt key: "_system_prompt_<sessionId>"
-   * const session = manager.getSession("chat-123");
-   * ```
-   */
-  static create(agent: SqlProvider): SessionManager;
-  withContext(label: string, options?: SessionContextOptions): this;
-  withCachedPrompt(provider?: WritableContextProvider): this;
-  /**
-   * Register a compaction function propagated to all sessions.
-   * Called by `Session.compact()` to compress message history.
-   */
-  onCompaction(
-    fn: (messages: SessionMessage[]) => Promise<CompactResult | null>
-  ): this;
-  /**
-   * Auto-compact when estimated token count exceeds the threshold.
-   * Propagated to all sessions. Requires `onCompaction()`.
-   */
-  compactAfter(tokenThreshold: number, options?: CompactAfterOptions): this;
-  /**
-   * Handle failures from automatic compaction in managed sessions.
-   */
-  onCompactionError(handler: CompactionErrorHandler): this;
-  /**
-   * Add a searchable context block that searches conversation history
-   * across all sessions managed by this manager.
-   *
-   * The model can use `search_context` to find relevant messages from
-   * any session. The block is readonly (no `set`).
-   *
-   * @example
-   * ```ts
-   * SessionManager.create(this)
-   *   .withContext("memory", { maxTokens: 1100 })
-   *   .withSearchableHistory("history")
-   *   .withCachedPrompt();
-   * ```
-   */
-  withSearchableHistory(label: string): this;
-  private _ensureReady;
-  private _ensureTable;
-  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;
-  get(sessionId: string): SessionInfo | null;
-  list(): SessionInfo[];
-  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): 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
-  ): 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;
-    createdAt: string;
-  }[];
-  tools(): ToolSet;
-  private _touch;
-}
-//#endregion
-//#region src/experimental/memory/session/providers/agent-context.d.ts
-declare class AgentContextProvider implements WritableContextProvider {
-  private agent;
-  private label;
-  private initialized;
-  constructor(agent: SqlProvider, label?: string);
-  init(label: string): void;
-  private ensureTable;
-  get(): Promise<string | null>;
-  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,
-  AgentSessionProvider,
-  type CompactAfterOptions,
-  type CompactionErrorHandler,
-  type ContextBlock,
-  type ContextConfig,
-  type ContextProvider,
-  type HistoryRowStat,
-  type PgClientLike,
-  type PostgresClient,
-  type PostgresConnection,
-  PostgresContextProvider,
-  PostgresSearchProvider,
-  PostgresSessionProvider,
-  R2SkillProvider,
-  type RecentHistoryResult,
-  type SearchProvider,
-  type SearchResult,
-  Session,
-  type SessionContextOptions,
-  type SessionInfo,
-  SessionManager,
-  type SessionManagerOptions,
-  type SessionMessage,
-  type SessionMessagePart,
-  type SessionOptions,
-  type SessionProvider,
-  type SessionTokenCounter,
-  type SessionTokenCounterInput,
-  type SkillProvider,
-  type SqlProvider,
-  type StoredCompaction,
-  type WritableContextProvider,
-  isSearchProvider,
-  isSkillProvider,
-  isWritableProvider
-};
-//# sourceMappingURL=index.d.ts.map