@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/agent/agent-sdk-types.d.ts

@@ -0,0 +1,809 @@
+import type { Options as ClaudeAgentOptions } from "@anthropic-ai/claude-agent-sdk";
+import type { AgentProviderNotice } from "@hyperdrive.bot/fleet-protocol/agent-types";
+import type { AgentAttachment } from "@hyperdrive.bot/fleet-protocol/messages";
+import type { PaseoToolCatalog } from "./tools/types.js";
+export type { AgentProviderNotice };
+export type AgentProvider = string;
+export interface AgentMetadata {
+    [key: string]: unknown;
+}
+/**
+ * Stdio-based MCP server (spawns a subprocess).
+ */
+export interface McpStdioServerConfig {
+    type: "stdio";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    /**
+     * When true, all tools from this server are always included in the prompt
+     * and never deferred behind tool search. Honored by the Claude provider.
+     */
+    alwaysLoad?: boolean;
+}
+/**
+ * HTTP-based MCP server.
+ */
+export interface McpHttpServerConfig {
+    type: "http";
+    url: string;
+    headers?: Record<string, string>;
+    /**
+     * When true, all tools from this server are always included in the prompt
+     * and never deferred behind tool search. Honored by the Claude provider.
+     */
+    alwaysLoad?: boolean;
+}
+/**
+ * SSE-based MCP server (Server-Sent Events over HTTP).
+ */
+export interface McpSseServerConfig {
+    type: "sse";
+    url: string;
+    headers?: Record<string, string>;
+    /**
+     * When true, all tools from this server are always included in the prompt
+     * and never deferred behind tool search. Honored by the Claude provider.
+     */
+    alwaysLoad?: boolean;
+}
+/**
+ * Canonical MCP server configuration.
+ * Discriminated union by `type` field.
+ * Each provider normalizes this to their expected format.
+ */
+export type McpServerConfig = McpStdioServerConfig | McpHttpServerConfig | McpSseServerConfig;
+export interface AgentMode {
+    id: string;
+    label: string;
+    description?: string;
+    icon?: string;
+    colorTier?: string;
+    isUnattended?: boolean;
+}
+export type ProviderStatus = "ready" | "loading" | "error" | "unavailable";
+export interface AgentModelDefinition {
+    provider: AgentProvider;
+    id: string;
+    label: string;
+    description?: string;
+    isDefault?: boolean;
+    metadata?: AgentMetadata;
+    contextWindowMaxTokens?: number;
+    thinkingOptions?: AgentSelectOption[];
+    defaultThinkingOptionId?: string;
+}
+export interface AgentSelectOption {
+    id: string;
+    label: string;
+    description?: string;
+    isDefault?: boolean;
+    metadata?: AgentMetadata;
+}
+export declare function normalizeAgentModelDefinition(model: AgentModelDefinition): AgentModelDefinition;
+export interface ProviderSnapshotEntry {
+    provider: AgentProvider;
+    status: ProviderStatus;
+    enabled: boolean;
+    error?: string;
+    models?: AgentModelDefinition[];
+    modes?: AgentMode[];
+    fetchedAt?: string;
+    label?: string;
+    description?: string;
+    defaultModeId?: string | null;
+    /**
+     * Wire-format family. Optional for backward compatibility with old daemons
+     * that did not emit this field; new daemons always set it.
+     */
+    wireFamily?: "anthropic-messages" | "openai-compatible" | "generic-acp";
+    /**
+     * Effective hot-swap targets — provider IDs this provider can swap TO
+     * mid-session. Empty array means no swap is currently allowed. Optional
+     * for backward compatibility; old daemons did not emit this.
+     */
+    compatibleProviders?: string[];
+}
+export interface AgentCreateConfigParent {
+    provider: AgentProvider;
+    modeId: string | null;
+    isUnattended: boolean;
+}
+export interface ResolveAgentCreateConfigInput {
+    provider: AgentProvider;
+    requestedMode: string | undefined;
+    featureValues: Record<string, unknown> | undefined;
+    parent: AgentCreateConfigParent | null;
+    unattended: boolean;
+    availableModes: AgentMode[] | undefined;
+}
+export interface ResolveAgentCreateConfigResult {
+    modeId: string | undefined;
+    featureValues: Record<string, unknown> | undefined;
+}
+export interface AgentCreateConfigUnattendedInput {
+    modeId: string | null;
+    config: AgentSessionConfig;
+    features?: AgentFeature[];
+    availableModes: AgentMode[];
+}
+export interface AgentFeatureToggle {
+    type: "toggle";
+    id: string;
+    label: string;
+    description?: string;
+    tooltip?: string;
+    icon?: string;
+    value: boolean;
+}
+export interface AgentFeatureSelect {
+    type: "select";
+    id: string;
+    label: string;
+    description?: string;
+    tooltip?: string;
+    icon?: string;
+    value: string | null;
+    options: AgentSelectOption[];
+}
+export type AgentFeature = AgentFeatureToggle | AgentFeatureSelect;
+export interface AgentCapabilityFlags {
+    [capability: string]: boolean | undefined;
+    supportsStreaming: boolean;
+    supportsSessionPersistence: boolean;
+    supportsSessionListing?: boolean;
+    supportsDynamicModes: boolean;
+    supportsMcpServers: boolean;
+    supportsNativePaseoTools?: boolean;
+    supportsReasoningStream: boolean;
+    supportsToolInvocations: boolean;
+    supportsRewindConversation?: boolean;
+    supportsRewindFiles?: boolean;
+    supportsRewindBoth?: boolean;
+}
+export interface AgentPersistenceHandle {
+    provider: AgentProvider;
+    sessionId: string;
+    /** Provider specific handle (Codex thread id, Claude resume token, etc). */
+    nativeHandle?: string;
+    metadata?: AgentMetadata;
+}
+export type AgentPromptContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+} | AgentAttachment;
+export type AgentPromptInput = string | AgentPromptContentBlock[];
+export interface AgentRunOptions {
+    outputSchema?: unknown;
+    resumeFrom?: AgentPersistenceHandle;
+    maxThinkingTokens?: number;
+    messageId?: string;
+}
+export interface AgentUsage {
+    inputTokens?: number;
+    cachedInputTokens?: number;
+    outputTokens?: number;
+    totalCostUsd?: number;
+    contextWindowMaxTokens?: number;
+    contextWindowUsedTokens?: number;
+}
+export declare const TOOL_CALL_ICON_NAMES: readonly ["wrench", "square_terminal", "eye", "pencil", "search", "bot", "sparkles", "brain", "mic_vocal"];
+export type ToolCallIconName = (typeof TOOL_CALL_ICON_NAMES)[number];
+export type ToolCallDetail = {
+    type: "shell";
+    command: string;
+    cwd?: string;
+    output?: string;
+    exitCode?: number | null;
+} | {
+    type: "read";
+    filePath: string;
+    content?: string;
+    offset?: number;
+    limit?: number;
+} | {
+    type: "edit";
+    filePath: string;
+    oldString?: string;
+    newString?: string;
+    unifiedDiff?: string;
+} | {
+    type: "write";
+    filePath: string;
+    content?: string;
+} | {
+    type: "search";
+    query: string;
+    toolName?: "search" | "grep" | "glob" | "web_search";
+    content?: string;
+    filePaths?: string[];
+    webResults?: Array<{
+        title: string;
+        url: string;
+    }>;
+    annotations?: string[];
+    numFiles?: number;
+    numMatches?: number;
+    durationMs?: number;
+    durationSeconds?: number;
+    truncated?: boolean;
+    mode?: "content" | "files_with_matches" | "count";
+} | {
+    type: "fetch";
+    url: string;
+    prompt?: string;
+    result?: string;
+    code?: number;
+    codeText?: string;
+    bytes?: number;
+    durationMs?: number;
+} | {
+    type: "worktree_setup";
+    worktreePath: string;
+    branchName: string;
+    log: string;
+    commands: Array<{
+        index: number;
+        command: string;
+        cwd: string;
+        log: string;
+        status: "running" | "completed" | "failed";
+        exitCode: number | null;
+        durationMs?: number;
+    }>;
+    truncated?: boolean;
+} | {
+    type: "sub_agent";
+    subAgentType?: string;
+    description?: string;
+    childSessionId?: string;
+    log: string;
+    actions?: Array<{
+        index: number;
+        toolName: string;
+        summary?: string;
+    }>;
+} | {
+    type: "plain_text";
+    label?: string;
+    text?: string;
+    icon?: ToolCallIconName;
+} | {
+    type: "plan";
+    text: string;
+} | {
+    type: "unknown";
+    input: unknown;
+    output: unknown;
+};
+interface ToolCallBase {
+    [key: string]: unknown;
+    type: "tool_call";
+    callId: string;
+    name: string;
+    detail: ToolCallDetail;
+    metadata?: Record<string, unknown>;
+}
+type ToolCallRunningTimelineItem = ToolCallBase & {
+    status: "running";
+    error: null;
+};
+type ToolCallCompletedTimelineItem = ToolCallBase & {
+    status: "completed";
+    error: null;
+};
+type ToolCallFailedTimelineItem = ToolCallBase & {
+    status: "failed";
+    error: unknown;
+};
+type ToolCallCanceledTimelineItem = ToolCallBase & {
+    status: "canceled";
+    error: null;
+};
+export type ToolCallTimelineItem = ToolCallRunningTimelineItem | ToolCallCompletedTimelineItem | ToolCallFailedTimelineItem | ToolCallCanceledTimelineItem;
+export interface CompactionTimelineItem {
+    [key: string]: unknown;
+    type: "compaction";
+    status: "loading" | "completed";
+    trigger?: "auto" | "manual";
+    preTokens?: number;
+}
+export type AgentTimelineItem = {
+    type: "user_message";
+    text: string;
+    messageId?: string;
+} | {
+    type: "assistant_message";
+    text: string;
+    messageId?: string;
+} | {
+    type: "reasoning";
+    text: string;
+} | ToolCallTimelineItem | {
+    type: "todo";
+    items: {
+        text: string;
+        completed: boolean;
+    }[];
+} | {
+    type: "error";
+    message: string;
+} | CompactionTimelineItem;
+export type AgentStreamEvent = {
+    type: "thread_started";
+    sessionId: string;
+    provider: AgentProvider;
+} | {
+    type: "turn_started";
+    provider: AgentProvider;
+    turnId?: string;
+} | {
+    type: "turn_completed";
+    provider: AgentProvider;
+    usage?: AgentUsage;
+    turnId?: string;
+} | {
+    type: "usage_updated";
+    provider: AgentProvider;
+    usage: AgentUsage;
+    turnId?: string;
+} | {
+    type: "mode_changed";
+    provider: AgentProvider;
+    currentModeId: string | null;
+    availableModes: AgentMode[];
+} | {
+    type: "model_changed";
+    provider: AgentProvider;
+    runtimeInfo: AgentRuntimeInfo;
+} | {
+    type: "thinking_option_changed";
+    provider: AgentProvider;
+    thinkingOptionId: string | null;
+} | {
+    type: "turn_failed";
+    provider: AgentProvider;
+    error: string;
+    code?: string;
+    diagnostic?: string;
+    turnId?: string;
+} | {
+    type: "turn_canceled";
+    provider: AgentProvider;
+    reason: string;
+    turnId?: string;
+} | {
+    type: "timeline";
+    item: AgentTimelineItem;
+    provider: AgentProvider;
+    turnId?: string;
+    timestamp?: string;
+} | {
+    type: "permission_requested";
+    provider: AgentProvider;
+    request: AgentPermissionRequest;
+    turnId?: string;
+} | {
+    type: "permission_resolved";
+    provider: AgentProvider;
+    requestId: string;
+    resolution: AgentPermissionResponse;
+    turnId?: string;
+} | {
+    type: "attention_required";
+    provider: AgentProvider;
+    reason: "finished" | "error" | "permission";
+    timestamp: string;
+};
+export declare function getAgentStreamEventTurnId(event: AgentStreamEvent): string | undefined;
+export type AgentPermissionRequestKind = "tool" | "plan" | "question" | "mode" | "other";
+export type AgentPermissionUpdate = AgentMetadata;
+export interface AgentPermissionAction {
+    id: string;
+    label: string;
+    behavior: "allow" | "deny";
+    variant?: "primary" | "secondary" | "danger";
+    intent?: "implement" | "implement_resume" | "dismiss";
+}
+export interface AgentPermissionRequest {
+    id: string;
+    provider: AgentProvider;
+    name: string;
+    kind: AgentPermissionRequestKind;
+    title?: string;
+    description?: string;
+    input?: AgentMetadata;
+    detail?: ToolCallDetail;
+    suggestions?: AgentPermissionUpdate[];
+    actions?: AgentPermissionAction[];
+    metadata?: AgentMetadata;
+}
+export type AgentPermissionResponse = {
+    behavior: "allow";
+    selectedActionId?: string;
+    updatedInput?: AgentMetadata;
+    updatedPermissions?: AgentPermissionUpdate[];
+} | {
+    behavior: "deny";
+    selectedActionId?: string;
+    message?: string;
+    interrupt?: boolean;
+};
+export interface AgentRunResult {
+    sessionId: string;
+    finalText: string;
+    usage?: AgentUsage;
+    timeline: AgentTimelineItem[];
+    canceled?: boolean;
+}
+export interface AgentRuntimeInfo {
+    provider: AgentProvider;
+    sessionId: string | null;
+    model?: string | null;
+    thinkingOptionId?: string | null;
+    modeId?: string | null;
+    extra?: AgentMetadata;
+}
+export type AgentSlashCommandKind = "command" | "skill";
+/**
+ * Represents a slash command available in an agent session.
+ * Commands are executed by sending them as prompts with / prefix.
+ */
+export interface AgentSlashCommand {
+    name: string;
+    description: string;
+    argumentHint: string;
+    kind?: AgentSlashCommandKind;
+}
+export interface ListImportableSessionsOptions {
+    limit?: number;
+    /**
+     * Optional cwd hint. Providers that can cheaply pre-filter importable
+     * sessions by working directory should do so before doing expensive work.
+     */
+    cwd?: string;
+}
+export interface ImportableProviderSession {
+    providerHandleId: string;
+    cwd: string;
+    title: string | null;
+    firstPromptPreview: string | null;
+    lastPromptPreview: string | null;
+    lastActivityAt: Date;
+}
+export interface ImportProviderSessionInput {
+    providerHandleId: string;
+    cwd: string;
+}
+export interface ImportProviderSessionContext {
+    config: AgentSessionConfig;
+    storedConfig: AgentSessionConfig;
+    launchContext?: AgentLaunchContext;
+}
+export interface ImportedTimelineEntry {
+    item: AgentTimelineItem;
+    timestamp?: string;
+}
+export interface ImportedProviderSession {
+    session: AgentSession;
+    config: AgentSessionConfig;
+    persistence: AgentPersistenceHandle;
+    timeline: ImportedTimelineEntry[];
+}
+export interface AgentSessionConfig {
+    provider: AgentProvider;
+    cwd: string;
+    /**
+     * Provider-agnostic system/developer instruction string.
+     * Mapped by each provider to its native instruction field.
+     */
+    systemPrompt?: string;
+    /**
+     * Daemon-level instructions appended at runtime. This is deliberately not
+     * persisted into agent config so daemon setting changes apply cleanly.
+     */
+    daemonAppendSystemPrompt?: string;
+    /**
+     * BCP-47 tag for the language the agent must WRITE and SPEAK back in
+     * ("en-US", "pt-BR"). Session-scoped and persisted, unlike
+     * `daemonAppendSystemPrompt`: it describes the work ("this agent works in
+     * English"), so it follows the agent across devices, clients and resume, and
+     * it applies to typed input just as much as to dictated or spoken input.
+     *
+     * Deliberately separate from the per-mode STT language
+     * (`features.{dictation,voiceMode}.stt.language`), which describes a
+     * microphone. Speaking Portuguese while the agent keeps working in English is
+     * a first-class combination.
+     *
+     * Kept structured rather than folded into `systemPrompt` as prose: voice mode
+     * rewrites `systemPrompt` by regex on every toggle
+     * (`stripVoiceModeSystemPrompt`). Providers compose the instruction at
+     * prompt-build time via `buildOutputLanguagePrompt`.
+     *
+     * Undefined means "no instruction", i.e. the model mirrors the user's own
+     * language, which is the pre-existing behaviour.
+     */
+    outputLanguage?: string;
+    /**
+     * The agent's standing objective, one line: why this agent exists.
+     *
+     * Durable and persisted, deliberately NOT the same thing as
+     * `SessionDigest.goal`. That one is per-session metadata the agent
+     * self-reports through `set_session_digest` and `mergeDigest` overwrites on
+     * every patch that carries the key, so it describes one careful run rather
+     * than the agent. An agent's objective has to be as durable as its system
+     * prompt, which means it lives here on the config and survives restart,
+     * resume and every session boundary.
+     */
+    goal?: string;
+    /**
+     * The job this agent is hired for, in JTBD framing.
+     *
+     * Kept separate from `goal` rather than folded into it because they answer
+     * different questions: `goal` is the outcome the agent is aiming at, and this
+     * is the hiring rationale, the job someone would otherwise have to do by hand.
+     * Collapsing the pair would lose whichever half the author did not write.
+     */
+    jobToBeDone?: string;
+    modeId?: string;
+    model?: string;
+    thinkingOptionId?: string;
+    featureValues?: Record<string, unknown>;
+    title?: string | null;
+    approvalPolicy?: string;
+    sandboxMode?: string;
+    networkAccess?: boolean;
+    webSearch?: boolean;
+    extra?: {
+        codex?: AgentMetadata;
+        claude?: Partial<ClaudeAgentOptions>;
+    };
+    mcpServers?: Record<string, McpServerConfig>;
+    /**
+     * Per-run tool allowlist in Claude Code permission-rule syntax, e.g.
+     * ["Read", "Bash(git:*)", "mcp__playwright__browser_navigate"].
+     *
+     * When present, a tool absent from the list is blocked BEFORE it executes and
+     * the model is told why. Undefined or empty means no allowlist. Enforced only
+     * by clients that set `AgentClient.supportsToolAllowlist`; a create call that
+     * asks any other provider for an allowlist is rejected rather than run
+     * unenforced.
+     */
+    allowedTools?: string[];
+    /**
+     * Internal agents are hidden from listings and don't trigger notifications.
+     * They are used for ephemeral system tasks like commit/PR generation.
+     */
+    internal?: boolean;
+}
+export interface AgentLaunchContext {
+    agentId?: string;
+    env?: Record<string, string>;
+    /**
+     * Runtime-only internal Paseo tools. This must never be persisted into
+     * AgentSessionConfig; providers may adapt it to their native tool surface.
+     */
+    paseoTools?: PaseoToolCatalog;
+}
+export interface AgentCreateSessionOptions {
+    /**
+     * Whether the provider should leave a durable native session behind.
+     * Defaults to true. Providers that cannot honor false should no-op.
+     */
+    persistSession?: boolean;
+    /**
+     * Story 3.6 — Fork a past session by seeding the new agent with `--resume <sid>`.
+     * The source JSONL must remain byte-identical (AC4); the new agent writes to
+     * a fresh JSONL with a new SID. Providers that don't support resume should
+     * ignore this field.
+     */
+    resumeSessionId?: string;
+}
+/**
+ * Returned by respondToPermission when the permission resolution requires
+ * a follow-up turn (e.g. Codex plan approval → implementation).
+ */
+export interface AgentPermissionResult {
+    followUpPrompt?: AgentPromptInput;
+}
+export type AgentBackgroundTaskStatus = "running" | "completed" | "failed" | "canceled";
+/**
+ * One background shell owned by an agent — a command the provider launched to
+ * outlive the turn (Claude Code's `Bash` with `run_in_background`). Kept
+ * provider-neutral so the daemon can project it without importing a provider.
+ */
+export interface AgentBackgroundTask {
+    id: string;
+    command: string | null;
+    description: string | null;
+    outputFile: string | null;
+    startedAt: string;
+    endedAt: string | null;
+    status: AgentBackgroundTaskStatus;
+    summary: string | null;
+}
+export interface AgentBackgroundTaskOutput {
+    taskId: string;
+    /** Tail of the captured output, already redacted. */
+    text: string;
+    /** True when the head of the file was dropped to honour the byte cap. */
+    truncated: boolean;
+    /** Full size of the capture on disk, so the client can say how much it cut. */
+    byteSize: number;
+}
+export interface AgentSession {
+    readonly provider: AgentProvider;
+    readonly id: string | null;
+    readonly capabilities: AgentCapabilityFlags;
+    readonly features?: AgentFeature[];
+    run(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<AgentRunResult>;
+    startTurn(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<{
+        turnId: string;
+    }>;
+    subscribe(callback: (event: AgentStreamEvent) => void): () => void;
+    streamHistory(): AsyncGenerator<AgentStreamEvent>;
+    getRuntimeInfo(): Promise<AgentRuntimeInfo>;
+    getAvailableModes(): Promise<AgentMode[]>;
+    getCurrentMode(): Promise<string | null>;
+    setMode(modeId: string): Promise<void | AgentProviderNotice>;
+    getPendingPermissions(): AgentPermissionRequest[];
+    respondToPermission(requestId: string, response: AgentPermissionResponse): Promise<AgentPermissionResult | void>;
+    describePersistence(): AgentPersistenceHandle | null;
+    interrupt(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Count of the agent's still-alive background shells (Claude Code `Bash`
+     * launched with `run_in_background`) that outlive the turn. Optional —
+     * providers that don't model background shells omit it (treated as 0).
+     */
+    getActiveBackgroundTaskCount?(): number;
+    /**
+     * The agent's background shells as records rather than a bare count — live
+     * ones first, then a bounded tail of recently finished ones so their output
+     * stays reachable. Optional per provider; omit when unmodelled.
+     */
+    listBackgroundTasks?(): AgentBackgroundTask[];
+    /**
+     * Read a background shell's captured output. Providers that stream a
+     * backgrounded command into a file return its (redacted, tailed) contents;
+     * returns null for an unknown id or a shell that captured nothing.
+     */
+    readBackgroundTaskOutput?(taskId: string, options?: {
+        maxBytes?: number;
+    }): Promise<AgentBackgroundTaskOutput | null>;
+    /**
+     * Dismiss a live background shell — the dismiss affordance. Providers that
+     * drive an interactive CLI (Claude Code over PTY) kill the shell INSIDE the
+     * CLI via its own keybinding; others fall back to untracking the id. Returns
+     * true if the dismiss was delivered. Optional per provider.
+     */
+    dismissBackgroundTask?(taskId: string): Promise<boolean>;
+    listCommands?(): Promise<AgentSlashCommand[]>;
+    setModel?(modelId: string | null): Promise<void>;
+    setThinkingOption?(thinkingOptionId: string | null): Promise<void | AgentProviderNotice>;
+    setFeature?(featureId: string, value: unknown): Promise<void>;
+    revertConversation?(input: {
+        messageId: string;
+    }): Promise<void>;
+    revertFiles?(input: {
+        messageId: string;
+    }): Promise<void>;
+    revertBoth?(input: {
+        messageId: string;
+    }): Promise<void>;
+    /**
+     * Map a turn id the app holds onto one that exists in this session's transcript.
+     *
+     * Declared here rather than duck-typed at the call site so `wrapSessionProvider` is
+     * forced to forward it. It was duck-typed first, and every `pool-*` provider silently
+     * lost it -- the wrapper rebuilds the session as a fresh object literal, so an
+     * undeclared method is indistinguishable from a provider that does not implement one.
+     *
+     * Implemented by the claude provider, where the PTY transport makes the app's id and
+     * the transcript uuid two different values. Returning the input unchanged is the
+     * correct answer everywhere else.
+     */
+    resolveTranscriptTurnId?(turnId: string): string;
+    /**
+     * The agent's terminal screen as it is CURRENTLY RENDERED, read out of band, or null when
+     * this session has no readable pane.
+     *
+     * Only the claude provider running the PTY transport under tmux (`PASEO_PTY_TMUX=1`) can
+     * answer this: it asks tmux for the settled pane instead of reconstructing a screen from
+     * the byte stream the transport is simultaneously consuming. Every other session -- SDK
+     * transport, bare pty, every ACP vendor -- has no pane and correctly returns null, which
+     * is what the client keys its affordance off. Never throws: an unavailable screen is a
+     * missing feature, not a failed request.
+     */
+    capturePane?(options?: {
+        ansi?: boolean;
+        scrollbackLines?: number;
+    }): Promise<string | null>;
+    /**
+     * Out-of-band prompt handler. When non-null, the manager runs the returned
+     * handler instead of allocating a turn. The handler emits stream events
+     * directly via the provided `emit` callback, which routes through the
+     * manager's persistence + broadcast pipeline. The active foreground turn
+     * (if any) is left untouched, so this is how mid-turn side-effect commands
+     * (e.g. /goal pause) reach the provider without canceling the running turn.
+     */
+    tryHandleOutOfBand?(prompt: AgentPromptInput): {
+        run(ctx: {
+            emit: (event: AgentStreamEvent) => void;
+        }): Promise<void>;
+    } | null;
+}
+export type FetchCatalogOptions = {
+    scope: "global";
+    force: boolean;
+    timeoutMs?: number;
+} | {
+    scope: "workspace";
+    cwd: string;
+    force: boolean;
+    timeoutMs?: number;
+};
+export interface ProviderCatalog {
+    models: AgentModelDefinition[];
+    modes: AgentMode[];
+}
+export interface AgentClient {
+    readonly provider: AgentProvider;
+    readonly capabilities: AgentCapabilityFlags;
+    /**
+     * True when this client can ENFORCE `AgentSessionConfig.allowedTools` at
+     * runtime (block a tool outside the list before it executes), not merely
+     * accept the field.
+     *
+     * Absent/false means the create call is rejected when an allowlist is set. A
+     * tool allowlist that is quietly dropped is worse than no allowlist: the
+     * caller believes a restriction is in force that is not, so this fails loudly
+     * instead. Derived providers (`pool` extends `claude`, and so on) reuse the
+     * base client class and therefore inherit the correct answer.
+     */
+    readonly supportsToolAllowlist?: boolean;
+    createSession(config: AgentSessionConfig, launchContext?: AgentLaunchContext, options?: AgentCreateSessionOptions): Promise<AgentSession>;
+    resumeSession(handle: AgentPersistenceHandle, overrides?: Partial<AgentSessionConfig>, launchContext?: AgentLaunchContext): Promise<AgentSession>;
+    /**
+     * Discover models and modes together. Implementations may use one upstream
+     * process, separate upstream calls, static modes, or private helpers; callers
+     * outside the provider do not get separate runtime model/mode probes.
+     * The registry is responsible for merging configured model overrides.
+     */
+    fetchCatalog(options: FetchCatalogOptions): Promise<ProviderCatalog>;
+    resolveCreateConfig?(input: ResolveAgentCreateConfigInput): ResolveAgentCreateConfigResult;
+    isCreateConfigUnattended?(input: AgentCreateConfigUnattendedInput): boolean;
+    listCommands?(config: AgentSessionConfig): Promise<AgentSlashCommand[]>;
+    listFeatures?(config: AgentSessionConfig): Promise<AgentFeature[]>;
+    listImportableSessions?(options?: ListImportableSessionsOptions): Promise<ImportableProviderSession[]>;
+    importSession?(input: ImportProviderSessionInput, context: ImportProviderSessionContext): Promise<ImportedProviderSession>;
+    /**
+     * Check if this provider is available (CLI binary is installed).
+     * Returns true if available, false otherwise.
+     */
+    isAvailable(): Promise<boolean>;
+    getDiagnostic?(): Promise<{
+        diagnostic: string;
+    }>;
+    /**
+     * Archive a persisted session in the native provider (best-effort).
+     * Called when Paseo archives an agent so the provider's own UI reflects the same state.
+     */
+    archiveNativeSession?(handle: AgentPersistenceHandle): Promise<void>;
+    /**
+     * Unarchive a persisted session in the native provider.
+     * Called before Paseo clears its archived flag so provider resume can succeed.
+     */
+    unarchiveNativeSession?(handle: AgentPersistenceHandle): Promise<void>;
+    /**
+     * Release any provider-owned resources held by this client (background
+     * processes, sockets, cached subprocesses, etc.). Called when the daemon
+     * shuts down. Must be idempotent.
+     */
+    shutdown?(): Promise<void>;
+}
+//# sourceMappingURL=agent-sdk-types.d.ts.map