@tangle-network/sdk-provider-cli-base 0.0.0-stage → 0.12.0

package/dist/index.d.mts

@@ -0,0 +1,1616 @@
+import { a as partitionImageAttachments, i as PreparedAttachment, n as MAX_TOTAL_INLINE_IMAGE_BYTES, o as preparePromptInputParts, r as PROMPT_SECTION_SEPARATOR, s as prependPromptSection, t as MAX_INLINE_IMAGE_BYTES } from "./prompt-input-BHn_1z69.mjs";
+import { AskUserBridge, DEFAULT_INTERACTION_DECISION_TIMEOUT_MS as PERMISSION_DECISION_TIMEOUT_MS, InteractionBroker, InteractionBroker as InteractionBroker$1, InteractionHttpBridge, PermissionPromptBridge, RequestPermissionBridge, RequestPlanBridge, brokerInteractionTools } from "@tangle-network/agent-core/interactions";
+import { CliExecResult, CliExitResult, CliLauncher, CliProcess, CliSpawnConfig, InvalidAttachmentError, JsonRpcError, RpcBridge, StreamParserConfig } from "@tangle-network/sdk-cli-runner";
+import { AgentExecutionInput, AgentExecutionOutcome, AgentExecutionResult, AgentProfile, AgentProfileSecretProvider, AgentRuntimeAttachments, BackendCapabilities, BackendMessage, CliAuthFile, DurablePlan, GetMessagesOptions, HarnessType, InputPart, InteractionExecutionBinding, InteractionResponse, LocalMcpConfig, McpConfig, McpStatusResponse, PlanProviderState, ProviderConfig, ReasoningEffort, RequestedInteractions, SdkHostServices, SdkPlanHost, SdkProviderAdapter, StreamEvent, TokenUsage, ToolPart } from "@tangle-network/agent-interface";
+import { BindableLaunchControl, HarnessId, HarnessId as HarnessId$1, WorkspacePlanApplication, WorkspacePlanApplication as WorkspacePlanApplication$1, WorkspacePlanReceipt } from "@tangle-network/agent-profile-materialize";
+import { HarnessSessionContract } from "@tangle-network/cli-agent-registry/session-contract";
+import { MessagePart, MessageStore, PersistedMessage, PersistedSession, SessionStore, readProviderMessageIds } from "@tangle-network/sdk-session-persistence";
+import { ProviderLogger } from "@tangle-network/cli-agent-registry";
+import { DEFAULT_INTERACTION_MCP_SERVER_NAME, InteractionMcpServer as InteractionMcpServer$1, InteractionMcpServerConfig as InteractionMcpServerConfig$1, interactionMcpToolName } from "@tangle-network/agent-core/interactions/mcp";
+
+//#region src/acp-process-launch.d.ts
+/** How to start the agent process for a session. */
+interface AcpProcessSpec {
+  command: string;
+  args: string[];
+  env?: Record<string, string>;
+  /** Status detail shown while the process starts. */
+  statusDetail: string;
+}
+/** The spawn request a bridge factory receives. */
+interface AcpBridgeSpawn {
+  command: string;
+  args: string[];
+  cwd: string;
+  env?: Record<string, string>;
+  rawCapturePath?: string;
+  uid?: number;
+  gid?: number;
+}
+/** Spawn an ACP agent over NDJSON stdio. The adapter owns abort, so no signal. */
+declare function spawnAcpBridge(request: AcpBridgeSpawn): RpcBridge;
+//#endregion
+//#region src/types.d.ts
+type InteractionToggleKind = keyof RequestedInteractions;
+type InteractionToggleConfig = boolean | RequestedInteractions;
+declare function interactionToggleEnabled(config: InteractionToggleConfig | undefined, kind: InteractionToggleKind): boolean;
+declare function enabledInteractionKinds<TKind extends InteractionToggleKind>(config: InteractionToggleConfig | undefined, supported: readonly TKind[]): TKind[];
+/**
+ * Per-turn interaction toggle carried on the execution input. Native harnesses
+ * treat plan mode as a per-turn property (toggle build/plan on any message), so
+ * the sidecar sends this turn's interactions on the execution input.
+ *
+ * The shared execution contract owns this field. Adapter initialization still
+ * accepts `true` as shorthand, but each turn carries an exact kind map.
+ */
+type PerTurnInteractionInput = Pick<AgentExecutionInput, "interactions">;
+/**
+ * Host-composed context for THIS turn only (e.g. the sidecar's container
+ * runtime snapshot): it must reach the model and nothing else. The caller's
+ * `parts`/`message` stay untouched, so recorders and message stores keep a
+ * transcript of exactly what the user sent.
+ *
+ * Optional for the same reason as `PerTurnInteractionInput.interactions`: the
+ * published `AgentExecutionInput` does not declare the field, and `systemPrompt`
+ * anchors the weak-type check.
+ */
+type EphemeralContextInput = {
+  ephemeralContext?: string;
+  systemPrompt?: unknown;
+};
+/**
+ * Read a turn's ephemeral context, rejecting a wrong-typed value loudly.
+ *
+ * The published `AgentExecutionInput` does not declare the field, so nothing
+ * type-checks it at the process boundary. Left unchecked, a caller passing a
+ * non-string gets it stringified into the model prompt (`[object Object]`) —
+ * a corrupted turn with no error anywhere. `undefined`/`null` mean "no context
+ * this turn"; an empty string is likewise nothing to append.
+ */
+declare function readEphemeralContext(input: EphemeralContextInput): string | undefined;
+/**
+ * Compose the model-facing prompt for a turn: the caller's own text, then this
+ * turn's ephemeral context. Call it at the point the prompt is handed to the
+ * provider — NEVER on the parts handed to `recordUserMessage` or the message
+ * store.
+ */
+declare function withEphemeralContext(promptText: string, input: EphemeralContextInput): string;
+/**
+ * Resolve whether an interaction kind is active for THIS turn. When the turn
+ * carries `interactions` it is authoritative — a complete set that can also
+ * turn a kind OFF mid-session; otherwise the adapter falls back to its latched
+ * config (the initialize-time wiring, or a direct non-sidecar caller's option).
+ */
+declare function turnInteractionEnabled(input: PerTurnInteractionInput, latched: InteractionToggleConfig | undefined, kind: InteractionToggleKind): boolean;
+/**
+ * Overlay this turn's interactions onto a latched config, returning a NEW
+ * object (no shared mutation — safe when one adapter instance serves concurrent
+ * turns from different sessions). When the turn omits `interactions` the config
+ * is returned unchanged, preserving behavior for direct non-sidecar callers.
+ * Adapters read plan/permission/question posture off the returned config so a
+ * mid-session toggle takes effect and can turn a kind off (which the latched
+ * config, only ever merged by updateConfig, cannot).
+ */
+declare function withTurnInteractions<TConfig extends {
+  interactions?: InteractionToggleConfig;
+}>(config: TConfig, input: PerTurnInteractionInput): TConfig;
+/**
+ * Logger interface for CLI providers.
+ */
+interface CliProviderLogger {
+  observePhase?: ProviderLogger["observePhase"];
+  debug(message: string, meta?: Record<string, unknown>): void;
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Base configuration shared by all CLI providers.
+ */
+interface CliProviderConfig {
+  /** Trusted native auth projection resolved by the owning execution host. */
+  nativeAuthEnv?: Record<string, string>;
+  nativeAuthSecretEnv?: string;
+  /** Sidecar-owned credential HOME for this adapter instance. */
+  runtimeHome?: string;
+  /**
+   * Shared, persistent agent HOME. With `runtimeHome`, a harness whose
+   * contract can move its native stores off HOME runs with this HOME and keeps
+   * those stores in `runtimeHome` (configDirHomeEnv). Absent for an
+   * isolated-profile identity, which keeps the private HOME.
+   */
+  agentHome?: string;
+  /** Trusted, adapter-wide native process identity supplied by the executor. */
+  subprocessUser?: {
+    uid: number;
+    gid: number;
+  };
+  /**
+   * The executor keeps this subprocess identity for later backends of the
+   * same session, principal and profile authority: the session's secret MCP
+   * scope and its warm native server outlive this adapter, so the next turn's
+   * backend reuses its running stdio servers and native server. Session end
+   * and their idle TTLs still stop them.
+   */
+  stableIsolatedIdentity?: boolean;
+  /** Executor-owned base for public, per-revision native profile controls. */
+  publicProfileRevisionRoot?: string;
+  /** Executor-owned base for UID-restricted secret profile revisions. */
+  secretProfileRevisionRoot?: string;
+  /** Root-only 32-byte HMAC key; never copied into a turn result. */
+  secretProfileNamingKeyPath?: string;
+  /**
+   * True when the CLI runs inside a sandbox container or VM, where the OS
+   * boundary already confines file access. False or absent means the CLI may
+   * run on a developer's host, so harness path guards stay in force.
+   */
+  sandboxedRuntime?: boolean;
+  /** Portable profile applied to this provider execution. */
+  profile?: AgentProfile;
+  runtimeAttachments?: AgentRuntimeAttachments;
+  /**
+   * Per-turn credential values resolved by secret references in this
+   * execution's runtime MCP attachments. The materialization secret provider
+   * checks this map before the host box environment; values are launch
+   * state only and never enter the CLI's inherited environment or logs.
+   */
+  runtimeSecrets?: Record<string, string>;
+  /** Path to the CLI executable */
+  cliPath?: string;
+  /** Default model to use */
+  model?: string;
+  /** Model provider selected by the caller. */
+  provider?: string;
+  /** API key (provider-specific env var name) */
+  apiKey?: string;
+  /** OpenAI-compatible or provider-native base URL. */
+  baseUrl?: string;
+  /** Optional auth files to materialize under the runtime home directory. */
+  authFiles?: Array<{
+    path: string;
+    content: string;
+    mode?: number;
+  }>;
+  /** Extra flags to pass to the CLI */
+  extraFlags?: string[];
+  /**
+   * Bypass all permission checks for fully autonomous operation.
+   * Each CLI has its own flag:
+   * - Claude Code: --dangerously-skip-permissions
+   * - Codex: --dangerously-bypass-approvals-and-sandbox
+   * - Factory Droids: --autonomy-level skip-permissions-unsafe
+   * Default: true (for headless/automated use)
+   */
+  bypassPermissions?: boolean;
+  /**
+   * Enable structured human interactions by kind. `true` means "all supported
+   * kinds for this adapter"; object form is the precise public surface:
+   * `{ question: true }`, `{ permission: true }`, `{ plan: true }`.
+   *
+   * Each adapter maps these requested kinds onto its native transport (MCP,
+   * reverse RPC, or extension hook) while all responses flow through the same
+   * `/interactions` API.
+   */
+  interactions?: InteractionToggleConfig;
+}
+/**
+ * Options for CLI provider adapter constructors.
+ */
+interface CliProviderOptions<TConfig extends CliProviderConfig = CliProviderConfig> {
+  /** Provider configuration */
+  config?: TConfig;
+  /** Logger instance */
+  logger?: CliProviderLogger;
+  /** Base storage path for session persistence */
+  storagePath?: string;
+  /** Storage subdirectory name (e.g., ".claude-code", ".codex") */
+  storageDir?: string;
+  /** Resolve opaque AgentProfile secret references at the private spawn boundary. */
+  profileSecretProvider?: AgentProfileSecretProvider;
+  /**
+   * For a secret profile revision: the keys the runtime itself manages (the
+   * box's TANGLE_API_KEY), which a turn may not deliver as runtimeSecrets.
+   * Their values reach only the executor's own MCP serving, never the launch.
+   * Anything else a secret revision references comes from runtimeSecrets.
+   */
+  secretProfileRuntimeKeyProvider?: AgentProfileSecretProvider;
+  /**
+   * Environment every CLI child gets in place of the inherited one for these
+   * keys: in a sandbox, the agent user's own HOME, PATH and cache paths, so a
+   * child never inherits the supervisor's cache paths it cannot write. The
+   * adapter's own environment still wins for any key it sets.
+   */
+  agentEnvironment?: () => Record<string, string | undefined>;
+  /**
+   * Start each turn's CLI through the consumer's own executor (a container
+   * slot, a jail) instead of a local spawn. It receives the assembled argv,
+   * cwd and environment; the adapter still parses, times and stops the turn.
+   */
+  launcher?: CliLauncher;
+  /**
+   * Stop what a turn's CLI leaves running in its process group when it exits.
+   * Off by default: a sandbox turn may start a process meant to outlive it.
+   */
+  ownProcessGroup?: boolean;
+}
+/**
+ * Per-turn input a CLI adapter reads beyond AgentExecutionInput: text added
+ * after the harness's own system prompt (a chat caller's system messages),
+ * kept apart from `systemPrompt`, which replaces it.
+ */
+type CliExecutionInput = AgentExecutionInput & {
+  appendSystemPrompt?: string;
+};
+/**
+ * CLI execution arguments.
+ */
+interface CliExecArgs {
+  /** CLI command */
+  command: string;
+  /** Command arguments */
+  args: string[];
+  /** Whether to send message via stdin */
+  useStdin: boolean;
+  /** Stdin prompt text before provider formatting. Defaults to the prepared user prompt. */
+  stdin?: string;
+  /**
+   * Working directory for the spawned process. Defaults to the execution
+   * workspaceRoot when omitted. Set when the CLI must run from a different root
+   * than the session workspace — e.g. nanoclaw's chat script derives its data
+   * dir (the daemon's Unix socket) from cwd, so it must run from the runtime
+   * root, not the sandbox workspace.
+   */
+  cwd?: string;
+}
+/**
+ * Internal state for tracking tool calls during execution.
+ */
+interface ToolCallState {
+  id: string;
+  name: string;
+  input: unknown;
+  startTime: number;
+  status: "pending" | "running" | "completed" | "failed";
+  output?: unknown;
+}
+/**
+ * Internal state for an execution run.
+ */
+interface ExecutionState {
+  /** Session ID (from provider or our persistence layer) */
+  sessionId?: string;
+  /** Message ID for part correlation */
+  messageId?: string;
+  /**
+   * Absolute root the CLI process ran with as its cwd. Used by
+   * `trackFilePart` to resolve a relative path it observes into the same
+   * absolute path a sibling observation reports absolutely, so the two unify
+   * on one dedupe key/url instead of minting divergent parts.
+   */
+  workspaceRoot?: string;
+  /** Text part ID (reused for streaming updates) */
+  textPartId?: string;
+  /** Active tool calls */
+  toolCalls: Map<string, ToolCallState>;
+  /** Accumulated text content */
+  textBuffer: string;
+  /** Accumulated reasoning/thinking blocks */
+  reasoningBuffer: string[];
+  /**
+   * Reasoning parts emitted so far — one entry per distinct reasoning block,
+   * carrying the stable part id downstream consumers key on. Maintained by
+   * `trackReasoningBlock`.
+   */
+  reasoningParts?: Array<{
+    id: string;
+    text: string;
+  }>;
+  /**
+   * File parts announced this reply, deduped by normalized path/data-URI key.
+   * Maintained by `trackFilePart`.
+   */
+  fileParts?: Array<{
+    id: string;
+    key: string;
+    filename?: string;
+    mediaType?: string;
+    url: string;
+  }>;
+  /** Structured native failure retained through process exit. */
+  failure?: {
+    message: string;
+    code?: string;
+    statusCode?: number;
+  };
+  /** Latest provider warning emitted before process exit. */
+  lastDiagnostic?: string;
+  /** Latest terminal status emitted by the provider stream. */
+  terminalStatus?: "completed" | "failed";
+  /** Observed usage; absent channels were not reported by the provider. */
+  tokenUsage?: Partial<TokenUsage>;
+}
+//#endregion
+//#region src/acp-protocol.d.ts
+/** The ACP protocol version this client speaks, and the oldest it accepts. */
+declare const ACP_PROTOCOL_VERSION = 1;
+declare const ACP_MIN_PROTOCOL_VERSION = 1;
+/** Settings every ACP agent process takes. */
+interface AcpBridgeConfig extends CliProviderConfig {
+  /** Protocol version requested in `initialize` (default 1). */
+  protocolVersion?: number;
+  /** Timeout for one `session/prompt` turn (default 10 min). */
+  promptTimeoutMs?: number;
+  /** Timeout for `initialize` and `session/new|load` (default 2 min). */
+  bootstrapTimeoutMs?: number;
+  /**
+   * How long an idle session keeps its agent process (default 5 min).
+   * 0 closes the process after every turn.
+   */
+  bridgeIdleMs?: number;
+}
+/** ACP content blocks this client reads or sends. */
+type AcpContentBlock = {
+  type: "text";
+  text: string;
+} | {
+  type: "image";
+  data?: string;
+  mimeType?: string;
+  uri?: string;
+} | {
+  type: "resource";
+  uri: string;
+  mimeType?: string;
+} /** Tool-call content: one content block wrapped one level deeper. */ | {
+  type: "content";
+  content: {
+    type: "text";
+    text: string;
+  };
+};
+interface AcpInitializeParams {
+  protocolVersion: number;
+  clientCapabilities: {
+    fs?: {
+      readTextFile?: boolean;
+      writeTextFile?: boolean;
+    };
+    terminal?: boolean;
+  };
+}
+interface AcpInitializeResult {
+  protocolVersion: number;
+  agentCapabilities?: Record<string, unknown>;
+  agentInfo?: {
+    name?: string;
+    title?: string;
+    version?: string;
+  };
+  authMethods?: Array<{
+    id: string;
+    name?: string;
+    description?: string;
+  }>;
+}
+interface AcpNewSessionResult {
+  sessionId: string;
+}
+interface AcpPromptResult {
+  stopReason: "end_turn" | "max_tokens" | "max_turn_requests" | "refusal" | "cancelled" | string;
+}
+/** `session/update` notification params; only the mapped kinds are typed. */
+interface AcpSessionUpdateParams {
+  sessionId: string;
+  update: {
+    sessionUpdate: "agent_message_chunk" | "agent_thought_chunk";
+    content: AcpContentBlock | AcpContentBlock[];
+  } | {
+    sessionUpdate: "tool_call";
+    toolCallId: string;
+    title?: string;
+    kind?: string;
+    status?: "pending" | "in_progress" | "completed" | "failed";
+    rawInput?: unknown;
+  } | {
+    sessionUpdate: "tool_call_update";
+    toolCallId: string;
+    status?: "pending" | "in_progress" | "completed" | "failed";
+    content?: AcpContentBlock[];
+    rawOutput?: unknown;
+  } | {
+    sessionUpdate: "plan";
+    entries: Array<{
+      content: string;
+      priority?: string;
+      status?: string;
+    }>;
+  } | {
+    sessionUpdate: string;
+    [key: string]: unknown;
+  };
+}
+/** One turn's inputs, resolved before any session or process work. */
+interface AcpTurn<TConfig extends AcpBridgeConfig> {
+  readonly config: TConfig;
+  /**
+   * The process configuration a cached session was started with. A turn
+   * with a different key gets a new process: an ACP agent reads its model
+   * and backing agent once, at startup.
+   */
+  readonly processKey: string;
+}
+/** Text carried by ACP content blocks, including tool-call content. */
+declare function acpContentText(content: AcpContentBlock | AcpContentBlock[] | undefined): string;
+/** Map an ACP stop reason onto a turn status. */
+declare function mapAcpStopReason(reason: string | undefined): {
+  status: "completed" | "failed";
+  detail?: string;
+};
+//#endregion
+//#region src/turn-process.d.ts
+/** A turn transport may finish while its provider server remains alive. */
+type CliTurnProcess = Pick<CliProcess, "pid" | "write" | "closeInput" | "kill" | "exitPromise" | "beginRawCapture"> & {
+  stderr?: NodeJS.ReadableStream;
+};
+type CliTurnSpawn<TConfig, TEvent> = {
+  input: AgentExecutionInput;
+  sessionId: string;
+  providerSessionId?: string;
+  config: TConfig;
+  execArgs: CliExecArgs;
+  workspaceRoot: string;
+  env: Record<string, string | undefined>;
+  signal: AbortSignal;
+  timeoutMs?: number;
+  parser: StreamParserConfig<TEvent>;
+  /**
+   * A process started before the turn it serves (a held spare): its raw
+   * capture opens when a turn adopts it (`beginRawCapture`), inside that
+   * turn's attempt, not at spawn.
+   */
+  deferRawCapture?: boolean;
+};
+/** One turn's launch, prepared for a caller that runs the process itself. */
+type PreparedCliLaunch = {
+  /** Pass to `execCli` or `launchCliProcess`, adding `signal` and `timeoutMs`. */spawn: CliSpawnConfig; /** Write to the child's stdin and close it; absent when the prompt is in argv. */
+  stdin?: string; /** The native session id the argv names, for a harness that pre-mints it. */
+  nativeSessionId?: string; /** The profile's workspace files and spawn inputs that were applied. */
+  workspacePlan?: WorkspacePlanReceipt;
+};
+//#endregion
+//#region src/adapter-lifecycle.d.ts
+/** Owns configuration, initialization, cancellation, and subprocess identity. */
+declare abstract class CliAdapterLifecycle<TConfig extends CliProviderConfig = CliProviderConfig> {
+  abstract readonly provider: string;
+  protected abstract readonly defaultCliPath: string;
+  /**
+   * The message log directory when the caller names none. Unset, it is the
+   * registry spec's `messageStorageDir` for `provider`, the one source; only
+   * an adapter for a provider the registry does not know sets it.
+   */
+  protected readonly defaultStorageDir?: string;
+  protected readonly inheritProcessEnv: boolean;
+  protected config: TConfig;
+  private readonly initialConfig;
+  protected logger: CliProviderLogger;
+  protected sessionStore: SessionStore | null;
+  protected messageStore: MessageStore | null;
+  protected storagePath: string;
+  private _storageDir;
+  private readonly agentEnvironment;
+  /** The consumer's executor for turn processes; a local spawn when absent. */
+  protected readonly launcher: CliLauncher | undefined;
+  /** Whether a turn's leftover process-group members are stopped at exit. */
+  protected readonly ownProcessGroup: boolean;
+  protected initialized: boolean;
+  protected readonly activeProcesses: Set<CliTurnProcess>;
+  private readonly initialization;
+  constructor(options?: CliProviderOptions<TConfig>);
+  /**
+   * Get the storage directory. Uses provided storageDir or falls back to defaultStorageDir.
+   */
+  protected get storageDir(): string;
+  /** Bind a live interaction to the exact provider execution that originated it. */
+  protected interactionExecutionBinding(input: AgentExecutionInput, sessionId: string): InteractionExecutionBinding;
+  /**
+   * The uid/gid every CLI process this adapter spawns runs as, or undefined
+   * when the host process is already unprivileged.
+   *
+   * This is an adapter-wide invariant, not a per-callsite option, because
+   * these CLIs seed their own state on first use — a sqlite database, a log
+   * directory, a downloaded-binary cache under the harness HOME. An auxiliary
+   * invocation left at root (`mcp add`, `mcp list`, `--version`) creates that
+   * tree root-owned, and the streamed run, which does drop privileges, then
+   * cannot open its own log and exits before emitting a single event.
+   */
+  protected subprocessIdentity(): {
+    uid: number;
+    gid: number;
+  } | undefined;
+  /** `subprocessIdentity` shaped for `spawn`'s options bag. */
+  protected subprocessSpawnOptions(): {
+    uid?: number;
+    gid?: number;
+  };
+  /**
+   * Run a one-shot CLI command under this adapter's subprocess identity.
+   *
+   * Every auxiliary invocation an adapter makes goes through here so the
+   * identity cannot be forgotten at a call site. Auxiliary output stays out
+   * of the streamed turn's raw evidence.
+   */
+  protected runCli(config: Omit<CliSpawnConfig, "rawCapturePath">): Promise<CliExecResult<unknown>>;
+  /**
+   * Run a builtin-only Node script under this adapter's subprocess identity
+   * and return its stdout. File work inside a directory the CLI user owns goes
+   * through here, so a root sidecar never creates, reads or writes there with
+   * its own rights: a link the agent plants reaches only what the agent could
+   * already reach. The script reads `args` from argv after `--` and `input`
+   * from stdin. A failure carries the script's stderr, not the script text.
+   */
+  protected runNodeAsSubprocess(script: string, args: readonly string[], input?: string): Promise<string>;
+  getCapabilities(): BackendCapabilities;
+  initialize(config: ProviderConfig & Pick<CliProviderConfig, "runtimeAttachments">): Promise<void>;
+  private initializeAtGeneration;
+  /**
+   * Auth/config files the adapter needs on disk that do NOT arrive through
+   * `config.model.authFiles` — e.g. a synthesized `~/.openclaw/openclaw.json`
+   * pointing at the managed router. The sidecar materializes these through the
+   * hardened `materializeCliAuthFiles` path AFTER `initialize()`, so an adapter
+   * can derive them from the resolved config/env. Default: none.
+   */
+  getManagedAuthFiles(): CliAuthFile[];
+  /** Provider-specific initialization runs inside the tracked lifecycle. */
+  protected afterInitialize(_config: ProviderConfig): Promise<void>;
+  /**
+   * The harness session contract this adapter honours (cli-agent-registry
+   * NATIVE_SESSION_CONTRACTS), or null for a provider that declares none.
+   * Registration refuses a harness spec without one; ACP overrides this per
+   * sub-agent.
+   */
+  protected sessionContract(): HarnessSessionContract | null;
+  shutdown(): Promise<void>;
+  healthCheck(): Promise<boolean>;
+  /** Run this CLI's own one-shot command (version, MCP) in the workspace. */
+  protected runAuxiliaryCli(args: string[], timeoutMs: number): Promise<CliExecResult<unknown>>;
+  updateConfig(config: Partial<TConfig>): Promise<TConfig>;
+  /**
+   * Build environment variables for CLI execution.
+   */
+  protected abstract buildExecEnv(config: TConfig): Record<string, string | undefined>;
+  /** Apply private native credentials to every CLI subprocess through one path. */
+  protected buildNativeExecutionEnvironment(config: TConfig): Record<string, string | undefined>;
+  protected getCliPath(): string;
+  protected ensureInitialized(): void;
+  protected getSessionStore(): SessionStore;
+  protected getMessageStore(): MessageStore;
+  /** The agent environment the host supplied (CliProviderOptions.agentEnvironment). */
+  protected agentEnvironmentValues(): Record<string, string | undefined>;
+  protected applyWritableHomeDefaults(adapterEnv: Record<string, string | undefined>, workspaceRoot: string): Record<string, string | undefined>;
+}
+//#endregion
+//#region src/adapter-profile.d.ts
+/** Owns native profile revisions, launch controls, and prompt composition. */
+declare abstract class CliAdapterProfile<TConfig extends CliProviderConfig = CliProviderConfig> extends CliAdapterLifecycle<TConfig> {
+  /** Native profile lowering explicitly owned by this adapter, never inferred from a path. */
+  protected readonly profileHarness: HarnessId$1 | undefined;
+  /** Trusted implementation capabilities; never read from caller-owned configuration. */
+  protected readonly supportsSecretProfileRevisions: boolean;
+  private readonly profileSecretProvider;
+  private readonly secretProfileRuntimeKeyProvider;
+  /**
+   * The materialized digest behind each secret revision. It stays here: the
+   * executor receipt is all a caller sees of a revision's resolved contents.
+   */
+  private readonly secretProfileMaterializedDigests;
+  /**
+   * The value behind each `{env:NAME}` reference in a secret revision's
+   * config, by that revision's application. Executor memory only: no launch
+   * environment, argv or file ever carries them.
+   */
+  private readonly secretProfileReferenceValues;
+  constructor(options?: CliProviderOptions<TConfig>);
+  /** Apply captured diagnostic identity to this spawn, after profile composition. */
+  /** The exact child environment a turn uses; shared with prewarm paths. */
+  protected buildTurnEnvironment(executionConfig: TConfig, profilePlan: WorkspacePlanApplication$1 | undefined, workspaceRoot: string, correlationHeaders: Readonly<Record<string, string>> | undefined): Record<string, string | undefined>;
+  /**
+   * A profile's declared executable tools, sealed in its revision, stand in
+   * for the app's own tool dirs on this launch's PATH tail. A secret profile's
+   * env no longer names the app's dirs (app env is scrubbed), so the sidecar's
+   * own SANDBOX_TOOL_BIN_DIRS says which inherited PATH entries they are.
+   */
+  private bindProfileToolBinDirs;
+  protected bindExecutionCorrelation(environment: Record<string, string | undefined>, correlationHeaders: Readonly<Record<string, string>> | undefined): Record<string, string | undefined>;
+  /**
+   * Provision the inline profile's files and native execution controls with the
+   * shared materializer used by cli-bridge. Unsupported portable controls fail
+   * before spawn unless the profile is explicitly best-effort
+   * (resources.failOnError: false), which materializes the supported subset
+   * and warns about the rest.
+   */
+  /**
+   * Launcher controls this adapter OWNS on the spawn it starts — see
+   * `BINDABLE_LAUNCH_CONTROLS` in the materializer. Empty by default: a plan
+   * whose intent needs a launcher binding then fails closed instead of being
+   * silently dropped. An adapter that really applies the plan's launch flags
+   * to its own spawn (sdk-provider-opencode selecting the plan's primary
+   * agent via `--agent`) overrides this with the controls it honors.
+   */
+  protected profileMaterializationBinds(): readonly BindableLaunchControl[];
+  /** Optional native instruction root. The adapter owns how its runtime locates this directory. */
+  protected profileAgentDirectory(_workspaceRoot: string): string | undefined;
+  /** Provider transport bound into the private immutable revision and receipt. */
+  protected secretProfileProviderConfig(): Record<string, unknown> | undefined;
+  /**
+   * The values behind a secret revision's `{env:NAME}` config references, for
+   * an executor that serves those references itself. Never pass them to the
+   * native process.
+   */
+  protected secretProfileReferences(application: WorkspacePlanApplication$1 | undefined): Readonly<Record<string, string>> | undefined;
+  protected materializeProfileResources(inputProfile: AgentProfile | undefined, workspaceRoot: string, ownerId?: string, sessionId?: string, scope?: "turn" | "prewarm"): Promise<WorkspacePlanApplication$1 | undefined>;
+  private applyProfileResources;
+  /**
+   * Publish the profile as an executor-sealed revision for this session's
+   * subprocess identity, and record the receipt that binds it to the turn.
+   */
+  private applySecretProfileRevision;
+  /**
+   * Prepare the same provider-composed native plan that execute() will check.
+   * This may publish an immutable public revision, but never starts a model turn.
+   */
+  preparePublicProfileRevision(input: AgentExecutionInput): Promise<{
+    workspacePlanDigest: string;
+    materializedDigest: string;
+    launchDigest: string;
+    conflicts: Array<{
+      relPath: string;
+      copyRelPath: string;
+      reason: "existing" | "symlink";
+    }>;
+  }>;
+  /** Prepare the private native plan and return only an opaque executor receipt. */
+  prepareSecretProfileRevision(input: AgentExecutionInput): Promise<{
+    workspacePlanDigest: string;
+    executorReceipt: string;
+    conflicts: Array<{
+      relPath: string;
+      copyRelPath: string;
+      reason: "existing" | "symlink";
+    }>;
+  }>;
+  /**
+   * What the native health check's verdict depends on besides a revision's
+   * bytes: the executable that loads them. A provider whose check runs
+   * through a configurable binary names it here.
+   */
+  protected secretProfileVerificationScope(): string;
+  /** A secret receipt is issued only after the provider can load this revision. */
+  protected verifyPreparedSecretProfileRevision(_input: AgentExecutionInput, _application: WorkspacePlanApplication$1): Promise<void>;
+  /** Resolve the canonical profile used for this execution. */
+  protected resolveExecutionProfile(requestPrompt: string | undefined): AgentProfile | undefined;
+  /** Select the profile materialized for this exact turn. */
+  protected resolveExecutionProfileForInput(input: AgentExecutionInput): AgentProfile | undefined;
+  /** Compose the provider's user-message channel for this exact turn. */
+  protected composePromptText(promptText: string, input: AgentExecutionInput): string;
+  protected withProfilePlan(config: TConfig, profilePlan: WorkspacePlanApplication$1 | undefined): TConfig;
+  protected resolveProfileSystemPrompt(requestPrompt: string | undefined, profilePlan: WorkspacePlanApplication$1 | undefined): string | undefined;
+  /**
+   * The plan's additive prompt intent for this spawn. No request-level
+   * counterpart exists (`AgentExecutionInput` carries only the replacement),
+   * so unlike {@link resolveProfileSystemPrompt} there is nothing to
+   * conflict-check against.
+   */
+  protected resolveProfileAppendSystemPrompt(profilePlan: WorkspacePlanApplication$1 | undefined): string | undefined;
+  protected resolveProfileModel(requestModel: string | undefined): string | undefined;
+  protected mergeProfilePlanEnvironment(environment: Record<string, string | undefined>, profilePlan: WorkspacePlanApplication$1 | undefined, preserveClearedVariables?: boolean): Record<string, string | undefined>;
+  /** Provider-owned allowlist for a generated revision control after env scrub. */
+  protected profilePlanMayFillClearedEnvironmentVariable(_name: string, _value: string): boolean;
+  protected preparePromptInput(parts: InputPart[], workspaceRoot: string, sessionId: string, options?: {
+    /** Override of the per-request inline-image budget — pass 0 on paths
+     *  that deliver markers only and would discard the base64. */
+    inlineImageBudgetBytes?: number;
+    /** Override of the adapter's nativeAttachmentKinds() for this call —
+     *  pass [] on paths that cannot forward any kind natively, so every
+     *  attachment keeps its canonical text marker. */
+    nativeAttachmentKinds?: ReadonlyArray<"image" | "file">;
+  }): Promise<{
+    promptText: string;
+    persistedParts: MessagePart[];
+    attachments: PreparedAttachment[];
+  }>;
+  /**
+   * Attachment kinds this adapter forwards natively via buildExecArgs (argv
+   * flag / stdin content block) instead of the `[Image: ...]` / `[File: ...]`
+   * text marker. The base adapter omits those kinds' markers from the prompt
+   * text — an adapter that opts a kind in MUST deliver every attachment of
+   * that kind itself, or the model never sees it.
+   */
+  protected nativeAttachmentKinds(): ReadonlyArray<"image" | "file">;
+}
+//#endregion
+//#region src/adapter-sessions.d.ts
+/** Owns durable transcripts, provider-native session bindings and the turn hooks providers override. */
+declare abstract class CliAdapterSessions<TConfig extends CliProviderConfig = CliProviderConfig> extends CliAdapterProfile<TConfig> {
+  createSession(options?: {
+    workspaceRoot?: string;
+  }): Promise<string>;
+  deleteSession(sessionId: string): Promise<boolean>;
+  /**
+   * Choose the native ID before its argv check, durable binding, and
+   * reservation. `input` and `timeoutMs` are the turn's, for a harness that
+   * decides here whether a process started earlier can serve it.
+   */
+  protected mintNativeSessionId(_context: {
+    sessionId: string;
+    workspaceRoot: string;
+    config: TConfig;
+    model?: string;
+    env: Record<string, string | undefined>;
+    signal: AbortSignal;
+    buildExecArgs: (nativeSessionId: string) => CliExecArgs;
+    input: AgentExecutionInput;
+    timeoutMs?: number;
+  }): string | Promise<string>;
+  /**
+   * Make a pre-minted native session durable before the CLI starts, for a
+   * harness that would otherwise write nothing until its first model reply
+   * (Pi). Called after the argv check and before spawn.
+   */
+  protected reserveNativeSession(_nativeSessionId: string, _context: {
+    workspaceRoot: string;
+  }): void | Promise<void>;
+  /**
+   * Verify that the provider can resume the native session binding. By
+   * default a session in a per-session store is resumable only when one of
+   * its declared files exists under the runtime HOME; a pre-minted id whose
+   * first turn died before the CLI wrote anything is not.
+   */
+  protected providerSessionIsResumable(runtimeHome: string, providerSessionId: string): boolean | Promise<boolean>;
+  /**
+   * Resolve the provider-native session id the next turn can resume, or
+   * undefined when no usable binding exists. Provider session data lives
+   * under the runtime home that minted it. A different home or missing
+   * provider storage cannot resume that session. A record without a home
+   * stamp predates the field, so treat it as same-home.
+   */
+  protected resumableProviderSessionId(session: PersistedSession): Promise<string | undefined>;
+  /** Bind a checkpoint-proven native session to this provider identity before execution. */
+  protected seedNativeSessionForResume(input: AgentExecutionInput, nativeSessionId: string): Promise<void>;
+  /**
+   * Forks the persisted session and copies its messages up to `messageId`.
+   * The forked record carries no provider session id, so its first turn
+   * starts a fresh CLI session and receives the copied transcript as
+   * execution-only context. Callers that address turns by their own session
+   * id (the sidecar) pass that id as `targetSessionId` so later turns find
+   * the forked record.
+   */
+  forkSession(options: {
+    sessionId: string;
+    messageId?: string;
+    workspaceRoot?: string;
+    targetSessionId?: string;
+  }): Promise<string>;
+  getMessages(options: GetMessagesOptions): Promise<BackendMessage[]>;
+  protected toBackendMessage(msg: PersistedMessage): BackendMessage;
+  protected buildAssistantParts(state: ExecutionState): MessagePart[];
+  protected extractToolInvocations(state: ExecutionState): AgentExecutionResult["toolInvocations"];
+  /**
+   * Names of tools this provider substitutes for a model tool call it could
+   * not parse into any real tool.
+   *
+   * Default: none. A provider that has one must say so, because these calls
+   * do not present as failures. OpenCode's `invalid` reports the parse error
+   * as its output and completes, so the repeated-failure guard reads a run of
+   * them as progress and clears its count on every one.
+   */
+  protected toolCallRepairToolNames(): ReadonlySet<string>;
+  /**
+   * Decide whether a non-zero exit should be treated as success.
+   *
+   * Default: no — any non-zero exit is a failure.
+   *
+   * Providers override this when their CLI has a known "exits non-zero
+   * on a successful run" quirk (e.g. kimi writes its resume trailer to
+   * stderr and exits non-zero even when the task completed cleanly).
+   *
+   * The decision is made AFTER the stream has drained and the exit
+   * code is known, so `state` reflects the full set of events the
+   * parser emitted (including any terminal `result` / `done` event).
+   * A safe heuristic is: "non-zero exit + stderr matches known trailer
+   * pattern + at least one assistant part was recorded".
+   */
+  protected isBenignNonZeroExit(_params: {
+    exitCode: number | null;
+    stderr: string;
+    state: ExecutionState;
+  }): boolean;
+  /** Observe settled process output before success/failure classification. */
+  protected afterCliProcessExit(_params: {
+    state: ExecutionState;
+    stderr: string;
+    exit: CliExitResult;
+    workspaceRoot: string;
+    env: Record<string, string | undefined>;
+    onEvent?: (event: StreamEvent) => void;
+  }): Promise<void>;
+  protected executionOutcome(_state: ExecutionState, _input: AgentExecutionInput): AgentExecutionOutcome | Promise<AgentExecutionOutcome>;
+  /**
+   * Format a message for stdin input.
+   */
+  protected formatStdinMessage(message: string): string;
+}
+//#endregion
+//#region src/adapter-mcp.d.ts
+/** Owns serialized MCP mutations and provider-native MCP status commands. */
+declare abstract class CliAdapterMcp<TConfig extends CliProviderConfig = CliProviderConfig> extends CliAdapterSessions<TConfig> {
+  /** Budget for one `mcp list` run, CLI startup and every server's handshake. */
+  protected readonly mcpStatusTimeoutMs: number;
+  private mcpMutationChain;
+  addMcp(name: string, config: McpConfig): Promise<void>;
+  private addMcpSerialized;
+  getMcpStatus(): Promise<McpStatusResponse>;
+  ensureMcps(required: Record<string, McpConfig>): Promise<void>;
+  /** Build MCP add command arguments. Override for CLI-specific syntax. */
+  protected buildMcpAddArgs(name: string, config: McpConfig): string[];
+  /**
+   * Build MCP list command arguments. Return null if not supported.
+   */
+  protected buildMcpListArgs(): string[] | null;
+  /** Parse MCP list output. Override for CLI-specific output format. */
+  protected parseMcpListOutput(output: string): McpStatusResponse;
+}
+//#endregion
+//#region src/turn-observer.d.ts
+interface TurnObserverOptions {
+  provider: string;
+  state: ExecutionState;
+  sessionId: string;
+  getRuntimeHome: () => string | undefined;
+  recorder: SdkHostServices["recorder"];
+  getSessionStore: () => SessionStore;
+  logger: CliProviderLogger;
+  repairToolNames: ReadonlySet<string>;
+  onEvent: ((event: StreamEvent) => void) | undefined;
+}
+/**
+ * Observes one turn's provider stream: keeps the execution state current,
+ * persists parts and the provider session id as they arrive, stops a turn
+ * that repeats a rejected tool call, and pings while the stream is quiet.
+ */
+declare class TurnObserver {
+  private readonly options;
+  providerSessionPersistence: Promise<void>;
+  providerSessionPersistenceError: unknown;
+  repeatedToolFailureTripped: boolean;
+  nativeSessionObserved: boolean;
+  private readonly partUpdates;
+  private readonly liveness;
+  private readonly repeatedToolFailureGuard;
+  private killForRepeatedToolFailure;
+  constructor(options: TurnObserverOptions);
+  flushPartUpdates(): Promise<void>;
+  attachProcess(process: CliTurnProcess): void;
+  startLiveness(executionSignal: AbortSignal, startTime: number): NodeJS.Timeout;
+  readonly onEvent: (event: StreamEvent) => void;
+  private observeToolPart;
+  private persistProviderSession;
+}
+//#endregion
+//#region src/execution-state.d.ts
+/**
+ * Creates a new execution state.
+ */
+declare function createExecutionState(sessionId?: string, messageId?: string, workspaceRoot?: string): ExecutionState;
+//#endregion
+//#region src/profile-config.d.ts
+/**
+ * Per-turn credential delivery wins over host-env resolution; the host box
+ * environment stays the fallback for references the turn did not deliver.
+ * With no turn secrets the host provider is returned unchanged, so the
+ * overlay adds no behavior to executions that never asked for it.
+ */
+declare function runtimeSecretsOverlay(runtimeSecrets: Record<string, string> | undefined, fallback: AgentProfileSecretProvider): AgentProfileSecretProvider;
+//#endregion
+//#region src/base-adapter.d.ts
+/**
+ * Base adapter for CLI-based AI agent providers.
+ *
+ * Subclasses must implement:
+ * - provider: string identifier
+ * - defaultCliPath: default CLI executable name
+ * - buildExecArgs(): build CLI execution arguments
+ * - buildExecEnv(): build environment variables
+ * - createEventParser(): create JSONL event parser
+ * - mapEventToStreamEvents(): map parsed events to StreamEvents
+ *
+ * The message log directory is the registry spec's `messageStorageDir` for
+ * `provider` (cli-agent-registry `messageStorageDirOf`); only an adapter for
+ * a provider the registry does not know sets `defaultStorageDir`.
+ *
+ * Optional overrides:
+ * - buildMcpAddArgs(): MCP add command arguments
+ * - buildMcpListArgs(): MCP list command arguments (if supported)
+ * - parseMcpListOutput(): parse MCP list output
+ */
+declare abstract class CliProviderAdapterBase<TConfig extends CliProviderConfig = CliProviderConfig, TEvent = unknown> extends CliAdapterMcp<TConfig> implements SdkProviderAdapter {
+  protected readonly supportsManagedQuote: boolean;
+  execute(input: AgentExecutionInput, services: SdkHostServices, onEvent?: (event: StreamEvent) => void): Promise<AgentExecutionResult>;
+  private executeInternal;
+  /**
+   * Record a successful turn: the provider session id, the assistant message,
+   * and the result, cached for a same-turnId retry.
+   */
+  protected completeTurn(params: {
+    input: AgentExecutionInput;
+    sessionId: string;
+    state: ExecutionState; /** The CLI turn's observer, whose coalesced part updates drain first. */
+    observer?: TurnObserver;
+    recorder: SdkHostServices["recorder"];
+    providerMessageIds: ReturnType<typeof readProviderMessageIds>;
+    profilePlan?: WorkspacePlanApplication$1;
+    startTime: number;
+    endTime: number;
+  }): Promise<AgentExecutionResult>;
+  /** Report and record a failed turn, then throw its error. */
+  private failCliTurn;
+  /**
+   * Open the turn's session (sidecar/provider persistence only; native CLI
+   * startup is measured separately). A same-turnId retry of a completed turn
+   * gets that turn's cached result instead of running again.
+   */
+  protected openTurnSession(input: AgentExecutionInput, recorder: SdkHostServices["recorder"], onEvent: ((event: StreamEvent) => void) | undefined): Promise<{
+    providerMessageIds: any;
+    cached: AgentExecutionResult;
+    sessionId: string;
+    providerSessionId: string | undefined;
+    transcriptReplay: "fork" | "restored" | undefined;
+  } | {
+    providerMessageIds: any;
+    cached: undefined;
+    sessionId: string;
+    providerSessionId: string | undefined;
+    transcriptReplay: "fork" | "restored" | undefined;
+  }>;
+  /** Provision the profile's cwd-native dimensions for this turn. */
+  private materializeTurnProfile;
+  /**
+   * Prepare the prompt and record the caller's own parts. `promptText`
+   * additionally carries the replayed transcript and this turn's ephemeral
+   * context, which are execution-only and stay out of both stores.
+   */
+  protected recordTurnPrompt(input: AgentExecutionInput, session: {
+    sessionId: string;
+    transcriptReplay: "fork" | "restored" | undefined;
+    providerMessageIds: ReturnType<typeof readProviderMessageIds>;
+  }, recorder: SdkHostServices["recorder"]): Promise<{
+    preparedInput: {
+      promptText: string;
+      persistedParts: readProviderMessageIds[];
+      attachments: PreparedAttachment[];
+    };
+    promptText: string;
+  }>;
+  /** Resolve this turn's config, environment and argv, and check them against the session contract. */
+  private planLaunch;
+  /** Reserve and announce the native session id a pre-minted harness already has. */
+  private bindNativeSession;
+  /** Spawn the turn's process, feed its input, and wait for it to exit. */
+  private runCliTurn;
+  /**
+   * Build CLI execution arguments for the exec command.
+   */
+  protected abstract buildExecArgs(params: {
+    message: string;
+    config: TConfig; /** Canonical identity for providers whose native config binds HTTP headers. */
+    correlationHeaders?: Readonly<Record<string, string>>;
+    model?: string;
+    sessionId?: string;
+    /**
+     * Set on a new session of a harness whose contract pre-mints its id: the
+     * adapter MUST start the native session under this id with the contract's
+     * identity args (e.g. `--session-id <id>`). The base checks the argv.
+     */
+    mintedSessionId?: string;
+    workspaceRoot: string;
+    systemPrompt?: string;
+    /**
+     * The plan's ADDITIVE prompt intent: the harness's own prompt stays in
+     * force and this text is added after it. NEVER the same channel as
+     * `systemPrompt` (a replacement) — an adapter must bind it to its
+     * harness's additive control, not substitute one for the other.
+     *
+     * The materializer sets it only for harnesses whose addition control is a
+     * launch argument (claude-code, pi and prime `--append-system-prompt`); an
+     * adapter for such a harness MUST bind it, or the intent the plan asserted
+     * supported is silently dropped. A profile that keeps the harness prompt
+     * (keepsHarnessSystemPrompt) also receives the host prompt here; codex
+     * binds it to `developer_instructions`, and opencode already carries it in
+     * its materialized addition file.
+     */
+    appendSystemPrompt?: string;
+    attachments?: PreparedAttachment[]; /** Preserve the origin of launch flags when a CLI needs one selected agent. */
+    profilePlan?: WorkspacePlanApplication$1;
+  }): CliExecArgs;
+  /** Create the provider event parser for CLI output. */
+  protected abstract createEventParser(state: ExecutionState, onEvent?: (event: StreamEvent) => void): StreamParserConfig<TEvent>;
+  /** How one turn's argv runs: cwd, environment, identity or launcher, stdio. */
+  private turnSpawnConfig;
+  /**
+   * The launch one turn would make, without starting it: the spawn config
+   * (argv, cwd, environment, identity or launcher), the stdin payload, and
+   * the profile files written into the workspace. Session and message
+   * stores are untouched and no held process is reserved, so a caller that
+   * runs the process itself (`execCli`) owns its output and lifecycle.
+   */
+  prepareLaunch(input: CliExecutionInput, options?: {
+    providerSessionId?: string;
+  }): Promise<PreparedCliLaunch>;
+  /** Override only when the provider has a turn transport besides a CLI child. */
+  protected spawnExecutionProcess(request: CliTurnSpawn<TConfig, TEvent>): CliTurnProcess | Promise<CliTurnProcess>;
+}
+//#endregion
+//#region src/acp-session-adapter.d.ts
+/**
+ * Shared lifecycle of a provider that drives an Agent Client Protocol agent
+ * over a JSON-RPC stdio bridge: one cached process and native ACP session per
+ * Tangle session, `initialize` then `session/new` (or `session/load` for a
+ * provider that resumes), serialized `session/prompt` turns, the cancel
+ * sequence (`session/cancel`, grace, close), `session/update` translation,
+ * idle reaping and eviction on process exit or turn failure.
+ *
+ * A provider supplies only its translation: how a turn resolves its config,
+ * how the process starts, the prompt blocks, and its own failure signals.
+ */
+declare abstract class AcpProviderAdapterBase<TConfig extends AcpBridgeConfig, TTurn extends AcpTurn<TConfig> = AcpTurn<TConfig>> extends CliProviderAdapterBase<TConfig> {
+  /** True when the agent supports `session/load` for a recorded native session. */
+  protected abstract readonly loadsNativeSessions: boolean;
+  private readonly acpSessions;
+  /** Resolve the turn's effective config. Throws before any session work. */
+  protected abstract resolveTurn(input: AgentExecutionInput): TTurn;
+  /**
+   * How to start the agent process. Runs only when no live process matches.
+   * May be async for a provider that must hand files it wrote to the agent user.
+   */
+  protected abstract processSpec(turn: TTurn, context: {
+    sessionId: string;
+    workspaceRoot: string;
+  }): AcpProcessSpec | Promise<AcpProcessSpec>;
+  /** The error a failed spawn surfaces; `missingBinary` when the command was not found. */
+  protected abstract spawnFailureMessage(failure: {
+    message: string;
+    missingBinary: boolean;
+  }, turn: TTurn): string;
+  /** The `session/prompt` blocks for a turn. */
+  protected abstract promptBlocks(input: AgentExecutionInput, prepared: {
+    promptText: string;
+    persistedParts: MessagePart[];
+    attachments: PreparedAttachment[];
+  }, turn: TTurn): AcpContentBlock[];
+  /** Spawn the bridge. Tests override it to swap the child process. */
+  protected spawnBridge(request: AcpBridgeSpawn): RpcBridge;
+  /** Refuse an agent version beyond the provider's own floor. */
+  protected checkAgentProtocolVersion(_advertised: number, _turn: TTurn): void;
+  /**
+   * Configure a native session the process just opened or loaded, before its
+   * first prompt (e.g. `session/set_model`). A failure fails the acquire.
+   */
+  protected onSessionOpened(_bridge: RpcBridge, _acpSessionId: string, _turn: TTurn, _options: {
+    timeoutMs: number;
+  }): Promise<void>;
+  /** Install reverse-call handlers on a new bridge, before `initialize`. */
+  protected onBridgeSpawned(_bridge: RpcBridge, _sessionId: string, _turn: TTurn): void;
+  /** Start per-turn state; the returned function ends it on every exit. */
+  protected beginTurn(_sessionId: string, _input: AgentExecutionInput, _onEvent: ((event: StreamEvent) => void) | undefined): () => void;
+  /** Inspect a failed tool's output; returned events precede its part update. */
+  protected onToolFailed(_sessionId: string, _failureText: string | undefined): StreamEvent[];
+  /**
+   * A failure the provider recorded for this session during the turn,
+   * cleared on read. It outranks the error the turn surfaced as.
+   */
+  protected takeTurnFailure(_sessionId: string): Error | undefined;
+  /** Release provider state tied to a session's process. */
+  protected onSessionEvicted(_sessionId: string): void;
+  /** Extra fields for the turn-failure log line. */
+  protected turnLogContext(_turn: TTurn): Record<string, unknown>;
+  /**
+   * One turn through the base turn pipeline: session open with transcript
+   * replay and cached-turn replay, then input and result recording around the
+   * bridge's `session/prompt`. The agent owns its profile, so the base's
+   * profile materialization does not run.
+   */
+  execute(input: AgentExecutionInput, services: SdkHostServices, onEvent?: (event: StreamEvent) => void): Promise<AgentExecutionResult>;
+  /** Report a failed turn, retire its process, and throw its error. */
+  private failAcpTurn;
+  private acquireAcpSession;
+  private checkProtocolVersion;
+  /**
+   * Open the native ACP session. A recorded session is loaded when the agent
+   * can; an agent that refuses the load starts a new native session, and the
+   * Tangle transcript stays the record of the earlier turns.
+   */
+  private openNativeSession;
+  /**
+   * One `session/prompt` turn. Abort sends `session/cancel` before closing so
+   * the agent can settle the turn; the bridge's own signal handling would
+   * close first and lose the notify.
+   */
+  private promptAcpSession;
+  private scheduleIdleReap;
+  private cancelIdleReap;
+  /** Close a session's agent process and drop it. Idempotent. */
+  protected evictAcpSession(sessionId: string, reason: string): void;
+  /** Evict every cached session whose process key matches. */
+  protected evictAcpSessionsWhere(matches: (processKey: string) => boolean, reason: string): void;
+  /** Translate one `session/update` notification into stream events. */
+  private mapAcpUpdate;
+  private mapToolStatus;
+  private formatBridgeError;
+  /**
+   * The error a failed process start surfaces. An agent that exits before its
+   * session opens reports why only on stderr, and an agent's JSON-RPC error
+   * carries its cause in `data`; a bare "process-exit" or "Internal error"
+   * hides both from the caller.
+   */
+  private sessionSetupError;
+  healthCheck(): Promise<boolean>;
+  shutdown(): Promise<void>;
+  addMcp(_name: string, _config: McpConfig): Promise<void>;
+  getMcpStatus(): Promise<McpStatusResponse>;
+  protected buildExecArgs(): never;
+  protected buildExecEnv(_config: TConfig): Record<string, string | undefined>;
+  protected createEventParser(): never;
+  protected buildMcpAddArgs(_name: string, _config: McpConfig | LocalMcpConfig): string[];
+}
+//#endregion
+//#region src/errors.d.ts
+/**
+ * A session's persisted transcript exists but could not be read for replay
+ * into the fresh provider session this turn starts. The turn fails instead
+ * of serving an empty conversation under the same session id. The sidecar's
+ * client-visible whitelist matches on `code`; the wire contract is the
+ * duck-typed field, not class identity.
+ */
+declare class SessionRehydrationError extends Error {
+  readonly code = "session_rehydration_failed";
+  constructor(message: string, cause: unknown);
+}
+/**
+ * Marks a turn failure the adapter raised before it planned the launch:
+ * session preparation or profile materialization refused, so no native
+ * process received this turn and it left no native transcript to copy.
+ * Only the adapter marks, on the error object it caught; error text never
+ * does, so a provider message that reads the same is not marked.
+ */
+declare function rejectNotLaunched<E>(error: E): never;
+/** Whether this error is one the adapter raised before launching anything. */
+declare function wasNeverLaunched(error: Error): boolean;
+//#endregion
+//#region src/event-parsers.d.ts
+/**
+ * Parser for harnesses that print one JSON event per line (claude-code,
+ * codex, amp, factory-droids). Values that fail `accept` are logged and
+ * dropped; unparseable lines become a `PARSE_ERROR` warning. The first event
+ * `isReady` accepts reports the CLI's own start time as `cli_initialize`,
+ * measured from parser creation, which immediately precedes the spawn.
+ */
+declare function jsonEventParser<TEvent>(logger: CliProviderLogger, onEvent: ((event: StreamEvent) => void) | undefined, spec: {
+  /** Names the harness in the "Received non-<label> event" warning. */label: string;
+  accept(raw: unknown): raw is TEvent;
+  map(event: TEvent): StreamEvent[];
+  isReady?(event: TEvent): boolean;
+}): StreamParserConfig<TEvent>;
+/** What a plaintext harness's line mapper records about the response. */
+interface PlaintextResponse {
+  /** Appends one line of the assistant's reply. */
+  text(line: string): void;
+  /** Records an error line; a turn with errors and no reply fails with the last one. */
+  error(message: string): void;
+}
+/**
+ * Parser for harnesses that print their reply as plain stdout lines (hermes,
+ * nanoclaw, forge). Lines classify into provider events; the reply is
+ * emitted as one text part when stdout closes. A turn that printed errors
+ * but no reply ends `failed` with the last error instead of an empty
+ * `completed`.
+ */
+declare function plaintextResponseParser<TEvent>(state: ExecutionState, onEvent: ((event: StreamEvent) => void) | undefined, spec: {
+  classify(line: string): TEvent | null;
+  map(event: TEvent, response: PlaintextResponse): StreamEvent[]; /** Failure detail when errors were seen but none carried a message. */
+  emptyFailureDetail: string;
+}): StreamParserConfig<TEvent>;
+//#endregion
+//#region src/execution-request-headers.d.ts
+/** Router column that joins a model request to the turn trace that caused it. */
+declare const EXECUTION_TRACE_HEADER = "X-Tangle-Trace-ID";
+declare const MANAGED_QUOTE_VERSION_HEADER = "X-Tangle-Managed-Quote-Version";
+/**
+ * Capture diagnostic identity without forwarding caller-supplied transport headers.
+ * `traceId` is the turn's trace id; a value no header can carry is omitted,
+ * because a trace is diagnostic and must never refuse the run.
+ */
+declare function executionCorrelationHeaders(binding: InteractionExecutionBinding | undefined, traceId?: string, quoteVersion?: string): Readonly<Record<string, string>> | undefined;
+//#endregion
+//#region src/file-parts.d.ts
+/** Infers a MIME type from a filename's extension. Unknown/no extension → undefined. */
+declare function inferMediaType(filename: string): string | undefined;
+/**
+ * Builds the canonical URL for a file part. A data URI passes through
+ * verbatim; a path is returned unchanged if it already carries a recognized
+ * scheme, else converted to a percent-encoded `file://` URL.
+ *
+ * Callers must pass an already-resolved absolute path — `trackFilePart`
+ * resolves relative paths (or drops the observation when it can't) before
+ * ever reaching here, so a relative path arriving at this layer means a
+ * caller bypassed that resolution. We throw rather than mint a malformed
+ * `file://` URL (e.g. `file://./chart.png`, whose authority is `.`).
+ */
+declare function buildFileUrl(input: {
+  path?: string;
+  dataUri?: string;
+}): string;
+/** Deterministic, stable part id for a file announced within one message. */
+declare function deterministicFilePartId(messageId: string, key: string): string;
+/**
+ * Stateless derivation of the canonical file-part fields for one observed
+ * path: resolve-once (normalize, then anchor a relative path to
+ * `workspaceRoot`), and from that single resolved path derive the dedupe
+ * `key`, the deterministic `id`, the `filename`, the inferred `mediaType`,
+ * and the percent-encoded `file://` `url` — so every consumer that surfaces
+ * the same file agrees on all five.
+ *
+ * Returns `null` for a relative path with no `workspaceRoot` to anchor it:
+ * detection is opportunistic and a fabricated location is worse than a
+ * missing part (see `trackFilePart` for the full rationale).
+ *
+ * This is the ONE derivation chain. `trackFilePart` (exec path, with
+ * ExecutionState memoization) and stateless mappers that own no
+ * ExecutionState (codex's app-server item mapper) both call it — never
+ * re-implement the chain, or the two paths drift.
+ */
+declare function deriveFilePart(input: {
+  path: string;
+  messageId: string;
+  workspaceRoot?: string;
+}): {
+  id: string;
+  key: string;
+  filename: string;
+  mediaType?: string;
+  url: string;
+} | null;
+/**
+ * Tracks a file an adapter observed being created/modified (e.g. from a
+ * write-tool call) and returns the canonical `FilePart` fields to stream,
+ * deduping by resolved-absolute-path or data-URI content so repeated writes
+ * to the same file update one part instead of appending duplicates.
+ *
+ * The path is normalized and resolved to an absolute form ONCE, and that same
+ * resolved value drives both the dedupe key and the `file://` url — so two
+ * observations of the same file that differ only in spelling (`./chart.png`
+ * vs `/workspace/chart.png`, or `/workspace/sub/../chart.png` vs
+ * `/workspace/chart.png`) unify on one part with one stable url, satisfying
+ * the stream invariant that a given part id keeps a stable url.
+ *
+ * A relative path can only be resolved against `state.workspaceRoot` (set by
+ * the adapter from the CLI's cwd). Detection here is opportunistic — a
+ * tool-call observation, not a guarantee of an absolute path — so when no
+ * workspaceRoot is available to anchor a relative path, we drop the
+ * observation (`null`) rather than fabricate an anchor (e.g. resolving
+ * against "/"): a wrong url is worse than a missing part, and a caller that
+ * genuinely lost the file would get a wrong, permanent url once it's on the
+ * stream.
+ *
+ * Detection is opportunistic for other reasons too: a delete, or an
+ * observation carrying neither a path nor a data URI, also yields no part
+ * (`null`) rather than an error — callers are not required to have a file
+ * signal on every tool result.
+ */
+declare function trackFilePart(state: ExecutionState, args: {
+  path?: string;
+  dataUri?: string;
+  filename?: string;
+  mediaType?: string;
+  changeKind?: "add" | "update" | "delete";
+}): {
+  id: string;
+  filename?: string;
+  mediaType?: string;
+  url: string;
+} | null;
+//#endregion
+//#region src/interaction-mcp-server.d.ts
+/**
+ * Compatibility adapter for callers that used the old optional `onStop` field.
+ * Agent Core owns the MCP server, retry-safe transport, and teardown lifecycle.
+ */
+type InteractionMcpServerConfig = Omit<InteractionMcpServerConfig$1, "onStop"> & {
+  onStop?: InteractionMcpServerConfig$1["onStop"];
+};
+declare class InteractionMcpServer extends InteractionMcpServer$1 {
+  constructor(config: InteractionMcpServerConfig);
+}
+//#endregion
+//#region src/interaction-support.d.ts
+/**
+ * Per-execution lifecycle wrapper for an MCP-capable harness. Permission and
+ * question tools use the live {@link InteractionBroker}; plan tools commit
+ * through {@link TerminalPlanSupport} and end the provider turn.
+ *
+ * Mirrors the claude-code permission-server pattern, but for the GENERIC
+ * `request_permission` / `ask_user` / `request_plan` tools the agent calls
+ * itself — there is no harness-specific reply contract, so any MCP-capable CLI
+ * (factory-droids, …) composes this with ~10 lines: declare the capability
+ * kinds, start/stop around the spawn, inject the server via the CLI's MCP
+ * mechanism, and forward `respondToInteraction` here.
+ *
+ * Unlike claude-code's `--permission-prompt-tool`, these generic tools fire
+ * only when the model chooses to call them. Permission is therefore advisory,
+ * while plan-capable adapters separately prove the terminal turn boundary.
+ */
+declare class McpInteractionSupport {
+  /** MCP server name; tool names become `mcp__<name>__<tool>`. */
+  private readonly serverName;
+  /**
+   * The {@link InteractionKind} values this harness wires (e.g.
+   * `[InteractionKind.Question, InteractionKind.Plan]`). Passed as the literal
+   * `InteractionKind.*` values so the coverage/live-e2e CI gates that grep
+   * `adapter.ts` see the declaration.
+   */
+  private readonly kinds;
+  /** The shared emit → block → respond → fail-closed round-trip. */
+  readonly broker: InteractionBroker$1;
+  private activeServer?;
+  private terminalPlan?;
+  constructor(/** MCP server name; tool names become `mcp__<name>__<tool>`. */
+
+  serverName: string,
+  /**
+   * The {@link InteractionKind} values this harness wires (e.g.
+   * `[InteractionKind.Question, InteractionKind.Plan]`). Passed as the literal
+   * `InteractionKind.*` values so the coverage/live-e2e CI gates that grep
+   * `adapter.ts` see the declaration.
+   */
+
+  kinds: readonly string[]);
+  /** The interaction kinds to advertise from `getCapabilities().interactions`. */
+  capabilityKinds(): string[];
+  /** The active per-execution server (its `url`/`token`), once started. */
+  get server(): InteractionMcpServer$1 | undefined;
+  /**
+   * Start a per-execution server bound to 127.0.0.1 with an ephemeral bearer
+   * token, registering only the enabled tools. `emit` is the live event sink;
+   * broker-backed tools block on an answer, while plans emit only after their
+   * terminal confirmation. Returns the server for CLI injection.
+   */
+  start(sessionId: string, binding: InteractionExecutionBinding, emit?: (event: StreamEvent) => void, plan?: {
+    planHost: SdkPlanHost;
+    providerState: () => PlanProviderState;
+    onCommitted?: (submitted: DurablePlan) => void | Promise<void>;
+  }): Promise<InteractionMcpServer$1>;
+  confirmSubmittedPlan(): Promise<DurablePlan>;
+  withdrawSubmittedPlan(reason: string): Promise<void>;
+  /** Close the request boundary before inspecting or withdrawing its plan. */
+  drainSubmittedPlan(sessionId: string): Promise<void>;
+  /**
+   * Fail-closed every pending interaction for the session, then stop the server.
+   * `failSession` runs FIRST so any request still blocked in the server resolves
+   * (deny) before close, and the whole thing swallows errors — it runs in adapter
+   * `finally` blocks and must never mask the turn's real error.
+   */
+  stop(sessionId: string): Promise<void>;
+  /**
+   * Route an inbound live `/interactions` response for permission or question.
+   * Plans are durable records and never enter this response channel.
+   */
+  respond(response: InteractionResponse): boolean;
+}
+//#endregion
+//#region src/mcp-commands.d.ts
+/** A local MCP server's argv: the `command` array, or `command` then `args`. */
+declare function localMcpArgv(config: McpConfig): string[];
+/**
+ * A local MCP server's environment, from `environment` (agent-backend-types)
+ * or `env` (agent-interface): reading one drops the other family's variables.
+ */
+declare function localMcpEnv(config: McpConfig): Record<string, string> | undefined;
+declare const isLocalMcpConfig: (c: McpConfig) => c is LocalMcpConfig;
+//#endregion
+//#region src/metering.d.ts
+type CliTokenUsage = NonNullable<ExecutionState["tokenUsage"]>;
+declare function readCliTokenUsage(raw: unknown): CliTokenUsage | undefined;
+declare function recordCliTokenUsage(state: ExecutionState, ...sources: unknown[]): boolean;
+/**
+ * Adds one usage report to the running total instead of replacing it.
+ *
+ * For a CLI that reports usage PER TURN (pi) rather than once per run,
+ * `recordCliTokenUsage` would leave the execution billed as its final turn
+ * alone. Use this wherever a single execution can produce more than one usage
+ * report; use `recordCliTokenUsage` when the CLI emits one cumulative total.
+ *
+ * Returns true when a usage report was found in `sources` and folded in.
+ */
+declare function accumulateCliTokenUsage(state: ExecutionState, ...sources: unknown[]): boolean;
+declare function parseCliUsageLine(line: string): Record<string, unknown> | undefined;
+//#endregion
+//#region src/reasoning-effort.d.ts
+/** The argv carrying `nativeReasoningControl` for a profile effort, or none. */
+declare function nativeEffortArgs(harness: HarnessType, effort: ReasoningEffort | undefined): string[];
+/**
+ * Kimi stays local until #14839: the sandbox ships kimi-cli 1.49.0 as
+ * `kimi-code` (binary `--thinking`/`--no-thinking`) while other paths run
+ * kimi-code 2.x. A model whose name has "thinking" or "reason" always thinks
+ * (kimi-cli `derive_model_capabilities`), so `off` throws there.
+ */
+declare function kimiThinkingArgs(level: ReasoningEffort | undefined, modelId?: string | null): string[];
+//#endregion
+//#region src/reasoning-parts.d.ts
+/**
+ * Assigns a stable part id and an append-only delta to a reasoning block
+ * emission, absorbing provider replay/growth patterns:
+ *
+ * - text exactly matches an already-tracked block → `null` (duplicate
+ *   delivery, e.g. a final assistant message replaying streamed content —
+ *   emit nothing). Byte-identical distinct blocks therefore dedupe to one
+ *   part; safer than duplicate-part spam.
+ * - text extends the most recent block → same part id, delta = the suffix
+ *   (cumulative re-emission of a growing block).
+ * - otherwise → a new block: fresh part id, delta = the full text, so
+ *   consumers can be pure appenders (prev text for a fresh id is empty).
+ */
+declare function trackReasoningBlock(state: ExecutionState, blockText: string): {
+  partId: string;
+  text: string;
+  delta: string;
+  isNewBlock: boolean;
+} | null;
+//#endregion
+//#region src/repeated-tool-failure.d.ts
+/**
+ * Guard against a turn that keeps sending a tool call the tool keeps
+ * rejecting.
+ *
+ * A CLI hands a rejected call back to the model and asks it to try again. It
+ * puts no bound on how often it does that. A model that cannot form a valid
+ * input therefore bills one round trip per attempt until an unrelated limit
+ * runs out, and the user is told about that limit rather than about the call.
+ * Staging measured 76 such attempts in 24.5 minutes, ending on a spent key
+ * budget.
+ *
+ * The bound has to sit here, not in the CLI. OpenCode drives the turn with
+ * `while (true)` in `session/prompt.ts`. Its per-agent `steps` bound defaults
+ * to `Infinity`, and reaching that bound only appends a message that asks the
+ * model to stop. Every tool stays enabled.
+ *
+ * The guard counts identical rejections in a row and nothing else. Any tool
+ * call that produces a result clears the count. A retry after a transient
+ * error is untouched, because it either succeeds or its error text moves. Only
+ * a model that cannot change its input reaches the limit.
+ */
+/** What a tripped guard reports to the caller. */
+interface RepeatedToolFailure {
+  /** The tool the model meant to call. */
+  tool: string;
+  /** Why the call was rejected, in the tool's own words. */
+  detail: string;
+  /** How many times in a row this exact rejection came back. */
+  count: number;
+}
+interface RepeatedToolFailureGuardOptions {
+  /** Identical failures in a row that trip the guard. At least 1. */
+  limit: number;
+  /**
+   * Tool names a provider substitutes for a model call it could not parse
+   * into any real tool.
+   *
+   * These do not present as failures. OpenCode rewrites an unparseable call to
+   * a tool named `invalid` that carries the parse error as its OUTPUT and
+   * completes. A guard that reads only `status` scores a run of them as
+   * progress and clears its count on every one.
+   */
+  repairToolNames?: ReadonlySet<string>;
+}
+interface RepeatedToolFailureGuard {
+  /**
+   * Feed one tool part. Returns the trip on the call that reaches the limit,
+   * and `undefined` every other time. A tripped guard stays tripped and
+   * reports once, so a caller can kill the turn without racing the events
+   * still in flight behind it.
+   */
+  observe(part: Pick<ToolPart, "id" | "tool" | "state">): RepeatedToolFailure | undefined;
+}
+declare function createRepeatedToolFailureGuard(options: RepeatedToolFailureGuardOptions): RepeatedToolFailureGuard;
+//#endregion
+//#region src/stream-parts.d.ts
+/**
+ * The text, reasoning and tool part emissions every stream-json harness
+ * shares. A provider's event mapper decodes its own wire shape, then calls
+ * these so part ids, buffers, tool timing and processing phases stay one
+ * implementation across claude-code, codex, kimi, amp and factory-droids.
+ */
+/**
+ * Records the CLI's native session id on the turn and announces it: the
+ * generic `session.updated` plus the provider-attributed observation the
+ * turn observer keys evidence on.
+ */
+declare function sessionObservedEvents(state: ExecutionState, provider: string, sessionId: string): StreamEvent[];
+/** Correlation fields every emitted part carries. */
+declare function streamPartBase(state: ExecutionState, partId?: string): {
+  id: string;
+  sessionID: string;
+  messageID: string;
+};
+/**
+ * Appends a text delta to the turn's single text part. The first text of a
+ * turn also signals the `generating` phase.
+ */
+declare function textDeltaEvents(state: ExecutionState, delta: string): StreamEvent[];
+/** The whole reply as one text part, for harnesses that do not stream. */
+declare function finalTextEvent(state: ExecutionState, text: string): StreamEvent;
+/**
+ * Applies a cumulative text frame (the whole assistant text so far). Only the
+ * suffix past the buffer is emitted; a frame that does not extend the buffer
+ * replaces it and is emitted whole.
+ */
+declare function textSnapshotEvents(state: ExecutionState, text: string): StreamEvent[];
+/**
+ * Records a thinking block under a stable part id (see trackReasoningBlock).
+ * With `signalPhase`, the turn's first block also signals `thinking`.
+ */
+declare function reasoningEvents(state: ExecutionState, thinking: string, options: {
+  signalPhase: boolean;
+}): StreamEvent[];
+/** Registers a running tool call and emits its running part. */
+declare function toolStartEvents(state: ExecutionState, call: {
+  id: string;
+  name: string;
+  input: unknown;
+}): StreamEvent[];
+/**
+ * Completes a tracked tool call. A successful result emits `afterSuccess`
+ * (file parts the provider detected) and then the `tool-result` phase. A
+ * result for an untracked call is a warning.
+ */
+declare function toolResultEvents(state: ExecutionState, result: {
+  id: string;
+  content: unknown;
+  isError: boolean;
+  metadata?: Record<string, unknown>;
+  afterSuccess?: (toolCall: ToolCallState) => StreamEvent[];
+}): StreamEvent[];
+//#endregion
+//#region src/terminal-plan-support.d.ts
+type TerminalPlanSupportOptions = {
+  planHost: SdkPlanHost;
+  providerState: () => PlanProviderState;
+  emit?: (event: StreamEvent) => void;
+  onCommitted?: (plan: DurablePlan) => void | Promise<void>;
+};
+/** One-shot durable plan submission for a single provider turn. */
+declare class TerminalPlanSupport {
+  private readonly options;
+  private committed?;
+  private submittedBody?;
+  private inFlight?;
+  private confirmInFlight?;
+  private confirmed;
+  constructor(options: TerminalPlanSupportOptions);
+  get plan(): DurablePlan | undefined;
+  /** Wait for a submission already accepted by this turn before failure cleanup. */
+  settleSubmission(): Promise<void>;
+  submit(body: string, sourceToolCallId: string): Promise<DurablePlan>;
+  confirm(): Promise<DurablePlan>;
+  withdraw(reason: string): Promise<void>;
+}
+//#endregion
+//#region src/writable-home.d.ts
+/** HOME and the XDG base directories a CLI resolves under it. */
+declare function homeXdgEnv(home: string): {
+  HOME: string;
+  XDG_CONFIG_HOME: string;
+  XDG_CACHE_HOME: string;
+  XDG_DATA_HOME: string;
+  XDG_STATE_HOME: string;
+};
+//#endregion
+export { ACP_MIN_PROTOCOL_VERSION, ACP_PROTOCOL_VERSION, type AcpBridgeConfig, type AcpBridgeSpawn, type AcpContentBlock, type AcpInitializeParams, type AcpInitializeResult, type AcpNewSessionResult, type AcpProcessSpec, type AcpPromptResult, AcpProviderAdapterBase, type AcpSessionUpdateParams, type AcpTurn, type AskUserBridge, type CliExecArgs, type CliExecutionInput, CliProviderAdapterBase, type CliProviderConfig, type CliProviderLogger, type CliProviderOptions, type CliTurnProcess, type CliTurnSpawn, DEFAULT_INTERACTION_MCP_SERVER_NAME, EXECUTION_TRACE_HEADER, type EphemeralContextInput, type ExecutionState, type HarnessId, InteractionBroker, InteractionHttpBridge, InteractionMcpServer, type InteractionMcpServerConfig, type InteractionToggleConfig, type InteractionToggleKind, InvalidAttachmentError, MANAGED_QUOTE_VERSION_HEADER, MAX_INLINE_IMAGE_BYTES, MAX_TOTAL_INLINE_IMAGE_BYTES, McpInteractionSupport, PERMISSION_DECISION_TIMEOUT_MS, PROMPT_SECTION_SEPARATOR, type PerTurnInteractionInput, type PermissionPromptBridge, type PlaintextResponse, type PreparedAttachment, type PreparedCliLaunch, type RepeatedToolFailure, type RepeatedToolFailureGuard, type RepeatedToolFailureGuardOptions, type RequestPermissionBridge, type RequestPlanBridge, SessionRehydrationError, TerminalPlanSupport, type TerminalPlanSupportOptions, type ToolCallState, type WorkspacePlanApplication, accumulateCliTokenUsage, acpContentText, brokerInteractionTools, buildFileUrl, createExecutionState, createRepeatedToolFailureGuard, deriveFilePart, deterministicFilePartId, enabledInteractionKinds, executionCorrelationHeaders, finalTextEvent, homeXdgEnv, inferMediaType, interactionMcpToolName, interactionToggleEnabled, isLocalMcpConfig, jsonEventParser, kimiThinkingArgs, localMcpArgv, localMcpEnv, mapAcpStopReason, nativeEffortArgs, parseCliUsageLine, partitionImageAttachments, plaintextResponseParser, preparePromptInputParts, prependPromptSection, readCliTokenUsage, readEphemeralContext, reasoningEvents, recordCliTokenUsage, rejectNotLaunched, runtimeSecretsOverlay, sessionObservedEvents, spawnAcpBridge, streamPartBase, textDeltaEvents, textSnapshotEvents, toolResultEvents, toolStartEvents, trackFilePart, trackReasoningBlock, turnInteractionEnabled, wasNeverLaunched, withEphemeralContext, withTurnInteractions };
+//# sourceMappingURL=index.d.mts.map