Context

/** An indivisible live exchange cannot fit. The caller must increase its budget or bound tool results. */
export declare class ContextCompactionError extends Error {
    readonly requiredTokens: number;
    readonly budget: number;
    constructor(requiredTokens: number, budget: number);
}

export declare class ContextCompactor {
    constructor(config: ContextCompactorConfig);
    compact(messages: ChatMessage[]): Promise<ChatMessage[]>;
}

export interface ContextFile {
    name: string;
    path: string;
    content: string;
    blocked?: string;
}

/**
 * `ContextProvider` is a pre-fetched data source attached to an Agent.
 *
 * Unlike Tools (which the LLM explicitly invokes), context providers run
 * automatically before every turn and inject their output into the system
 * prompt. Good for "the agent should always know X" data: my calendar, recent
 * Slack messages, current SQL row counts, file contents the agent referenced.
 *
 * Typical usage:
 *
 * ```ts
 * const calendar = new FilesystemContextProvider({ basePath: "./notes", glob: "*.md" });
 * const agent = new Agent({ context: [calendar], ... });
 * ```
 */
export interface ContextProvider {
    readonly name: string;
    /**
     * Fetch the current context. Called once per agent run before the LLM is invoked.
     * Returning an empty string causes the provider to contribute nothing.
     */
    fetchContext(query: string, ctx: RunContext): Promise<string>;
}

export declare function countConversationTokens(messages: ChatMessage[]): number;

export declare class DatabaseContextProvider implements ContextProvider {
    readonly name: string;
    constructor(cfg: DatabaseContextProviderConfig);
    fetchContext(_query: string, ctx: RunContext): Promise<string>;
}

export interface DatabaseContextProviderConfig {
    /**
     * Function called on every run to produce the context string. The agent's
     * `RunContext` is passed in so you can scope queries to the current user/tenant.
     */
    fetch: (ctx: RunContext) => Promise<string>;
    /** Provider name for logs (e.g. `"postgres-users"`). */
    label?: string;
}

export declare class FilesystemContextProvider implements ContextProvider {
    readonly name = "filesystem";
    constructor(cfg: FilesystemContextProviderConfig);
    fetchContext(_query: string, _ctx: RunContext): Promise<string>;
}

export interface FilesystemContextProviderConfig {
    /** Base directory all paths are read from. */
    basePath: string;
    /** Files to include (relative paths, optionally with `**` wildcards expanded by `glob`). */
    files?: string[];
    /** Optional glob pattern (uses `node:fs.glob` when available). */
    glob?: string;
    /** Per-file character cap. Default 4000. */
    maxCharsPerFile?: number;
    /** Overall character cap. Default 16000. */
    maxTotalChars?: number;
}

export declare function formatContextFiles(files: ContextFile[]): string;

/** A user turn, all its tool rounds and the concluding assistant form one atomic group. */
export declare function groupConversationTurns(messages: ChatMessage[]): ChatMessage[][];

export declare class HttpContextProvider implements ContextProvider {
    readonly name = "http";
    constructor(cfg: HttpContextProviderConfig);
    fetchContext(_query: string, _ctx: RunContext): Promise<string>;
}

export interface HttpContextProviderConfig {
    url: string;
    /** Headers forwarded with the fetch. */
    headers?: Record<string, string>;
    /** Optional SSRF allowlist. */
    allowedHosts?: string[];
    /** Optional response transformer. */
    transform?: (rawBody: string) => string;
    /** Char cap. */
    maxChars?: number;
}

/**
 * Load project instruction files (AGENTS.md and friends).
 *
 * Walks from `cwd` up to the git root and merges matching files.
 * Only one project-file type is used (first match in PROJECT_FILES order).
 */
export declare function loadContextFiles(opts?: LoadContextFilesOptions): Promise<ContextFile[]>;

export interface LoadContextFilesOptions {
    /** Working directory to start from. Default: process.cwd() */
    cwd?: string;
    /** Max characters kept per file. Default: 20000 */
    maxChars?: number;
    /** Skip the prompt-injection scan. Default: false */
    skipScan?: boolean;
}

/**
 * Resolve all configured providers in parallel, label each block, and join
 * them into a single context string suitable for the system prompt.
 */
export declare function resolveContextProviders(providers: ContextProvider[], query: string, ctx: RunContext): Promise<string>;

/**
 * Host messages are immutable. Closed historical tool/replay groups may be removed
 * atomically; a retained or current group must keep every opaque/call/result item.
 */
export declare function validateConversationTransform(before: readonly ChatMessage[], after: readonly ChatMessage[]): void;