Types

export type AccountInfo = {
  id: string;
  provider: string;
  label: string;
  email?: string;
  plan?: string;
  signedIn: boolean;
  isDefault: boolean;
  loginBroken?: boolean;
  accentColor?: string;
  createdAt?: string;
  usage?: AccountUsage;
};

export type AccountUsage = {
  state: "ok" | "stale" | "expired" | "signed_out" | "no_reading" | "error";
  readAt: string | null;
  note: string | null;
  windows: Array<{
    type: string;
    label: string;
    percentLeft: number;
    resetsAt: string | null;
    unlimited?: true;
    countLeft?: number;
    countTotal?: number;
  }>;
};

export interface AdeChatClient {
  accounts: AccountManagement["accounts"];
  credentials: AccountManagement["credentials"];
  presets: AccountManagement["presets"];
  providers: {
    /**
     * Per-provider install, auth and availability.
     *
     * Served from the runtime's probe cache when the runtime supports it, and
     * derived from the model catalog when it does not. Read `source` on each
     * record before presenting any of it as a fact about the machine.
     */
    status(): Promise<Record<string, ProviderStatus>>;
    /**
     * The same map, with the runtime's probe cache bypassed.
     *
     * This is the "I just installed it" button. It spawns `--version` for every
     * provider, so it is the slow path — `status()` and the `onChange` poll
     * never bypass the cache.
     */
    refresh(): Promise<Record<string, ProviderStatus>>;
    onChange(cb: (status: Record<string, ProviderStatus>) => void): Unsubscribe;
    /** Runtime-derived controls for a provider, or `unsupported` when absent. */
    capabilities(provider: string): Promise<ProviderCapabilities>;
  };
  models: {
    list(): Promise<ModelCatalogEntry[]>;
    /**
     * Called with the whole catalog when it changes: a provider signs in or
     * out, or the runtime's catalog gains or drops a model. Driven by the same
     * poll as `providers.onChange`, and called only when a model's id,
     * `isAvailable`, `connected` or `isDefault` changed. Not called with the
     * current list on subscribe; call `list()` for that. SDK >= 0.4.
     */
    onChange(cb: (models: ModelCatalogEntry[]) => void): Unsubscribe;
    /**
     * The model a new thread should use, or null when none qualifies. See
     * `pickDefaultModel` for the rule; this reads a fresh catalog first.
     * SDK >= 0.4.
     */
    defaultModel(opts?: DefaultModelOptions): Promise<ModelCatalogEntry | null>;
  };
  threads: {
    /** Open a thread, creating it when the key is new to this home. */
    open(key: string, opts: ThreadOpenOptions): Promise<AdeThread>;
    /**
     * Reopen a key this home already stores. The provider and model come from
     * the stored record, so an app that reopens `"support"` after a restart
     * does not have to remember how it was created.
     */
    open(key: string, opts?: ThreadResumeOptions): Promise<AdeThread>;
    /**
     * Every chat in this home, archived ones included, newest activity first
     * is NOT guaranteed — sort on `updatedAt` yourself.
     */
    list(): Promise<ThreadSummary[]>;
    /**
     * One thread's summary, by key, or null when the runtime has no session for
     * it: a key this home never opened, a deleted key, or a key whose session
     * the runtime lost (the next `open` recreates it). The same row `list()`
     * would return, without reading every chat. SDK >= 0.4.
     */
    get(key: string): Promise<ThreadSummary | null>;
    /**
     * Delete a thread: its runtime session, its transcript, and its key.
     *
     * A running turn is interrupted FIRST, so subscribers receive the turn's
     * `done` before the session goes away rather than a stream that simply
     * stops. Then the runtime deletes the session, the key is removed from the
     * thread store, and a live `AdeThread` for the key is released — it throws
     * `disposed`-style errors from the runtime afterwards, so drop it.
     *
     * A key whose session the runtime already lost is still removed. A key the
     * store does not know and no live thread holds throws `thread_not_found`.
     * Throws `invalid_option` on a runtime without the `delete` action.
     */
    delete(key: string): Promise<void>;
    /**
     * Archive a thread. The key and transcript are kept; `list()` reports it
     * with `archived: true`, and `unarchive` brings it back.
     *
     * Like `delete`, a running turn is interrupted first so it ends with a
     * `done` event rather than silently. Throws `thread_not_found` for a key
     * the store does not know, and `invalid_option` on a runtime without the
     * `archive` action.
     */
    archive(key: string): Promise<void>;
    /** Reverse `archive`. Same errors. */
    unarchive(key: string): Promise<void>;
  };
  doctor(): Promise<DoctorReport>;
  exportThread(key: string): Promise<string>;
  /** Run a temporary thread and delete it after the final answer is received. */
  run<T = unknown>(prompt: string, options: RunOptions): Promise<T | string>;
  /**
   * Listen for runtime lifecycle events: `"exit"`, `"transport"`, `"restart"`.
   * See {@link AdeClientEventMap} for the payloads. Returns the unsubscribe.
   *
   * Listeners survive an `autoRestart`, because the client object does.
   */
  on<E extends AdeClientEvent>(event: E, cb: (payload: AdeClientEventMap[E]) => void): Unsubscribe;
  /**
   * Stop the runtime and release this client. Idempotent.
   *
   * Ends any turn still in flight, and — like every teardown on this surface —
   * without an `error` or `done` event first: the child process goes away, so
   * subscribers simply stop receiving. Deliberately NOT guarded the way
   * `setModel` is, because dispose is the teardown path and a shutdown that can
   * refuse is worse than a truncated reply. If a caller needs the reply, it
   * must await the turn before disposing; the transcript is durable either way
   * and `exportThread` still returns everything that was persisted.
   */
  dispose(): Promise<void>;
}

export type AdeClientEvent = (typeof ADE_CLIENT_EVENTS)[number];

export type AdeClientEventMap = {
  /**
   * The runtime process this client spawned exited without `dispose()`.
   * `error` is the tail of its stderr, when it wrote any. Not emitted in attach
   * mode, where the client owns no process — watch `transport` there.
   */
  exit: { code: number | null; signal: string | null; error: string | null };
  /**
   * The socket to the runtime closed unexpectedly (`"closed"`), or an
   * `autoRestart` brought it back (`"reconnected"`).
   */
  transport: { state: "closed" | "reconnected"; error: string | null };
  /**
   * One `autoRestart` attempt finished. `attempt` counts from 1 per outage.
   * `final` is true when no further attempt follows for this outage: the
   * attempt succeeded (`ok: true`), or it failed and was the last one
   * `maxAttempts` allows (the client gave up; the runtime stays down until the
   * host creates a new client). SDK >= 0.4.
   */
  restart: { attempt: number; ok: boolean; error: string | null; final: boolean };
  /**
   * A thread left, or came back to, the host's active list through this
   * client: `threads.delete` (`"deleted"`), `threads.archive` (`"archived"`)
   * or `threads.unarchive` (`"unarchived"`). Emitted after the action
   * succeeds, whoever called it: host code in the main process, or a renderer
   * over the Electron bridge. A change made by another client of the same
   * runtime (ADE desktop) is not reported. SDK >= 0.4.
   */
  threadLifecycle: { key: string; change: "deleted" | "archived" | "unarchived" };
  /** A provider turn stopped because its current account reached a usage limit. */
  usageLimit: import("./types.js").UsageLimitEvent;
};

export type AdeErrorCode =
  | "binary_not_found"
  | "download_failed"
  | "checksum_mismatch"
  | "spawn_failed"
  | "connect_failed"
  | "handshake_failed"
  | "rpc_error"
  | "rpc_timeout"
  | "transport_closed"
  | "protocol_error"
  | "thread_not_found"
  | "invalid_option"
  /**
   * No runtime could be resolved and `allowDownload: false` forbade fetching
   * one. A packaging mistake must fail here, loudly, rather than work on the
   * developer's machine through a silent download and fail on a locked-down
   * user's.
   */
  | "runtime_unavailable"
  /**
   * `approve()` named an item that is not pending. A stop, a teardown, or an
   * earlier call already settled it; the engine settles unknown items silently,
   * so the SDK checks first and says so rather than letting a no-op look like
   * a success.
   */
  | "approval_not_found"
  /**
   * A bridge refused the call before it reached the SDK — the host's
   * `authorize` hook said no. Used by `@ade-dev/sdk/electron`.
   */
  | "unauthorized"
  | "disposed"
  /**
   * The runtime's version is outside `SUPPORTED_RUNTIME_RANGE` and the host
   * asked `createAdeChat` to refuse it (`requireCompatibleRuntime: true`).
   * Without that option an unsupported runtime connects with a logged warning.
   */
  | "runtime_incompatible"
  /**
   * The call was refused only because a turn is running on the thread:
   * `setModel`, a reasoning `update`, `retry`, `editLast`, or a runtime action
   * that must wait for the turn to end. Nothing changed. Wait for the turn to
   * finish (or `interrupt()` it), then call again. `setModel` and `update`
   * also accept `{ force: true }`. Before SDK 0.4 these refusals used
   * `invalid_option`.
   */
  | "turn_in_flight"
  /**
   * The thread's provider, or the runtime, cannot do what was asked. Nothing
   * changed. `retry` and `editLast` throw it for a provider other than Claude
   * or Codex, and for a runtime older than the `rerunLastTurn` action.
   */
  | "unsupported"
  | "invalid_output"
  /**
   * A provider sign-in ended without signing in: it failed, was cancelled, or
   * expired. The handle's last status says which (`state`) and why (`message`).
   */
  | "sign_in_failed";

export type AdeProvider =
  | "claude"
  | "codex"
  | "cursor"
  | "droid"
  | "opencode"
  | "pi"
  | "muse"
  | "qwen"
  | "kimi"
  | "grok"
  | "copilot"
  | "devin"
  | "antigravity"
  | (string & {});

export interface AdeThread {
  /**
   * The runtime session id. Stable for the life of the thread, EXCEPT across a
   * recreate: if an `autoRestart` finds the runtime lost the session, the key
   * is rebuilt on a new session and this id changes. Key your own state on
   * `key`, not on this.
   */
  readonly id: string;
  readonly key: string;
  /**
   * The thread's title, or null. Updated by `update({ title })`; the runtime
   * may also retitle a thread after its first turn, which this reflects at the
   * next open or `update`.
   */
  readonly title: string | null;
  /**
   * What the thread's model resolved to, with the catalog display name.
   *
   * Kept current by `setModel`. Null only when the runtime reported no model.
   * Show `displayName` rather than the id when it is non-null: after a CLI
   * update retires a model the runtime resolves the id forward, and the raw id
   * a host stored is then the wrong label.
   */
  readonly model: ThreadModelSelection | null;
  /**
   * What the provider did with this thread's `mcpServers` / strict-mode request.
   *
   * Only Claude enforces strict mode outright. Every other provider is
   * best-effort with a named `residual`, so an embedder that promised its users
   * an isolated tool surface must read this rather than assume the request
   * landed whole. Populated on create AND on resume — a reopened thread rebuilds
   * the same tool surface it started with, and reports the same caveat.
   *
   * Null means one of two things, and they are NOT equivalent:
   *   - the thread asked for neither `mcpServers` nor strict mode; or
   *   - the runtime did not report one. Older runtimes omit the field
   *     entirely. The SDK logs a warning in that case rather than letting a
   *     missing report read as "nothing was requested" — if you asked for
   *     servers and got null here, treat the guarantee as unverified.
   */
  readonly mcpCapability: McpCapabilityReport | null;
  /**
   * What the provider did with this thread's `instructions`.
   *
   * Null when the thread asked for none, or when an older runtime reported
   * nothing — the same two-case ambiguity `mcpCapability` has, and for the same
   * reason: the SDK does not invent a verdict it did not receive.
   *
   * `level` is `"applied"` on Claude, Codex, OpenCode and Pi, which all take
   * instructions through a channel of their own; `"best-effort"` on Cursor and
   * Droid, where ADE merges the text into a prompt it already prefixes.
   */
  readonly instructionsCapability: InstructionsCapability | null;
  /**
   * What the provider did with this thread's `settingSources`.
   *
   * Only Claude has a real switch. Codex reports `"best-effort"` for `project`
   * and `all` because it always reads its own user-level file too, and every
   * other provider reports `"ignored"` — the value did not reach it.
   */
  readonly settingSourcesCapability: SettingSourcesCapability | null;
  /**
   * What the provider could enforce of this thread's permission policy.
   *
   * Null when the thread opened with a preset rather than a policy. Read
   * `level` before telling a user their rules are in force: only Claude gates
   * every tool call against the policy, Codex approximates it with containment
   * and approval settings, and the rest cannot express it at all.
   */
  readonly permissionCapability: PermissionCapability | null;
  /**
   * Queue a message for the agent.
   *
   * DISPATCH-RESOLUTION ASYMMETRY: this resolves when the turn has been
   * DISPATCHED, not when the reply is complete. Nothing in the returned promise
   * tells you a turn is still streaming, so code that runs after an `await
   * send(...)` must not assume the thread is idle. Before any destructive
   * operation — `setModel`, `dispose` — either await the completion event on
   * `on("status")` or check the thread's status; `setModel` enforces this for
   * you and throws rather than silently ending the turn.
   *
   * With an `mcpHeaders` callback and remote MCP servers, the headers are
   * resolved again first (see `refreshMcpHeaders`), so a token that expired
   * since the last turn is replaced before this one. A refresh that fails is
   * logged and the message is still sent, on the headers the session has.
   */
  send(text: string, opts?: SendOptions): Promise<void>;
  /**
   * Add input to the turn in flight, without waiting for it to end.
   *
   * Needs text, attachments, or both. Attachments follow the same rules as
   * `send`. Resolves once the runtime accepted the steer, not once the agent
   * read it.
   */
  steer(text: string, opts?: SteerOptions): Promise<void>;
  interrupt(): Promise<void>;
  /**
   * Rename the thread, or change its reasoning effort or fast mode.
   *
   * A title-only update is allowed at any time. `reasoningEffort` and
   * `fastMode` are refused while a turn is in flight (`AdeError` code
   * `turn_in_flight`, SDK >= 0.4) unless `{ force: true }`:
   * on Codex a settings change the provider rejects tears the provider down,
   * which ends the turn without `error` or `done` — the silent truncation the
   * client's destructive-while-streaming rule forbids. Await the turn or
   * `interrupt()` first.
   *
   * Resolves with the title and model as the runtime reports them afterwards.
   */
  update(patch: ThreadUpdate, opts?: ThreadUpdateOptions): Promise<ThreadUpdateResult>;
  /**
   * Run the last user turn again, as if the first attempt never happened.
   *
   * The runtime rolls the provider conversation back to just before the last
   * user message, removes that message and everything after it from the
   * thread's history, and sends the same message (text and attachments) again.
   * The history then holds the message once. Files the old turn changed are
   * NOT restored: the rollback covers the conversation, not the disk.
   *
   * The result does not say whether the old turn wrote files, because the
   * runtime cannot tell which of YOUR tools write. A host that lets the agent
   * write can find them itself: the removed events are the ones at or after
   * `retractedFromSequence` in your own copy of the history, so inspect their
   * tool calls and warn the user if any of them was a write.
   *
   * What a subscriber sees, in order: `session_meta_updated` with
   * `historyInvalidated: true` and the new `historyGeneration` (drop your copy
   * of the events at or after `retractedFromSequence`, or re-read `history()`),
   * then the new turn's `user_message`, `status: started`, and the rest of the
   * turn. A `history()` or `historyPage()` read after the call returns only the
   * new attempt.
   *
   * Claude and Codex only. Throws `turn_in_flight` while a turn runs or waits
   * on an approval (nothing changed; await it or `interrupt()` first),
   * `unsupported` for another provider or a runtime without the action, and
   * `rpc_error` when the thread has no user message yet.
   *
   * Resolves once the new turn is dispatched, not once it ends.
   */
  retry(): Promise<ThreadRerunResult>;
  /**
   * Replace the last user message with `text` and run it again.
   *
   * Everything `retry` says applies: same rollback, same event sequence, same
   * errors, and the history shows only the edited message. `text` may be empty
   * only when `opts.attachments` is non-empty. Attachments default to the
   * original message's.
   */
  editLast(text: string, opts?: EditLastOptions): Promise<ThreadRerunResult>;
  /**
   * Replace this thread's caller MCP servers wholesale.
   *
   * For a credential or URL that changed: a rotated bearer token, a port that
   * moved. The provider picks the new servers up on the next turn. Header
   * values are sent to the runtime and never persisted by the SDK — the thread
   * store keeps header names only.
   *
   * A remote server passed without `headers` gets them from the client's
   * `mcpHeaders` callback, when there is one.
   *
   * Mid-turn, the runtime validates the servers at once (a bad map still
   * rejects) and queues them for the end of the running turn — completed,
   * interrupted or failed — and the call resolves. A later call replaces a
   * queued map. Until the swap the summary reports `mcpServersPending: true`,
   * and `mcpCapability` keeps describing the servers the running turn has. A
   * runtime without `capabilities.personalChats.deferredMcpUpdates` refuses
   * mid-turn instead (`turn_in_flight`).
   *
   * Refused by the SDK on a runtime that does not advertise
   * `capabilities.personalChats.updateMcpServers` (`invalid_option`) — an older
   * runtime would ignore the field and leave the old credentials in place,
   * which is worse than failing. The same goes for `allowedTools` /
   * `disallowedTools` on a runtime without `mcpToolFilters`, and for a filter
   * the thread's provider cannot enforce (see `McpToolFilter`).
   *
   * A map identical to the one this client last sent for the thread — header
   * values included — is not sent again: the call resolves with the current
   * `mcpCapability` and the provider is left alone. So a renderer that reloads
   * and repeats the same `refresh` does not restart anything.
   *
   * Resolves with the thread's new `mcpCapability`.
   */
  updateMcpServers(servers: Record<string, McpServerConfig>): Promise<McpCapabilityReport | null>;
  /**
   * Resolve this thread's MCP header values again through the client's
   * `mcpHeaders` callback and push them when they changed.
   *
   * `send`, `retry` and `editLast` already do this before every turn; call it
   * yourself right after rotating a token, so the swap does not wait for the
   * next message. The servers are the thread's own (the last map it was
   * opened or updated with); only the header values of its remote servers
   * that carry headers are re-resolved, and a thread with none is a no-op. Values
   * identical to the last ones sent push nothing. Mid-turn the push is queued
   * for the end of the turn, as `updateMcpServers` is.
   *
   * Throws `invalid_option` without an `mcpHeaders` callback, on a runtime
   * without `updateMcpServers`, and when the callback supplies nothing for a
   * server that needs headers: pushing would replace that server's live
   * credentials with none. A callback that throws rejects this call with its
   * error. Resolves with the thread's `mcpCapability`.
   */
  refreshMcpHeaders(): Promise<McpCapabilityReport | null>;
  /**
   * Switch this thread's model, including across providers — the runtime tears
   * the old one down and replays the transcript into the new one.
   *
   * Refused while a turn is in flight (code `turn_in_flight`, SDK >= 0.4)
   * unless `{ force: true }`: the switch would
   * end that turn without emitting `error` or `done`, so a caller who did not
   * know a turn was running would see the response simply stop. Await the turn
   * or `interrupt()` first.
   *
   * Returns what the model actually resolved to — the runtime resolves aliases
   * and CLI-wrapped ids, so it can differ from what you passed — together with
   * the four capability reports on the new provider. The same reports are
   * emitted as a `capabilities_changed` envelope on the `status` channel.
   */
  setModel(modelId: string, opts?: SetModelOptions): Promise<SetModelResult>;
  /**
   * The durable transcript, newest `limit` events (all of them when omitted,
   * up to the runtime's own cap of about 20,000 events / 2 MB). For a long
   * thread prefer `historyPage`, which reads one bounded page at a time.
   */
  history(opts?: { limit?: number }): Promise<AgentChatEventEnvelope[]>;
  /** Token totals observed on this thread; cost is present only when reported by the provider. */
  usage(): ThreadUsage;
  /**
   * One page of the durable transcript, for "load older" on scroll.
   *
   * Without `beforeSequence` this is the newest page. Each page reports the
   * cursor for the one before it. Events are oldest-first within a page.
   *
   * On a runtime without the `getEventHistoryPage` action, only the newest page
   * is available: an older-page request returns an empty page with
   * `hasMore: false` and logs once.
   */
  historyPage(opts?: HistoryPageOptions): Promise<ThreadHistoryPage>;
  /**
   * Answer an approval this thread emitted.
   *
   * AN UNANSWERED APPROVAL BLOCKS THE TURN, with no timeout anywhere in the
   * runtime. This call and `interrupt()` are the only two ways out, and they
   * are not the same: this one answers the request and lets the turn continue,
   * while `interrupt()` aborts the turn without answering anything. A policy
   * with `approvalTimeoutMs` adds a third: the SDK declines the request itself
   * when the time runs out.
   *
   * Resolves once the runtime accepts the decision, NOT once the tool has run —
   * the same dispatch-resolution asymmetry `send()` has.
   *
   * Throws `approval_not_found` when the item is not pending: a stop, a
   * teardown, or an earlier call already settled it. The engine settles unknown
   * items silently, so without this check an answer to a dead card would look
   * like it worked.
   *
   * Use `respond()` for questions and plan approvals. This method accepts only
   * `"approval"` and `"permissions"` requests; an MCP elicitation that only
   * asks "may this tool run?" arrives as `"approval"` and is answerable here.
   *
   * `accept_always` settles this request and every later one the provider
   * considers the same, for the life of the session.
   */
  approve(itemId: string, decision: ApprovalDecision, responseText?: string): Promise<void>;
  /**
   * Every request this thread is currently blocked on.
   *
   * Call it after a reload to restore approval cards: the requests outlive the
   * client that saw the events. The `answerable` field identifies whether the
   * runtime supports a response for each request. Questions and plan approvals
   * use `respond()` when that action is available; tool approvals use
   * `approve()`.
   */
  pendingApprovals(): Promise<ApprovalRequest[]>;
  /**
   * Answer a question, structured question, or plan approval through the
   * runtime's `respondToInput` action. Question answers are keyed by question
   * id. Plan approval uses an explicit `decision` (`accept` or `decline`); the
   * SDK never infers it from option labels.
   */
  respond(requestId: string, response: ThreadRespondOptions): Promise<void>;
  /** Mutable queued sends belonging to this thread. */
  readonly queue: {
    list(): Promise<ThreadQueueItem[]>;
    cancel(id: string): Promise<void>;
    edit(id: string, text: string): Promise<void>;
    move(id: string, index: number): Promise<void>;
    dispatch(id: string): Promise<void>;
    cancelDispatched(id: string): Promise<void>;
    restore(): Promise<void>;
  };
  interrupt(options?: ThreadInterruptOptions): Promise<void>;
  stopTask(taskId: string): Promise<void>;
  slashCommands(): Promise<AgentChatSlashCommand[]>;
  recover(options?: { turnId?: string; action?: "wait" | "nudge" | "retry_same_runtime" | "restart_resume" }): Promise<AgentChatRecoverTurnResult>;
  resolveUnprocessed(args: { steerId: string; action: "run_next" | "dismiss" }): Promise<AgentChatResolveUnprocessedMessageResult>;
  readonly usageLimit: {
    resumeNow(): Promise<AgentChatUsageLimitResult>;
    continueOnAlternate(): Promise<AgentChatUsageLimitResult>;
  };
  switchAccount(instanceId: string): Promise<AgentChatSwitchAccountResult>;
  on(event: ThreadEventChannel, cb: (envelope: AgentChatEventEnvelope) => void): Unsubscribe;
}

export type AgentChatCodexCollaborationMode = "default" | "plan";

export type AgentChatEvent = {
  type: string;
  [key: string]: unknown;
};

export type AgentChatEventEnvelope = {
  sessionId: string;
  timestamp: string;
  event: AgentChatEvent;
  sequence?: number;
  /**
   * Mirrors `AgentChatEventEnvelope["provenance"]` in ADE's `shared/types/chat.ts`,
   * NARROWED on purpose: only the keys an SDK consumer can act on are named.
   *
   * ADE stamps more than this — orchestration routing (`targetKind`,
   * `sourceSessionId`, `attemptId`, `stepKey`, `laneId`, `runId`), fork shape
   * (`replayFork`), and other ADE-only metadata. These describe surfaces this
   * package does not have: a sidecar drives its own thread with the `agent`
   * role, so it is never the orchestrator reading routing keys or ADE metadata.
   * Naming them here would advertise surfaces that do not exist.
   *
   * The index signature is what makes that narrowing safe rather than lossy:
   * the runtime is downloaded and can be newer than the SDK, so every key ADE
   * stamps still arrives and still reads, typed `unknown`. Add a key to the
   * named set only when this package grows a use for it.
   */
  provenance?: {
    messageId?: string;
    providerMessageId?: string;
    threadId?: string | null;
    role?: "user" | "orchestrator" | "worker" | "agent" | null;
    [key: string]: unknown;
  };
};

export type AgentChatFileRef = {
  path: string;
  name?: string;
  mimeType?: string;
  bytes?: number;
  /**
   * How the provider receives the file.
   *
   * `"image"` sends the bytes as an image the model can see (Claude and Codex
   * both take image input). `"file"` sends a path hint the model can open with
   * its own tools. When absent, the SDK fills it in before sending with the
   * runtime's own rule, exported as `inferAttachmentType(path, mimeType)`: any
   * `image/*` `mimeType` is an image; otherwise the extension of `path`
   * decides (`.bmp .gif .heic .heif .ico .jpeg .jpg .png .svg .tif .tiff
   * .webp` are images), and everything else is `"file"`. Before 0.3 the field
   * did not exist and every image arrived as a path hint.
   */
  type?: "file" | "image";
  /**
   * Whether the runtime may read the file's bytes. Defaults to true.
   *
   * `false` is REFERENCE-ONLY: the runtime never opens the file, never copies
   * it to a staging directory, and hands the model the path alone — even for an
   * image. Use it for files that must not be downloaded as a side effect, such
   * as a macOS File Provider placeholder, where reading the bytes hydrates the
   * whole file from the cloud.
   *
   * An older runtime ignores the field and reads the bytes as before; the SDK
   * cannot detect that from here, so treat reference-only as a request until
   * your runtime is at least the SDK's supported minimum
   * (`SUPPORTED_RUNTIME_RANGE`).
   */
  hydrate?: boolean;
};

export type AgentChatHostConfigLevel = "applied" | "best-effort" | "ignored";

export type AgentChatInstructions = {
  mode: "append" | "replace";
  text: string;
};

export type AgentChatSessionStatus = "active" | "idle" | "ended";

export type AgentChatSessionSummary = {
  sessionId: string;
  laneId: string;
  provider: string;
  model: string;
  title?: string | null;
  reasoningEffort?: string | null;
  permissionMode?: AgentChatPermissionMode;
  /** Accepted Codex app-server collaboration mode, when a live runtime reports one. */
  codexEffectiveCollaborationMode?: AgentChatCodexCollaborationMode;
  /** True when a live Codex runtime confirms there is no accepted turn mode. */
  codexEffectiveCollaborationModeWasCleared?: boolean;
  status: AgentChatSessionStatus;
  startedAt: string;
  endedAt: string | null;
  archivedAt?: string | null;
  lastActivityAt: string;
  lastOutputPreview: string | null;
  summary: string | null;
  awaitingInput?: boolean;
  /**
   * The working directory the runtime actually bound the session to, echoed
   * back in its own spelling. Present only when one was requested.
   *
   * This is the canonical answer: the engine resolves the path before it
   * stores it, so a symlinked or differently-cased spelling of one directory
   * comes back as one string. A client that records the caller's spelling
   * instead reports a resume mismatch on a `cwd` that never changed.
   */
  requestedCwd?: string | null;
  /** Catalog model id the session is bound to, when the runtime reports one. */
  modelId?: string;
  /** Present only when the chat was created with an MCP request. */
  mcpCapability?: McpCapabilityReport;
  /**
   * True while MCP servers sent mid-turn wait for that turn to end.
   * `mcpCapability` still describes the servers the running turn has.
   */
  mcpServersPending?: boolean;
  /**
   * Present only when the chat was created with `instructions`. Absent means
   * nothing was requested — NOT that the request was dropped.
   */
  instructionsCapability?: {
    level: AgentChatHostConfigLevel;
    mode: "append" | "replace";
    mechanism: string;
    detail: string | null;
  } | null;
  /** Present only when the chat was created with `settingSources`. */
  settingSourcesCapability?: {
    level: AgentChatHostConfigLevel;
    value: AgentChatSettingSources;
    mechanism: string;
    detail: string | null;
  } | null;
  /** Present only when the chat was created with a permission policy. */
  permissionCapability?: {
    level: "enforced" | "best-effort" | "unsupported";
    mechanism: string;
    residual: string | null;
  } | null;
  [key: string]: unknown;
};

export type AgentChatSettingSources = "none" | "project" | "user" | "all";

export type ApiCredentialInfo = {
  provider: string;
  credentialId: string;
  label: string;
  envVar?: string;
  baseUrl?: string;
  protocol?: "openai-compatible" | "openai-responses" | "anthropic";
  models?: string[];
  source: "store" | "env" | "config";
  createdAt: string;
  updatedAt: string;
  maskedTail?: string;
};

export type ApprovalDecision = "accept" | "accept_always" | "reject";

export type ApprovalRequest = {
  /** The id to pass to `approve()`. */
  itemId: string;
  /** Groups retries of one logical action, when the provider reports one. */
  logicalItemId?: string;
  /** The shape of the thing being confirmed. */
  kind: "command" | "file_change" | "tool_call";
  /**
   * The finer-grained kind.
   *
   * `"approval"` and `"permissions"` are answerable with `approve()`. Use
   * `respond()` for `"question"` and `"structured_question"` requests, with
   * answers keyed by question id, and for `"plan_approval"` with an explicit
   * decision. A runtime may leave other request kinds read-only.
   */
  requestKind?: PendingInputKind;
  /** Human-readable and provider-supplied. Safe to render. */
  description: string;
  turnId?: string;
  /** Provider payload: the command string, the patch, the tool input. */
  detail?: unknown;
  /** Which provider raised it. */
  provider: AdeProvider;
  /** The original prompts for requests answered through `respond()`. */
  questions?: PendingInputRequest["questions"];
  /** False when the runtime cannot answer this request through the SDK. */
  answerable?: boolean;
};

export type AttachmentRootCheck = { ok: true; root: string } | { ok: false; reason: string };

export type AttachmentRootFilterResult = {
  /** Valid roots, canonicalized, de-duplicated, capped. Pass these to `threads.open`. */
  roots: string[];
  /** One entry per refused or over-the-limit input, with the reason it was refused. */
  dropped: Array<{ root: string; reason: string }>;
};

export type BundledRuntime = {
  /** Absolute path of the runtime binary inside the platform package. */
  binaryPath: string;
  /** Absolute path that `ADE_RUNTIME_ROOT` must name. */
  runtimeRoot: string;
  /** Absolute path that `ADE_RUNTIME_NODE_MODULES` must name. */
  nodeModulesPath: string;
  /** e.g. `@ade-dev/runtime-darwin-arm64`. */
  packageName: string;
  /** The ADE release version the package was cut from. */
  version: string;
};

export type CapabilitiesChangedEvent = {
  type: "capabilities_changed";
  synthetic: true;
} & ThreadCapabilities;

export type CreateAdeChatOptions = {
  /** Isolated per-app ADE state root. Created if missing. */
  home: string;
  /** Pin a specific `ade` build. Skips PATH discovery and the downloader. */
  binaryPath?: string;
  /**
   * Where the native modules the runtime dlopens live. Maps to
   * `ADE_RUNTIME_NODE_MODULES`. Required alongside `binaryPath` when the
   * modules are not beside the binary, which is the normal case for an app
   * bundle: the binary lands in `Contents/Resources/ade-runtime/bin` and the
   * modules in `Contents/Resources/ade-runtime/native/node_modules`.
   */
  runtimeNodeModules?: string;
  /** Maps to `ADE_RUNTIME_ROOT`. Defaults to the parent of `runtimeNodeModules`. */
  runtimeRoot?: string;
  /**
   * Never reach the network. Throws `runtime_unavailable` instead of
   * downloading. Defaults to true, which preserves 0.1.x behavior.
   *
   * A shipping app wants false: a packaging mistake then fails loudly in QA,
   * rather than working on the developer's machine through a silent download
   * and failing on a locked-down user's.
   */
  allowDownload?: boolean;
  /** Release channel for the downloader: `latest` (default) or a tag. */
  channel?: string;
  logger?: (line: string) => void;
  /**
   * Default instructions for every thread this client opens.
   *
   * A per-thread `instructions` wins outright — it is not merged with this one,
   * because two texts silently concatenated is nobody's intent. Use this for
   * the persona your whole app shares and the per-thread field for a narrower
   * one.
   */
  instructions?: ThreadInstructions;
  /**
   * Supplies MCP header values — usually a bearer token — per thread and
   * server, at the moment they are needed.
   *
   * The SDK never writes header values to disk: the thread store keeps header
   * NAMES only. So a resume, a recreate after the runtime lost a session, and
   * an `autoRestart` all need the values again, and this is where they come
   * from when the caller did not pass them (`refresh.mcpServers` on
   * `threads.open` wins over it; headers passed explicitly on a create win over
   * it too). May return a Promise, so the host can refresh an OAuth token
   * first; return undefined for a server that needs no headers.
   *
   * Also called before every `send`, `retry` and `editLast` of a thread with
   * remote servers, and by `thread.refreshMcpHeaders()`: when the values
   * changed (a token rotated), the SDK pushes them and the runtime restarts
   * the provider between turns on the same provider thread, so a long chat
   * never runs on an expired token. Unchanged values push nothing, so keep
   * the callback cheap — return a cached token until it nears expiry.
   *
   * On a resume the SDK pushes the resolved servers to the runtime with
   * `updateSession`, so a rotated token takes effect on the next turn. That
   * needs a runtime advertising `capabilities.personalChats.updateMcpServers`;
   * an older one keeps whatever it had and the SDK logs a warning. Two cases
   * push nothing: when this callback supplies no value for any server that
   * needs one (re-sending would replace the session's live credentials with
   * none; logged), and when the resolved servers, values included, are the
   * ones this client already sent for the thread.
   */
  mcpHeaders?: McpHeadersResolver;
  /**
   * Respawn the runtime when it exits unexpectedly. Off by default.
   *
   * `true` uses 5 attempts with a 1 s backoff that doubles per attempt;
   * the object form overrides either. Each attempt emits
   * `client.on("restart")`. On success the client re-handshakes, rebinds its
   * event stream, and re-opens every thread it had open from the stored
   * record — header values resolved again through `mcpHeaders` — so the
   * thread objects a host holds, and a bridge built on this client, keep
   * working. The client object itself never changes.
   *
   * A turn in flight when the runtime died is NOT resumed: each live thread
   * already received a synthetic `status` / `turnStatus: "failed"` envelope,
   * and the transcript keeps everything that was persisted.
   *
   * Not attempted after `dispose()`, and not in attach mode for a runtime the
   * SDK did not start — there the client only reconnects to the same socket.
   */
  autoRestart?: boolean | { maxAttempts?: number; backoffMs?: number };
  /**
   * Refuse a runtime whose version is outside `SUPPORTED_RUNTIME_RANGE`,
   * throwing `AdeError("runtime_incompatible")` from `createAdeChat` (and
   * failing an `autoRestart` attempt the same way).
   *
   * Off by default: an unsupported runtime connects, logs one warning, and
   * degrades feature by feature. `doctor().runtime.compatibility` reports the
   * verdict either way. Dev builds (`0.0.0`, or no version) always pass.
   */
  requireCompatibleRuntime?: boolean;
  /**
   * Where `binaryPath` came from. Set by `resolvePackagedRuntime()`, which
   * returns `source: "packaged"` so that spreading its result into these
   * options makes `doctor().runtime.source` report `"packaged"` rather than
   * `"explicit"`. Ignored without `binaryPath`.
   */
  source?: "packaged";
  /**
   * Reuse the runtime host's provider logins. Defaults to false (isolated
   * per-app logins). SDK 0.7 changes the default from machine logins; pass
   * true to keep relying on the host machine's Claude/Codex login.
   */
  useMachineLogin?: boolean;
  /**
   * The environment the runtime starts with. Defaults to this process's
   * environment. `useMachineLogin: false` isolates the providers' sign-in
   * folders, not variables: an `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` or
   * `CURSOR_API_KEY` here is visible to the runtime, so leave them out when end
   * users must run only on their own logins and keys. The host's own `ADE_*`
   * variables are always removed.
   */
  env?: NodeJS.ProcessEnv;
  /**
   * Resolve a host-vault credential id to a secret for one thread session.
   * The value is pushed to the runtime for the live session and never saved
   * in the SDK thread record.
   */
  resolveSecret?: (provider: AdeProvider, credentialId: string) => string | undefined | Promise<string | undefined>;
  /** Usage-limit behavior for new threads. Defaults to `wait`. */
  onUsageLimit?: "failover" | "wait" | "ask";
};

export type DefaultModelOptions = {
  /**
   * Only models a thread can use now: `isAvailable` and `connected` (the
   * provider is signed in). Default true.
   */
  available?: boolean;
  /**
   * Only these providers, in order of preference: the first provider with a
   * qualifying model wins. Omit for every provider.
   */
  providers?: readonly string[];
  /**
   * Your own ranking inside one provider's qualifying models (SDK 0.5). Return
   * a number greater than zero to prefer a model — the highest score wins.
   * Return 0, a negative number, or a non-finite number for "no opinion": that
   * model is then ranked the way it is ranked without this option.
   *
   * Use it to state a cost or family preference instead of keeping your own
   * copy of the rule. For example, to start new chats on the newest Sonnet:
   *
   *   prefer: (model) => (/sonnet/i.test(model.id) ? 1 : 0)
   *
   * A model that nobody scores falls back to `isDefault`, then to catalog
   * order, so passing this option never removes a model from the pool.
   *
   * A callback that throws propagates out of `pickDefaultModel` (and out of
   * `client.models.defaultModel`), like every other host callback that is part
   * of an operation. It is not swallowed: a ranking that fails silently would
   * pick a model you did not ask for.
   */
  prefer?: (model: ModelCatalogEntry) => number;
};

export type DoctorReport = {
  ok: boolean;
  /**
   * Version of this SDK package. Reported alongside the runtime version
   * because a mismatched pair is the first thing to check when an embedder's
   * chat misbehaves: the two ship on separate cadences, and the SDK is the
   * half that lives inside the embedder's own build.
   */
  sdkVersion: string;
  binary: {
    path: string;
    /** Version string reported by `<binary> --version`, when it answered. */
    version: string | null;
    source: "option" | "path" | "download" | "cache";
    /**
     * Whether THIS client verified the binary against a published SHA256SUMS.
     *
     * False is not an accusation — a caller-supplied `binaryPath`, an `ade`
     * found on PATH, and a reuse of an earlier download are all unverified by
     * this client because it did not fetch them. It is only meaningful as
     * "provenance was checked here", which is what an operator wants to know
     * when auditing where the running binary came from.
     */
    checksumVerified: boolean;
  };
  /**
   * Runtime provenance: which of the five resolution steps produced the binary,
   * where its native modules came from, and whether the OS considers it signed.
   *
   * `binary` above is the 0.1.x view and keeps its four `source` values.
   * `source` and `signature` here are the two fields to put in a support
   * bundle: together they separate "the app is running the runtime we signed
   * and shipped" from "the app quietly downloaded one on this machine", which
   * is the difference an embedder cannot otherwise see.
   */
  runtime: {
    /**
     * `"packaged"` is an explicit runtime whose options came from
     * `resolvePackagedRuntime()` — the copy inside the host's own signed app
     * bundle. `"explicit"` is any other caller-pinned `binaryPath`.
     */
    source:
      | "explicit"
      | "packaged"
      | "bundled-package"
      | "cached-download"
      | "path"
      | "downloaded"
      | "attached";
    binaryPath: string;
    version: string | null;
    /** `ADE_RUNTIME_ROOT` as spawned, or null when the install carries its own. */
    runtimeRoot: string | null;
    /** `ADE_RUNTIME_NODE_MODULES` as spawned. */
    nodeModulesPath: string | null;
    /**
     * macOS and Windows only. Null on Linux, in attach mode, and whenever the
     * check could not run — "not known", never "not signed".
     *
     * `accepted` on macOS is Gatekeeper's verdict on the outermost `.app` the
     * runtime is embedded in (a nested binary assessed alone is always
     * "rejected" as not an app), and null when it cannot be judged. Only
     * `accepted: false` means the OS refused it.
     */
    signature: { signed: boolean; authority?: string; accepted?: boolean | null } | null;
    /** True only when THIS client downloaded a runtime during its lifetime. */
    downloadedThisSession: boolean;
    checksumVerified: boolean;
    /**
     * Whether the runtime's self-reported version is inside the range this SDK
     * supports (`SUPPORTED_RUNTIME_RANGE`).
     *
     * An unsupported runtime still connects: features it lacks are detected
     * and degrade with a logged line. Pass `requireCompatibleRuntime: true` to
     * `createAdeChat` to refuse it instead. A dev build (`0.0.0`, or no version
     * at all) counts as supported and says so in `note`.
     */
    compatibility: RuntimeCompatibility;
  };
  socket: {
    path: string;
    connected: boolean;
    /** Runtime info from the `ade/initialize` result, when the runtime sent it. */
    runtimeVersion: string | null;
    pid: number | null;
  };
  events: {
    mode: "push" | "drain" | "unavailable";
    /** Buffer epoch last observed; a change means the runtime restarted. */
    epoch: string | null;
    gapsRecovered: number;
  };
  providers: Record<string, ProviderStatus>;
  logins: {
    mode: "isolated" | "machine" | "attached";
    perProvider: Record<string, "isolated" | "shared" | "unknown">;
  };
  threads: { tracked: number; live: number };
  /** Most recent errors the client recorded, newest last. Capped. */
  recentErrors: Array<{ at: string; scope: string; message: string }>;
};

export type DownloadRequest = {
  /** Directory that receives `bin/ade` and `runtime/<target>/node_modules`. */
  home: string;
  /** Release channel: `latest` (default) or an explicit tag such as `v1.2.69`. */
  channel: string;
  repo: string;
  target: RuntimeTarget;
  logger: (line: string) => void;
  signal?: AbortSignal;
  /**
   * Refuse to install a runtime whose checksum cannot be verified. Defaults to
   * true; set false only for a channel that genuinely publishes no SHA256SUMS.
   */
  requireChecksum?: boolean;
};

export type DownloadResult = {
  /** Absolute path of the installed `ade` binary. */
  binaryPath: string;
  /** Absolute path of the extracted native runtime root. */
  runtimeRoot: string;
  /** True when a checksum from a published SHA256SUMS was verified. */
  checksumVerified: boolean;
};

export type EditLastOptions = {
  /** Text shown to the user when it differs from what the agent receives. */
  displayText?: string;
  /**
   * Files for the edited message, replacing the original's. Omit to keep the
   * original message's attachments; pass `[]` to drop them.
   */
  attachments?: AgentChatFileRef[];
};

export type HistoryPageOptions = {
  /**
   * Return events strictly older than this `sequence`. Omit for the newest
   * page. Pass the previous page's `nextBeforeSequence` to walk backwards.
   */
  beforeSequence?: number;
  /**
   * At most this many events. The runtime pages by bytes, so a page can hold
   * fewer; when it holds more, the SDK keeps the newest `limit` and moves the
   * cursor so nothing is skipped. Defaults to 200.
   */
  limit?: number;
};

export type HostConfigCapability = {
  /**
   * Always true on a non-null report: a report exists only for a request that
   * was made. Retained because the field is part of the published shape and
   * because a null report is ambiguous, so code that has a report in hand can
   * still say plainly which of the two cases it is not in.
   */
  requested: boolean;
  level: AgentChatHostConfigLevel;
  /** How the provider implemented it, for logs and support threads. */
  mechanism: string;
  /** Why the level is not `"applied"`, or null when it is. */
  detail: string | null;
} & Record<string, unknown>;

export type InstructionsCapability = HostConfigCapability & {
  mode: "append" | "replace";
};

export type JsonSchema = {
  type?: "object" | "array" | "string" | "number" | "integer" | "boolean" | "null";
  properties?: Record<string, JsonSchema>;
  required?: string[];
  items?: JsonSchema;
  enum?: unknown[];
  additionalProperties?: boolean | JsonSchema;
  title?: string;
  description?: string;
  $schema?: string;
  $id?: string;
  default?: unknown;
  examples?: unknown[];
};

export type KnownAgentChatEvent =
  | {
      type: "user_message";
      text: string;
      displayText?: string;
      messageId?: string;
      turnId?: string;
      steerId?: string;
      deliveryState?: "queued" | "accepted" | "processed" | "unprocessed" | "delivered" | "inline" | "failed";
      attachments?: AgentChatFileRef[];
    }
  | { type: "user_message_resolution"; steerId: string; action: "run_next" | "dismiss"; state: "completed"; replacementMessageId?: string }
  | { type: "queue_reordered"; steerIds: string[] }
  | {
    type: "queue_recovery";
    recoveryId: string;
    state: "available" | "restored" | "expired";
    messageCount: number;
    /** On `restored`: the messages put back in the queue. */
    restoredSteers?: Array<{ steerId: string; text: string; attachments?: AgentChatFileRef[] }>;
  }
  | { type: "text"; text: string; messageId?: string; turnId?: string }
  | { type: "reasoning"; text?: string; turnId?: string }
  | { type: "tool_call"; tool: string; args: unknown; itemId: string; turnId?: string }
  | { type: "tool_result"; tool: string; result: unknown; itemId?: string; turnId?: string }
  | { type: "tokens"; [key: string]: unknown }
  | { type: "context_usage"; [key: string]: unknown }
  | { type: "codex_token_usage"; [key: string]: unknown }
  | {
      /**
       * The provider is blocked and wants a decision. Answer it with
       * `thread.approve(itemId, …)`.
       *
       * AN UNANSWERED REQUEST BLOCKS THE TURN. There is no timeout anywhere in
       * the runtime: the turn stays parked until `approve()` or `interrupt()`.
       * A host that receives this event and renders nothing has a chat that
       * looks frozen, so render a card for every one of them.
       */
      type: "approval_request";
      itemId: string;
      logicalItemId?: string;
      kind: "command" | "file_change" | "tool_call";
      description: string;
      turnId?: string;
      detail?: unknown;
      /**
       * The finer-grained kind. `"question"` and the other prose kinds ride
       * this event because `kind` has no word for a question — they cannot be
       * answered with approve/decline, so render them read-only.
       */
      requestKind?: PendingInputKind;
    }
  | {
      /** An `approval_request` with this `itemId` is settled. Upgrade the card. */
      type: "pending_input_resolved";
      itemId: string;
      resolution: "accepted" | "declined" | "cancelled";
      answers?: Record<string, string | string[]>;
      turnId?: string;
    }
  | { type: "status"; [key: string]: unknown }
  | { type: "error"; [key: string]: unknown }
  | {
      type: "budget_exceeded";
      budget: { maxCostUsd?: number; maxTokens?: number };
      usage: {
        inputTokens: number;
        outputTokens: number;
        totalTokens: number;
        complete?: boolean;
        contextWindow?: number;
        costUsd?: number;
      };
      turnId?: string;
      resumed?: boolean;
    }
  | { type: "done"; [key: string]: unknown };

export type McpCapabilityReport = {
  /**
   * What strict mode achieved — meaningful ONLY when `strictRequested` is true.
   * Read that field first.
   */
  level: "enforced" | "best-effort" | "unsupported";
  /**
   * How the provider implemented the request, for logs and support threads.
   *
   * Describes ENFORCEMENT when `strictRequested` is true, and DELIVERY (how the
   * supplied servers were handed to the provider) when it is false.
   */
  mechanism: string;
  /**
   * What strict mode could NOT exclude, or null when nothing leaked through.
   *
   * Always null when `strictRequested` is false: nothing was asked to be
   * excluded, so nothing leaked.
   */
  residual: string | null;
  /**
   * Whether this thread asked ADE to withhold the user's and project's own MCP
   * config — i.e. `loadUserMcpServers: false`, explicitly or by supplying
   * `mcpServers` without opting back in.
   *
   * THE FIRST FIELD TO READ. When it is false the caller asked for delivery
   * only: the user's own MCP config loads by design, and `level` makes no
   * isolation claim at all — treating `level === "enforced"` as "only my tools
   * are loaded" on a delivery-only thread would be exactly backwards.
   *
   * An older runtime that predates the field omits it, and the SDK reports
   * false rather than guessing. That is the conservative direction: it
   * understates isolation instead of promising one that was never verified.
   */
  strictRequested: boolean;
  /**
   * False when the provider has no MCP surface and supplied servers were
   * dropped.
   *
   * PREFER `level`. On a current runtime this is effectively always true —
   * `create` refuses the only case that would make it false — so branching on
   * it tells you nothing that `level` does not tell you better. It is retained
   * because it is part of the published shape, not because it is useful.
   *
   * Older runtimes additionally returned false for a strict-only request
   * (strict mode with no servers) that had in fact been enforced, which made
   * `!delivered` read a success as a failure. Anything keyed on this field
   * against a pre-fix runtime is suspect; `level === "unsupported"` is the
   * check that was always correct.
   */
  delivered: boolean;
};

export type McpHeadersResolver = (
  key: string,
  serverName: string,
) => Record<string, string> | undefined | Promise<Record<string, string> | undefined>;

export type McpServerConfig =
  | ({ type: "http" | "sse"; url: string; headers?: Record<string, string> } & McpToolFilter)
  | ({
      type: "stdio";
      command: string;
      args?: string[];
      env?: Record<string, string>;
    } & McpToolFilter);

export type McpToolFilter = {
  /** Only these tools reach the model. Never empty. */
  allowedTools?: string[];
  /** These tools never reach the model. Applied after `allowedTools`. */
  disallowedTools?: string[];
};

export type ModelCatalogEntry = {
  /** Canonical ADE registry id — this is what `ThreadOpenOptions.model` takes. */
  id: string;
  displayName: string;
  /**
   * The provider group this model belongs to. One of the six
   * {@link AdeProvider} values for every model this SDK can open a thread on;
   * typed open because the runtime's catalog is downloaded and can list a
   * provider group newer than this SDK.
   *
   * Because it is open, `ThreadOpenOptions.provider` (typed `AdeProvider`) will
   * not take it without narrowing. Narrow it with `isSupportedProvider` — an
   * SDK export since 0.4 — rather than a cast:
   *
   *   if (!isSupportedProvider(entry.provider)) return;
   *   ade.threads.open(key, { provider: entry.provider, model: entry.id });
   */
  provider: AdeProvider | (string & {});
  /** Provider-native model ref ADE sends under the hood. */
  runtimeModelId: string;
  isDefault: boolean;
  isAvailable: boolean;
  connected: boolean;
  requiresConfiguration: boolean;
  reasoningEfforts: string[];
  defaultReasoningEffort: string | null;
  description: string | null;
};

export type PackagedRuntime = {
  /** Absolute path of `bin/ade` (`bin/ade.exe` on Windows). */
  binaryPath: string;
  /** Absolute path of `native/`, which becomes `ADE_RUNTIME_ROOT`. */
  runtimeRoot: string;
  /** Absolute path of `native/node_modules`, which becomes `ADE_RUNTIME_NODE_MODULES`. */
  runtimeNodeModules: string;
  source: "packaged";
};

export type PendingInputKind = (typeof PENDING_INPUT_KINDS)[number];

export type PendingInputOption = {
  label: string;
  value: string;
  description?: string;
  recommended?: boolean;
  preview?: string;
  previewFormat?: "markdown" | "html";
};

export type PendingInputQuestion = {
  id: string;
  header?: string;
  question: string;
  options?: PendingInputOption[] | null;
  multiSelect?: boolean;
  allowsFreeform?: boolean;
  isSecret?: boolean;
  defaultAssumption?: string | null;
  impact?: string | null;
};

export type PendingInputRequest = {
  requestId: string;
  itemId?: string;
  source: PendingInputSource;
  kind: PendingInputKind;
  title?: string | null;
  description?: string | null;
  questions: PendingInputQuestion[];
  allowsFreeform: boolean;
  blocking: boolean;
  canProceedWithoutAnswer: boolean;
  options?: PendingInputOption[];
  providerMetadata?: Record<string, unknown>;
  autoResolutionMs?: number | null;
  turnId?: string | null;
};

export type PendingInputSource =
  | "claude"
  | "codex"
  | "cursor"
  | "droid"
  | "opencode"
  | "pi"
  | "muse"
  | "acp"
  | "ade";

export type PermissionCapability = {
  level: "enforced" | "best-effort" | "unsupported";
  mechanism: string;
  residual: string | null;
};

export type PermissionPreset = "always-allow" | "default";

export type ProbeRuntimeSignatureOptions = {
  platform?: NodeJS.Platform;
  spawn?: SignatureCommandRunner;
};

export type ProviderCapabilities = {
  permissionModes: AgentChatPermissionMode[];
  reasoningEfforts: string[];
  fastMode: boolean;
  multipleAccounts: boolean;
  signIn: "cli-login" | "device-code" | "api-key" | "none";
  apiKeys: boolean;
  presets: boolean;
  mcp: "full" | "partial" | "none";
};

export type ProviderStatus = {
  provider: string;
  displayName: string;
  /**
   * A usable binary or package was found.
   *
   * On a derived record this is `modelCount > 0`, which answers a different
   * question — "does ADE know models for this provider" — so do not present it
   * as a filesystem fact unless `source` is `"probed"`.
   */
  installed: boolean;
  /** Absolute path the runtime would spawn. Null when not found or derived. */
  binaryPath: string | null;
  /** Verbatim first line of `--version`. Null on a timeout, or when derived. */
  version: string | null;
  /**
   * Credentials the CLI can use were found.
   *
   * On a probed record this is a credential-file check. On a derived one it
   * means "the catalog resolved at least one connected model", which a stale
   * catalog can report after the credential expired — `stale` carries that.
   */
  authenticated: boolean;
  /** How, when the probe could tell: subscription, api-key, oauth, unknown. */
  authMethod?: string | null;
  /** Remediation ADE supplies. Null on a derived record. */
  installCommand: string | null;
  loginCommand: string | null;
  docsUrl: string | null;
  /** True when at least one model is usable right now. */
  available: boolean;
  /** True when every usable path needs setup first. */
  requiresConfiguration: boolean;
  modelCount: number;
  /**
   * True when something behind this verdict was served from the cache rather
   * than probed on this call: a cached model catalog, or a cached probe record.
   * It does not mean the record is past the runtime's TTL — a record inside the
   * TTL is served from the cache and is stale by this definition.
   */
  stale: boolean;
  /** How this record was produced. Read this before trusting the rest. */
  source: "probed" | "derived";
  /** ISO timestamp of the probe, or of the derivation. */
  checkedAt: string;
  /** Human-readable note from the probe, when it had one. */
  detail?: string | null;
  /** Provider controls, present only when the runtime advertises them. */
  capabilities?: ProviderCapabilities;
  /** Config-home isolation used by this runtime, when it can report it. */
  isolation?: "isolated" | "shared";
};

export type ProviderStatusProbeRecord = {
  provider?: string;
  displayName?: string;
  installed?: boolean;
  binaryPath?: string | null;
  version?: string | null;
  authenticated?: boolean;
  authMethod?: string | null;
  installCommand?: string | null;
  loginCommand?: string | null;
  docsUrl?: string | null;
  source?: "probed";
  stale?: boolean;
  checkedAt?: string;
  detail?: string | null;
  capabilities?: ProviderCapabilities;
  isolation?: "isolated" | "shared";
};

export type ProviderStatusRpcResult = {
  checkedAt: string;
  providers: Record<string, ProviderStatusProbeRecord>;
};

export type ResolveBundledRuntimeOptions = {
  /**
   * Directory or file to resolve the package from. Defaults to this module's
   * own location, which is what an embedder wants: the runtime package sits
   * beside `@ade-dev/sdk` in the same `node_modules` tree.
   */
  resolveFrom?: string;
  platform?: NodeJS.Platform;
  arch?: string;
};

export type ResolvedBinarySource =
  | "explicit"
  | "packaged"
  | "bundled-package"
  | "cached-download"
  | "path"
  | "downloaded";

export type ResolvePackagedRuntimeOptions = {
  /** Directory under `resourcesPath` that holds the runtime. Defaults to `"ade-runtime"`. */
  dir?: string;
  /** Defaults to `process.platform`. Decides the binary name and the Mach-O check. */
  platform?: NodeJS.Platform;
  /** Defaults to `process.arch`. The architecture the binary must be able to run. */
  arch?: string;
};

export type RunOptions = Omit<ThreadOpenOptions, "provider" | "model"> & {
  provider: AdeProvider;
  model: string;
  schema?: JsonSchema;
  budget?: ThreadBudget;
  /**
   * Longest one turn may take, in ms (default 10 minutes). On expiry the turn
   * is interrupted and `run()` rejects with `rpc_timeout`.
   */
  timeoutMs?: number;
};

export type RuntimeCompatibility = {
  supported: boolean;
  /** The range this SDK build supports, e.g. `">=1.2.81 <2.0.0"`. */
  range: string;
  /** What the runtime reported on `ade/initialize`, or null when it sent none. */
  version: string | null;
  /** Why a version counted as supported without being checked, when it did. */
  note: string | null;
};

export type RuntimeDownloader = (request: DownloadRequest) => Promise<DownloadResult>;

export type RuntimeSignature = {
  /** True when the OS reports a signature of any kind, ad-hoc included. */
  signed: boolean;
  /** The signing authority, when readable: a certificate subject or Team ID. */
  authority?: string;
  /**
   * Whether the OS accepts the runtime for execution.
   *
   * On macOS this is Gatekeeper's verdict (`spctl --assess --type execute`).
   * A runtime embedded in an app bundle is assessed through the OUTERMOST
   * enclosing `.app`, because Gatekeeper judges a nested helper as part of the
   * app that carries it: assessed on its own, a correctly signed and notarized
   * embedded binary is "rejected (the code is valid but does not seem to be an
   * app)". When the binary is not inside a bundle and Gatekeeper answers that
   * way, the verdict is `null` — not known — never `false`.
   *
   * On Windows it is whether the Authenticode chain is valid.
   *
   * Absent or null: acceptance could not be determined. Only `false` means
   * the OS refused it.
   */
  accepted?: boolean | null;
};

export type RuntimeTarget = {
  /** e.g. `darwin-arm64`, `linux-x64`, `win32-x64`. */
  target: string;
  binaryAsset: string;
  archiveAsset: string;
};

export type SendOptions = {
  /** Files to attach. `type` is inferred when absent; see `AgentChatFileRef`. */
  attachments?: AgentChatFileRef[];
  /** Text shown to the user when it differs from what the agent receives. */
  displayText?: string;
  reasoningEffort?: string | null;
};

export type SetModelOptions = {
  /**
   * Switch even with a turn in flight, accepting that the turn ends with no
   * completion event. Only meaningful mid-turn; ignored on an idle thread.
   */
  force?: boolean;
};

export type SetModelResult = ThreadModelSelection & { capabilities: ThreadCapabilities };

export type SettingSourcesCapability = HostConfigCapability & {
  value: AgentChatSettingSources;
};

export type SignInHandle = {
  on(event: "update", listener: (status: SignInStatus) => void): () => void;
  submitCode(code: string): Promise<void>;
  cancel(): Promise<void>;
  done: Promise<AccountInfo>;
};

export type SignInStatus = {
  loginId: string;
  instanceId: string;
  provider: string;
  state: "running" | "verifying" | "succeeded" | "failed" | "cancelled" | "expired";
  url: string | null;
  awaitingCode: boolean;
  deviceCode?: string;
  email?: string;
  message?: string;
  startedAt: string;
  endedAt?: string;
};

export type SteerOptions = {
  /**
   * Files to hand the running turn. Same shape and inference as
   * `SendOptions.attachments`. A steer with attachments may have empty text.
   */
  attachments?: AgentChatFileRef[];
};

export type SyntheticRuntimeLostStatusEvent = {
  type: "status";
  /**
   * `"failed"`, the runtime's own word for a turn that ended badly, so a
   * subscriber that already maps `turnStatus` needs no new case. Tell it apart
   * from a runtime-sent failure by `synthetic: true`.
   */
  turnStatus: "failed";
  message: string;
  synthetic: true;
};

export type ThreadBudget = {
  maxCostUsd?: number;
  maxTokens?: number;
};

export type ThreadCapabilities = {
  mcpCapability: McpCapabilityReport | null;
  permissionCapability: PermissionCapability | null;
  instructionsCapability: InstructionsCapability | null;
  settingSourcesCapability: SettingSourcesCapability | null;
};

export type ThreadEventChannel = "event" | "usage" | "status";