@claude-code-kit/agent 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,722 @@
+import { z } from 'zod';
+
+/**
+ * Type definitions for @claude-code-kit/agent.
+ * This is the single source of truth for all agent-related types.
+ */
+
+interface TextContentPart {
+    type: "text";
+    text: string;
+}
+interface ImageContentPart {
+    type: "image";
+    data: string;
+    mediaType: string;
+}
+type ContentPart = TextContentPart | ImageContentPart;
+interface ToolCall {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+interface SystemMessage {
+    role: "system";
+    content: string;
+}
+interface UserMessage {
+    role: "user";
+    content: string | ContentPart[];
+}
+interface AssistantMessage {
+    role: "assistant";
+    content: string | ContentPart[];
+    toolCalls?: ToolCall[];
+}
+interface ToolResultMessage {
+    role: "tool";
+    toolCallId: string;
+    content: string | ContentPart[];
+    isError?: boolean;
+}
+/**
+ * Protocol-level message used in the agent loop and LLM provider communication.
+ *
+ * This type represents the canonical message format for agent conversations,
+ * tool calls, and tool results. It is distinct from the display-oriented
+ * `Message` type in `@claude-code-kit/ui`, which adds fields like `id` and
+ * `timestamp` for rendering. The `useAgent` bridge handles conversion between
+ * the two formats automatically.
+ */
+type Message = SystemMessage | UserMessage | AssistantMessage | ToolResultMessage;
+interface ToolContext {
+    workingDirectory: string;
+    abortSignal: AbortSignal;
+    onProgress?: (progress: ToolProgress) => void;
+    env?: Record<string, string>;
+}
+interface ToolProgress {
+    percent?: number;
+    message?: string;
+}
+interface ToolResult {
+    content: string;
+    isError?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface ToolDefinition<TInput = unknown> {
+    name: string;
+    description: string;
+    inputSchema: z.ZodType<TInput>;
+    execute(input: TInput, context: ToolContext): Promise<ToolResult>;
+    isReadOnly?: boolean;
+    isDestructive?: boolean;
+    requiresConfirmation?: boolean;
+    timeout?: number;
+}
+type StreamChunk = {
+    type: "text";
+    text: string;
+} | {
+    type: "tool_use_start";
+    toolCall: {
+        id: string;
+        name: string;
+    };
+} | {
+    type: "tool_use_delta";
+    text: string;
+} | {
+    type: "tool_use_end";
+} | {
+    type: "thinking";
+    text: string;
+} | {
+    type: "usage";
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+} | {
+    type: "done";
+    stopReason?: string;
+} | {
+    type: "error";
+    error: Error;
+};
+interface ProviderTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+interface ChatOptions {
+    model: string;
+    messages: Message[];
+    tools?: ProviderTool[];
+    systemPrompt?: string;
+    maxTokens?: number;
+    temperature?: number;
+    signal?: AbortSignal;
+}
+interface LLMProvider {
+    chat(options: ChatOptions): AsyncGenerator<StreamChunk>;
+    countTokens?(messages: Message[]): Promise<number>;
+}
+interface TextEvent {
+    type: "text";
+    text: string;
+}
+interface ToolCallEvent {
+    type: "tool_call";
+    toolCall: ToolCall;
+}
+interface ToolResultEvent {
+    type: "tool_result";
+    toolCallId: string;
+    result: ToolResult;
+}
+interface ThinkingEvent {
+    type: "thinking";
+    text: string;
+}
+interface UsageEvent {
+    type: "usage";
+    inputTokens: number;
+    outputTokens: number;
+}
+interface ErrorEvent {
+    type: "error";
+    error: Error;
+}
+interface DoneEvent {
+    type: "done";
+    messages: Message[];
+}
+type AgentEvent = TextEvent | ToolCallEvent | ToolResultEvent | ThinkingEvent | UsageEvent | ErrorEvent | DoneEvent;
+interface PermissionRequest {
+    tool: string;
+    input: Record<string, unknown>;
+    isReadOnly?: boolean;
+}
+interface PermissionResult {
+    decision: "allow" | "deny";
+    reason?: string;
+}
+type PermissionHandler = (request: PermissionRequest) => Promise<PermissionResult>;
+interface PermissionConfig {
+    alwaysAllow?: string[];
+    alwaysDeny?: string[];
+    sessionApproved?: Set<string>;
+    autoApproveReadOnly?: boolean;
+    onPermission?: PermissionHandler;
+}
+interface Session {
+    getMessages(): Message[];
+    setMessages(messages: Message[]): void;
+    clear(): void;
+}
+interface CompactionStrategy {
+    compact(messages: Message[], maxTokens: number): Message[] | Promise<Message[]>;
+}
+interface AgentConfig {
+    provider: LLMProvider;
+    model: string;
+    systemPrompt?: string;
+    tools?: ToolDefinition[];
+    maxTokens?: number;
+    temperature?: number;
+    contextLimit?: number;
+    compactionStrategy?: CompactionStrategy;
+    session?: Session;
+    permissionHandler?: PermissionHandler;
+    workingDirectory?: string;
+    maxTurns?: number;
+}
+
+/**
+ * Headless agent that runs an LLM query loop with tool execution.
+ *
+ * Stateful — maintains message history across `run()` calls.
+ * Platform-agnostic — works in Node.js scripts, CLI apps, web servers, anywhere.
+ */
+declare class Agent {
+    private provider;
+    private model;
+    private systemPrompt?;
+    private maxTokens?;
+    private temperature?;
+    private maxTurns;
+    private session;
+    private toolRegistry;
+    private contextManager;
+    private permissionHandler;
+    private workingDirectory;
+    private abortController;
+    constructor(config: AgentConfig);
+    /**
+     * Run the agent loop. Yields events as the agent processes the input.
+     *
+     * The loop:
+     * 1. Add user message(s) to conversation
+     * 2. Check compaction
+     * 3. Call provider.chat() with messages + tools
+     * 4. Stream chunks, accumulate text + tool calls
+     * 5. If tool_use: check permission -> execute -> add results -> loop to step 2
+     * 6. If end_turn: yield done event with full message history
+     */
+    run(input: string | Message[]): AsyncGenerator<AgentEvent>;
+    /**
+     * Simple API that wraps run() — sends a message and returns the final text response.
+     */
+    chat(input: string): Promise<string>;
+    /** Abort the current run. */
+    abort(): void;
+    /** Replace the provider (e.g. to switch models mid-conversation). */
+    setProvider(provider: LLMProvider): void;
+    /** Get the full message history. */
+    getMessages(): Message[];
+    /** Clear the message history. */
+    clearMessages(): void;
+    /** Add a tool to the registry. */
+    addTool(tool: ToolDefinition): void;
+    /** Remove a tool from the registry. */
+    removeTool(name: string): boolean;
+    /** Replace the permission handler at runtime. */
+    setPermissionHandler(handler: PermissionHandler): void;
+    private executeToolCalls;
+}
+
+/**
+ * Registry that holds tool definitions and provides lookup + execution.
+ */
+declare class ToolRegistry {
+    private tools;
+    register(tool: ToolDefinition): void;
+    unregister(name: string): boolean;
+    get(name: string): ToolDefinition | undefined;
+    has(name: string): boolean;
+    list(): ToolDefinition[];
+    /**
+     * Returns all tools in the provider-ready format (name, description, JSON Schema).
+     */
+    toProviderFormat(): ProviderTool[];
+    /**
+     * Execute a tool by name with the given input.
+     */
+    execute(name: string, input: Record<string, unknown>, context: ToolContext): Promise<ToolResult>;
+    clear(): void;
+}
+
+/**
+ * Estimate token count for a message using the ~4 chars/token heuristic.
+ */
+declare function estimateTokens(message: Message): number;
+/**
+ * Estimate total token count for an array of messages.
+ */
+declare function estimateTotalTokens(messages: Message[]): number;
+/**
+ * Manages the conversation context window, triggering compaction
+ * when approaching the token limit.
+ */
+declare class ContextManager {
+    private contextLimit;
+    private compactionStrategy;
+    private provider;
+    /** Compact when usage exceeds this fraction of the context limit */
+    private compactionThreshold;
+    constructor(options: {
+        contextLimit?: number;
+        compactionStrategy?: CompactionStrategy;
+        provider?: LLMProvider;
+    });
+    /**
+     * Count tokens for the messages. Uses provider.countTokens if available,
+     * otherwise falls back to heuristic estimation.
+     */
+    countTokens(messages: Message[]): Promise<number>;
+    /**
+     * Check if compaction is needed and apply it if so.
+     * Returns the (possibly compacted) messages array.
+     */
+    maybeCompact(messages: Message[]): Promise<Message[]>;
+    /**
+     * Force compaction (e.g. after receiving a "context too long" error from the API).
+     */
+    forceCompact(messages: Message[]): Promise<Message[]>;
+    setContextLimit(limit: number): void;
+    setCompactionStrategy(strategy: CompactionStrategy): void;
+}
+
+/**
+ * No-op compaction strategy that returns messages unchanged.
+ * Used when no compaction is desired.
+ */
+declare class NoopCompaction implements CompactionStrategy {
+    compact(messages: Message[], _maxTokens: number): Message[];
+}
+
+/**
+ * Sliding window compaction: keeps the system message (if any) plus
+ * the most recent messages that fit within the token budget.
+ *
+ * When compacting, older messages are dropped from the middle, preserving
+ * the system message at the start and the most recent messages at the end.
+ */
+declare class SlidingWindowCompaction implements CompactionStrategy {
+    compact(messages: Message[], maxTokens: number): Message[];
+}
+
+interface CompactionResult {
+    /** The compacted message array. */
+    messages: Message[];
+    /** Estimated token count before compaction. */
+    tokensBefore: number;
+    /** Estimated token count after compaction. */
+    tokensAfter: number;
+    /** Name of the strategy that was applied. */
+    strategy: string;
+}
+/**
+ * LLM-based compaction that summarizes older messages and keeps only
+ * the most recent N messages verbatim.
+ *
+ * Implements `CompactionStrategy` so it can be used with `AgentConfig.compactionStrategy`.
+ * The LLM provider must be passed in the constructor since the `compact()` interface
+ * only receives `(messages, maxTokens)`.
+ *
+ * The synchronous `compact()` method (required by the interface) kicks off an
+ * async summarization internally. Use `compactAsync()` when you need the full
+ * `CompactionResult` with token stats.
+ */
+declare class SummarizationCompaction implements CompactionStrategy {
+    private keepRecentN;
+    private thresholdFraction;
+    private summaryMaxTokens;
+    private summaryModel;
+    private provider;
+    constructor(provider: LLMProvider, options?: {
+        keepRecentN?: number;
+        thresholdFraction?: number;
+        summaryMaxTokens?: number;
+        /** Model to use for generating summaries. Defaults to "claude-3-5-haiku-20241022". */
+        summaryModel?: string;
+    });
+    /** Return true when the current usage exceeds the configured threshold. */
+    shouldCompact(messages: Message[], tokenCount: number, contextLimit: number): boolean;
+    /**
+     * Async compaction conforming to the CompactionStrategy interface.
+     * Uses the LLM provider to summarize older messages before dropping them.
+     */
+    compact(messages: Message[], _maxTokens: number): Promise<Message[]>;
+    /**
+     * Async compaction that uses the LLM provider to summarize older messages.
+     * Returns a `CompactionResult` with full token stats.
+     */
+    compactAsync(messages: Message[]): Promise<CompactionResult>;
+}
+
+/**
+ * In-memory session that holds conversation messages.
+ * Messages are lost when the process exits.
+ */
+declare class InMemorySession implements Session {
+    private messages;
+    getMessages(): Message[];
+    setMessages(messages: Message[]): void;
+    clear(): void;
+}
+
+/**
+ * JSONL-backed session that persists conversation messages to disk.
+ * Each session is stored as `{directory}/{id}.jsonl`, one JSON message per line.
+ */
+declare class FileSession implements Session {
+    private directory;
+    private id;
+    private messages;
+    constructor(directory: string, id: string);
+    /** Return a snapshot of the in-memory messages. */
+    getMessages(): Message[];
+    /** Replace the in-memory messages and persist to disk. */
+    setMessages(messages: Message[]): void;
+    /** Clear in-memory messages (does not delete the file). */
+    clear(): void;
+    /** Resolve the .jsonl file path for this session. */
+    filePath(): string;
+    /** Load messages from disk into memory. Returns self for chaining. */
+    load(): Promise<this>;
+    /** Write current in-memory messages to disk (overwrites the file). */
+    save(): Promise<void>;
+    /** Append a single message to the file without rewriting it. */
+    append(message: Message): Promise<void>;
+}
+/**
+ * Store that creates and manages file-backed sessions in a directory.
+ *
+ * @example
+ * ```ts
+ * const store = new FileSessionStore("./sessions");
+ * const session = await store.load("my-session");
+ * // ... use session ...
+ * await store.save("my-session", session);
+ * ```
+ */
+declare class FileSessionStore {
+    private directory;
+    constructor(directory: string);
+    /** Create a new (empty) session without persisting it. */
+    create(id: string): FileSession;
+    /** Load an existing session from disk. Returns null if not found. */
+    load(id: string): Promise<FileSession | null>;
+    /** Persist the current messages of a session to disk. */
+    save(id: string, session: FileSession): Promise<void>;
+    /** List all session IDs in the directory. */
+    list(): Promise<string[]>;
+    /** Delete a session file from disk. */
+    delete(id: string): Promise<void>;
+}
+
+/**
+ * Create a tiered permission handler from a configuration object.
+ *
+ * Permission tiers (checked in order):
+ *  1. Always allow list — tool is unconditionally allowed
+ *  2. Always deny list — tool is unconditionally denied
+ *  3. Session approved — tool was approved earlier in this session
+ *  4. Read-only auto-approve — if enabled, read-only tools are allowed
+ *  5. Callback — delegate to a custom handler (e.g. prompt the user)
+ *  6. Default — allow (no permission handler = auto-approve everything)
+ */
+declare function createPermissionHandler(config: PermissionConfig): PermissionHandler;
+/**
+ * Permission handler that allows everything. Useful for fully automated pipelines.
+ */
+declare const allowAll: PermissionHandler;
+/**
+ * Default permission handler: allows read-only tools, denies everything else.
+ * Used when no permissionHandler is configured in AgentConfig.
+ */
+declare const allowReadOnly: PermissionHandler;
+/**
+ * Permission handler that denies everything. Useful for dry-run / audit mode.
+ */
+declare const denyAll: PermissionHandler;
+
+interface AnthropicProviderOptions {
+    apiKey?: string;
+    baseURL?: string;
+}
+/**
+ * Provider adapter for the Anthropic Messages API.
+ *
+ * Requires `@anthropic-ai/sdk` as an optional peer dependency.
+ * The SDK is dynamically imported at first use.
+ */
+declare class AnthropicProvider implements LLMProvider {
+    private options;
+    private clientPromise;
+    constructor(options?: AnthropicProviderOptions);
+    chat(options: ChatOptions): AsyncGenerator<StreamChunk>;
+    countTokens(messages: Message[]): Promise<number>;
+}
+
+interface OpenAIProviderOptions {
+    apiKey?: string;
+    baseURL?: string;
+}
+/**
+ * Provider adapter for OpenAI-compatible Chat Completions API.
+ *
+ * Supports any OpenAI-compatible endpoint (OpenAI, Ollama, vLLM, Groq, Together)
+ * via the `baseURL` option.
+ *
+ * Requires `openai` SDK as an optional peer dependency.
+ */
+declare class OpenAIProvider implements LLMProvider {
+    private options;
+    private clientPromise;
+    constructor(options?: OpenAIProviderOptions);
+    chat(options: ChatOptions): AsyncGenerator<StreamChunk>;
+    countTokens(messages: Message[]): Promise<number>;
+}
+
+/**
+ * Mock provider for testing. Takes a queue of scripted responses —
+ * each run() call shifts one response off the queue and streams it.
+ *
+ * @example
+ * ```ts
+ * const provider = new MockProvider([
+ *   [{ type: "text", text: "Hello!" }, { type: "done" }],
+ *   [{ type: "text", text: "Goodbye!" }, { type: "done" }],
+ * ]);
+ * ```
+ */
+declare class MockProvider implements LLMProvider {
+    private queue;
+    private callLog;
+    constructor(responses: StreamChunk[][]);
+    chat(options: ChatOptions): AsyncGenerator<StreamChunk>;
+    countTokens(messages: Message[]): Promise<number>;
+    /** Get the log of all chat() calls made to this provider. */
+    getCalls(): ChatOptions[];
+    /** Check if all scripted responses have been consumed. */
+    isEmpty(): boolean;
+}
+
+type AuthMethodApiKey = {
+    type: "api-key";
+    envVar?: string;
+    inputLabel?: string;
+};
+type AuthMethodBaseUrlKey = {
+    type: "base-url-key";
+    defaultBaseURL: string;
+    envVar?: string;
+    inputLabel?: string;
+};
+type AuthMethodNone = {
+    type: "none";
+};
+type AuthMethod = AuthMethodApiKey | AuthMethodBaseUrlKey | AuthMethodNone;
+type AuthType = AuthMethod["type"];
+interface ProviderRegistration {
+    displayName: string;
+    description?: string;
+    authMethods: AuthMethod[];
+    defaultModel?: string;
+    models?: string[];
+    /** Factory that creates a configured LLMProvider from resolved credentials */
+    createProvider: (config: {
+        apiKey?: string;
+        baseURL?: string;
+        token?: string;
+    }) => LLMProvider;
+}
+type AuthFlowStep = "select-provider" | "select-auth-method" | "input-credentials" | "select-model" | "done";
+interface AuthFlowProviderOption {
+    name: string;
+    displayName: string;
+    description?: string;
+}
+interface AuthFlowState {
+    step: AuthFlowStep;
+    providers?: AuthFlowProviderOption[];
+    authMethods?: AuthMethod[];
+    models?: string[];
+    currentProvider?: string;
+    currentAuthMethod?: AuthMethod;
+    currentModel?: string;
+    result?: {
+        provider: LLMProvider;
+        model: string;
+        providerName: string;
+    };
+}
+interface AuthStorage {
+    get(provider: string): Promise<string | null>;
+    set(provider: string, credential: string): Promise<void>;
+    delete(provider: string): Promise<void>;
+    list(): Promise<string[]>;
+}
+interface AuthOptions {
+    storage?: AuthStorage;
+    /** Default: ~/.claude-code-kit/credentials.json */
+    storagePath?: string;
+}
+
+interface ProviderInfo {
+    name: string;
+    registration: ProviderRegistration;
+    hasCredential: boolean;
+}
+/**
+ * Open provider registry — register any LLM provider with multiple auth methods,
+ * then authenticate and get a configured LLMProvider instance.
+ *
+ * Supports an interactive step-by-step flow:
+ *   select-provider → select-auth-method → input-credentials → select-model → done
+ *
+ * Credential resolution order (for automatic auth):
+ * 1. Environment variable (if any auth method has `envVar`)
+ * 2. Stored credential (from AuthStorage)
+ * 3. Error (credential required but not found)
+ */
+declare class AuthRegistry {
+    private providers;
+    private storage;
+    constructor(options?: AuthOptions);
+    /**
+     * Register a provider. Open — any provider, any auth type.
+     * Overwrites existing registration with the same name.
+     */
+    register(name: string, registration: ProviderRegistration): void;
+    unregister(name: string): boolean;
+    getRegistration(name: string): ProviderRegistration | undefined;
+    /**
+     * Get the list of available models for a registered provider.
+     */
+    getModels(providerName: string): string[];
+    private resolveEnvCredential;
+    /**
+     * Authenticate and get a configured LLMProvider.
+     *
+     * Resolution order for each auth method (tried in order):
+     * 1. Environment variable (if method has `envVar`)
+     * 2. Stored credential (from AuthStorage)
+     * 3. Next auth method
+     *
+     * If no method resolves, throws.
+     *
+     * For providers with a `type: 'none'` auth method, no credential is required.
+     */
+    authenticate(name: string): Promise<LLMProvider>;
+    /**
+     * Get a provider using only environment variables — no storage, no prompts.
+     * Throws if no env var resolves (or provider has a 'none' method).
+     */
+    fromEnv(name: string): LLMProvider;
+    storeCredential(name: string, credential: string): Promise<void>;
+    listProviders(): Promise<ProviderInfo[]>;
+    logout(name: string): Promise<void>;
+    /**
+     * Start the interactive auth flow.
+     * Returns the initial state with all available providers listed.
+     */
+    interactive(): AuthFlowState;
+    /**
+     * Advance the interactive flow by selecting a provider.
+     */
+    selectProvider(providerName: string): AuthFlowState;
+    /**
+     * Advance the interactive flow by selecting an auth method.
+     * Only needed when a provider has multiple auth methods.
+     */
+    selectAuthMethod(providerName: string, methodIndex: number): AuthFlowState;
+    /**
+     * Advance the interactive flow by providing credentials.
+     * Stores the credential and moves to model selection (or done).
+     */
+    inputCredentials(providerName: string, method: AuthMethod, credentials: {
+        apiKey?: string;
+        baseURL?: string;
+        token?: string;
+    }): Promise<AuthFlowState>;
+    /**
+     * Advance the interactive flow by selecting a model.
+     * Returns the final 'done' state with a configured provider.
+     */
+    selectModel(providerName: string, method: AuthMethod, model: string, credentials?: {
+        apiKey?: string;
+        baseURL?: string;
+        token?: string;
+    }): Promise<AuthFlowState>;
+}
+
+/**
+ * File-based credential storage.
+ * Stores credentials as a JSON object `{ [provider]: credential }`.
+ */
+declare class FileAuthStorage implements AuthStorage {
+    private filePath;
+    constructor(filePath?: string);
+    get(provider: string): Promise<string | null>;
+    set(provider: string, credential: string): Promise<void>;
+    delete(provider: string): Promise<void>;
+    list(): Promise<string[]>;
+    private read;
+    private write;
+}
+/**
+ * In-memory credential storage for testing.
+ */
+declare class MemoryAuthStorage implements AuthStorage {
+    private store;
+    get(provider: string): Promise<string | null>;
+    set(provider: string, credential: string): Promise<void>;
+    delete(provider: string): Promise<void>;
+    list(): Promise<string[]>;
+}
+
+/**
+ * Pre-registered common LLM providers.
+ * Each supports multiple auth methods — the user picks one during interactive flow.
+ * Users can override any of these or add their own via `registry.register()`.
+ */
+declare const PRESET_PROVIDERS: Record<string, ProviderRegistration>;
+
+/**
+ * Create an AuthRegistry with all preset providers pre-registered.
+ *
+ * @example
+ * ```ts
+ * const auth = createAuth();
+ * const provider = await auth.authenticate('anthropic');
+ * // or register your own
+ * auth.register('my-llm', { displayName: 'My LLM', authMethods: [...], ... });
+ * ```
+ */
+declare function createAuth(options?: AuthOptions): AuthRegistry;
+
+export { Agent, type AgentConfig, type AgentEvent, AnthropicProvider, type AssistantMessage, type AuthFlowProviderOption, type AuthFlowState, type AuthFlowStep, type AuthMethod, type AuthMethodApiKey, type AuthMethodBaseUrlKey, type AuthMethodNone, type AuthOptions, AuthRegistry, type AuthStorage, type AuthType, type ChatOptions, type CompactionResult, type CompactionStrategy, type ContentPart, ContextManager, type DoneEvent, type ErrorEvent, FileAuthStorage, FileSession, FileSessionStore, type ImageContentPart, InMemorySession, type LLMProvider, MemoryAuthStorage, type Message, MockProvider, NoopCompaction, OpenAIProvider, PRESET_PROVIDERS, type PermissionConfig, type PermissionHandler, type PermissionRequest, type PermissionResult, type ProviderInfo, type ProviderRegistration, type ProviderTool, type Session, SlidingWindowCompaction, type StreamChunk, SummarizationCompaction, type SystemMessage, type TextContentPart, type TextEvent, type ThinkingEvent, type ToolCall, type ToolCallEvent, type ToolContext, type ToolDefinition, type ToolProgress, ToolRegistry, type ToolResult, type ToolResultEvent, type ToolResultMessage, type UsageEvent, type UserMessage, allowAll, allowReadOnly, createAuth, createPermissionHandler, denyAll, estimateTokens, estimateTotalTokens };