agents/dist/context/index.d.ts

A home for your AI agents

import { ToolSet } from "ai";

//#region src/context/sqlite-provider.d.ts
/** Minimal tagged-template SQL surface used by SQLite context providers. */
interface SqlProvider {
  sql<T = Record<string, string | number | boolean | null>>(
    strings: TemplateStringsArray,
    ...values: (string | number | boolean | null)[]
  ): T[];
}
/** SQLite-backed writable context block provider. */
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/context/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>;
}
/**
 * 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
 *
 * Entries live in one namespaced FTS5 table, separate from the session
 * message index.
 *
 * @example
 * ```ts
 * const context = new ContextBlocks([
 *   { label: "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>;
}
//#endregion
//#region src/context/blocks.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>;
}
/**
 * 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
   *  - SearchProvider (get+search+set?) → searchable via search_context
   *  If omitted, auto-wired to writable SQLite when using builder. */
  provider?: ContextProvider | WritableContextProvider | 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 SearchProvider */
  isSearchable: boolean;
}
/**
 * Manages context blocks with frozen snapshot support.
 */
declare class ContextBlocks {
  private configs;
  private blocks;
  private snapshot;
  private loaded;
  private promptStore;
  private defaultProvider;
  /**
   * @param configs Blocks to load on first use.
   * @param promptStore Persists the frozen system prompt, keeping the
   *   provider's prefix cache warm across wakes.
   * @param defaultProvider Supplies storage for blocks declared without a
   *   provider, so a host can offer durable writable blocks by label alone.
   */
  constructor(
    configs: ContextConfig[],
    promptStore?: WritableContextProvider,
    defaultProvider?: (label: string) => ContextProvider
  );
  /** Fill in the host's storage for a block declared without a provider. */
  private withDefaultProvider;
  /**
   * Load all blocks from their providers. Hosts call this once at startup;
   * every other entry point loads lazily.
   */
  load(): Promise<void>;
  /** Initialize a block's provider and read its current content. */
  private loadBlock;
  /**
   * Dynamically register a new context block after initialization.
   * Used by extensions to contribute context at runtime.
   *
   * If blocks have already been loaded, the new block's provider is
   * initialized and loaded immediately. The snapshot is NOT updated
   * automatically — call `refreshSystemPrompt()` to rebuild.
   */
  addBlock(input: ContextConfig): Promise<ContextBlock>;
  /**
   * Remove a dynamically registered context block.
   * Used during extension unload cleanup.
   *
   * Returns true if the block existed and was removed.
   * The snapshot is NOT updated automatically — call
   * `refreshSystemPrompt()` to rebuild.
   */
  removeBlock(label: string): boolean;
  /**
   * Get a block by label.
   */
  getBlock(label: string): ContextBlock | null;
  /**
   * Get all blocks.
   */
  getBlocks(): ContextBlock[];
  /**
   * Set block content. Writes to provider immediately.
   * Does NOT update the frozen snapshot.
   */
  setBlock(label: string, content: string): Promise<ContextBlock>;
  /** Index a search entry within a searchable block. */
  private setSearchEntry;
  /** Search a searchable block. */
  private searchContext;
  /**
   * Append content to a block.
   */
  appendToBlock(label: string, content: string): Promise<ContextBlock>;
  private renderPrompt;
  /**
   * The frozen system prompt. The first call renders the blocks and stores
   * the result; every later call returns that same string, so the model
   * provider's prefix cache stays warm. Block edits do not change it until
   * `refreshSystemPrompt()` is called.
   */
  freezeSystemPrompt(): Promise<string>;
  /**
   * Reload every block from its provider, re-render the system prompt, and
   * persist it. Use this after block content has changed.
   */
  refreshSystemPrompt(): Promise<string>;
  /**
   * AI tools for context blocks.
   *
   * Auto-wired based on provider capabilities:
   * - `set_context` — when any block is writable
   * - `search_context` — when any block is a search provider
   */
  tools(): Promise<ToolSet>;
}
//#endregion
export {
  AgentContextProvider,
  AgentSearchProvider,
  type ContextBlock,
  ContextBlocks,
  type ContextConfig,
  type ContextProvider,
  type SearchProvider,
  type SqlProvider,
  type WritableContextProvider
};
//# sourceMappingURL=index.d.ts.map