agents 0.8.7 → 0.10.0

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

@@ -1,66 +1,6 @@
-import { r as CompactResult } from "../../../compaction-helpers-DkJreaDR.js";
+import { r as CompactResult } from "../../../compaction-helpers-CHNQeyRm.js";
 import { ToolSet, UIMessage } from "ai";
 
-//#region src/experimental/memory/session/context.d.ts
-/**
- * Storage interface for a single context block.
- * Each block can have its own backing store (R2, SQLite, KV, in-memory, etc.)
- * If `set` is omitted, the block is readonly.
- */
-interface ContextProvider {
-  get(): Promise<string | null>;
-  set?(content: string): Promise<void>;
-}
-/**
- * Configuration for a context block.
- */
-interface ContextConfig {
-  /** Block label — used as key and in tool descriptions */
-  label: string;
-  /** Human-readable description (shown to AI in tool) */
-  description?: string;
-  /** Initial content — used when provider returns null or is absent */
-  initialContent?: string;
-  /** Maximum tokens allowed. Enforced on set. */
-  maxTokens?: number;
-  /** If true, AI cannot modify this block via tools */
-  readonly?: boolean;
-  /** Storage provider. If omitted, auto-wired to SQLite when using builder. */
-  provider?: ContextProvider;
-}
-/**
- * A loaded context block with computed token count.
- */
-interface ContextBlock {
-  label: string;
-  description?: string;
-  content: string;
-  tokens: number;
-  maxTokens?: number;
-  readonly?: boolean;
-}
-//#endregion
-//#region src/experimental/memory/session/types.d.ts
-/**
- * Options for querying messages
- */
-interface MessageQueryOptions {
-  limit?: number;
-  offset?: number;
-  before?: Date;
-  after?: Date;
-  role?: "user" | "assistant" | "system";
-}
-/**
- * Options for creating a Session.
- */
-interface SessionOptions {
-  /** Context blocks for the system prompt. */
-  context?: ContextConfig[];
-  /** Provider for persisting the frozen system prompt. */
-  promptStore?: ContextProvider;
-}
-//#endregion
 //#region src/experimental/memory/session/provider.d.ts
 interface SearchResult {
   id: string;
@@ -138,6 +78,173 @@ declare class AgentSessionProvider implements SessionProvider {
   private parseRows;
 }
 //#endregion
+//#region src/experimental/memory/session/search.d.ts
+/**
+ * Storage interface for searchable context.
+ *
+ * - `get()` returns a summary of indexed content (rendered into system prompt)
+ * - `search(query)` full-text search (via search_context tool)
+ * - `set(key, content)` indexes content under a key (via set_context tool)
+ */
+interface SearchProvider extends ContextProvider {
+  search(query: string): Promise<string | null>;
+  set?(key: string, content: string): Promise<void>;
+}
+/**
+ * Check if a provider is a SearchProvider (has a `search` method).
+ */
+declare function isSearchProvider(provider: unknown): provider is SearchProvider;
+/**
+ * SearchProvider backed by Durable Object SQLite with FTS5.
+ *
+ * - `get()` returns a count of indexed entries
+ * - `search(query)` full-text search using FTS5
+ * - `set(key, content)` indexes or replaces content under a key
+ *
+ * Each instance uses a namespaced FTS5 table to avoid collisions
+ * with the session message search.
+ *
+ * @example
+ * ```ts
+ * Session.create(this)
+ *   .withContext("knowledge", {
+ *     provider: new AgentSearchProvider(this)
+ *   })
+ * ```
+ */
+declare class AgentSearchProvider implements SearchProvider {
+  private agent;
+  private label;
+  private initialized;
+  constructor(agent: SqlProvider);
+  init(label: string): void;
+  private ensureTable;
+  get(): Promise<string | null>;
+  search(query: string): Promise<string | null>;
+  set(key: string, content: string): Promise<void>;
+  private deleteFTS;
+}
+//#endregion
+//#region src/experimental/memory/session/skills.d.ts
+/**
+ * Storage interface for skill collections.
+ *
+ * - `get()` returns metadata listing (rendered into system prompt)
+ * - `load(key)` fetches full content (via load_context tool)
+ * - `set(key, content, description?)` writes an entry (via set_context tool)
+ */
+interface SkillProvider extends ContextProvider {
+  load(key: string): Promise<string | null>;
+  set?(key: string, content: string, description?: string): Promise<void>;
+}
+/**
+ * Check if a provider is a SkillProvider (has a `load` method).
+ */
+declare function isSkillProvider(provider: unknown): provider is SkillProvider;
+/**
+ * SkillProvider backed by an R2 bucket.
+ *
+ * - `get()` returns a metadata listing of all skills (key + description)
+ * - `load(key)` fetches a skill's full content
+ * - `set(key, content, description?)` writes a skill
+ *
+ * Descriptions are pulled from R2 custom metadata (`description` key).
+ * If a prefix is provided, it is prepended on storage operations and
+ * stripped from keys in metadata.
+ *
+ * @example
+ * ```ts
+ * const skills = new R2SkillProvider(env.SKILLS_BUCKET, { prefix: "skills/" });
+ * ```
+ */
+declare class R2SkillProvider implements SkillProvider {
+  private bucket;
+  private prefix;
+  constructor(bucket: R2Bucket, options?: {
+    prefix?: string;
+  });
+  get(): Promise<string | null>;
+  load(key: string): Promise<string | null>;
+  set(key: string, content: string, description?: string): Promise<void>;
+}
+//#endregion
+//#region src/experimental/memory/session/context.d.ts
+/**
+ * Base storage interface for a context block.
+ * A provider with only `get()` is readonly.
+ */
+interface ContextProvider {
+  get(): Promise<string | null>;
+  /** Called by the context system to provide the block label before first use. */
+  init?(label: string): void;
+}
+/**
+ * Writable context provider — extends ContextProvider with `set()`.
+ * Blocks backed by this provider are writable via the `set_context` tool.
+ */
+interface WritableContextProvider extends ContextProvider {
+  set(content: string): Promise<void>;
+}
+/**
+ * Check if a provider is writable (has a `set` method).
+ */
+declare function isWritableProvider(provider: unknown): provider is WritableContextProvider;
+/**
+ * Configuration for a context block.
+ */
+interface ContextConfig {
+  /** Block label — used as key and in tool descriptions */
+  label: string;
+  /** Human-readable description (shown to AI in tool) */
+  description?: string;
+  /** Maximum tokens allowed. Enforced on set. */
+  maxTokens?: number;
+  /** Storage provider. Determines block behavior:
+   *  - ContextProvider (get only) → readonly
+   *  - WritableContextProvider (get+set) → writable via set_context
+   *  - SkillProvider (get+load+set?) → on-demand via load_context
+   *  - SearchProvider (get+search+set?) → searchable via search_context
+   *  If omitted, auto-wired to writable SQLite when using builder. */
+  provider?: ContextProvider | WritableContextProvider | SkillProvider | SearchProvider;
+}
+/**
+ * A loaded context block with computed token count.
+ */
+interface ContextBlock {
+  label: string;
+  description?: string;
+  content: string;
+  tokens: number;
+  maxTokens?: number;
+  /** True if provider is writable (has set) */
+  writable: boolean;
+  /** True if backed by a SkillProvider */
+  isSkill: boolean;
+  /** True if backed by a SearchProvider */
+  isSearchable: boolean;
+}
+//#endregion
+//#region src/experimental/memory/session/types.d.ts
+/**
+ * Options for querying messages
+ */
+interface MessageQueryOptions {
+  limit?: number;
+  offset?: number;
+  before?: Date;
+  after?: Date;
+  role?: "user" | "assistant" | "system";
+}
+/**
+ * Options for creating a Session.
+ */
+interface SessionOptions {
+  /** Context blocks for the system prompt. */
+  context?: ContextConfig[];
+  /** Provider for persisting the frozen system prompt. */
+  promptStore?: WritableContextProvider;
+}
+//#endregion
 //#region src/experimental/memory/session/session.d.ts
 type SessionContextOptions = Omit<ContextConfig, "label">;
 declare class Session {
@@ -159,17 +266,14 @@ declare class Session {
    * @example
    * ```ts
    * const session = Session.create(this)
-   *   .withContext("soul", { initialContent: "You are helpful.", readonly: true })
+   *   .withContext("soul", { provider: { get: async () => "You are helpful." } })
    *   .withContext("memory", { description: "Learned facts", maxTokens: 1100 })
    *   .withCachedPrompt();
    *
-   * // Custom storage (R2, KV, etc.)
+   * // Skills from R2 (on-demand loading via load_context tool)
    * const session = Session.create(this)
-   *   .withContext("workspace", {
-   *     provider: {
-   *       get: () => env.BUCKET.get("ws.md").then(o => o?.text() ?? null),
-   *       set: (c) => env.BUCKET.put("ws.md", c),
-   *     }
+   *   .withContext("skills", {
+   *     provider: new R2SkillProvider(env.SKILLS_BUCKET, { prefix: "skills/" })
    *   })
    *   .withCachedPrompt();
    * ```
@@ -177,7 +281,7 @@ declare class Session {
   static create(agent: SqlProvider): Session;
   forSession(sessionId: string): this;
   withContext(label: string, options?: SessionContextOptions): this;
-  withCachedPrompt(provider?: ContextProvider): this;
+  withCachedPrompt(provider?: WritableContextProvider): this;
   /**
    * Register a compaction function. Called by `compact()` to compress
    * message history into a summary overlay.
@@ -222,20 +326,141 @@ declare class Session {
     content: string;
     createdAt?: string;
   }>;
-  /** Returns update_context tool for writing to context blocks. */
+  /** 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 {
+  maxContextMessages?: number;
+}
+declare class SessionManager {
+  private agent;
+  private _maxContextMessages;
+  private _pending;
+  private _cachedPrompt?;
+  private _compactionFn?;
+  private _tokenThreshold?;
+  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()
+   *   .maxContextMessages(50);
+   *
+   * // 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;
+  maxContextMessages(count: number): this;
+  /**
+   * Register a compaction function propagated to all sessions.
+   * Called by `Session.compact()` to compress message history.
+   */
+  onCompaction(fn: (messages: UIMessage[]) => Promise<CompactResult | null>): this;
+  /**
+   * Auto-compact when estimated token count exceeds the threshold.
+   * Propagated to all sessions. Requires `onCompaction()`.
+   */
+  compactAfter(tokenThreshold: number): 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): void;
+  rename(sessionId: string, name: string): void;
+  append(sessionId: string, message: UIMessage, parentId?: string): Promise<string>;
+  upsert(sessionId: string, message: UIMessage, parentId?: string): Promise<string>;
+  appendAll(sessionId: string, messages: UIMessage[], parentId?: string): Promise<string | null>;
+  getHistory(sessionId: string, leafId?: string): UIMessage[];
+  getMessageCount(sessionId: string): number;
+  clearMessages(sessionId: string): void;
+  deleteMessages(sessionId: string, messageIds: string[]): void;
+  getBranches(sessionId: string, messageId: string): UIMessage[];
+  /**
+   * 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>;
+  needsCompaction(sessionId: string): boolean;
+  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;
+  }): {
+    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 ContextProvider {
+declare class AgentContextProvider implements WritableContextProvider {
   private agent;
   private label;
   private initialized;
-  constructor(agent: SqlProvider, label: string);
+  constructor(agent: SqlProvider, label?: string);
+  init(label: string): void;
   private ensureTable;
   get(): Promise<string | null>;
   set(content: string): Promise<void>;
 }
 //#endregion
-export { AgentContextProvider, AgentSessionProvider, type ContextBlock, type ContextConfig, type MessageQueryOptions, type SearchResult, Session, type SessionContextOptions, type SessionOptions, type SessionProvider, type SqlProvider, type StoredCompaction };
+export { AgentContextProvider, AgentSearchProvider, AgentSessionProvider, type ContextBlock, type ContextConfig, type ContextProvider, type MessageQueryOptions, R2SkillProvider, type SearchProvider, type SearchResult, Session, type SessionContextOptions, type SessionInfo, SessionManager, type SessionManagerOptions, type SessionOptions, type SessionProvider, type SkillProvider, type SqlProvider, type StoredCompaction, type WritableContextProvider, isSearchProvider, isSkillProvider, isWritableProvider };
 //# sourceMappingURL=index.d.ts.map