@camerontaylor/paseo-server 0.8.0-fork.1

package/dist/server/server/agent/providers/acp-agent.d.ts

@@ -0,0 +1,703 @@
+import { type ChildProcessWithoutNullStreams } from "node:child_process";
+import type { ProcessTerminator } from "../../../utils/tree-kill.js";
+import type { ReadableStream as NodeReadableStream, WritableStream as NodeWritableStream } from "node:stream/web";
+import { ClientSideConnection, type Client as ACPClient, type ClientCapabilities as ACPClientCapabilities, type CreateTerminalRequest, type InitializeResponse, type KillTerminalRequest, type LoadSessionResponse, type NewSessionResponse, type ReadTextFileRequest, type RequestPermissionRequest, type RequestPermissionResponse, type ResumeSessionResponse, type SessionConfigOption, type SessionMode, type SessionModelState, type SessionNotification, type TerminalOutputRequest, type TerminalOutputResponse, type ToolCallContent, type ToolCallLocation, type ToolCallStatus, type ToolKind, type Usage, type WaitForTerminalExitRequest, type WriteTextFileRequest, type Stream as ACPStream } from "@agentclientprotocol/sdk";
+import type { Logger } from "pino";
+import { type AgentCapabilityFlags, type AgentClient, type AgentCreateConfigUnattendedInput, type AgentFeature, type AgentLaunchContext, type AgentMetadata, type AgentMode, type AgentModelDefinition, type AgentPermissionRequest, type AgentPermissionResponse, type AgentPersistenceHandle, type AgentPromptInput, type AgentRunOptions, type AgentRunResult, type AgentRuntimeInfo, type AgentSession, type AgentSessionConfig, type AgentSlashCommand, type AgentStreamEvent, type AgentUsage, type FetchCatalogOptions, type ProviderRefreshContext, type ImportableProviderSession, type ImportProviderSessionContext, type ImportProviderSessionInput, type ListImportableSessionsOptions, type ProviderCatalog, type ResolveAgentCreateConfigInput, type ResolveAgentCreateConfigResult } from "../agent-sdk-types.js";
+import { type ProviderRuntimeSettings } from "../provider-launch-config.js";
+import { type DiagnosticEntry } from "./diagnostic-utils.js";
+export declare function summarizeACPRequestError(error: unknown): {
+    message: string;
+    code?: string;
+    diagnostic?: string;
+};
+export declare const DEFAULT_ACP_CAPABILITIES: AgentCapabilityFlags;
+export type ACPClientCapabilityMeta = Record<string, unknown>;
+export declare function buildACPClientCapabilities(meta?: ACPClientCapabilityMeta, override?: ACPClientCapabilities): ACPClientCapabilities;
+export declare function createLoggedNdJsonStream(output: NodeWritableStream, input: NodeReadableStream, options: {
+    logger: Logger;
+    provider: string;
+}): ACPStream;
+export type ACPExtensionCommandsParser = (method: string, params: Record<string, unknown>) => AgentSlashCommand[] | null;
+/**
+ * Context handed to an {@link ACPCatalogModelResolver} during `fetchCatalog`. It exposes
+ * the already-derived models plus the live probe session so a resolver can refine them
+ * (e.g. switch through each model to read back per-model options) without re-implementing
+ * the catalog plumbing.
+ */
+export interface ACPCatalogModelResolverContext {
+    connection: ClientSideConnection;
+    sessionId: string;
+    models: AgentModelDefinition[];
+    configOptions: SessionConfigOption[] | null | undefined;
+    runRequest: <T>(request: () => Promise<T>) => Promise<T>;
+    transformConfigOptions: (configOptions: SessionConfigOption[]) => SessionConfigOption[];
+    logger: Logger;
+    provider: string;
+}
+/**
+ * Optional hook that refines the catalog's model list using the live probe session.
+ * The base client ships no resolver — catalog discovery derives models from the initial
+ * session response and never mutates the probe. Providers that need per-model data (Kimi)
+ * inject a resolver so the extra round trips stay off every other ACP.
+ */
+export type ACPCatalogModelResolver = (context: ACPCatalogModelResolverContext) => Promise<AgentModelDefinition[]>;
+interface ACPAgentClientOptions {
+    provider: string;
+    logger: Logger;
+    runtimeSettings?: ProviderRuntimeSettings;
+    defaultCommand: [string, ...string[]];
+    defaultModes?: AgentMode[];
+    catalogModelResolver?: ACPCatalogModelResolver;
+    modelTransformer?: (models: AgentModelDefinition[]) => AgentModelDefinition[];
+    sessionResponseTransformer?: (response: SessionStateResponse) => SessionStateResponse;
+    configOptionsTransformer?: (configOptions: SessionConfigOption[]) => SessionConfigOption[];
+    configFeatureOptions?: ACPConfigFeatureOption[];
+    clientCapabilities?: ACPClientCapabilities;
+    clientCapabilityMeta?: ACPClientCapabilityMeta;
+    modeIdTransformer?: (modeId: string) => string | null;
+    toolSnapshotTransformer?: (snapshot: ACPToolSnapshot) => ACPToolSnapshot;
+    providerModeWriter?: (context: ACPProviderModeWriterContext) => Promise<ACPProviderModeWriteResult>;
+    beforeModeWriter?: (context: ACPProviderModeWriterContext) => Promise<ACPBeforeModeWriteResult>;
+    thinkingOptionWriter?: (connection: ClientSideConnection, sessionId: string, thinkingOptionId: string) => Promise<void>;
+    capabilities?: AgentCapabilityFlags;
+    extensionCommandsParser?: ACPExtensionCommandsParser;
+    waitForInitialCommands?: boolean;
+    initialCommandsWaitTimeoutMs?: number;
+    terminateProcess?: ProcessTerminator;
+    now?: () => number;
+}
+export interface ACPAgentSessionOptions {
+    provider: string;
+    logger: Logger;
+    runtimeSettings?: ProviderRuntimeSettings;
+    defaultCommand: [string, ...string[]];
+    defaultModes: AgentMode[];
+    modelTransformer?: (models: AgentModelDefinition[]) => AgentModelDefinition[];
+    sessionResponseTransformer?: (response: SessionStateResponse) => SessionStateResponse;
+    configOptionsTransformer?: (configOptions: SessionConfigOption[]) => SessionConfigOption[];
+    configFeatureOptions?: ACPConfigFeatureOption[];
+    clientCapabilities?: ACPClientCapabilities;
+    clientCapabilityMeta?: ACPClientCapabilityMeta;
+    modeIdTransformer?: (modeId: string) => string | null;
+    toolSnapshotTransformer?: (snapshot: ACPToolSnapshot) => ACPToolSnapshot;
+    providerModeWriter?: (context: ACPProviderModeWriterContext) => Promise<ACPProviderModeWriteResult>;
+    beforeModeWriter?: (context: ACPProviderModeWriterContext) => Promise<ACPBeforeModeWriteResult>;
+    thinkingOptionWriter?: (connection: ClientSideConnection, sessionId: string, thinkingOptionId: string) => Promise<void>;
+    capabilities: AgentCapabilityFlags;
+    extensionCommandsParser?: ACPExtensionCommandsParser;
+    handle?: AgentPersistenceHandle;
+    agentId?: string;
+    launchEnv?: Record<string, string>;
+    waitForInitialCommands?: boolean;
+    initialCommandsWaitTimeoutMs?: number;
+    terminateProcess?: ProcessTerminator;
+}
+export interface SpawnedACPProcess {
+    child: ChildProcessWithoutNullStreams;
+    connection: ClientSideConnection;
+    initialize: InitializeResponse;
+    stderrChunks?: string[];
+}
+type UninitializedACPProcess = Omit<SpawnedACPProcess, "initialize"> & {
+    initialize?: InitializeResponse;
+};
+interface ACPProcessTransport {
+    child: ChildProcessWithoutNullStreams;
+    connection: ClientSideConnection;
+    stderrChunks: string[];
+    spawnReady: Promise<void>;
+    spawnError: Promise<never>;
+}
+export interface ACPToolSnapshot {
+    toolCallId: string;
+    title: string;
+    kind?: ToolKind | null;
+    status?: ToolCallStatus | null;
+    content?: ToolCallContent[] | null;
+    locations?: ToolCallLocation[] | null;
+    rawInput?: unknown;
+    rawOutput?: unknown;
+}
+export type SessionStateResponse = NewSessionResponse | LoadSessionResponse | ResumeSessionResponse;
+interface TerminalExit {
+    exitCode?: number | null;
+    signal?: string | null;
+}
+export interface ConfigOptionSelector {
+    id: string;
+    label: string;
+    description?: string;
+    isDefault?: boolean;
+    metadata?: AgentMetadata;
+}
+export interface ACPConfigFeatureOption {
+    id: string;
+    configId: string;
+    category?: string;
+    label: string;
+    description?: string;
+    tooltip?: string;
+    icon?: string;
+    emptyOptionLabel?: string;
+}
+export type SelectConfigOption = Extract<SessionConfigOption, {
+    type: "select";
+}>;
+interface SelectConfigChoice {
+    value: string;
+    name: string;
+    description?: string | null;
+    group?: string;
+}
+type AvailableACPModel = NonNullable<SessionModelState["availableModels"]>[number];
+interface ACPModeSelection {
+    availableMode: AgentMode | null;
+    configOption: SelectConfigOption | null;
+    configChoice: SelectConfigChoice | null;
+    hasAvailableModes: boolean;
+}
+interface ACPModelSelection {
+    availableModel: AvailableACPModel | null;
+    configOption: SelectConfigOption | null;
+    configChoice: SelectConfigChoice | null;
+    hasAvailableModels: boolean;
+}
+export interface ACPProviderModeWriterContext {
+    connection: ClientSideConnection;
+    sessionId: string;
+    requestedModeId: string;
+    currentModeId: string | null;
+    selection: ACPModeSelection;
+    configOptions: SessionConfigOption[];
+    logger: Logger;
+}
+export interface ACPProviderModeWriteResult {
+    handled: boolean;
+    currentModeId?: string;
+    configOptions?: SessionConfigOption[];
+}
+export interface ACPBeforeModeWriteResult {
+    configOptions?: SessionConfigOption[];
+}
+export declare function mapACPUsage(usage: Usage | null | undefined): AgentUsage | undefined;
+export declare function resolveACPModeSelection({ modeId, availableModes, configOptions, }: {
+    modeId: string;
+    availableModes: AgentMode[];
+    configOptions: SessionConfigOption[] | null | undefined;
+}): ACPModeSelection;
+export declare function resolveACPModelSelection({ modelId, availableModels, configOptions, }: {
+    modelId: string;
+    availableModels: AvailableACPModel[] | null | undefined;
+    configOptions: SessionConfigOption[] | null | undefined;
+}): ACPModelSelection;
+export declare function deriveModesFromACP(fallbackModes: AgentMode[], modeState?: {
+    availableModes?: SessionMode[] | null;
+    currentModeId?: string | null;
+} | null, configOptions?: SessionConfigOption[] | null): {
+    modes: AgentMode[];
+    currentModeId: string | null;
+};
+export declare function deriveModelDefinitionsFromACP(provider: string, models: SessionModelState | null | undefined, configOptions?: SessionConfigOption[] | null): AgentModelDefinition[];
+export declare function deriveFeaturesFromACP(configOptions: SessionConfigOption[] | null | undefined, featureOptions: ACPConfigFeatureOption[]): AgentFeature[];
+declare function resolveACPCreateConfig(input: ResolveAgentCreateConfigInput): ResolveAgentCreateConfigResult;
+declare function isACPCreateConfigUnattended(input: AgentCreateConfigUnattendedInput): boolean;
+export declare class ACPAgentClient implements AgentClient {
+    readonly provider: string;
+    readonly capabilities: AgentCapabilityFlags;
+    readonly resolveCreateConfig: typeof resolveACPCreateConfig;
+    readonly isCreateConfigUnattended: typeof isACPCreateConfigUnattended;
+    protected readonly logger: Logger;
+    protected readonly runtimeSettings?: ProviderRuntimeSettings;
+    protected readonly defaultCommand: [string, ...string[]];
+    protected readonly defaultModes: AgentMode[];
+    private readonly catalogModelResolver?;
+    private readonly modelTransformer?;
+    private readonly sessionResponseTransformer?;
+    private readonly configOptionsTransformer?;
+    private readonly configFeatureOptions;
+    private readonly clientCapabilities?;
+    private readonly clientCapabilityMeta?;
+    private readonly modeIdTransformer?;
+    private readonly toolSnapshotTransformer?;
+    private readonly providerModeWriter?;
+    private readonly beforeModeWriter?;
+    private readonly thinkingOptionWriter?;
+    private readonly waitForInitialCommands;
+    private readonly initialCommandsWaitTimeoutMs;
+    private readonly extensionCommandsParser?;
+    private readonly importPromptCache;
+    private readonly now;
+    protected readonly terminateProcess: ProcessTerminator;
+    constructor(options: ACPAgentClientOptions);
+    createSession(config: AgentSessionConfig, launchContext?: AgentLaunchContext): Promise<AgentSession>;
+    /**
+     * Builds the session instance behind `createSession`/`resumeSession`. A fork
+     * provider overrides this to substitute its own session subclass while
+     * keeping the shared launch, transform, and capability plumbing.
+     */
+    protected createAgentSession(config: AgentSessionConfig, options: ACPAgentSessionOptions): ACPAgentSession;
+    resumeSession(handle: AgentPersistenceHandle, overrides?: Partial<AgentSessionConfig>, launchContext?: AgentLaunchContext): Promise<AgentSession>;
+    fetchCatalog(options: FetchCatalogOptions, context?: ProviderRefreshContext): Promise<ProviderCatalog>;
+    listFeatures(config: AgentSessionConfig): Promise<AgentFeature[]>;
+    listImportableSessions(options?: ListImportableSessionsOptions): Promise<ImportableProviderSession[]>;
+    private describeImportableSession;
+    private loadImportPromptPreviews;
+    private closeLoadedSession;
+    importSession(input: ImportProviderSessionInput, context: ImportProviderSessionContext): Promise<import("../agent-sdk-types.js").ImportedProviderSession>;
+    isAvailable(): Promise<boolean>;
+    protected spawnProcess(launchEnv?: Record<string, string>, options?: {
+        initializeTimeoutMs?: number;
+        onSpawned?: (probe: UninitializedACPProcess) => void;
+        client?: ACPClient;
+    }): Promise<SpawnedACPProcess>;
+    protected spawnTransport(launchEnv?: Record<string, string>, client?: ACPClient): Promise<ACPProcessTransport>;
+    protected initializeTransport(transport: ACPProcessTransport, initializeTimeoutMs?: number): Promise<InitializeResponse>;
+    protected buildProbeClient(onSessionUpdate?: (params: SessionNotification) => void | Promise<void>): ACPClient;
+    protected closeProbe(probe: UninitializedACPProcess, sessionId?: string | null): Promise<void>;
+    protected runACPRequest<T>(request: () => Promise<T>): Promise<T>;
+    protected buildACPProbeDiagnosticRows(options?: {
+        cwd?: string;
+        phaseTimeoutMs?: number;
+    }): Promise<DiagnosticEntry[]>;
+    protected resolveLaunchCommand(): Promise<{
+        command: string;
+        args: string[];
+    }>;
+    private assertProvider;
+    protected transformSessionResponse(response: SessionStateResponse): SessionStateResponse;
+}
+/**
+ * Fail-closed ceiling on how long a staged replacement may wait for the stop
+ * boundary in front of it. Follows the OpenCode pending-abort deadline: it
+ * bounds the caller's wait, it never manufactures provider readiness. Expiry
+ * rejects only the queued replacement and leaves the session stopping.
+ */
+export declare const ACP_STOPPED_TURN_ADMISSION_TIMEOUT_MS = 10000;
+/**
+ * Foreground admission phases for one ACP session.
+ *
+ * - `idle` — no foreground turn and no unresolved stop.
+ * - `reserved` — a successor atomically acquired the foreground slot but has not
+ *   called `connection.prompt` yet.
+ * - `running` — a foreground prompt is active.
+ * - `stopping` — an immutable stop boundary is installed for a foreground or
+ *   provider-owned turn; admission is closed until that stop's proof completes.
+ *
+ * Transitions: idle→running (ordinary start), idle→stopping (stop installed),
+ * stopping→reserved (gates satisfied, successor committed), reserved→running
+ * (before the prompt write), reserved→idle and reserved→stopping (reservation
+ * rolled back when the send fails). `running` leaves only through `finishTurn`
+ * (→idle) or a stop install (→stopping); a stop never reverts to running for the
+ * turn it stopped. `activeForegroundTurnId` carries the turn that owns the
+ * foreground slot in every non-idle phase, so a stopping session still tags its
+ * events with the turn being stopped.
+ */
+export type ACPAdmissionState = "idle" | "reserved" | "running" | "stopping";
+/**
+ * Which kind of turn a stop boundary stops. `foreground` is a Paseo-issued ACP
+ * prompt; `provider-owned` is a turn a provider started on its own and mirrors
+ * into Paseo. The boundary mechanics are identical for both.
+ */
+export type ACPStopKind = "foreground" | "provider-owned";
+/**
+ * Correlation a permission denial carries into the stop router: the request id
+ * it resolves and the turn the request was raised on, when it carried one. A
+ * suppressed cancellation write logs these so the suppression stays observable
+ * and attributable.
+ */
+export interface ACPStopCorrelation {
+    readonly permissionRequestId: string;
+    readonly turnId?: string;
+}
+interface ACPStopCancelAttempt {
+    readonly revision: number;
+    settled: boolean;
+    outcome: "pending" | "success" | "rejected";
+}
+interface ACPStagedSuccessor {
+    /** Names the queued replacement; independent of stop identity and revision. */
+    readonly token: string;
+    readonly release: Deferred<void>;
+    readonly deadline: ReturnType<typeof setTimeout>;
+}
+/**
+ * One stop boundary over a single turn. Identity fields are immutable for the
+ * life of the stop: a repeated Stop reuses the same record and only moves proof
+ * and revision state, so an old promise can never open a newer stop.
+ *
+ * Three concepts stay separate here: `stopId` (identity), `cancelIssuedRevision`
+ * (retry/attempt number), and `successorToken` (which queued replacement may
+ * commit). Never derive one from another.
+ */
+export interface ACPStopRecord {
+    readonly stopId: string;
+    /** Explicit id of the foreground or provider-owned turn being stopped. */
+    readonly stoppedTurnId: string;
+    /** Session and ordered live connection captured at install time. */
+    readonly sessionId: string;
+    readonly connection: ClientSideConnection;
+    /** Bumped whenever the session adopts a connection; detects a replacement. */
+    readonly connectionRevision: number;
+    readonly kind: ACPStopKind;
+    /** Terminal proof for `stoppedTurnId`; duplicate terminals stay idempotent. */
+    terminalObserved: boolean;
+    /** Guards exactly-once terminal delivery for the stopped turn. */
+    terminalDelivered: boolean;
+    /** Every cancellation write issued for this stop, in issue order. */
+    readonly cancelAttempts: ACPStopCancelAttempt[];
+    cancelIssuedRevision: number;
+    cancelSettledRevision: number;
+    newestCancelSucceeded: boolean;
+    /** Set once by the one death path; a death-settled ledger is final. */
+    deathSettled: boolean;
+    /** At most one queued successor. `releasedSuccessorToken` names the one that may commit. */
+    stagedSuccessor: ACPStagedSuccessor | null;
+    releasedSuccessorToken: string | null;
+    /** Provider-specific proof slot. The generic boundary only reads it. */
+    providerGateSatisfied: boolean;
+}
+interface Deferred<T> {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (error: unknown) => void;
+}
+export declare class ACPAgentSession implements AgentSession, ACPClient {
+    readonly provider: string;
+    readonly capabilities: AgentCapabilityFlags;
+    protected readonly logger: Logger;
+    private readonly runtimeSettings?;
+    private readonly defaultCommand;
+    private readonly defaultModes;
+    protected readonly modelTransformer?: (models: AgentModelDefinition[]) => AgentModelDefinition[];
+    private readonly sessionResponseTransformer?;
+    private readonly configOptionsTransformer?;
+    private readonly configFeatureOptions;
+    private readonly clientCapabilities?;
+    private readonly clientCapabilityMeta?;
+    private readonly modeIdTransformer?;
+    private readonly toolSnapshotTransformer?;
+    private readonly providerModeWriter?;
+    private readonly beforeModeWriter?;
+    private readonly thinkingOptionWriter?;
+    private readonly agentId?;
+    private readonly launchEnv?;
+    private readonly subscribers;
+    private readonly pendingPermissions;
+    private pendingUserMessage;
+    private submittedUserMessageTurnId;
+    private readonly toolCalls;
+    private readonly terminalEntries;
+    private readonly persistedHistory;
+    private readonly initialHandle?;
+    private readonly config;
+    private child;
+    private connection;
+    private agentCapabilities;
+    private sessionId;
+    private currentMode;
+    private availableModes;
+    private currentModel;
+    private availableModels;
+    private thinkingOptionId;
+    private currentTitle;
+    private lastActivityAt;
+    private configOptions;
+    private cachedCommands;
+    private commandsReadyDeferred;
+    private commandsReadySettled;
+    private waitForInitialCommands;
+    private initialCommandsWaitTimeoutMs;
+    private readonly extensionCommandsParser?;
+    private currentTurnUsage;
+    private activeForegroundTurnId;
+    /**
+     * Foreground admission state and the stop boundary in front of it. See
+     * {@link ACPAdmissionState} for the phases and their transitions. Both move
+     * only inside synchronous sections: a reservation is never split across an
+     * `await`, so no event, echo, turn id, or prompt can escape before ownership
+     * is taken.
+     */
+    private admissionState;
+    private stop;
+    private connectionRevision;
+    private connectionDeathSignal;
+    private fallbackAssistantMessageId;
+    private closed;
+    private historyPending;
+    private replayingHistory;
+    private bootstrapThreadEventPending;
+    private readonly terminateProcess;
+    constructor(config: AgentSessionConfig, options: ACPAgentSessionOptions);
+    protected getAcpSessionId(): string | null;
+    protected getAcpConnection(): ClientSideConnection | null;
+    protected getForegroundTurnId(): string | null;
+    protected getAdmissionState(): ACPAdmissionState;
+    protected getCurrentStop(): ACPStopRecord | null;
+    /** One-key read-only view of the launch environment. Never exposes the object. */
+    protected getLaunchEnv(name: string): string | undefined;
+    get id(): string | null;
+    initializeNewSession(): Promise<void>;
+    /**
+     * IMPORTANT: Some ACP providers (e.g., Devin CLI) require all three params
+     * (sessionId, cwd, mcpServers) to be present in session/load or
+     * unstable_resumeSession — even when mcpServers is an empty array — and
+     * return "Invalid params" if any are omitted. Never drop cwd or mcpServers
+     * from these calls regardless of capabilities.
+     */
+    initializeResumedSession(): Promise<void>;
+    private closeAfterInitializationFailure;
+    run(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<AgentRunResult>;
+    startTurn(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<{
+        turnId: string;
+    }>;
+    /**
+     * The single admission path for every foreground prompt, ordinary or staged
+     * behind a stop.
+     *
+     * 1. A call that arrives while a stop is installed becomes that stop's staged
+     *    successor — at most one per stop; a second concurrent call throws the
+     *    foreground-active error instead of displacing the first.
+     * 2. It then waits for the stop's gates (authoritative terminal, settled and
+     *    successful cancellation writes, provider proof) inside
+     *    {@link ACP_STOPPED_TURN_ADMISSION_TIMEOUT_MS}. The deadline rejects only
+     *    this waiter; it never sends a prompt and never opens readiness.
+     * 3. {@link reserveForegroundSlot} rechecks every fact and reserves the
+     *    foreground slot with no `await` in between.
+     * 4. Only after the reservation are the turn id and the start-side effects
+     *    produced, in the order ACP always used them.
+     */
+    protected startTurnWithAdmission(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<{
+        turnId: string;
+    }>;
+    /**
+     * Registers the caller as a stop's sole staged successor. A call with no stop
+     * in front of it commits immediately; a call while the foreground slot is held
+     * throws, exactly as it always has.
+     */
+    private stageAdmission;
+    /**
+     * Deadline expiry rejects the queued replacement and nothing else: no prompt,
+     * no turn event, no user echo, no turn id. The stop stays installed, so a
+     * later request can still be evaluated on its own facts.
+     */
+    private expireStagedSuccessor;
+    /**
+     * Detaches and disarms the stop's staged successor, clearing the deadline and
+     * the token slot together. This is the whole of successor cleanup, so close and
+     * supersession can call it without touching stop state.
+     */
+    private takeStagedSuccessor;
+    /** Invalidates the queued replacement without touching the stop identity. */
+    protected invalidateStagedSuccessor(stop: ACPStopRecord, reason: string): void;
+    /**
+     * The one death path for the stop boundary, invoked by every way the session
+     * observes its process or transport died: the child exit handler, the
+     * connection close signal, and close. The SDK delivers `cancel()` as a
+     * notification whose write errors are swallowed, so on a dead pipe an
+     * undelivered cancel resolves as a settled success — death therefore settles
+     * EVERY attempt, including recorded successes, as rejected, records provider
+     * death proof, and rejects the staged successor immediately instead of
+     * leaving it to the admission deadline. Idempotent: the first observation
+     * wins and later ones (a signal abort after the exit handler, or close) are
+     * no-ops. Gated on the stop's captured identity, so a stop captured on an
+     * older connection stays untouched.
+     */
+    private settleStopOnObservedDeath;
+    /**
+     * Opens the staged successor only when every fact the stop owes is present:
+     * the session identity it captured, terminal proof for the turn it stopped, a
+     * fully settled and successful cancellation ledger, and provider proof. Any
+     * gap keeps the session stopping — nothing infers readiness here.
+     */
+    private evaluateStopGate;
+    /**
+     * The cancellation ledger: every cancellation write issued for the stop must
+     * have settled, and the newest must have succeeded. An older rejected write is
+     * recovered only by a newer successful one after everything has settled, so no
+     * unresolved write can trail behind a committed successor. A stop that never
+     * issued a write owes the ledger nothing — foreground stops always issue their
+     * first write synchronously after install, and a write that throws before it is
+     * sent is recorded as rejected.
+     */
+    private isCancelLedgerSatisfied;
+    /** The stop's captured identity must still be the live one. */
+    private stopIdentityMatches;
+    /**
+     * Reserves the foreground slot. Every check re-verifies a fact the release
+     * already proved; any mismatch fails closed and leaves the stop installed.
+     */
+    private reserveForegroundSlot;
+    private rollbackReservation;
+    /**
+     * Installs a stop boundary. Must run synchronously before the first
+     * cancellation write it is followed by, so admission closes before any
+     * asynchronous cancellation work begins.
+     */
+    protected installStop(input: {
+        kind: ACPStopKind;
+        stoppedTurnId: string;
+        reason: string;
+    }): ACPStopRecord;
+    /**
+     * The one foreground stop operation. Interrupt, permission denial, and a
+     * repeated Stop all land here: it installs the boundary, or reuses the one
+     * installed, and returns when the cancellation write it issued settles.
+     * Settling a write proves transport completion only — the stop stays installed
+     * until terminal proof and a fully settled ledger arrive.
+     *
+     * With no stop-able turn the cancellation write is suppressed entirely (AC13):
+     * no stop is installed and admission state is untouched. A denial caller
+     * passes `correlation`, and the suppression logs
+     * `provider.acp.deny_cancel_suppressed` with a `reason` that separates the
+     * not-initialized session from the no-active-turn case — review finding 3.
+     */
+    protected stopForegroundTurn(input: {
+        reason: string;
+        correlation?: ACPStopCorrelation;
+    }): Promise<void>;
+    /**
+     * Issues one cancellation write on the connection the stop captured and tracks
+     * its promise in that stop's ledger. A write that rejects — or throws before it
+     * is sent — is recorded as rejected, which keeps the boundary closed.
+     */
+    private issueCancelWrite;
+    private settleCancelAttempt;
+    /** Provider-specific stop proof. The generic boundary needs none of it. */
+    protected isProviderStopGateSatisfied(stop: ACPStopRecord): boolean;
+    /** Records provider stop proof and re-evaluates admission. */
+    protected markProviderStopGateSatisfied(stop: ACPStopRecord): void;
+    /**
+     * Names the provider facts a stop is still waiting on, empty once the gate is
+     * satisfied. The generic boundary has one opaque gate; a provider subclass
+     * overrides this so an admission deadline names what it is missing instead of
+     * only reporting a boolean.
+     */
+    protected describeProviderStopGate(stop: ACPStopRecord): string[];
+    /**
+     * Provider-specific proof for a stop settled by the death path, recorded
+     * after the ledger is closed and before the staged successor is rejected.
+     * The generic boundary records none; a subclass records what its own stop
+     * gate still owes (a GJC ownerless abort settles its pending attempt as a
+     * reject so the gate names the real reason).
+     */
+    protected recordProviderStopDeath(stop: ACPStopRecord, reason: string): void;
+    subscribe(callback: (event: AgentStreamEvent) => void): () => void;
+    streamHistory(): AsyncGenerator<AgentStreamEvent>;
+    getRuntimeInfo(): Promise<AgentRuntimeInfo>;
+    getAvailableModes(): Promise<AgentMode[]>;
+    getCurrentMode(): Promise<string | null>;
+    get features(): AgentFeature[];
+    private ensureCommandsReadyDeferred;
+    private settleCommandsReady;
+    private waitForCommandsReady;
+    listCommands(): Promise<AgentSlashCommand[]>;
+    setMode(modeId: string): Promise<void>;
+    private setModeWithSelection;
+    private createProviderModeWriterContext;
+    setModel(modelId: string | null): Promise<void>;
+    private setModelWithSelection;
+    setThinkingOption(thinkingOptionId: string | null): Promise<void>;
+    setFeature(featureId: string, value: unknown): Promise<void>;
+    private applyConfigOptionResponse;
+    getPendingPermissions(): AgentPermissionRequest[];
+    respondToPermission(requestId: string, response: AgentPermissionResponse): Promise<void>;
+    /**
+     * Routes a deny+interrupt by stop kind. The generic router knows two kinds: a
+     * foreground turn gets the ordinary foreground stop plus its cancellation
+     * ledger, and no stop-able turn suppresses the write with an observable log.
+     * A subclass with another stop kind overrides this; the base deliberately
+     * carries no subclass-specific stop identity or routing knowledge.
+     */
+    protected stopTurnOnPermissionDenial(correlation: ACPStopCorrelation): Promise<void>;
+    describePersistence(): AgentPersistenceHandle | null;
+    /**
+     * Cancels the current foreground turn through the stop boundary. Returning
+     * means the cancellation notification write settled — nothing more. It does not
+     * clear the stop, does not terminalize the turn, and does not make the session
+     * ready for a replacement.
+     */
+    interrupt(): Promise<void>;
+    close(): Promise<void>;
+    requestPermission(params: RequestPermissionRequest): Promise<RequestPermissionResponse>;
+    sessionUpdate(params: SessionNotification): Promise<void>;
+    private deliverTranslatedEvents;
+    extNotification(method: string, params: Record<string, unknown>): Promise<void>;
+    private applyResolvedCommands;
+    readTextFile(params: ReadTextFileRequest): Promise<{
+        content: string;
+    }>;
+    writeTextFile(params: WriteTextFileRequest): Promise<Record<string, never>>;
+    createTerminal(params: CreateTerminalRequest): Promise<{
+        terminalId: string;
+    }>;
+    terminalOutput(params: TerminalOutputRequest): Promise<TerminalOutputResponse>;
+    waitForTerminalExit(params: WaitForTerminalExitRequest): Promise<TerminalExit>;
+    releaseTerminal(params: {
+        sessionId: string;
+        terminalId: string;
+    }): Promise<void>;
+    killTerminal(params: KillTerminalRequest): Promise<Record<string, never>>;
+    /**
+     * Subscribes the one death path to the connection's close signal, covering
+     * transport death that no process exit event reports. The SDK aborts
+     * `signal` when the connection's stream ends; test connections without one,
+     * and already-subscribed signals, are skipped.
+     */
+    protected observeConnectionDeath(connection: ClientSideConnection): void;
+    private spawnProcess;
+    private runACPRequest;
+    private acpMcpServers;
+    private applySessionState;
+    private transformConfigOptions;
+    private transformModeId;
+    private applyConfiguredOverrides;
+    private warnInvalidSelection;
+    private modelSelectionUnavailableMessage;
+    private isModelSelectionUnavailableError;
+    private translateSessionUpdate;
+    private handleUserMessageChunk;
+    private flushPendingUserMessage;
+    private handleToolCallUpdate;
+    private createMessageTimelineItem;
+    private resolveAssistantMessageId;
+    private handleCurrentModeUpdate;
+    private handleConfigOptionUpdate;
+    private handleSessionInfoUpdate;
+    private handleUsageUpdate;
+    private handlePromptResponse;
+    private wrapTimeline;
+    protected pushEvent(event: AgentStreamEvent): void;
+    private emitSubmittedUserMessage;
+    private runtimeInfo;
+    /**
+     * Settles a foreground turn. `turnId` is checked against live state before
+     * anything moves:
+     *
+     * - the stopped turn of the installed boundary records terminal proof (once)
+     *   and releases the gate, without leaving the stopping phase while
+     *   cancellation writes are still unresolved or failed;
+     * - the current foreground turn settles ordinarily and hands the slot back;
+     * - anything else is a terminal from an earlier generation and is dropped
+     *   instead of clearing a reserved or running successor.
+     *
+     * After close nothing is emitted and no state moves.
+     */
+    protected finishTurn(turnId: string, event: Extract<AgentStreamEvent, {
+        type: "turn_completed" | "turn_failed" | "turn_canceled";
+    }>): void;
+    /** Emits a terminal event once, after the buffered provider echo is flushed. */
+    private deliverTerminal;
+    private emitBootstrapThreadEvent;
+    private synthesizeCanceledToolCalls;
+    private collectDiagnostic;
+    private getTerminalEntry;
+}
+export declare function findSelectConfigOption({ configOptions, category, id, }: {
+    configOptions: SessionConfigOption[] | null | undefined;
+    category: string;
+    id?: string;
+}): SelectConfigOption | null;
+export declare function deriveSelectorOptions(configOptions: SessionConfigOption[] | null | undefined, category: string): ConfigOptionSelector[];
+export {};
+//# sourceMappingURL=acp-agent.d.ts.map