agents 0.8.5 → 0.8.7

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

@@ -1,251 +1,241 @@
-import { UIMessage } from "ai";
+import { r as CompactResult } from "../../../compaction-helpers-DkJreaDR.js";
+import { ToolSet, UIMessage } from "ai";
 
-//#region src/experimental/memory/session/types.d.ts
+//#region src/experimental/memory/session/context.d.ts
 /**
- * Options for querying messages
+ * 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 MessageQueryOptions {
-  /** Maximum number of messages to return */
-  limit?: number;
-  /** Number of messages to skip */
-  offset?: number;
-  /** Only return messages created before this timestamp */
-  before?: Date;
-  /** Only return messages created after this timestamp */
-  after?: Date;
-  /** Filter by role */
-  role?: "user" | "assistant" | "system";
+interface ContextProvider {
+  get(): Promise<string | null>;
+  set?(content: string): Promise<void>;
 }
 /**
- * Granular microCompaction rules.
- * Each rule can be true (use default), false (disable), or a number (custom threshold).
+ * Configuration for a context block.
  */
-interface MicroCompactionRules {
-  /**
-   * Truncate tool outputs over this size (in chars).
-   * @default 30000 chars
-   */
-  truncateToolOutputs?: boolean | number;
-  /**
-   * Truncate text parts over this size in older messages (in chars).
-   * @default 10000 chars
-   */
-  truncateText?: boolean | number;
-  /**
-   * Number of recent messages to keep intact (not truncated).
-   * @default 4
-   */
-  keepRecent?: number;
+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;
 }
 /**
- * Compaction function - user implements this to decide how to compact messages.
- * Could summarize with LLM, truncate, filter, or anything else.
- *
- * @param messages Current messages in the session
- * @returns New messages to replace the current ones
+ * A loaded context block with computed token count.
  */
-type CompactFunction = (messages: UIMessage[]) => Promise<UIMessage[]>;
-/**
- * Configuration for full compaction (LLM summarization)
- */
-interface CompactionConfig {
-  /**
-   * Token threshold for automatic compaction.
-   * When estimated tokens exceed this, compact() is called automatically on append().
-   * If not set, auto-compaction is disabled (you can still call compact() manually).
-   */
-  tokenThreshold?: number;
-  /**
-   * Function to compact messages.
-   * Receives current messages as stored, returns new messages.
-   */
-  fn: CompactFunction;
+interface ContextBlock {
+  label: string;
+  description?: string;
+  content: string;
+  tokens: number;
+  maxTokens?: number;
+  readonly?: boolean;
 }
+//#endregion
+//#region src/experimental/memory/session/types.d.ts
 /**
- * Result of compaction operation
+ * Options for querying messages
  */
-interface CompactResult {
-  /** Whether compaction succeeded */
-  success: boolean;
-  /** Error message if compaction failed */
-  error?: string;
+interface MessageQueryOptions {
+  limit?: number;
+  offset?: number;
+  before?: Date;
+  after?: Date;
+  role?: "user" | "assistant" | "system";
 }
 /**
- * Options for creating a session provider
+ * Options for creating a Session.
  */
-interface SessionProviderOptions {
-  /**
-   * Lightweight compaction that doesn't require LLM calls.
-   * Truncates tool outputs and long text in older messages.
-   *
-   * Runs automatically on every `append()` — older messages (beyond `keepRecent`)
-   * are truncated in storage.
-   * This is a destructive operation: original content is permanently replaced.
-   * `getMessages()` returns stored content as-is (already compacted).
-   *
-   * - `true` - enable with default rules
-   * - `false` - disable
-   * - `{ ... }` - enable with custom rules
-   *
-   * @default true
-   */
-  microCompaction?: boolean | MicroCompactionRules;
-  /**
-   * Full compaction with custom function (typically LLM summarization).
-   */
-  compaction?: CompactionConfig;
+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;
+  role: string;
+  content: string;
+  createdAt?: string;
+  sessionId?: string;
+}
+interface StoredCompaction {
+  id: string;
+  summary: string;
+  fromMessageId: string;
+  toMessageId: string;
+  createdAt: string;
+}
 /**
- * Session storage provider interface.
- *
- * Implement this interface to create custom session storage backends.
- * Providers handle CRUD only — compaction is orchestrated by the Session wrapper.
+ * Session storage provider.
+ * Messages are tree-structured via parentId for branching.
  */
 interface SessionProvider {
-  /**
-   * Get messages with optional filtering
-   */
-  getMessages(options?: MessageQueryOptions): UIMessage[];
-  /**
-   * Get a single message by ID
-   */
   getMessage(id: string): UIMessage | null;
   /**
-   * Get the last N messages (most recent)
-   */
-  getLastMessages(n: number): UIMessage[];
-  /**
-   * Append one or more messages to storage.
+   * Get conversation as a path from root to leaf.
+   * Applies compaction overlays. If leafId is null, uses the latest leaf.
    */
-  appendMessages(messages: UIMessage | UIMessage[]): Promise<void>;
+  getHistory(leafId?: string | null): UIMessage[];
+  getLatestLeaf(): UIMessage | null;
+  getBranches(messageId: string): UIMessage[];
+  getPathLength(leafId?: string | null): number;
   /**
-   * Update an existing message
+   * Append a message. Parented to the latest leaf unless parentId is provided.
+   * Idempotent — same message.id twice is a no-op.
    */
+  appendMessage(message: UIMessage, parentId?: string | null): void;
   updateMessage(message: UIMessage): void;
-  /**
-   * Delete messages by ID
-   */
   deleteMessages(messageIds: string[]): void;
-  /**
-   * Clear all messages
-   */
   clearMessages(): void;
-  /**
-   * Fetch messages outside the recent window (for microCompaction).
-   * Returns all messages except the most recent `keepRecent`.
-   */
-  getOlderMessages(keepRecent: number): UIMessage[];
-  /**
-   * Bulk replace all messages (used by compact).
-   * Clears existing messages and inserts the new ones,
-   * preserving original created_at timestamps where possible.
-   */
-  replaceMessages(messages: UIMessage[]): Promise<void>;
-}
-//#endregion
-//#region src/experimental/memory/session/session.d.ts
-declare class Session {
-  private storage;
-  private microCompactionRules;
-  private compactionConfig;
-  constructor(storage: SessionProvider, options?: SessionProviderOptions);
-  getMessages(options?: MessageQueryOptions): UIMessage[];
-  getMessage(id: string): UIMessage | null;
-  getLastMessages(n: number): UIMessage[];
-  append(messages: UIMessage | UIMessage[]): Promise<void>;
-  updateMessage(message: UIMessage): void;
-  deleteMessages(messageIds: string[]): void;
-  clearMessages(): void;
-  compact(): Promise<CompactResult>;
-  /**
-   * Pre-check for auto-compaction using token estimate heuristic.
-   */
-  private shouldAutoCompact;
+  addCompaction(summary: string, fromMessageId: string, toMessageId: string): StoredCompaction;
+  getCompactions(): StoredCompaction[];
+  searchMessages?(query: string, limit?: number): SearchResult[];
 }
 //#endregion
 //#region src/experimental/memory/session/providers/agent.d.ts
-/**
- * Interface for objects that provide a sql tagged template method.
- * This matches the Agent class's sql method signature.
- */
 interface SqlProvider {
   sql<T = Record<string, string | number | boolean | null>>(strings: TemplateStringsArray, ...values: (string | number | boolean | null)[]): T[];
 }
-/**
- * Session provider that wraps an Agent's SQLite storage.
- * Provides pure CRUD — compaction is handled by the Session wrapper.
- *
- * @example
- * ```typescript
- * import { Session, AgentSessionProvider } from "agents/experimental/memory/session";
- *
- * // In your Agent class:
- * session = new Session(new AgentSessionProvider(this));
- *
- * // With compaction options:
- * session = new Session(new AgentSessionProvider(this), {
- *   microCompaction: { truncateToolOutputs: 2000, keepRecent: 10 },
- *   compaction: { tokenThreshold: 20000, fn: summarize }
- * });
- * ```
- */
 declare class AgentSessionProvider implements SessionProvider {
   private agent;
   private initialized;
-  constructor(agent: SqlProvider);
+  private sessionId;
   /**
-   * Ensure the messages table exists
+   * @param agent - Agent or any object with a `sql` tagged template method
+   * @param sessionId - Optional session ID to isolate multiple sessions in the same DO.
+   *                    Messages are filtered by session_id within shared tables.
    */
+  constructor(agent: SqlProvider, sessionId?: string);
   private ensureTable;
-  /**
-   * Get all messages in AI SDK format
-   */
-  getMessages(options?: MessageQueryOptions): UIMessage[];
-  /**
-   * Append one or more messages to storage.
-   */
-  appendMessages(messages: UIMessage | UIMessage[]): Promise<void>;
-  /**
-   * Update an existing message
-   */
+  getMessage(id: string): UIMessage | null;
+  getHistory(leafId?: string | null): UIMessage[];
+  getLatestLeaf(): UIMessage | null;
+  getBranches(messageId: string): UIMessage[];
+  getPathLength(leafId?: string | null): number;
+  appendMessage(message: UIMessage, parentId?: string | null): void;
   updateMessage(message: UIMessage): void;
-  /**
-   * Delete messages by their IDs
-   */
   deleteMessages(messageIds: string[]): void;
-  /**
-   * Clear all messages from the session
-   */
   clearMessages(): void;
-  /**
-   * Get a single message by ID
-   */
-  getMessage(id: string): UIMessage | null;
-  /**
-   * Get the last N messages (most recent)
-   */
-  getLastMessages(n: number): UIMessage[];
-  /**
-   * Fetch messages outside the recent window (for microCompaction).
-   * Returns all messages except the most recent `keepRecent`.
-   */
-  getOlderMessages(keepRecent: number): UIMessage[];
-  /**
-   * Bulk replace all messages.
-   * Preserves original created_at timestamps for surviving messages.
-   */
-  replaceMessages(messages: UIMessage[]): Promise<void>;
-  /**
-   * Validate message structure
-   */
-  private isValidMessage;
-  /**
-   * Parse message rows from SQL results into UIMessages.
-   */
+  addCompaction(summary: string, fromMessageId: string, toMessageId: string): StoredCompaction;
+  getCompactions(): StoredCompaction[];
+  searchMessages(query: string, limit?: number): SearchResult[];
+  private latestLeafRow;
+  private indexFTS;
+  private deleteFTS;
+  private applyCompactions;
+  private parse;
   private parseRows;
 }
 //#endregion
-export { AgentSessionProvider, type CompactFunction, type CompactResult, type CompactionConfig, type MessageQueryOptions, type MicroCompactionRules, Session, type SessionProvider, type SessionProviderOptions, type SqlProvider };
+//#region src/experimental/memory/session/session.d.ts
+type SessionContextOptions = Omit<ContextConfig, "label">;
+declare class Session {
+  private storage;
+  private context;
+  private _agent?;
+  private _broadcaster?;
+  private _sessionId?;
+  private _pending?;
+  private _cachedPrompt?;
+  private _compactionFn?;
+  private _tokenThreshold?;
+  private _ready;
+  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.
+   *
+   * @example
+   * ```ts
+   * const session = Session.create(this)
+   *   .withContext("soul", { initialContent: "You are helpful.", readonly: true })
+   *   .withContext("memory", { description: "Learned facts", maxTokens: 1100 })
+   *   .withCachedPrompt();
+   *
+   * // Custom storage (R2, KV, etc.)
+   * 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),
+   *     }
+   *   })
+   *   .withCachedPrompt();
+   * ```
+   */
+  static create(agent: SqlProvider): Session;
+  forSession(sessionId: string): this;
+  withContext(label: string, options?: SessionContextOptions): this;
+  withCachedPrompt(provider?: ContextProvider): this;
+  /**
+   * Register a compaction function. Called by `compact()` to compress
+   * message history into a summary overlay.
+   */
+  onCompaction(fn: (messages: UIMessage[]) => Promise<CompactResult | null>): this;
+  /**
+   * Auto-compact when estimated token count exceeds the threshold.
+   * Checked after each `appendMessage`. Requires `onCompaction()`.
+   */
+  compactAfter(tokenThreshold: number): this;
+  private _ensureReady;
+  getHistory(leafId?: string | null): UIMessage[];
+  getMessage(id: string): UIMessage | null;
+  getLatestLeaf(): UIMessage | null;
+  getBranches(messageId: string): UIMessage[];
+  getPathLength(leafId?: string | null): number;
+  private _broadcast;
+  private _emitStatus;
+  private _emitError;
+  appendMessage(message: UIMessage, parentId?: string | null): Promise<void>;
+  updateMessage(message: UIMessage): void;
+  deleteMessages(messageIds: string[]): void;
+  clearMessages(): void;
+  addCompaction(summary: string, fromMessageId: string, toMessageId: string): StoredCompaction;
+  getCompactions(): 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>;
+  freezeSystemPrompt(): Promise<string>;
+  refreshSystemPrompt(): Promise<string>;
+  search(query: string, options?: {
+    limit?: number;
+  }): Array<{
+    id: string;
+    role: string;
+    content: string;
+    createdAt?: string;
+  }>;
+  /** Returns update_context tool for writing to context blocks. */
+  tools(): Promise<ToolSet>;
+}
+//#endregion
+//#region src/experimental/memory/session/providers/agent-context.d.ts
+declare class AgentContextProvider implements ContextProvider {
+  private agent;
+  private label;
+  private initialized;
+  constructor(agent: SqlProvider, label: string);
+  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 };
 //# sourceMappingURL=index.d.ts.map