@dugleelabs/copair 1.2.0 → 1.4.0

package/dist/api.d.ts

@@ -0,0 +1,738 @@
+import { z, ZodTypeAny } from 'zod';
+import { EventEmitter } from 'node:events';
+
+interface Message {
+    role: 'user' | 'assistant' | 'system';
+    content: ContentBlock[];
+}
+type ContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+} | {
+    type: 'tool_result';
+    toolUseId: string;
+    content: string;
+    isError?: boolean;
+};
+interface StreamChunk {
+    type: 'text' | 'tool_call' | 'tool_call_delta' | 'usage' | 'error' | 'done';
+    text?: string;
+    toolCall?: {
+        id: string;
+        name: string;
+        arguments: string;
+        metadata?: Record<string, unknown>;
+    };
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    error?: string;
+}
+interface ProviderOptions {
+    model: string;
+    maxTokens?: number;
+    temperature?: number;
+    systemPrompt?: string;
+    stream: boolean;
+}
+interface Provider {
+    readonly name: string;
+    readonly supportsToolCalling: boolean;
+    readonly supportsStreaming: boolean;
+    readonly maxContextWindow: number;
+    /** When true, the provider can fall back to a built-in web search tool when the agent's configured web search fails. */
+    readonly supportsNativeSearch?: boolean;
+    chat(messages: Message[], tools: ToolDefinition$1[], options: ProviderOptions): AsyncIterableIterator<StreamChunk>;
+    countTokens?(messages: Message[]): Promise<number>;
+}
+interface ToolDefinition$1 {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+
+declare const ProviderConfigSchema: z.ZodObject<{
+    api_key: z.ZodOptional<z.ZodString>;
+    base_url: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<{
+        anthropic: "anthropic";
+        openai: "openai";
+        google: "google";
+        "openai-compatible": "openai-compatible";
+    }>>;
+    models: z.ZodRecord<z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+        max_tokens: z.ZodOptional<z.ZodNumber>;
+        context_window: z.ZodOptional<z.ZodNumber>;
+        supports_tool_calling: z.ZodOptional<z.ZodBoolean>;
+        supports_streaming: z.ZodOptional<z.ZodBoolean>;
+        tool_call_format: z.ZodOptional<z.ZodEnum<{
+            dsml: "dsml";
+            "qwen-xml": "qwen-xml";
+            "fenced-block": "fenced-block";
+        }>>;
+    }, z.core.$strip>>;
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const CopairConfigSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    default_model: z.ZodOptional<z.ZodString>;
+    providers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        api_key: z.ZodOptional<z.ZodString>;
+        base_url: z.ZodOptional<z.ZodString>;
+        type: z.ZodOptional<z.ZodEnum<{
+            anthropic: "anthropic";
+            openai: "openai";
+            google: "google";
+            "openai-compatible": "openai-compatible";
+        }>>;
+        models: z.ZodRecord<z.ZodString, z.ZodObject<{
+            id: z.ZodString;
+            max_tokens: z.ZodOptional<z.ZodNumber>;
+            context_window: z.ZodOptional<z.ZodNumber>;
+            supports_tool_calling: z.ZodOptional<z.ZodBoolean>;
+            supports_streaming: z.ZodOptional<z.ZodBoolean>;
+            tool_call_format: z.ZodOptional<z.ZodEnum<{
+                dsml: "dsml";
+                "qwen-xml": "qwen-xml";
+                "fenced-block": "fenced-block";
+            }>>;
+        }, z.core.$strip>>;
+        timeout_ms: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    permissions: z.ZodDefault<z.ZodObject<{
+        mode: z.ZodDefault<z.ZodEnum<{
+            ask: "ask";
+            "auto-approve": "auto-approve";
+            deny: "deny";
+        }>>;
+        allow_commands: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        allow_paths: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        deny_paths: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    feature_flags: z.ZodDefault<z.ZodObject<{
+        model_routing: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    mcp_servers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        command: z.ZodString;
+        args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        timeout_ms: z.ZodOptional<z.ZodNumber>;
+        inherit_env: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    plugins: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    web_search: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodEnum<{
+            tavily: "tavily";
+            serper: "serper";
+            searxng: "searxng";
+        }>;
+        api_key: z.ZodOptional<z.ZodString>;
+        base_url: z.ZodOptional<z.ZodString>;
+        max_results: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    identity: z.ZodDefault<z.ZodObject<{
+        name: z.ZodDefault<z.ZodString>;
+        email: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    context: z.ZodDefault<z.ZodObject<{
+        summarization_model: z.ZodOptional<z.ZodString>;
+        max_sessions: z.ZodDefault<z.ZodNumber>;
+        knowledge_max_size: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    knowledge: z.ZodDefault<z.ZodObject<{
+        warn_size_kb: z.ZodDefault<z.ZodNumber>;
+        max_size_kb: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    ui: z.ZodDefault<z.ZodObject<{
+        bordered_input: z.ZodDefault<z.ZodBoolean>;
+        status_bar: z.ZodDefault<z.ZodBoolean>;
+        syntax_highlight: z.ZodDefault<z.ZodBoolean>;
+        output_collapsing: z.ZodDefault<z.ZodBoolean>;
+        vi_mode: z.ZodDefault<z.ZodBoolean>;
+        suggestions: z.ZodDefault<z.ZodBoolean>;
+        tab_completion: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    security: z.ZodOptional<z.ZodObject<{
+        path_validation: z.ZodDefault<z.ZodEnum<{
+            strict: "strict";
+            warn: "warn";
+        }>>;
+        redact_high_entropy: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    network: z.ZodOptional<z.ZodObject<{
+        web_search_timeout_ms: z.ZodDefault<z.ZodNumber>;
+        provider_timeout_ms: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type CopairConfig = z.infer<typeof CopairConfigSchema>;
+type ProviderConfig = z.infer<typeof ProviderConfigSchema>;
+
+type ProviderFactory = (config: ProviderConfig, model: string) => Provider;
+declare class ProviderRegistry {
+    private factories;
+    private instances;
+    register(name: string, factory: ProviderFactory): void;
+    resolve(providerName: string, config: ProviderConfig, model: string): Provider;
+    has(name: string): boolean;
+    availableProviders(): string[];
+}
+
+interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+interface ToolResult {
+    content: string;
+    isError?: boolean;
+}
+interface Tool {
+    definition: ToolDefinition;
+    /**
+     * Zod schema for runtime validation of tool input before execution (FR-02).
+     * Required for all built-in tools. MCP tools omit this field and receive
+     * no schema validation (passthrough).
+     */
+    inputSchema?: ZodTypeAny;
+    requiresPermission: boolean;
+    execute(input: Record<string, unknown>): Promise<ToolResult>;
+}
+
+declare class ToolRegistry {
+    private builtinTools;
+    private mcpTools;
+    register(tool: Tool): void;
+    registerMcpTools(serverName: string, tools: Tool[]): void;
+    get(name: string): Tool | undefined;
+    getAllDefinitions(): ToolDefinition[];
+}
+
+interface AllowRules {
+    /** bash entries: exact match, or prefix if the pattern ends with " *" */
+    bash: string[];
+    /**
+     * git entries: matched against the args string.
+     * Entry is the subcommand (e.g. "diff") — automatically covers all
+     * flags for that subcommand (e.g. "diff --cached", "diff HEAD~1").
+     */
+    git: string[];
+    /**
+     * write / edit entries: glob patterns matched against the file path.
+     * Supports * (within a segment) and ** (across segments).
+     */
+    write: string[];
+    edit: string[];
+}
+declare class AllowList {
+    private rules;
+    constructor(rules?: Partial<AllowRules>);
+    /**
+     * Returns true when the operation is explicitly listed and should bypass
+     * the approval prompt. Called by ApprovalGate before prompting.
+     */
+    matches(toolName: string, input: Record<string, unknown>): boolean;
+    private matchBash;
+    private matchGit;
+    private matchPath;
+}
+
+interface ToolInfo {
+    name: string;
+    label: string;
+    input: Record<string, unknown>;
+}
+interface ToolCompleteInfo {
+    name: string;
+    label: string;
+    durationMs: number;
+    result?: string;
+}
+interface DiffHunk {
+    oldStart: number;
+    newStart: number;
+    lines: string[];
+}
+interface DiffInfo {
+    filePath: string;
+    hunks: DiffHunk[];
+}
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cost: number;
+    sessionInputTokens: number;
+    sessionOutputTokens: number;
+    sessionCost: number;
+    contextPercent?: number;
+}
+type ApprovalAnswer = 'allow' | 'always' | 'deny' | 'all' | 'similar';
+interface ApprovalRequest {
+    toolName: string;
+    input: Record<string, unknown>;
+    summary: string;
+    index: number;
+    total: number;
+    diff?: DiffInfo;
+    /** Present when a bash command references a sensitive system path. */
+    warning?: string;
+}
+interface AgentBridgeEvents {
+    'stream-text': (text: string) => void;
+    'stream-code-block': (code: string, lang: string) => void;
+    'tool-start': (tool: ToolInfo) => void;
+    'tool-complete': (tool: ToolCompleteInfo) => void;
+    'tool-denied': (tool: {
+        name: string;
+        label: string;
+    }) => void;
+    'approval-request': (request: ApprovalRequest, respond: (answer: ApprovalAnswer) => void) => void;
+    'diff': (diff: DiffInfo) => void;
+    'usage': (usage: TokenUsage) => void;
+    'thinking-start': () => void;
+    'thinking-stop': () => void;
+    'turn-complete': () => void;
+    'error': (message: string) => void;
+    'input-request': (respond: (input: string) => void) => void;
+}
+type EventName = keyof AgentBridgeEvents;
+/**
+ * Event-based bridge between the agent loop and the ink UI.
+ *
+ * The agent loop emits events (stream chunks, tool status, approval requests)
+ * and the UI subscribes to render them. Input flows back from the UI to the
+ * agent via callback functions passed in event payloads.
+ */
+declare class AgentBridge extends EventEmitter {
+    /** Turn-scoped flag: when true, remaining tool calls skip approval. */
+    approveAllForTurn: boolean;
+    emit<K extends EventName>(event: K, ...args: Parameters<AgentBridgeEvents[K]>): boolean;
+    on<K extends EventName>(event: K, listener: AgentBridgeEvents[K]): this;
+    once<K extends EventName>(event: K, listener: AgentBridgeEvents[K]): this;
+    off<K extends EventName>(event: K, listener: AgentBridgeEvents[K]): this;
+    /** Reset turn-scoped state. Called on 'turn-complete'. */
+    resetTurn(): void;
+}
+
+/**
+ * Append-only audit log for a single copair session.
+ *
+ * Each session produces one audit.jsonl file at:
+ *   .copair/sessions/<id>/audit.jsonl
+ *
+ * Every line is a JSON-serialized AuditEntry. The file is created with mode
+ * 0o600 on first write and is append-only — existing entries are never
+ * modified or deleted by this module.
+ *
+ * input_summary is always redacted and truncated to ≤ 200 chars before
+ * writing so that raw secrets never appear in the audit log.
+ */
+type AuditEvent = 'session_start' | 'session_end' | 'tool_call' | 'approval' | 'denial' | 'path_block' | 'schema_rejection' | 'bash_sensitive_path';
+type AuditOutcome = 'allowed' | 'denied' | 'error';
+interface AuditEntry {
+    ts: string;
+    event: AuditEvent;
+    tool?: string;
+    /** Truncated (≤ 200 chars) and redacted summary of tool input. Never contains raw secrets. */
+    input_summary?: string;
+    approved_by?: 'user' | 'allow_list' | 'auto';
+    outcome: AuditOutcome;
+    detail?: string;
+}
+/** Input to append() — ts is added automatically; input_summary is raw (will be redacted). */
+type AuditEntryInput = Omit<AuditEntry, 'ts'>;
+declare class AuditLog {
+    private readonly logPath;
+    constructor(sessionDir: string);
+    /** Append one entry. input_summary is redacted and truncated before writing. */
+    append(input: AuditEntryInput): Promise<void>;
+    getLogPath(): string;
+}
+
+type RiskLevel = 'safe' | 'needs-approval' | 'always-ask';
+type GateMode = 'ask' | 'auto-approve' | 'deny';
+declare class ApprovalGate {
+    private mode;
+    private alwaysAllow;
+    private allowList;
+    private trustedPaths;
+    private bridge;
+    private auditLog;
+    private pendingIndex;
+    private pendingTotal;
+    constructor(mode?: GateMode, allowList?: AllowList | null);
+    /** Set the bridge for ink-based approval prompts. */
+    setBridge(bridge: AgentBridge): void;
+    setAuditLog(log: AuditLog): void;
+    /** Set context for batch approval counting. */
+    setApprovalContext(index: number, total: number): void;
+    /** Register a path as trusted. File mutations under/at this path skip approval. */
+    addTrustedPath(path: string): void;
+    /** Check if a tool call targets a trusted path. Only applies to write/edit tools. */
+    isTrustedPath(toolName: string, input: Record<string, unknown>): boolean;
+    classify(toolName: string, input: Record<string, unknown>): RiskLevel;
+    /**
+     * Gate check. Called unconditionally before every tool execution.
+     * Returns true if execution may proceed, false if denied.
+     *
+     * The agent never calls this. ToolExecutor calls it. The agent only
+     * sees the resulting ExecutionResult.
+     */
+    allow(toolName: string, input: Record<string, unknown>): Promise<boolean>;
+    /** Bridge-based approval: emit event and await response from ink UI. */
+    private bridgePrompt;
+    /** Legacy approval prompt: reads from /dev/tty directly (not stdin).
+     *
+     * @param defaultAllow  When true (used for `always-ask` tools like web_search),
+     *   pressing Enter without typing confirms the action.  For all other tools the
+     *   safe default is to deny on empty input.
+     */
+    private legacyPrompt;
+}
+
+/**
+ * Repository boundary enforcement for all file-system tool operations.
+ *
+ * PathGuard is a session singleton instantiated once at startup and injected
+ * into ToolExecutor. All path checking is centralized there — individual tools
+ * receive an already-resolved path and never call PathGuard directly. This
+ * ensures new file tools cannot accidentally bypass the boundary check.
+ *
+ * P0 policy: all paths outside the project root are unconditionally denied.
+ * P1 policy: PathPolicy introduces an allow_paths escape hatch (subject to
+ * normal approval gate) and a deny_paths override for the built-in deny list.
+ * Paths matching the deny list are always denied, regardless of allow_paths.
+ *
+ * Check order (outside-project paths only):
+ *   1. Built-in deny list / deny_paths → hard deny
+ *   2. allow_paths glob match → allow (to approval gate)
+ *   3. Default → deny (strict) or warn+allow (warn mode)
+ *
+ * Note on .env patterns: BUILTIN_DENY includes glob patterns for .env files
+ * scoped to paths outside the project root. Paths inside the project root
+ * return at step 1 of check() before the deny list is evaluated, so .env
+ * files inside the project are subject only to the normal approval gate.
+ */
+type PathGuardResult = {
+    allowed: true;
+    resolvedPath: string;
+} | {
+    allowed: false;
+    reason: 'access-denied' | 'parent-missing';
+};
+/**
+ * P1 policy configuration for cross-project path access.
+ * Sourced from `permissions.allow_paths` and `permissions.deny_paths` in config.
+ */
+interface PathPolicy {
+    /** Glob patterns of paths outside the project root that the agent may request access to. */
+    allowPaths: string[];
+    /**
+     * Glob patterns unconditionally denied regardless of approval mode or session overrides.
+     * When non-empty, replaces BUILTIN_DENY entirely. To add to the built-in list, spread
+     * BUILTIN_DENY into this array.
+     */
+    denyPaths: string[];
+}
+declare class PathGuard {
+    private projectRoot;
+    private mode;
+    private expandedDenyPatterns;
+    private expandedAllowPatterns;
+    constructor(cwd: string, mode?: 'strict' | 'warn', policy?: PathPolicy);
+    /**
+     * Resolve a path and check it against the project boundary and deny/allow lists.
+     *
+     * @param rawPath   The raw path string from tool input.
+     * @param mustExist true for read operations (file must exist); false for
+     *                  write/edit operations (parent dir must exist).
+     */
+    check(rawPath: string, mustExist: boolean): PathGuardResult;
+    private isDenied;
+    private isAllowed;
+    /**
+     * Attempt to locate the git repository root starting from cwd.
+     * Falls back to cwd itself if not inside a git repo.
+     *
+     * Runs exactly once per session (at PathGuard construction).
+     */
+    static findProjectRoot(cwd: string): string;
+}
+
+interface ExecutionResult {
+    content: string;
+    isError?: boolean;
+    /** True when the gate blocked execution. The agent sees this as a tool error. */
+    denied?: boolean;
+    /** Actual tool execution time in ms (excludes approval prompt wait). */
+    _durationMs?: number;
+}
+/**
+ * Executes tools on behalf of the agent loop.
+ *
+ * This is the only path through which a tool may run. The execution order is:
+ *   1. FR-02: Zod schema validation (rejects malformed input before anything else)
+ *   2. Approval gate (unconditional — cannot be bypassed)
+ *   3. FR-03: PathGuard boundary check (centralized — individual tools never call PathGuard)
+ *   4. Tool execution
+ *   5. FR-04: Redact secrets from output before returning to agent
+ *
+ * The agent has no reference to the ApprovalGate or PathGuard and cannot
+ * influence whether these checks run.
+ */
+declare class ToolExecutor {
+    private readonly registry;
+    private readonly gate;
+    private readonly pathGuard;
+    private auditLog;
+    constructor(registry: ToolRegistry, gate: ApprovalGate, pathGuardOrCwd?: PathGuard | string);
+    setAuditLog(log: AuditLog): void;
+    execute(toolName: string, rawInput: Record<string, unknown>, onApproved?: () => void): Promise<ExecutionResult>;
+    /**
+     * Inspect tool input for known path fields and run each through PathGuard.
+     * Returns an error ExecutionResult if any path is denied, otherwise null.
+     * Mutates input[field] with the resolved (realpath) value on success so the
+     * tool uses a canonical path rather than a potentially traversal-containing one.
+     *
+     * Centralised here so individual tools never need to call PathGuard directly.
+     */
+    private checkPaths;
+}
+
+interface PluginContext {
+    config: CopairConfig;
+    providerRegistry: ProviderRegistry;
+    toolRegistry: ToolRegistry;
+    version: string;
+    edition: 'community' | 'pro';
+}
+interface PreRequestEvent {
+    messages: Message[];
+    tools: ToolDefinition$1[];
+    systemPrompt: string;
+    provider: Provider;
+    model: string;
+    /** Metadata plugins can attach — survives across hooks in the same turn */
+    meta: Record<string, unknown>;
+}
+interface PostRequestEvent {
+    messages: Message[];
+    response: {
+        text: string;
+        toolCalls: Array<{
+            id: string;
+            name: string;
+            input: Record<string, unknown>;
+        }>;
+        usage: {
+            inputTokens: number;
+            outputTokens: number;
+        } | null;
+    };
+    provider: Provider;
+    model: string;
+    meta: Record<string, unknown>;
+}
+interface ProviderInterceptEvent {
+    currentProvider: Provider;
+    model: string;
+    messages: Message[];
+    tokenCount: number;
+}
+interface PreToolCallEvent {
+    toolName: string;
+    input: Record<string, unknown>;
+    meta: Record<string, unknown>;
+}
+interface PostToolCallEvent {
+    toolName: string;
+    input: Record<string, unknown>;
+    result: ExecutionResult;
+    meta: Record<string, unknown>;
+}
+interface SessionEvent {
+    sessionId: string;
+    model: string;
+    config: CopairConfig;
+    type: 'create' | 'resume' | 'close';
+}
+interface CopairPlugin {
+    /** Unique plugin name (e.g., 'copair-pro/demo') */
+    name: string;
+    /** Plugin version (informational, not enforced) */
+    version: string;
+    /**
+     * Called once during bootstrap, after config is loaded.
+     * Use for setup: register custom providers, tools, commands.
+     */
+    initialize?(context: PluginContext): Promise<void> | void;
+    /**
+     * Called before each LLM request.
+     * Can modify messages, tools, or swap the provider.
+     */
+    preRequest?(event: PreRequestEvent): Promise<PreRequestEvent> | PreRequestEvent;
+    /**
+     * Called after each LLM response (full turn, after streaming completes).
+     * Read-only observation point.
+     */
+    postRequest?(event: PostRequestEvent): Promise<void> | void;
+    /**
+     * Called before provider.chat() — can return a different provider.
+     * This is the hook for smart model switching.
+     */
+    providerInterceptor?(event: ProviderInterceptEvent): Provider | undefined;
+    /** Called before a tool executes (after validation + approval) */
+    preToolCall?(event: PreToolCallEvent): Promise<PreToolCallEvent> | PreToolCallEvent;
+    /** Called after a tool executes */
+    postToolCall?(event: PostToolCallEvent): Promise<void> | void;
+    /** Called when a session starts or resumes */
+    sessionStart?(event: SessionEvent): Promise<void> | void;
+    /** Called when a session ends */
+    sessionEnd?(event: SessionEvent): Promise<void> | void;
+    /** Cleanup on shutdown */
+    destroy?(): Promise<void> | void;
+}
+
+declare class PluginManager {
+    private plugins;
+    /**
+     * Register a plugin instance. Called during bootstrap
+     * (either from config.yaml or programmatic API).
+     */
+    register(plugin: CopairPlugin): void;
+    /**
+     * Load plugins from config.yaml `plugins` array.
+     * Each entry is a package name or local path resolved via import().
+     */
+    loadFromConfig(pluginPaths: string[]): Promise<void>;
+    /** Initialize all plugins (called once during bootstrap). */
+    initialize(context: PluginContext): Promise<void>;
+    /**
+     * Run preRequest hooks in registration order.
+     * Each plugin receives the (possibly modified) event from the prior plugin.
+     */
+    preRequest(event: PreRequestEvent): Promise<PreRequestEvent>;
+    /** Run postRequest hooks (observation only). */
+    postRequest(event: PostRequestEvent): Promise<void>;
+    /**
+     * Run providerInterceptor hooks. First plugin to return
+     * a non-undefined provider wins (short-circuit).
+     */
+    interceptProvider(event: ProviderInterceptEvent): Provider;
+    preToolCall(event: PreToolCallEvent): Promise<PreToolCallEvent>;
+    postToolCall(event: PostToolCallEvent): Promise<void>;
+    sessionStart(event: SessionEvent): Promise<void>;
+    sessionEnd(event: SessionEvent): Promise<void>;
+    /** Destroy all plugins on shutdown. */
+    destroy(): Promise<void>;
+    /** Get the count of registered plugins. */
+    get count(): number;
+}
+
+declare class ConversationManager {
+    private messages;
+    append(role: Message['role'], content: ContentBlock[]): void;
+    appendText(role: Message['role'], text: string): void;
+    getHistory(): Message[];
+    clear(): void;
+    get length(): number;
+    toJSONL(): string;
+    static fromJSONL(data: string): Message[];
+}
+
+type FormatName = 'dsml' | 'qwen-xml' | 'fenced-block';
+
+interface AgentOptions {
+    systemPrompt?: string;
+    maxTokens?: number;
+    temperature?: number;
+    toolCallFormat?: FormatName;
+    bridge?: AgentBridge;
+    pluginManager?: PluginManager;
+}
+declare class Agent {
+    private provider;
+    private toolRegistry;
+    private executor;
+    private conversation;
+    private contextWindow;
+    private renderer;
+    private options;
+    private _model;
+    private formatter;
+    private textFilter;
+    private pluginManager?;
+    constructor(provider: Provider, model: string, toolRegistry: ToolRegistry, executor: ToolExecutor, options?: AgentOptions);
+    get model(): string;
+    getConversation(): ConversationManager;
+    /**
+     * Switch to a new provider/model mid-session.
+     * Summarizes the conversation using the current model, then reinitializes.
+     */
+    switchModel(newProvider: Provider, newModel: string): Promise<void>;
+    handleMessage(userInput: string): Promise<{
+        usage: {
+            inputTokens: number;
+            outputTokens: number;
+        } | null;
+        /** Input tokens from the last API call — reflects actual context window usage. */
+        lastInputTokens: number;
+    }>;
+}
+
+interface SessionMetadata {
+    id: string;
+    identifier: string;
+    model: string;
+    created: string;
+    lastActive: string;
+    messageCount: number;
+    hasSummary: boolean;
+    branch?: string;
+    identifierDerived?: boolean;
+}
+declare class SessionManager {
+    private metadata;
+    private sessionDir;
+    private sessionsDir;
+    private saveOffset;
+    private projectRoot;
+    constructor(projectRoot: string);
+    create(model: string, branch?: string): Promise<SessionMetadata>;
+    save(messages: Message[]): Promise<void>;
+    resume(sessionId: string): Promise<{
+        metadata: SessionMetadata;
+        messages: Message[];
+        summary: string | null;
+    }>;
+    close(messages?: Message[], summarizer?: {
+        summarize(messages: Message[]): Promise<string | null>;
+    }): Promise<void>;
+    updateIdentifier(identifier: string): void;
+    rename(newName: string): void;
+    getMetadata(): SessionMetadata | null;
+    getSessionDir(): string;
+    static listSessions(sessionsDir: string): Promise<SessionMetadata[]>;
+    static deleteSession(sessionsDir: string, sessionId: string): Promise<void>;
+    static migrateGlobalRecovery(sessionsDir: string, projectRoot: string): Promise<SessionMetadata | null>;
+    static cleanup(sessionsDir: string, maxSessions: number): Promise<void>;
+}
+
+declare function getVersionString(options?: BootstrapOptions): string;
+interface BootstrapOptions {
+    edition?: 'community' | 'pro';
+    editionVersion?: string;
+    plugins?: CopairPlugin[];
+    argv?: string[];
+}
+declare function bootstrapCLI(options?: BootstrapOptions): Promise<void>;
+
+export { Agent, type AgentOptions, ApprovalGate, type BootstrapOptions, type CopairConfig, type CopairPlugin, type Message, type PluginContext, PluginManager, type PostRequestEvent, type PostToolCallEvent, type PreRequestEvent, type PreToolCallEvent, type Provider, type ProviderInterceptEvent, type ProviderOptions, ProviderRegistry, type SessionEvent, SessionManager, type StreamChunk, type Tool, type ToolDefinition$1 as ToolDefinition, ToolExecutor, ToolRegistry, type ToolResult, bootstrapCLI, getVersionString };