@cursor/bdk 0.2.1

package/dist/types.d.ts

@@ -0,0 +1,3375 @@
+/**
+ * Public types for @cursor/bdk.
+ *
+ * The framework is filesystem-first: customers author an agent as files under
+ * an `agent/` directory (markdown for prose, TypeScript for typed behavior),
+ * and the framework discovers those files, compiles them into an
+ * {@link AgentProject}, and serves the agent over channels using the Cursor
+ * SDK as the execution harness.
+ */
+import type { InteractionUpdate, SDKCustomTool, ToolName } from "@cursor/sdk";
+import type { z } from "zod";
+import type { FileSystem } from "./filesystem.js";
+import type { ContinuationClaim, ContinuationIdentity, MailboxContinuation } from "./internal/continuation-identity.js";
+import type { OtelConfig, OtelDefinition } from "./otel.js";
+import type { StorageDefinition } from "./storage.js";
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | JsonObject;
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+/** A plain JSON Schema object (already-serialized tool input schema). */
+export type JsonSchemaObject = Record<string, unknown>;
+/**
+ * Discriminates the `define*` helper that produced a module's default export
+ * so discovery can validate that a file landed in the right authored slot.
+ */
+export type DefinitionKind = "agent" | "instructions" | "tool" | "skill" | "extension" | "disabled-tool" | "disabled-connection" | "disabled" | "connection" | "channel" | "http-channel" | "schedule" | "reminder" | "hook" | "eval" | "storage" | "artifacts" | "otel";
+export interface BrandedDefinition<K extends DefinitionKind> {
+    readonly __agentServe: K;
+}
+/**
+ * A Cursor model selection. Either a bare model id (`"gpt-5.2"`) or an id
+ * with model parameters, mirroring the Cursor SDK's `ModelSelection`.
+ */
+export type ModelSetting = string | {
+    id: string;
+    params?: Array<{
+        id: string;
+        value: string;
+    }>;
+};
+/**
+ * Model used when the root agent omits `model` (local Cursor agents have no
+ * harness-level default of their own).
+ */
+export declare const DEFAULT_MODEL: ModelSetting;
+/** Runtime selector. New public agents use the default local runtime. */
+export type AgentRuntime = "local" | "cloud" | "grokbot";
+/** Options used when launching Cursor cloud agents. */
+export interface AgentCloudOptions {
+    env?: {
+        type: "cloud";
+        name?: string;
+    } | {
+        type: "pool";
+        name?: string;
+    } | {
+        type: "machine";
+        name?: string;
+    };
+    repos?: Array<{
+        url: string;
+        startingRef?: string;
+        prUrl?: string;
+    }>;
+    workOnCurrentBranch?: boolean;
+    autoCreatePR?: boolean;
+    skipReviewerRequest?: boolean;
+    /**
+     * Per-session env vars injected into the cloud agent's shell.
+     * When set, the cloud API mints the SDK agent id (persisted as
+     * {@link SessionRecord.sdkAgentId}).
+     */
+    envVars?: Record<string, string>;
+}
+/** Safe `/v1/info` projection of {@link AgentCloudOptions}; secret values are omitted. */
+export type AgentCloudPublicInfo = Omit<AgentCloudOptions, "envVars"> & {
+    envVarsConfigured?: boolean;
+};
+export declare function toPublicCloudInfo(cloud: AgentCloudOptions): AgentCloudPublicInfo;
+/**
+ * Session-scoped facts a `root` factory needs and does not otherwise
+ * have at `defineAgent` time. The factory returns a handle: each
+ * method must observe the current binding. Do not snapshot the tree.
+ */
+export interface RootContext {
+    sessionId: string;
+    agentName?: string;
+    continuationKey?: string;
+    host?: {
+        files: HostFilesApi;
+        reminders?: ReminderHostApi;
+        kv?: HostKvApi;
+    };
+}
+/** Input to `defineAgent` (authored at `agent/agent.ts`). */
+export interface AgentConfig {
+    /**
+     * Cursor model to run the agent on. Defaults to {@link DEFAULT_MODEL} on
+     * the root agent when omitted. Subagents omit it to inherit the parent's
+     * model.
+     */
+    model?: ModelSetting;
+    /**
+     * Models to try, in order, when {@link model} is rejected before the
+     * turn produces any output: catalog refusal ("Cannot use this model")
+     * or a capacity error (`resource_exhausted` / `[unavailable]`). The
+     * rejection is usually inside agent creation, before authored tools
+     * run, so a fallback list on the agent is the only retry that can save
+     * the turn. Each entry is the same shape as {@link model}.
+     */
+    fallbacks?: readonly ModelSetting[];
+    /**
+     * What this agent is for. Required on subagents: the parent model reads it
+     * to decide when to delegate. Optional (documentation only) on the root.
+     */
+    description?: string;
+    /** Display name override. Defaults to the package name / directory name. */
+    name?: string;
+    /**
+     * Inline instructions. Prefer `instructions.md` next to `agent.ts`; this
+     * exists for subagents and generated configs.
+     */
+    instructions?: string;
+    /**
+     * Execution runtime. Defaults to `"local"`. Compatibility strings
+     * `"cloud"` and `"grokbot"` remain for agents that already ship; they
+     * are not a product surface. New agents omit this field.
+     */
+    runtime?: AgentRuntime;
+    /**
+     * The FileSystem the model can see. Omit it and the root is the host
+     * disk. A static handle (`tempFs`, `unionFs`, ...) is that object on
+     * every session — writes are shared. Pass `(ctx) => …` and return a
+     * new handle per session when you want isolation. A factory that
+     * returns the same object still shares. Incompatible with
+     * {@link local} `cwd` / `workspaceDir` / `sandbox` and with
+     * {@link runtime} `"cloud"`.
+     */
+    root?: FileSystem | ((ctx: RootContext) => FileSystem | Promise<FileSystem>);
+    /**
+     * Cloud attach defaults merged under per-session
+     * {@link SendMessageOptions.cloud}. Used by existing agents that still
+     * set {@link runtime} `"cloud"` and by hybrid channel/tool handoffs.
+     * In-process `agent/tools` run on local turns only.
+     */
+    cloud?: AgentCloudOptions;
+    /** Local harness defaults. */
+    local?: AgentLocalOptions;
+    /**
+     * Managed-hosting declarations (`agent-sdk deploy` onto Cursor's
+     * agent-serve hosting). The manifest is the source of truth: deploy reads
+     * it and sends it with the deployment request. Ignored by local serving.
+     */
+    hosting?: AgentHostingOptions;
+    /**
+     * Engine-wide turn admission limits. See {@link AgentConcurrencyOptions}.
+     */
+    concurrency?: AgentConcurrencyOptions;
+    /**
+     * Framework-provided model-facing tools, opted in per capability. See
+     * {@link BuiltinToolsConfig}.
+     */
+    builtinTools?: BuiltinToolsConfig;
+    /**
+     * Allowlist of built-in harness tools offered to the model
+     * (`AgentOptions.tools` on the SDK). Opt-in by design: unset keeps the
+     * model's full standard toolset, and once set the agent gets exactly
+     * what it names — nothing more, `[]` meaning no native built-in tools.
+     * There is deliberately no exclusion form: an agent that restricts
+     * tools states what it keeps, so tools the platform adds later stay
+     * off until someone opts in.
+     *
+     * `"mcp"` is always granted alongside a configured allowlist. It is
+     * transport, not capability: this kit's own server tools reach the
+     * model over the SDK custom-tool MCP path, so omitting it would
+     * silently strand `agent/tools/`. What MCP actually exposes stays
+     * governed by the second layer — the tools you author, the connections
+     * you declare, and the harness cwd's ambient `.cursor` config (point
+     * `local.cwd` outside checkouts whose MCP servers the agent must not
+     * see, and `local.sandbox` makes MCP calls fail closed).
+     *
+     * Names use the SDK's public tool vocabulary (`"shell"`, `"read"`,
+     * `"edit"`, `"grep"`, `"glob"`, `"ls"`, `"task"`, ...). `"shell"` is a
+     * capability group that also grants shell stdin writes — and is what
+     * `execution: "agent"` tool scripts run through, so an allowlist
+     * without it strands them (discovery warns). `"task"` gates subagents.
+     * Unknown names fail the turn (`ConfigurationError` at `Agent.create`).
+     *
+     * This is not a security boundary against the serve host: like
+     * `local.sandbox`, it only shapes what the model can call.
+     */
+    tools?: ToolName[];
+    /**
+     * Hosted architecture. Defaults to `"v2"`. Set `"v1"` to stay on the
+     * resident-engine architecture.
+     */
+    architecture?: AgentArchitecture;
+    /**
+     * Persistent hosting for `architecture: "v2"`.
+     *
+     * Default (`false`): each session boots a pod from the release snapshot;
+     * framework and author state are mirrored to Cursor stores because pod
+     * disks are disposable.
+     *
+     * `true`: one long-lived pod per deployment runs each deployed version as
+     * a container over one state directory on the pod's disk. Nothing is
+     * mirrored: that directory is the durable copy. A redeploy starts the new
+     * version beside the old one on the same state, then drains the old one.
+     */
+    persistent?: boolean;
+}
+/** Hosted architecture on {@link AgentConfig.architecture}. */
+export type AgentArchitecture = "v1" | "v2";
+/**
+ * Built-in tools on {@link AgentConfig.builtinTools}. Each enabled
+ * capability materializes as ordinary server tools at discovery time, so
+ * turns, direct calls, `info`, and the playground treat them like authored
+ * tools. Authored tools with the same name win with a warning.
+ */
+export interface BuiltinToolsConfig {
+    /**
+     * Reminder tools bound to the current conversation, over
+     * {@link HostContext.reminders}: `reminders_create`, `reminders_list`,
+     * and `reminders_cancel` (the name the framework's reminder fire prompt
+     * tells the model to call when a stop condition is met). Sessions
+     * without a continuation key cannot arm reminders.
+     */
+    reminders?: boolean;
+}
+/**
+ * Turn admission limits on {@link AgentConfig.concurrency}.
+ *
+ * ```ts
+ * export default defineAgent({
+ *   // At most 3 sessions run a model turn at once; the rest queue FIFO.
+ *   concurrency: { maxRunningTurns: 3 },
+ * });
+ * ```
+ */
+export interface AgentConcurrencyOptions {
+    /**
+     * Max model turns running at once across **all** of this agent's
+     * sessions. When every slot is busy, newly admitted turns queue FIFO
+     * (surfaced as a durable `turn.queued` event and `queued: true` on
+     * `GET /v1/sessions`) instead of failing; each queued turn starts as
+     * soon as a slot frees. Positive integer, hard-capped at
+     * {@link MAX_RUNNING_TURNS_LIMIT}. Omit for unlimited.
+     *
+     * A queued turn still counts as `running` for busy semantics
+     * (follow-ups preempt it; direct write-effect tool calls get
+     * `SessionBusyError`),
+     * and a follow-up that preempts a queued turn re-queues at the back.
+     */
+    maxRunningTurns?: number;
+}
+/**
+ * Hard ceiling for {@link AgentConcurrencyOptions.maxRunningTurns}.
+ * Matches the eval harness ceiling: each running turn issues model
+ * provider requests, so unbounded parallelism is never meaningful.
+ */
+export declare const MAX_RUNNING_TURNS_LIMIT = 200;
+/**
+ * Managed-hosting block on {@link AgentConfig.hosting}.
+ */
+export interface AgentHostingOptions {
+    /**
+     * Domains the deployed engine pod may reach (egress allowlist), e.g.
+     * `"api.example.com"` or `"*.example.com"` (single leading wildcard).
+     * Lowercase hostnames with at least two labels and an alphabetic TLD;
+     * max 20. `agent-sdk deploy` sends these as `egressAllowedDomains`
+     * (unioned with any `--allow-domain` flags). Only valid on repo-backed
+     * deployments. Deployment-scoped like {@link secretNames}: not capped by
+     * the team's Cloud Agent egress allowlist. The platform still merges a
+     * bootstrap set (npm, Slack, Cursor API) at provision time.
+     */
+    egressDomains?: string[];
+    /**
+     * Secret names this agent expects at runtime (declarative documentation;
+     * values are never authored in files). `agent-sdk deploy` warns when a
+     * declared name is not set on the deployment — set values with
+     * `agent-sdk secrets set <slug> NAME`.
+     */
+    secretNames?: string[];
+    /**
+     * Name of a container image the team pushed with
+     * `agent-sdk images push <local-image> --name <name>`; the deployed agent
+     * runs inside it instead of the platform's default `node:22` image. The
+     * image must be `linux/amd64` and provide `bash`, `node` (>= 22.13) and
+     * `npm` on `PATH`. Requires `architecture: "v2"`; today only
+     * `persistent: true` agents honor it. Deploy pins the image bytes it saw
+     * (sha256); pushing the same name again takes effect on the next deploy.
+     */
+    image?: string;
+}
+/**
+ * Local runtime options on {@link AgentConfig.local}.
+ */
+export interface AgentLocalOptions {
+    /**
+     * Default local harness cwd parent. Absolute, or relative to the agent
+     * project root. Each session uses `<cwd>/<sessionId>` unless a per-send
+     * {@link SendMessageOptions.workspaceDir} overrides it.
+     *
+     * When omitted, a project nested in another git repo (a monorepo package)
+     * defaults to `~/.cache/agent-serve/<dir>` so Cursor does not load the
+     * enclosing checkout's AGENTS.md, rules, skills, or MCP servers. A
+     * standalone git root keeps the in-project session workspace. Point this
+     * at a checkout when the agent must inherit that tree.
+     */
+    cwd?: string;
+    /**
+     * One harness cwd shared by every session, for agents that work inside an
+     * existing checkout. Absolute, or relative to the agent project root.
+     * Takes precedence over {@link cwd}; a per-send
+     * {@link SendMessageOptions.workspaceDir} still wins over both.
+     *
+     * The SDK keys its local executor — Cursor rules, skills, MCP, the ignore
+     * mappings — on the harness cwd, so a shared directory resolves the
+     * workspace once per serve process instead of once per session. With
+     * `cwd`'s `<cwd>/<sessionId>` layout that cache never hits, and on a large
+     * repo each session pays the full scan again.
+     *
+     * Sessions are no longer isolated from each other on disk: they share a
+     * working tree, and a file one turn writes is visible to the next. Agent
+     * scaffold (`AGENTS.md`, skills, tool scripts) is kept out of the shared
+     * directory and delivered inline instead, so pointing this at a repo does
+     * not write Agent SDK files into it — but `workspaceFiles` still lands in
+     * the harness cwd, as it does for a per-send override.
+     */
+    workspaceDir?: string;
+    /**
+     * Run the harness inside Cursor's local sandbox (`sandboxOptions.enabled`
+     * on the SDK). Off by default, matching the SDK: shell then auto-approves
+     * and inherits the serve process environment — including any credentials
+     * the host holds.
+     *
+     * Turn this on for agents whose turns read untrusted input (webhook
+     * payloads, PR diffs, inbound chat). It is a real tool boundary rather
+     * than a prompt-level one, so it still holds when the model is steered
+     * into ignoring its instructions.
+     */
+    sandbox?: boolean;
+}
+export type AgentConfigDefinition = AgentConfig & BrandedDefinition<"agent">;
+/** Input to `defineInstructions` (authored at `agent/instructions.ts`). */
+export interface InstructionsConfig {
+    markdown: string;
+}
+export type InstructionsDefinition = InstructionsConfig & BrandedDefinition<"instructions">;
+export type ToolResultContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType?: string;
+};
+/**
+ * JSON-ish value a tool may return. Unlike {@link JsonValue} this permits
+ * `undefined` leaves (and thus optional object properties), because the
+ * result is JSON-serialized before it reaches the model and `undefined`
+ * fields are simply dropped — so authored tools can return objects shaped by
+ * optional fields without fighting the type system.
+ */
+export type ToolResultValue = string | number | boolean | null | undefined | ToolResultValue[] | readonly ToolResultValue[] | {
+    [key: string]: ToolResultValue;
+};
+/**
+ * What a tool's `execute` may return. Strings are passed to the model
+ * verbatim, JSON values are serialized, and the envelope form carries rich
+ * content and an error flag.
+ */
+export type ToolExecuteResult = ToolResultValue | {
+    content: ToolResultContent[];
+    isError?: boolean;
+    /**
+     * Structured result for tools that declare an `outputSchema`: MCP
+     * clients require `structuredContent` on calls to schema-declaring
+     * tools. Plain-object returns get it filled in automatically; the
+     * envelope form (needed for images or `isError`) sets it here.
+     */
+    structuredContent?: JsonObject;
+};
+/** Repo-agnostic GitHub client on the agent-serve host. */
+export interface HostGitHubClient {
+    getOctokit(): Promise<import("@octokit/rest").Octokit>;
+}
+/** Bot-token Slack Web API client on the agent-serve host. */
+export interface HostSlackClient {
+    getClient(): Promise<import("@slack/web-api").WebClient>;
+}
+/** Host-side handle for calling an MCP connection from a server tool or channel handler. */
+export interface HostMcpRegistry {
+    /** MCP connection names (filenames under `agent/mcp-connections/`). */
+    names(): string[];
+    listTools(connectionName: string): Promise<HostMcpToolInfo[]>;
+    callTool(connectionName: string, toolName: string, args?: Record<string, unknown>): Promise<HostMcpCallResult>;
+}
+/**
+ * MCP spec tool annotations (`Tool.annotations`, 2025-03-26 revision).
+ *
+ * A closed type on purpose: these are exactly the fields listing-time
+ * bounding keeps, so the type matches what a reader can ever see — and the
+ * hints are behavioral, so a misspelled or wrong-typed key must not
+ * masquerade as a declaration.
+ */
+export interface McpToolAnnotations {
+    /** Human-readable display name for the tool, length-capped at listing. */
+    title?: string;
+    /** The tool does not modify its environment. */
+    readOnlyHint?: boolean;
+    /** The tool may perform destructive updates (meaningful when not read-only). */
+    destructiveHint?: boolean;
+    /** Repeated calls with the same arguments have no additional effect. */
+    idempotentHint?: boolean;
+    /** The tool may interact with an open world of external entities. */
+    openWorldHint?: boolean;
+}
+export interface HostMcpToolInfo {
+    name: string;
+    description?: string;
+    inputSchema?: JsonObject;
+    outputSchema?: JsonObject;
+    /**
+     * MCP spec tool annotations, bounded at listing time to the
+     * {@link McpToolAnnotations} fields. Untrusted server hints — consumers
+     * that classify on them must fail closed when absent, and absent is
+     * exactly what a server that declares nothing produces.
+     */
+    annotations?: McpToolAnnotations;
+}
+export interface HostMcpCallResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    } | {
+        type: "image";
+        data: string;
+        mimeType?: string;
+    } | {
+        type: string;
+        [key: string]: unknown;
+    }>;
+    isError?: boolean;
+    structuredContent?: JsonObject;
+}
+/**
+ * Durable Slack follow-up nudge + ask-claim API attached to {@link HostContext}.
+ * Used for mid-turn inject, boundary resume skip, and delayed-parent dedupe.
+ */
+export interface SlackNudgeHostApi {
+    append(input: {
+        continuationKey: string;
+        sourceTs: string;
+        text: string;
+        author?: string;
+    }): Promise<boolean>;
+    /** Drain pending nudges and return a `<slack_followup>` block, if any. */
+    drainFormatted(continuationKey: string): Promise<string | undefined>;
+    clear(continuationKey: string): Promise<void>;
+    hasUndelivered(continuationKey: string): Promise<boolean>;
+    isDelivered(continuationKey: string, sourceTs: string): Promise<boolean>;
+    /** Claim `channelId:message.ts` exactly once (false = already seen). */
+    tryClaimAsk(channelId: string, messageTs: string): Promise<boolean>;
+    /** Release a claim after a failed send so Slack redelivery can retry. */
+    releaseAsk(channelId: string, messageTs: string): Promise<void>;
+}
+/**
+ * Shared host services available on every tool / hook / channel / schedule
+ * surface. Channel packs attach this as `ctx.host` so handlers can tap
+ * GitHub, Slack, or MCP without the pack depending on another platform.
+ */
+export interface HostContext {
+    /**
+     * Authored MCP connections (`agent/mcp-connections/*` and
+     * `agent/host-connections/*`). Call a specific MCP tool deterministically
+     * without going through the agent loop.
+     */
+    mcp: HostMcpRegistry;
+    /**
+     * Host GitHub client (PAT / env / `gh auth` / App). Prefer webhook
+     * `ctx.github` (installation-scoped) when handling a GitHub delivery.
+     */
+    github: HostGitHubClient;
+    /** Host Slack Web API client (`SLACK_BOT_TOKEN` / channel envPrefix). */
+    slack: HostSlackClient;
+    /**
+     * Per-session reminders (create / list / cancel / dispatch). Present once
+     * the serve host has attached a {@link ReminderRunner}.
+     */
+    reminders?: ReminderHostApi;
+    /**
+     * Slack ask-dedupe / nudge helpers. Always present on a live
+     * {@link SessionEngine} host. A busy Slack thread's follow-ups queue here
+     * and reach the running agent at its next tool boundary, via the workspace
+     * carrier hook; whatever the carrier does not reach in time still drains
+     * into the boundary turn, deduped by source ts.
+     */
+    slackNudges?: SlackNudgeHostApi;
+    /**
+     * Playground eval batches (`/v1/dev/evals*`). Present once the serve host
+     * has attached an {@link import("./evals.js").HostEvalsApi}. Used by the
+     * built-in Slack `eval` directive and available to tools/handlers.
+     */
+    evals?: import("./evals.js").HostEvalsApi;
+    /**
+     * Author-facing durable JSON KV (`agentkit/v1/{agent}/kv/…`). Backed by
+     * `agent/storage.ts` (`defineStorage`) when authored; otherwise files
+     * under `--state-root/kv`. Prefer this over ad-hoc files under the
+     * project tree so state survives host replacement.
+     */
+    kv: HostKvApi;
+    /**
+     * Author-facing durable files (`agentkit/v1/{agent}/files/…`). On
+     * Cursor-managed hosting they live in the deployment's durable store;
+     * otherwise under `--state-root/files`. Use this for file-shaped state —
+     * evidence, reports, hand-offs to a delegated run — that must outlive the
+     * process.
+     */
+    files: HostFilesApi;
+    /**
+     * Author-facing OpenTelemetry metrics and session tags. Always present.
+     * Counters and histograms no-op when no meter is running. `setAttributes`
+     * still tags the open session when a collector is attached.
+     */
+    otel: HostOtelApi;
+}
+/** Host-facing JSON key-value API attached to {@link HostContext.kv}. */
+export interface HostKvApi {
+    /** Read one value. Miss → `undefined`. */
+    get(key: string): Promise<JsonValue | undefined>;
+    /** Write or replace one value. */
+    put(key: string, value: JsonValue): Promise<void>;
+    /** Remove one key. No-op when missing. */
+    delete(key: string): Promise<void>;
+}
+/** A value plus its opaque version token, as returned by CAS-capable reads. */
+export interface KvVersionedEntry {
+    value: JsonValue;
+    /**
+     * Opaque per-key token that changes on every successful write. Callers
+     * must not parse it — backends mint whatever is cheap for them (a
+     * counter, a UUID, an `updated_at`/`xmin` pair, …).
+     */
+    version: string;
+}
+/**
+ * Outcome of a conditional write. On conflict the backend returns the
+ * entry it observed (`undefined` when the key is absent), so a CAS retry
+ * loop gets its re-read for free instead of paying a second round trip.
+ */
+export type KvCasResult = {
+    ok: true;
+    version: string;
+} | {
+    ok: false;
+    current: KvVersionedEntry | undefined;
+};
+/**
+ * Conditional-write superset of {@link HostKvApi}. Version-token CAS was
+ * chosen over compare-value: every candidate backend can mint a cheap
+ * opaque token (counter, UUID, row version), while compare-value would
+ * force deep JSON equality with key-order pitfalls on each of them. The
+ * agent-facing `host.kv` stays plain {@link HostKvApi}; storage backends
+ * supply CAS via the optional `cas` group on `defineStorage`.
+ */
+export interface HostKvCasApi extends HostKvApi {
+    /** Read one value with its version token. Miss → `undefined`. */
+    getWithVersion(key: string): Promise<KvVersionedEntry | undefined>;
+    /** Create the key only when absent. Conflict returns the existing entry. */
+    putIfAbsent(key: string, value: JsonValue): Promise<KvCasResult>;
+    /**
+     * Replace the value only when the key still carries `expectedVersion`.
+     * Conflict (version moved, or key deleted) returns the current entry.
+     */
+    putIfVersion(key: string, value: JsonValue, expectedVersion: string): Promise<KvCasResult>;
+    /** All keys under a prefix, in ascending key order. */
+    listKeys(prefix: string): Promise<string[]>;
+}
+/**
+ * Runtime probe: does this KV implement the CAS superset? Only for
+ * stores of unknown provenance — e.g. a caller-supplied {@link HostKvApi}
+ * object whose static type does not carry the CAS methods. A
+ * `defineStorage` backend declares CAS through its `cas` group instead
+ * and never needs probing.
+ */
+export declare function supportsKvCas(kv: HostKvApi): kv is HostKvCasApi;
+/**
+ * Which set of files a call addresses.
+ *
+ * `"session"` (the default) is private to one session. `"deployment"` is shared
+ * by every session of the agent and survives redeploys; `partition` subdivides
+ * it for author-chosen groupings such as a pull request or a customer.
+ */
+export type HostFilesScope = "session" | "deployment" | {
+    kind: "session";
+    sessionId?: string;
+} | {
+    kind: "deployment";
+    partition?: string;
+};
+/** Scope selector shared by every {@link HostFilesApi} call. */
+export interface HostFilesCallOptions {
+    scope?: HostFilesScope;
+}
+/** One entry from {@link HostFilesApi.list}. */
+export interface HostFileEntry {
+    /** Path within the scope, as authors address it. */
+    path: string;
+    size: number;
+    /** Last-modified epoch ms, when the sink tracks one. */
+    mtimeMs?: number;
+}
+/** Result of {@link HostFilesApi.stat}. */
+export interface HostFileStat {
+    size: number;
+    mtimeMs?: number;
+    /** Opaque version tag; pass back as `ifMatch` to make a write conditional. */
+    etag?: string;
+}
+/**
+ * What the configured sink actually supports. Read these instead of assuming:
+ * the same authored code runs against local disk, an Agent Store, and whatever
+ * a customer plugged in, and those differ in ways that change correctness.
+ */
+export interface HostFilesCapabilities {
+    /**
+     * Conditional writes are enforced, so a lost race raises
+     * `FileConflictError` instead of silently clobbering. False means
+     * last-writer-wins.
+     */
+    conflictDetection: boolean;
+    /**
+     * Files have a real local path ({@link HostFilesApi.materializedPath}) the
+     * harness can open with ordinary file tools. False means the model cannot
+     * reach them directly — only authored handler code (tools, hooks) can,
+     * through this API.
+     */
+    materialized: boolean;
+    /** Largest value the sink accepts, when it declares a limit. */
+    maxBytes?: number;
+}
+/**
+ * Durable files attached to {@link HostContext.files}.
+ *
+ * Deliberately not a filesystem: no handles, no seeking, no rename, no
+ * directories, no errno. Paths are addresses within a {@link HostFilesScope},
+ * never filesystem paths — {@link materializedPath} is the one place a real
+ * path appears, and it is `undefined` whenever the sink keeps no local copy.
+ */
+export interface HostFilesApi {
+    /** What the configured sink supports. */
+    readonly capabilities: HostFilesCapabilities;
+    /** Bind `"session"`-scoped calls to `sessionId`. */
+    forSession(sessionId: string): HostFilesApi;
+    /** Read as text. Miss → `undefined`. */
+    read(path: string, options?: HostFilesCallOptions & {
+        encoding?: BufferEncoding;
+    }): Promise<string | undefined>;
+    /** Read as bytes. Miss → `undefined`. */
+    readBytes(path: string, options?: HostFilesCallOptions): Promise<Uint8Array | undefined>;
+    /**
+     * Write or replace. Pass `ifMatch` with a {@link HostFileStat.etag} to make
+     * the write conditional, or `null` to require that it does not exist —
+     * enforced only when {@link HostFilesCapabilities.conflictDetection} is set.
+     */
+    write(path: string, data: string | Uint8Array, options?: HostFilesCallOptions & {
+        ifMatch?: string | null;
+    }): Promise<void>;
+    /** Remove one path. No-op when missing. */
+    remove(path: string, options?: HostFilesCallOptions): Promise<void>;
+    /** Entries whose path starts with `prefix` (all when omitted), in path order. */
+    list(prefix?: string, options?: HostFilesCallOptions): Promise<HostFileEntry[]>;
+    exists(path: string, options?: HostFilesCallOptions): Promise<boolean>;
+    stat(path: string, options?: HostFilesCallOptions): Promise<HostFileStat | undefined>;
+    /**
+     * Absolute local path the harness can read, or `undefined` when the sink
+     * keeps no local copy. Never use it as an identity — pass paths and scopes
+     * to the other calls so the same code works against a sink that has none.
+     */
+    materializedPath(path: string, options?: HostFilesCallOptions): string | undefined;
+}
+/** Attribute bag accepted by {@link HostOtelApi}. `undefined` values are dropped. */
+export type HostOtelAttributes = Record<string, string | number | boolean | undefined>;
+/**
+ * Author-facing OpenTelemetry surface on {@link HostContext.otel}.
+ *
+ * Metrics and tags only — no custom spans, and no raw OTel `Meter` /
+ * `Tracer`. First-party names (`cursor.token.usage`, …) and join keys
+ * (`cursor.conversation.id`, `agent_sdk.session_id`, `agent_sdk.agent`,
+ * …) are reserved.
+ */
+export interface HostOtelApi {
+    /** True when a meter is running and `increment` / `record` export. */
+    readonly enabled: boolean;
+    /**
+     * Merge tags onto this host binding. On a session-bound host they join
+     * open turn/tool spans and later first-party metrics. Unbound tags
+     * stay on this host instance only.
+     */
+    setAttributes(attributes: HostOtelAttributes): void;
+    /** Add 1 to a counter. */
+    increment(name: string, attributes?: HostOtelAttributes): void;
+    /** Add `value` to a counter. */
+    increment(name: string, value: number, attributes?: HostOtelAttributes): void;
+    /** Record one histogram observation. */
+    record(name: string, value: number, attributes?: HostOtelAttributes): void;
+}
+/** Runtime context handed to a tool's `execute`. */
+export interface ToolContext {
+    /** Correlates with `actions.requested` / `action.result` stream events. */
+    toolCallId?: string;
+    /** The session this tool call runs inside. */
+    session: SessionInfo;
+    /** Absolute path of the session's materialized workspace directory. */
+    workspaceDir: string;
+    /**
+     * Absolute path of the agent's durable state root (shared across every
+     * session of this agent).
+     */
+    stateRoot: string;
+    /** Shared host services (MCP / GitHub / Slack). */
+    host: HostContext;
+    /**
+     * Start or resume a session on any channel (cross-channel handoff).
+     * Same semantics as a channel route's `send`, with an explicit channel id.
+     * `auth` defaults to this tool call's session principal (like HTTP
+     * channel `send`); pass explicitly to override.
+     */
+    send(channelId: string, message: string, options?: SendMessageOptions): Promise<ChannelSession>;
+    /** Look up a session on a channel (e.g. refresh `sdkAgentId` after a turn). */
+    getSession(channelId: string, sessionId: string): Promise<ChannelSession | null>;
+    /**
+     * Durable artifacts, bound to this tool call's session: `tag` auto-fills
+     * `sessionId` (and `turnId` when known).
+     */
+    artifacts: ArtifactsApi;
+    /**
+     * Append a session event onto this call's in-flight turn. Same shape as a
+     * Task subagent stream (`parentCallId`, `subagent.called` /
+     * `subagent.completed`). Omitted for scratch `callTool` with no session.
+     */
+    emit?: (payload: SessionEventPayload) => void;
+    /** The session's frozen `asOf`, or the wall clock. Use instead of `Date.now()`. */
+    now(): Date;
+    /**
+     * The session's frozen instant (ISO-8601), when it has one. Present exactly
+     * when this is an `asOf` session. A tool that reaches other tools itself —
+     * the script sandbox — reads it to apply the same forward-time guard to the
+     * calls it makes, which do not pass back through the host's gate.
+     */
+    asOf?: string;
+}
+/**
+ * Where a tool's body runs.
+ *
+ * - `"server"` (default): in-process on the agent-serve host via Cursor SDK
+ *   custom tools. Only available when the agent {@link AgentConfig.runtime}
+ *   is `"local"`.
+ * - `"agent"` — materialized into the session workspace as a shell
+ *   script the Cursor agent invokes. Requires
+ *   {@link ToolConfig.script}; `execute` is not used.
+ */
+export type ToolExecution = "server" | "agent";
+/**
+ * Whether a server tool call must pause for human approval before
+ * `execute` runs. Boolean always gates; a predicate decides per call from
+ * validated input only (no {@link ToolContext} — runs before the gate).
+ */
+export type ToolNeedsApproval<TInput> = boolean | ((input: TInput) => boolean | Promise<boolean>);
+/**
+ * Whether invoking a tool can change anything outside this session.
+ *
+ * `"read"` cannot, by construction — a query, a file read, a listing.
+ * `"write"` changes something a person or another agent will later see: an
+ * external system (a comment, a message, a ticket) or shared storage another
+ * session reads back.
+ *
+ * This is what {@link SendMessageOptions.dryRun} enforces. In a dry-run
+ * session a write is answered by the host and never executed, while reads run
+ * for real — so an agent can be run against real data to see what it *would*
+ * have done.
+ *
+ * A tool that declares nothing is treated as a write: a dry run promises
+ * "nothing outside this session changed", which it cannot promise about a tool
+ * it knows nothing about. An unannotated tool is therefore useless in a dry
+ * run.
+ */
+export type ToolEffect = "read" | "write";
+/** Authored `defineConnection({ effects })` — one effect or a set. */
+export type ConnectionEffects = ToolEffect | readonly ToolEffect[];
+export declare function isToolEffect(value: unknown): value is ToolEffect;
+/**
+ * Normalize authored {@link ConnectionConfig.effects} to a unique list.
+ * Invalid values are left for discovery to reject — this only collapses
+ * `"read"` / `["read"]` / duplicates.
+ */
+export declare function normalizeConnectionEffects(effects: ConnectionEffects): ToolEffect[];
+/**
+ * Trim, drop blanks, and unique-preserve authored
+ * {@link ConnectionConfig.tools} name lists. Invalid shapes are left
+ * for discovery.
+ */
+export declare function normalizeConnectionTools(tools: readonly string[]): string[];
+/** True when `toolName` passes the connection's `tools` / `disallowedTools` filter. */
+export declare function connectionAllowsTool(filter: {
+    tools?: readonly string[];
+    disallowedTools?: readonly string[];
+}, toolName: string): boolean;
+/**
+ * A tool's declared {@link ToolEffect} — fixed, or decided per call from
+ * validated input for tools that read or write depending on their arguments
+ * (an HTTP request keyed on method, a SQL tool keyed on statement).
+ */
+export type ToolEffectDeclaration<TInput> = ToolEffect | ((input: TInput) => ToolEffect);
+export interface ToolConfig<TInput> {
+    description: string;
+    /**
+     * Where the tool body runs. Defaults to `"server"` (in-process on the
+     * agent-serve process). Use `"agent"` to materialize a workspace script
+     * the Cursor agent invokes instead.
+     */
+    execution?: ToolExecution;
+    /**
+     * Zod schema (validated before `execute` runs) or a plain JSON Schema
+     * object (forwarded to the model as-is, unvalidated). Omit to accept any
+     * JSON object.
+     */
+    inputSchema?: z.ZodType<TInput> | JsonSchemaObject;
+    /**
+     * JSON Schema for the tool's structured output (`Tool.outputSchema` from
+     * the MCP spec), as a zod schema (converted, never validated against) or a
+     * plain JSON Schema object. Advertised when declared and omitted
+     * otherwise — results are not validated against it.
+     */
+    outputSchema?: z.ZodTypeAny | JsonSchemaObject;
+    /**
+     * When true (or when the predicate returns true), the host parks the
+     * in-flight tool call until a human approves or denies via
+     * `POST /v1/session/:sessionId/approvals/:callId`. Only supported for
+     * `execution: "server"` tools on the local runtime.
+     */
+    needsApproval?: ToolNeedsApproval<TInput>;
+    /**
+     * Whether this tool changes anything outside the session. Undeclared means
+     * write, so a dry run stubs it — see {@link ToolEffect}.
+     */
+    effect?: ToolEffectDeclaration<TInput>;
+    /**
+     * Input properties that carry time bounds. In a session created with
+     * {@link SendMessageOptions.asOf}, every named argument must be an
+     * absolute ISO-8601 instant with a timezone, no later than the session's
+     * frozen instant — a call that omits one, or supplies a relative or later
+     * value, is refused so the model retries with absolute bounds. Names must
+     * exist in {@link inputSchema}; a session with `asOf` refuses to start
+     * otherwise, because a misspelled name would silently check nothing.
+     * Ignored in sessions without `asOf`.
+     */
+    timeArgs?: readonly string[];
+    /**
+     * What a write tool returns in a dry-run session instead of executing.
+     *
+     * Omit for a tool whose result the caller only acknowledges. Supply one when
+     * the result is read structurally — a caller that uses `result.revision`
+     * breaks on a bare string — so a dry run stays on the same path production
+     * takes. Ignored unless {@link effect} resolves to `"write"`.
+     */
+    dryRunResult?: ToolExecuteResult | ((input: TInput) => ToolExecuteResult);
+    /**
+     * In-process implementation. Required when {@link execution} is
+     * `"server"` (the default); ignored for `"agent"` tools.
+     */
+    execute?: (input: TInput, ctx: ToolContext) => ToolExecuteResult | Promise<ToolExecuteResult>;
+    /**
+     * Agent tools: shell script body written into the session workspace.
+     * Receives a JSON object on stdin and should print the result on
+     * stdout. Required when {@link execution} is `"agent"`.
+     */
+    script?: string;
+}
+/** Discovered tool definition with erased input generics. */
+export interface ToolDefinition extends BrandedDefinition<"tool"> {
+    readonly description: string;
+    readonly execution?: ToolExecution;
+    readonly inputSchema?: z.ZodTypeAny | JsonSchemaObject;
+    readonly outputSchema?: z.ZodTypeAny | JsonSchemaObject;
+    readonly needsApproval?: ToolNeedsApproval<never>;
+    readonly effect?: ToolEffectDeclaration<never>;
+    readonly timeArgs?: readonly string[];
+    readonly dryRunResult?: ToolExecuteResult | ((input: never) => ToolExecuteResult);
+    readonly execute?: (input: never, ctx: ToolContext) => ToolExecuteResult | Promise<ToolExecuteResult>;
+    readonly script?: string;
+}
+/** Input to `defineSkill` (authored at `agent/skills/<name>.ts`). */
+export interface SkillConfig {
+    /** Routing hint advertised to the model in the skills catalog. */
+    description?: string;
+    /** The skill body (becomes `SKILL.md`). */
+    markdown: string;
+    /** Package-relative sibling files, e.g. `references/checklist.md`. */
+    files?: Record<string, string>;
+}
+export type SkillDefinition = SkillConfig & BrandedDefinition<"skill">;
+/**
+ * Input to `defineExtension`, the `extension.ts` at the root of an
+ * agent-shaped tree (`tools/`, `skills/`, `lib/`).
+ */
+export interface ExtensionOptions<TConfig, TInput = TConfig> {
+    /** The tree's directory; pass `import.meta.dirname`. */
+    root: string;
+    /** What the extension adds; shown by `info`. */
+    description?: string;
+    /** Mount configuration schema. A consumer's settings are validated at mount. */
+    config?: z.ZodType<TConfig, z.ZodTypeDef, TInput>;
+    /** Choose which contribution groups this mount includes. */
+    contributions?: (config: TConfig) => ExtensionContributionSelection;
+}
+/** Contribution groups a configured extension mount may include or omit. */
+export interface ExtensionContributionSelection {
+    /** Include tools from the extension tree. Defaults to true. */
+    tools?: boolean;
+    /** Include skills from the extension tree. Defaults to true. */
+    skills?: boolean;
+}
+/**
+ * What `extension.ts` default-exports. A consumer calls it from
+ * `agent/extensions/<ns>.ts` to mount the extension with a configuration;
+ * the extension's own modules import it to read that configuration.
+ */
+export interface Extension<TConfig = undefined, TInput = TConfig> extends ExtensionDeclaration {
+    (...args: undefined extends TInput ? [config?: TInput] : [config: TInput]): ExtensionMount;
+    /** The mounted configuration (schema defaults applied); throws before the mount. */
+    readonly config: TConfig;
+}
+/** The mount-independent part of an {@link Extension}: an agent-shaped tree. */
+export interface ExtensionDeclaration {
+    readonly root: string;
+    readonly description: string | undefined;
+}
+/** A Cursor plugin directory declared by `cursorPlugin`. */
+export interface CursorPluginDeclaration extends ExtensionDeclaration {
+    readonly layout: "cursor-plugin";
+    readonly variables: Record<string, string>;
+}
+/** What `agent/extensions/<ns>.ts` default-exports. */
+export interface ExtensionMount extends BrandedDefinition<"extension"> {
+    readonly extension: ExtensionDeclaration | CursorPluginDeclaration;
+    readonly config: unknown;
+    readonly contributions?: ExtensionContributionSelection;
+}
+/** `cursorPlugin({ ... })`: mount a Cursor plugin directory as an extension. */
+export interface CursorPluginOptions {
+    /**
+     * The plugin directory: the one holding `.cursor-plugin/plugin.json`
+     * (or `.claude-plugin/plugin.json` / `plugin.json`). A relative path
+     * resolves against the project root.
+     */
+    path: string;
+    /**
+     * Values for the `${NAME}` placeholders in the plugin's MCP config, the
+     * variables a Cursor install prompts for. Names the mount omits fall back
+     * to `process.env`; a placeholder nothing resolves fails discovery.
+     */
+    variables?: Record<string, string>;
+}
+/**
+ * `export default disableTool()` in a directory mount's `tools/<name>.ts`
+ * removes the extension's `<ns>__<name>`.
+ */
+export type DisabledToolDefinition = BrandedDefinition<"disabled-tool">;
+/**
+ * `export default disableConnection()` in a directory mount's
+ * `mcp-connections/<server>.ts` removes the extension's `<ns>__<server>`.
+ */
+export type DisabledConnectionDefinition = BrandedDefinition<"disabled-connection">;
+/**
+ * `export default disable()` / `disableSkill()` / `disableHook()` /
+ * `disableChannel()` / `disableSchedule()` / `disableSubagent()` /
+ * `disableInstructions()` / `disableArtifacts()` in a directory mount
+ * removes that contribution from the matching overlay slot.
+ */
+export type DisabledDefinition = BrandedDefinition<"disabled">;
+/** One mounted extension and the names it contributed. */
+export interface DiscoveredExtension {
+    /** Mount namespace: the filename stem or directory name under `agent/extensions/`. */
+    name: string;
+    description?: string;
+    /** Composed tool names (`<ns>__<name>`), overrides applied. */
+    tools: string[];
+    /** Composed skill names (`<ns>__<name>`), overrides applied. */
+    skills: string[];
+    /** Composed MCP connection names (`<ns>__<server>`). */
+    connections: string[];
+    /** Composed host MCP connection names (`<ns>__<server>`). */
+    hostConnections: string[];
+    /** Composed subagent names (`<ns>__<id>`). */
+    subagents: string[];
+    /** Composed hook names (`<ns>__<name>`). */
+    hooks: string[];
+    /** Composed channel ids (`<ns>__<id>`). */
+    channels: string[];
+    /** Composed schedule names (`<ns>__<name>`). */
+    schedules: string[];
+    /** Whether the mount contributed an instructions fragment. */
+    instructions: boolean;
+    /** Workspace seed paths the mount contributed. */
+    seedFiles: string[];
+    /** Composed artifact kind names (`<ns>__<kind>`). */
+    artifactKinds: string[];
+}
+/**
+ * Transport for an MCP connection, mirroring the Cursor SDK's
+ * `McpServerConfig` shapes — plus two agent-serve variants that stay
+ * symbolic until the server starts:
+ *
+ * - `agent` addresses a **peer agent** mounted on the same serve host by
+ *   slug; it resolves to that agent's MCP endpoint (`/<slug>/v1/mcp`).
+ * - `cursorAccount` exposes the **Cursor account's MCP connectors** (the
+ *   HTTP/SSE servers the operator already authorized in Cursor). It
+ *   resolves to a bridge on this host that executes every tool **on the
+ *   Cursor backend** with the account's stored OAuth credentials — tokens
+ *   never reach this host.
+ */
+export type ConnectionTransport = {
+    type?: "stdio";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+} | {
+    type?: "http" | "sse";
+    url: string;
+    headers?: Record<string, string>;
+    /** Host PKCE OAuth; `agent-sdk mcp oauth <name>`. No Authorization header. */
+    oauth?: true;
+} | {
+    /** Slug of a peer agent mounted on the same serve host. */
+    agent: string;
+} | {
+    /** Expose the Cursor account's MCP connectors (backend-executed). */
+    cursorAccount: true;
+    /**
+     * Restrict to these connector names after discovery normalization.
+     * Authored configs may also pass `"*"` / `["*"]` (see
+     * {@link ConnectionConfig}); those normalize to `undefined` (= all).
+     */
+    servers?: string[];
+};
+/** True for the peer-agent transport variant (`{ agent: "<slug>" }`). */
+export declare function isPeerConnectionTransport(transport: ConnectionTransport): transport is {
+    agent: string;
+};
+/** True for the Cursor account transport variant (`{ cursorAccount: true }`). */
+export declare function isCursorAccountTransport(transport: ConnectionTransport): transport is {
+    cursorAccount: true;
+    servers?: string[];
+};
+/**
+ * Normalize an authored Cursor account `servers` filter.
+ *
+ * `undefined`, `"*"`, and `["*"]` (after trim) all mean every connected
+ * HTTP/SSE server on the account. Returns a concrete allowlist, or
+ * `undefined` for all. Does not validate emptiness, blank entries, or a
+ * mixed `"*"` + names list — discovery owns those diagnostics.
+ */
+export declare function normalizeCursorAccountServers(servers: string[] | "*" | undefined): string[] | undefined;
+/** True when an authored allowlist mixes `"*"` with other connector names. */
+export declare function cursorAccountServersHasMixedWildcard(servers: string[] | "*" | undefined): boolean;
+/**
+ * True for an HTTP/SSE transport authorized with host PKCE OAuth
+ * (`defineConnection({ url, oauth: true })`). The tokens live on the serve
+ * host (`mcp-auth.json` / `MCP_OAUTH_*`), so only host-side MCP clients can
+ * use them.
+ */
+export declare function isHostOauthConnectionTransport(transport: ConnectionTransport): transport is Extract<ConnectionTransport, {
+    url: string;
+}> & {
+    oauth: true;
+};
+/**
+ * True for transports that stay symbolic at discovery time and are resolved
+ * by the serve host once it is listening (peers and the Cursor account
+ * bridge). Symbolic transports never reach the SDK or the host MCP registry
+ * unresolved.
+ */
+export declare function isSymbolicConnectionTransport(transport: ConnectionTransport): boolean;
+/** One TypeScript tool on `defineConnection({ tools })`. */
+export type InlineStdioToolConfig = {
+    description: string;
+    inputSchema?: z.ZodTypeAny | JsonSchemaObject;
+    /** Output JSON Schema (zod converted, never validated); advertised when declared. */
+    outputSchema?: z.ZodTypeAny | JsonSchemaObject;
+    execute: (input: JsonObject) => unknown | Promise<unknown>;
+};
+/** `defineConnection({ tools })`. TypeScript in; stdio MCP out. */
+export type InlineStdioConnectionConfig = {
+    tools: Record<string, InlineStdioToolConfig>;
+};
+/**
+ * Authored MCP connection config (`defineConnection(...)`).
+ *
+ * For Cursor account connections, `servers` may be omitted, `"*"`, or
+ * `["*"]` to forward every connected HTTP/SSE connector; a concrete
+ * `string[]` allowlists by connector name. Discovery normalizes the
+ * wildcard forms to an unfiltered {@link ConnectionTransport}.
+ *
+ * `{ tools }` authors TypeScript handlers. Discovery packages them into a
+ * stdio MCP server the agent environment can spawn.
+ */
+export type ConnectionConfig = (((Exclude<ConnectionTransport, {
+    cursorAccount: true;
+}> | {
+    cursorAccount: true;
+    /**
+     * Which account connectors to expose.
+     *
+     * - Omit, pass `"*"`, or pass `["*"]` to forward **every** connected
+     *   HTTP/SSE server on the account (no per-connector allowlist).
+     * - Pass connector names as they appear in the Cursor account's MCP
+     *   config (e.g. `["Linear", "Notion"]`) to restrict the set.
+     */
+    servers?: string[] | "*";
+}) & {
+    /**
+     * Tool-name allowlist. Same shape as {@link AgentConfig.tools}:
+     * when set, only these MCP tool names (the server's `tools/list`
+     * names) are advertised and callable through `host.mcp`. Names
+     * the server does not list are omitted, not guessed.
+     *
+     * A list of names is an allowlist. An object of handlers authors
+     * TypeScript tools ({@link InlineStdioConnectionConfig}).
+     *
+     * On a model-visible connection this requires {@link advertiseTools}:
+     * an attached server would still expose every tool. On
+     * `host-connections/` it restricts `host.mcp` alone.
+     *
+     * Combines with {@link disallowedTools} as deny-wins.
+     */
+    tools?: readonly string[];
+}) | InlineStdioConnectionConfig) & {
+    /** Documentation only; shown in `info` output. */
+    description?: string;
+    /**
+     * Per-session auth: called at turn-build time with the session's
+     * {@link SessionInfo}, returning headers merged over the transport's
+     * static `headers` for that session's use of this connection. This is
+     * how a multi-tenant agent injects the caller's identity — it derives
+     * who the session is for host-side and mints a tenant-scoped
+     * credential; the model never sees a tenant parameter and can never
+     * choose the tenant.
+     *
+     * Derive the identity from durable session facts — `session.auth`,
+     * `session.id`, or your channel's own session state. Do **not** key it
+     * off `session.continuationKey`: it is a channel routing key, and channels
+     * may re-key it independently of the authenticated principal.
+     *
+     * Works attached or advertised. Advertised connections
+     * ({@link advertiseTools}) open per-operation clients with the
+     * evaluated headers. Attached connections ride the turn's SDK
+     * `mcpServers`, passed on every send rather than pinned on the cached
+     * per-session agent handle, so every turn — follow-ups, reminder
+     * wakes — runs on headers evaluated for that turn. The cost: when any
+     * attached connection has `auth`, *all* of the agent's attached
+     * connections are configured per send, so the harness opens fresh MCP
+     * clients for them each turn (stdio servers respawn per turn — avoid
+     * pairing an auth'd connection with a stateful stdio server), and
+     * workspace prewarm omits auth'd connections rather than attaching
+     * them without an identity.
+     *
+     * HTTP/SSE transports only, not combinable with `oauth: true`
+     * (discovery rejects both). A callback that throws fails the turn: a
+     * turn never silently runs without the connection's identity.
+     * `host.mcp` calls from server tools keep the static headers only.
+     */
+    auth?: ConnectionAuthProvider;
+    /**
+     * Advertise this connection's tools by name instead of leaving them
+     * behind the MCP meta-tools: at turn-build time the engine lists the
+     * connection's tools and synthesizes a named 1:1 passthrough server
+     * tool per entry — the server's own names, descriptions, and live
+     * schemas — merged into the authored `agent/tools/` catalog. The raw
+     * connection is then not attached to the model (it stays available on
+     * `host.mcp`), so each tool appears exactly once.
+     *
+     * Fail-closed: a `listTools` failure, an invalid tool name, or a name
+     * collision (with an authored tool or another advertised connection)
+     * fails the turn — a turn never silently runs with a shrunken toolset.
+     * The listing runs once per turn; point this at endpoints that can
+     * answer `tools/list` cheaply. Tools whose MCP `annotations.title` is
+     * `do-not-call` are omitted (vendor host-UI / MCP Apps helpers).
+     */
+    advertiseTools?: boolean;
+    /**
+     * With {@link advertiseTools}, a `listTools` or `auth` failure skips this
+     * connection (zero tools from it) instead of failing the turn. Other
+     * advertised connections still fail closed. Requires `advertiseTools`.
+     */
+    optional?: boolean;
+    /**
+     * Intended effects of tools this connection serves. When set, only
+     * tools whose classified effect is in this set are advertised — a
+     * connection that wants reads never puts a write, or a tool nothing
+     * classified, in the model's toolset.
+     *
+     * Classification is the same fail-closed read of MCP annotations the
+     * dry-run gate uses (`readOnlyHint` / `destructiveHint`). A tool the
+     * server does not classify is omitted, not guessed. Servers that leave
+     * tools unannotated stay empty here until they annotate or a trusted
+     * listing injects a known-read hint.
+     *
+     * Requires {@link advertiseTools}: this filters the named passthroughs
+     * the model sees. A single value (`"read"`) and an array (`["read"]`)
+     * are the same.
+     */
+    effects?: ConnectionEffects;
+    /**
+     * Tool-name denylist. Same shape as the Cursor SDK's
+     * `disallowedTools`: when set, these MCP tool names are omitted from
+     * the advertised set and rejected on `host.mcp`. Combines with
+     * {@link ConnectionConfig.tools} as deny-wins.
+     *
+     * On a model-visible connection this requires {@link advertiseTools}.
+     * On `host-connections/` it restricts `host.mcp` alone.
+     */
+    disallowedTools?: readonly string[];
+};
+/**
+ * Per-session connection auth on {@link ConnectionConfig.auth}: session →
+ * headers merged over the transport's static headers for that session's
+ * turns. See the field docs for the fail-closed semantics.
+ */
+export type ConnectionAuthProvider = (session: SessionInfo) => ConnectionAuthResult | Promise<ConnectionAuthResult>;
+/** What a {@link ConnectionAuthProvider} returns. */
+export type ConnectionAuthResult = {
+    headers: Record<string, string>;
+};
+/** True when the connection authors tools instead of a spawn/URL/peer. */
+export declare function isInlineStdioConnection(connection: ConnectionConfig): connection is InlineStdioConnectionConfig & {
+    description?: string;
+};
+/**
+ * An MCP connection is available to the agent (SDK `mcpServers`), host
+ * (`ctx.host.mcp`), and channel/schedule handlers.
+ */
+export type ConnectionDefinition = ConnectionConfig & BrandedDefinition<"connection">;
+/** Who initiated a session (or an authenticated channel request). */
+export interface AuthContext {
+    /** Which policy authenticated the caller, e.g. `"local-dev"`. */
+    authenticator: string;
+    principalId: string;
+    principalType: "user" | "service" | "runtime";
+    attributes?: Record<string, string>;
+}
+export interface AuthRequestInfo {
+    /** Client IP, or null when the host cannot provide it. */
+    requestIp: string | null;
+}
+/**
+ * A route auth policy. Return an {@link AuthContext} to admit the request,
+ * or null to pass to the next policy in the chain. A request is rejected
+ * with 401 when every policy in the chain returns null.
+ */
+export type AuthPolicy = (request: Request, info: AuthRequestInfo) => AuthContext | null | Promise<AuthContext | null>;
+export interface SessionEventEnvelope {
+    /** Monotonic per-session event index; reconnect with `?startIndex=`. */
+    index: number;
+    sessionId: string;
+    /** Present on turn-scoped events. */
+    turnId?: string;
+    /** ISO-8601 timestamp. */
+    at: string;
+}
+export interface ActionCall {
+    callId: string;
+    toolName: string;
+    args?: unknown;
+    /**
+     * When set, this tool call belongs to a nested subagent turn whose
+     * parent `task` tool call id is `parentCallId`.
+     */
+    parentCallId?: string;
+}
+/** Human decision for a parked {@link ToolConfig.needsApproval} tool call. */
+export type ApprovalDecision = "approve" | "deny";
+/** Durable record of a tool call waiting on human approval. */
+export interface PendingApproval {
+    callId: string;
+    turnId: string;
+    toolName: string;
+    args: unknown;
+    requestedAt: string;
+}
+/** Durable record of a tool call waiting on MCP authorization. */
+export interface PendingAuth {
+    callId: string;
+    turnId: string;
+    toolName: string;
+    connection: string;
+    authUrl: string;
+    requestedAt: string;
+}
+export type SessionEventPayload = {
+    type: "session.started";
+    data: {
+        channelId: string;
+        dryRun?: boolean;
+    };
+} | {
+    /** Cursor SDK agent id is known (cloud: `bc-…`; local: session id). */
+    type: "agent.bound";
+    data: {
+        sdkAgentId: string;
+        url?: string;
+    };
+} | {
+    type: "message.received";
+    data: {
+        text: string;
+    };
+} | {
+    /**
+     * The turn was admitted while every {@link AgentConcurrencyOptions.maxRunningTurns}
+     * slot was busy; it waits FIFO and `turn.started` follows once a slot
+     * frees. `position` is 1-based among waiting turns at enqueue time.
+     */
+    type: "turn.queued";
+    data: {
+        position: number;
+        maxRunningTurns: number;
+    };
+} | {
+    type: "turn.started";
+    data: Record<string, never>;
+} | {
+    type: "step.started";
+    data: {
+        stepId: number;
+    };
+} | {
+    type: "step.completed";
+    data: {
+        stepId: number;
+        durationMs: number;
+    };
+} | {
+    type: "reasoning.appended";
+    data: {
+        delta: string;
+        text: string;
+        parentCallId?: string;
+    };
+} | {
+    type: "reasoning.completed";
+    data: {
+        durationMs?: number;
+        parentCallId?: string;
+    };
+} | {
+    type: "message.appended";
+    data: {
+        delta: string;
+        text: string;
+        parentCallId?: string;
+    };
+} | {
+    type: "message.completed";
+    data: {
+        text: string;
+        finishReason: "stop" | "tool_call";
+        parentCallId?: string;
+    };
+} | {
+    type: "actions.requested";
+    data: {
+        calls: ActionCall[];
+        parentCallId?: string;
+    };
+} | {
+    /**
+     * A server tool with {@link ToolConfig.needsApproval} is parked until
+     * a human resolves it. The turn stays running; send follow-ups
+     * after `session.waiting` as usual.
+     */
+    type: "action.approval_requested";
+    data: {
+        callId: string;
+        toolName: string;
+        args?: unknown;
+        parentCallId?: string;
+    };
+} | {
+    type: "action.approval_resolved";
+    data: {
+        callId: string;
+        toolName: string;
+        decision: ApprovalDecision;
+        by?: string;
+        parentCallId?: string;
+    };
+} | {
+    /**
+     * A host MCP call/list needs OAuth. The turn stays running until
+     * the human completes the `authUrl` and the runtime retries.
+     */
+    type: "action.auth_requested";
+    data: {
+        callId: string;
+        toolName: string;
+        connection: string;
+        authUrl: string;
+        parentCallId?: string;
+    };
+} | {
+    type: "action.auth_resolved";
+    data: {
+        callId: string;
+        toolName: string;
+        connection: string;
+        decision: ApprovalDecision;
+        by?: string;
+        parentCallId?: string;
+    };
+} | {
+    type: "action.result";
+    data: {
+        callId: string;
+        toolName: string;
+        output?: unknown;
+        isError: boolean;
+        /**
+         * The tool never ran: a write answered by the host in a `dryRun`
+         * session. `actions.requested` still carries the arguments the model
+         * chose, so this is the marker that separates "what it would have
+         * done" from a real effect when reading a trajectory.
+         */
+        stubbed?: true;
+        parentCallId?: string;
+    };
+} | {
+    /**
+     * A dry-run call was refused because nothing classifies the tool's
+     * effect: the MCP server sent no readOnlyHint/destructiveHint and no
+     * server-side classification exists for it. The per-run count of these
+     * is the coverage signal — how much of a backtest was actually
+     * runnable, reported rather than assumed.
+     */
+    type: "action.effect_unclassified";
+    data: {
+        callId: string;
+        toolName: string;
+        connection?: string;
+    };
+} | {
+    type: "subagent.called";
+    data: {
+        callId: string;
+        name?: string;
+        description?: string;
+    };
+} | {
+    type: "subagent.completed";
+    data: {
+        callId: string;
+        name?: string;
+    };
+} | {
+    /** An artifact was tagged for this session (see {@link ArtifactsApi.tag}). */
+    type: "artifact.tagged";
+    data: {
+        id: string;
+        kind: string;
+        key?: string;
+        title?: string;
+        data: JsonValue;
+        source: ArtifactSource;
+    };
+} | {
+    type: "turn.completed";
+    data: {
+        result?: string;
+        usage?: TurnUsage;
+        cost?: TurnCost;
+    };
+} | {
+    /**
+     * The harness accepted the turn and named the run. Emitted once the
+     * send lands, so a channel can show the request id while the turn is
+     * still going rather than after it. Quote it verbatim when correlating
+     * with backend logs — never abbreviated.
+     */
+    type: "turn.bound";
+    data: {
+        requestId: string;
+    };
+} | {
+    type: "turn.failed";
+    data: {
+        message: string;
+        /** Machine-readable terminal status. Omitted on legacy stored events. */
+        status?: "error" | "cancelled";
+    };
+} | {
+    /**
+     * A Slack follow-up queued mid-turn reached the running agent: the
+     * workspace carrier moved it from `pending/` to `delivered/` at a tool
+     * boundary. Channels use this to reposition a live progress message
+     * below the follow-up, which Slack cannot do any other way.
+     */
+    type: "nudge.delivered";
+    data: Record<string, never>;
+} | {
+    type: "session.waiting";
+    data: Record<string, never>;
+} | {
+    type: "session.completed";
+    data: Record<string, never>;
+} | {
+    type: "session.failed";
+    data: {
+        message: string;
+    };
+};
+export type SessionEvent = SessionEventEnvelope & SessionEventPayload;
+export type SessionEventType = SessionEventPayload["type"];
+export interface TurnUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    reasoningTokens?: number;
+}
+/**
+ * Dollar cost of one turn's token usage (one agent loop pass).
+ * Recorded on `turn.completed` events so traces, the playground, and the
+ * CLI can aggregate spend. Computed by
+ * `POST /v1/models/estimate-cost` — billed usage events when available
+ * (credits, discounts, CTF), otherwise live catalog pricing.
+ */
+export interface TurnCost {
+    /** Charged total for the turn, in USD. */
+    totalUsd: number;
+    inputUsd: number;
+    outputUsd: number;
+    cacheReadUsd: number;
+    cacheWriteUsd: number;
+    /** Model id the cost was priced against. */
+    model: string;
+    /** `"usage"` is billed events; `"catalog"` is live list pricing. */
+    source: "usage" | "catalog";
+    rawCostCents?: number;
+    chargedCents?: number;
+}
+export type SessionMode = "chat" | "task";
+/**
+ * Why the session exists. `"eval"` is regression traffic (`defineEval` /
+ * `agent-sdk eval` / playground Evals). Default `"live"`.
+ */
+export type SessionPurpose = "live" | "eval";
+/** Read-only view of a session, handed to tools, hooks, and channel events. */
+export interface SessionInfo {
+    id: string;
+    channelId: string;
+    mode: SessionMode;
+    /** Omit / `"live"` for production traffic; `"eval"` for eval harness sessions. */
+    purpose?: SessionPurpose;
+    /** True when write-classified tool calls are answered by the host. */
+    dryRun?: boolean;
+    /** Frozen instant this session reads at; absent means the wall clock. */
+    asOf?: string;
+    auth: AuthContext | null;
+    title?: string;
+    /**
+     * Channel-local continuation key when the session is addressable for
+     * follow-ups / reminders. Null when the session is not re-keyable.
+     */
+    continuationKey?: string | null;
+    /**
+     * Cursor SDK agent id once bound (hosted ids start with `bc-`; local
+     * turns use the session id). Hosted ids are minted during the first
+     * send, so read this from a fresh `getSession()` handle after a turn
+     * completes — unless the session was created with a seeded
+     * {@link SendMessageOptions.sdkAgentId}.
+     */
+    sdkAgentId?: string;
+}
+/** Persisted session record (stored at `sessions/<id>/session.json`). */
+export interface SessionRecord {
+    sessionId: string;
+    channelId: string;
+    mode: SessionMode;
+    /**
+     * `"eval"` for harness sessions. Older records omit this (treated as
+     * `"live"`).
+     */
+    purpose?: SessionPurpose;
+    /** Frozen at create from {@link SendMessageOptions.dryRun}. */
+    dryRun?: boolean;
+    /** Frozen at create from {@link SendMessageOptions.asOf}. */
+    asOf?: string;
+    /** Channel-local continuation key; null when the session is not addressable. */
+    continuationKey: string | null;
+    /**
+     * Rotating HTTP follow-up credential for a channel-owned session.
+     * Omitted until HTTP accepts the first follow-up.
+     */
+    httpContinuationKey?: string;
+    auth: AuthContext | null;
+    title?: string;
+    channelState?: JsonValue;
+    /** Cursor SDK agent id for this session. */
+    sdkAgentId?: string;
+    /**
+     * When set, local harness turns use this directory as `cwd` (e.g. a PR
+     * worktree). Session scaffold files still land under the session workspace.
+     */
+    workspaceOverride?: string;
+    /**
+     * One-shot files for the next turn (see
+     * {@link SendMessageOptions.workspaceFiles}). Cleared after apply.
+     */
+    pendingWorkspaceFiles?: Record<string, string | {
+        encoding: "base64";
+        data: string;
+        mimeType?: string;
+    }>;
+    /**
+     * One-shot vision images for the next turn (see
+     * {@link SendMessageOptions.images}). Cleared after apply.
+     */
+    pendingImages?: Array<{
+        data: string;
+        mimeType: string;
+    }>;
+    /**
+     * Per-session cloud attach options captured at session creation, merged
+     * over the agent's static `cloud` config on every turn of this session.
+     */
+    cloudOverride?: AgentCloudOptions;
+    /**
+     * Server-tool calls parked for human approval. Cleared when resolved
+     * or when the host process restarts without a live waiter (the in-flight
+     * SDK tool callback cannot be resumed after process restart).
+     */
+    pendingApprovals?: PendingApproval[];
+    /**
+     * Server-tool MCP calls parked for host or Cursor-account OAuth.
+     * Cleared when resolved or when the host restarts without a live waiter.
+     */
+    pendingAuths?: PendingAuth[];
+    turnCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface TurnOutcome {
+    status: "finished" | "error" | "cancelled";
+    result?: string;
+    errorMessage?: string;
+    /** Stable machine-readable runner code when the failure supplied one. */
+    errorCode?: string;
+    /** Why a cancelled turn stopped, when the engine observed the boundary. */
+    cancellationReason?: "signal" | "runner";
+    usage?: TurnUsage;
+    /** Cost of {@link usage} from the Cloud Agents cost endpoint. */
+    cost?: TurnCost;
+}
+/**
+ * Session metadata returned by `GET /v1/sessions` (and consumed by the
+ * bundled playground). Includes the current wire-format continuation token:
+ * the listing is a testing/observability surface for callers already
+ * admitted by the route auth chain.
+ */
+export interface SessionSummary {
+    sessionId: string;
+    channelId: string;
+    mode: SessionMode;
+    title?: string;
+    turnCount: number;
+    /** True while a turn is executing right now (including queued turns). */
+    running: boolean;
+    /**
+     * True while the session's admitted turn is waiting for a
+     * {@link AgentConcurrencyOptions.maxRunningTurns} slot (subset of
+     * {@link running}). Omitted when the agent has no turn limit.
+     */
+    queued?: boolean;
+    createdAt: string;
+    updatedAt: string;
+    /** True when write-classified tool calls are answered by the host. */
+    dryRun?: boolean;
+    /** Active wire token for HTTP follow-ups, or null when not addressable. */
+    continuationToken: string | null;
+    /**
+     * Conversation permalink (Slack thread, else GitHub PR).
+     */
+    externalUrl?: string;
+    /** GitHub PR when the session is about one. */
+    prUrl?: string;
+}
+/**
+ * Where `GET /v1/sessions` loaded rows from.
+ * - `cursor-hosted` — durable Bugbot `agent_serve_kv` via `cursorHostedStorage`
+ * - `local` — the serve process `--state-root` session store
+ */
+export type SessionListSource = "cursor-hosted" | "local";
+/**
+ * A session handle scoped to the channel that owns it. This is what channel
+ * route handlers get back from `send()` / `getSession()`.
+ */
+export interface ChannelSession {
+    readonly id: string;
+    /** Channel-local continuation key currently addressing this session. */
+    readonly continuationToken: string | null;
+    /** True when this `send()` created the session. */
+    readonly isNew: boolean;
+    /**
+     * True when `admission: "coalesce"` enqueued this message behind an
+     * in-flight turn instead of starting immediately (Slack busy path).
+     */
+    readonly coalesced?: boolean;
+    readonly info: SessionInfo;
+    /**
+     * Replay recorded events from `startIndex`, then follow live (NDJSON).
+     * A handle from `send()` defaults `startIndex` to this admission so a
+     * resumed continuation does not replay earlier turns.
+     */
+    getEventStream(options?: {
+        startIndex?: number;
+    }): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Resolves after the currently running turn reaches a terminal event and
+     * handlers already queued for that session have settled.
+     */
+    waitForCompletion(): Promise<TurnOutcome>;
+    /** Re-key the session's channel-local continuation token. */
+    setContinuationToken(token: string | null): Promise<void>;
+}
+export interface SendMessageOptions {
+    /**
+     * Who is sending; flows to `session.auth` on newly created sessions.
+     * On HTTP channel routes, defaults to the request principal from
+     * {@link ChannelHandlerArgs.auth}. Pass explicitly to override (e.g.
+     * `null` or a Slack-derived principal).
+     */
+    auth?: AuthContext | null;
+    /**
+     * Channel-local continuation token. When it addresses an existing session
+     * the message is a follow-up; otherwise a new session is created keyed by
+     * this token. Omit to always create a fresh session.
+     *
+     * `/v2` selectors refuse this field — pass {@link mailboxContinuation} or
+     * a structured {@link claim} instead.
+     */
+    continuationToken?: string;
+    /**
+     * v2 mailbox stamp from the control plane (hosted verified ingress or
+     * the local CP). Channel adapters do not extract. Ignored on v1.
+     */
+    mailboxContinuation?: MailboxContinuation;
+    /**
+     * v2 host join. Never a concatenated `pr:owner/repo#N` string — the
+     * registry mints `cont:` bytes from this claim.
+     */
+    claim?: ContinuationClaim;
+    /** Initial channel state for newly created sessions. */
+    state?: JsonValue;
+    /**
+     * On resume (continuation hit), shallow-merge into the existing session
+     * channel state before the turn starts. Null / undefined values in the
+     * patch do not overwrite existing keys, so sticky fields (stream ts,
+     * progress banner comment id, …) survive while wake-derived fields
+     * (`headSha`, refs) refresh. Ignored on create; pass {@link state} there.
+     */
+    refreshState?: JsonValue;
+    /** Session display title (applied when creating a new session). */
+    title?: string;
+    /**
+     * Session purpose at create time. `"eval"` marks regression traffic so
+     * hooks and telemetry can tell it from live sessions.
+     */
+    purpose?: SessionPurpose;
+    /**
+     * Answer every write-classified tool call from the host instead of running
+     * it, for this session's whole life (create only — a follow-up cannot clear
+     * it, so a session that starts as a rehearsal stays one).
+     *
+     * Reads execute, writes are answered and recorded, and the arguments the
+     * model chose stay on the session log as the record of the intended action.
+     */
+    dryRun?: boolean;
+    /**
+     * ISO-8601 instant with a timezone, frozen at create: the prompt states
+     * it, {@link ToolContext.now} returns it, and every tool call is checked
+     * against it — a relative time argument (`now-1h`), an absolute one after
+     * the instant, or an omitted window a vendor schema declares is refused so
+     * the model retries with explicit absolute bounds. Tools may also declare
+     * {@link ToolConfig.timeArgs} for precise per-field checking. The check
+     * reads arguments, not behavior: a tool that reads present state without a
+     * time argument still answers from the present.
+     */
+    asOf?: string;
+    /**
+     * Absolute directory used as the local harness `cwd` for this session.
+     * On create, sets the session workspace. On resume (continuation hit),
+     * refreshes `workspaceOverride` when the path differs — e.g. a newer PR
+     * worktree after synchronize.
+     */
+    workspaceDir?: string;
+    /**
+     * Relative path to contents for the next turn. On create, queued for the
+     * first turn; on resume, merged into pending files. Prefer this over
+     * {@link workspaceDir} when you only need to inject a few host-prepared
+     * files. Values may be utf8 strings or
+     * `{ encoding: "base64", data }` blobs (Slack attachments, binary docs).
+     */
+    workspaceFiles?: Record<string, string | {
+        encoding: "base64";
+        data: string;
+        mimeType?: string;
+    }>;
+    /**
+     * Base64 images for this turn's Cursor SDK `send({ images })` (vision).
+     * Cleared after the turn starts. Slack inbound fills this from uploads.
+     */
+    images?: Array<{
+        data: string;
+        mimeType: string;
+    }>;
+    /**
+     * Per-session cloud attach options, merged over the agent's static
+     * `cloud` config (new sessions only). When set, this session attaches
+     * even if {@link AgentConfig.runtime} is `"local"`. Cannot be combined
+     * with {@link clearCloudOverride}.
+     */
+    cloud?: AgentCloudOptions;
+    /**
+     * Clear cloud attach options retained by an existing continuation
+     * session before starting this turn. Cannot be combined with
+     * {@link cloud}. No-op on a new session.
+     */
+    clearCloudOverride?: boolean;
+    /**
+     * Seed the Cursor SDK agent id for a new session (ignored when the
+     * continuation token matches an existing session). A `bc-…` value
+     * reattaches the first turn to that hosted conversation.
+     */
+    sdkAgentId?: string;
+    /**
+     * Turn admission when a session is already busy.
+     * - `"preempt"` (default) — interrupt the in-flight turn (HTTP / MCP).
+     * - `"coalesce"` — enqueue and return without interrupting (Slack).
+     */
+    admission?: "preempt" | "coalesce";
+    /**
+     * Optional source message timestamp for coalesce queue items. When a
+     * mid-turn nudge already delivered this `sourceTs`, boundary resume skips it.
+     */
+    coalesceSourceTs?: string;
+}
+export type SendMessageFn = (message: string, options?: SendMessageOptions) => Promise<ChannelSession>;
+/**
+ * Channel id recorded on the synthetic session info handed to tools invoked
+ * directly (outside any existing session).
+ */
+export declare const DIRECT_TOOL_CALL_CHANNEL_ID = "direct";
+/** Options for {@link CallToolFn} — calling an authored tool directly. */
+export interface CallToolOptions {
+    /** Who is calling; becomes the tool context's session auth. */
+    auth?: AuthContext | null;
+    /**
+     * Address the session by its wire continuation token
+     * (`<channelId>:<key>`, as `/v1/sessions` lists it). A token that maps
+     * to a live (or restorable) session behaves exactly like passing that
+     * session's {@link sessionId} — ownership check, turn serialization, and
+     * event recording included. A token with no session behind it runs the
+     * call scratch-bound with the token's channel id and continuation key as
+     * the call's session identity, so deployments whose tools resolve state
+     * from the continuation key (e.g. VFS mounts rebuilt by a binding
+     * resolver) can serve it with no live session. Mutually exclusive with
+     * {@link sessionId}.
+     */
+    continuationToken?: string;
+    /**
+     * Run the tool inside an existing session: the tool sees that session's
+     * info and materialized workspace, and the call is recorded on the
+     * session's event stream (`actions.requested` / `action.result` under a
+     * per-call `turnId`). Rejected while a model turn is running on the
+     * session. Omit to run against an ephemeral scratch workspace under
+     * `<stateRoot>/tool-calls/<callId>` (materialized with seed files and
+     * removed after the call) with a synthetic
+     * {@link DIRECT_TOOL_CALL_CHANNEL_ID} session info.
+     */
+    sessionId?: string;
+}
+/** Result of a direct (deterministic) tool call. */
+export interface ToolCallOutcome {
+    toolName: string;
+    /** Correlates with the recorded events for session-bound calls. */
+    callId: string;
+    /** True when the tool threw or returned an error envelope. */
+    isError: boolean;
+    /** Normalized result, exactly as the model would receive it. */
+    result: unknown;
+    /**
+     * Human-readable failure text when {@link isError} is true (joined text
+     * parts from the error envelope, or a string result). Prefer this over
+     * re-parsing {@link result} in channel handlers.
+     */
+    errorMessage?: string;
+    durationMs: number;
+    /** Present when the call ran inside an existing session. */
+    sessionId?: string;
+    /**
+     * Present (true) when a session-bound call could not materialize a
+     * session-owned harness cwd and ran in a scratch workspace instead.
+     * The session identity still applied (read-effect calls only get here),
+     * but `ctx.workspaceDir` was not the session workspace — callers
+     * rendering results as session state should surface this.
+     *
+     * A shared `local.workspaceDir` the host cannot create (a phantom path
+     * like `/repo`) is kept as-is and does not set this flag.
+     */
+    scratchWorkspace?: true;
+}
+/**
+ * Call an authored server tool (`agent/tools/<name>.ts`) deterministically:
+ * the input is validated against the tool's schema (zod schemas validate;
+ * plain JSON Schema inputs pass through unvalidated, matching the model
+ * path) and `execute` runs in-process, without a model turn deciding to
+ * call it. Rejects unknown tools, `execution: "agent"` tools, and invalid
+ * input by throwing.
+ */
+export type CallToolFn = (toolName: string, input?: unknown, options?: CallToolOptions) => Promise<ToolCallOutcome>;
+export type RouteMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface ChannelHandlerArgs {
+    /** Route parameters extracted from the path pattern. */
+    params: Record<string, string>;
+    requestIp: string | null;
+    /** Auth context resolved by the channel's auth chain. */
+    auth: AuthContext | null;
+    /**
+     * Validated JSON body when the route declares `bodySchema` (Zod).
+     * Prefer this over `request.json()` so the body is not read twice.
+     */
+    body?: unknown;
+    /**
+     * Validated query object when the route declares `querySchema` (Zod).
+     * Built from `URLSearchParams` (string values) before validation.
+     */
+    query?: unknown;
+    /** Shared host services (MCP / GitHub / Slack). Same as tool `ctx.host`. */
+    host: HostContext;
+    /** Start or resume a session on this channel. */
+    send: SendMessageFn;
+    /** Look up an existing session on this channel. */
+    getSession(sessionId: string): Promise<ChannelSession | null>;
+    /** Hand inbound work to a different channel (cross-channel hand-off). */
+    receive(channel: ChannelDefinition | HttpChannelDefinition | string, input: ReceiveInput): Promise<ChannelSession>;
+    /** Call an authored server tool directly (no model turn). */
+    callTool: CallToolFn;
+    /** Extend server lifetime tracking for background work. */
+    waitUntil(promise: Promise<unknown>): void;
+    /**
+     * Absolute playground + NDJSON trace URLs for a session on this agent
+     * mount (single-agent `""` or multi-agent `"/<slug>"`). Prefer this over
+     * rebuilding paths from the request URL.
+     */
+    sessionUrls(request: Request, sessionId: string): {
+        playgroundUrl: string;
+        traceUrl: string;
+    };
+    /**
+     * Durable artifacts (unbound — channel handlers have no ambient session;
+     * pass `sessionId` in `tag` input to attribute one).
+     */
+    artifacts: ArtifactsApi;
+    /** Hosted Slack admission uses this to paint a warm follow-up. */
+    hasContinuationSession?(continuationToken: string): Promise<boolean>;
+    isContinuationBusy?(continuationToken: string): Promise<boolean>;
+    getContinuationLastBotMessageTs?(continuationToken: string): Promise<string | undefined>;
+    interruptContinuation?(continuationToken: string): Promise<boolean>;
+}
+export type ChannelRouteHandler = (request: Request, args: ChannelHandlerArgs) => Response | Promise<Response>;
+/**
+ * Channel HTTP routes must declare a Zod schema (plain JSON Schema objects
+ * are not accepted — TypeScript will reject them).
+ */
+export type ChannelRouteSchema = z.ZodTypeAny;
+/** Handler args with a required, schema-inferred `query`. */
+export type ChannelHandlerArgsWithQuery<TQuery> = ChannelHandlerArgs & {
+    query: TQuery;
+};
+/** Handler args with a required, schema-inferred `body`. */
+export type ChannelHandlerArgsWithBody<TBody> = ChannelHandlerArgs & {
+    body: TBody;
+};
+/** Handler args with inferred `body` and optional inferred `query`. */
+export type ChannelHandlerArgsWithBodyAndQuery<TBody, TQuery> = ChannelHandlerArgs & {
+    body: TBody;
+    query: TQuery;
+};
+/**
+ * GET routes must declare a Zod `querySchema` (use `z.object({})` when there
+ * are no query params — path params still live on `args.params`).
+ */
+export interface ChannelGetRouteSpec<TQuery extends z.ZodTypeAny = z.ZodTypeAny> {
+    description?: string;
+    querySchema: TQuery;
+    handler: (request: Request, args: ChannelHandlerArgsWithQuery<z.infer<TQuery>>) => Response | Promise<Response>;
+}
+/**
+ * POST / PUT / PATCH routes must declare a Zod `bodySchema`. Optional
+ * `querySchema` when the route also reads search params.
+ */
+export interface ChannelBodyRouteSpec<TBody extends z.ZodTypeAny = z.ZodTypeAny, TQuery extends z.ZodTypeAny | undefined = undefined> {
+    description?: string;
+    bodySchema: TBody;
+    querySchema?: TQuery;
+    handler: (request: Request, args: TQuery extends z.ZodTypeAny ? ChannelHandlerArgsWithBodyAndQuery<z.infer<TBody>, z.infer<TQuery>> : ChannelHandlerArgsWithBody<z.infer<TBody>>) => Response | Promise<Response>;
+}
+/**
+ * DELETE routes may declare Zod schemas when useful; neither is required.
+ */
+export interface ChannelDeleteRouteSpec<TBody extends z.ZodTypeAny | undefined = undefined, TQuery extends z.ZodTypeAny | undefined = undefined> {
+    description?: string;
+    bodySchema?: TBody;
+    querySchema?: TQuery;
+    handler: ChannelRouteHandler;
+}
+export interface ChannelRoute {
+    method: RouteMethod;
+    path: string;
+    handler: ChannelRouteHandler;
+    description?: string;
+    bodySchema?: ChannelRouteSchema;
+    querySchema?: ChannelRouteSchema;
+}
+/** Input to a channel's `receive` hook (and to `args.receive(...)`). */
+export interface ReceiveInput {
+    message: string;
+    auth: AuthContext | null;
+    /** Channel-specific delivery target (e.g. a chat channel id). */
+    target?: JsonObject;
+}
+/**
+ * Per-event channel context. `state` is mutable. Turn events receive the
+ * state snapshot captured for that turn; handler mutations are recursively
+ * merged into the latest persisted state so fields refreshed by overlapping
+ * deliveries survive. At paths changed by the handler, objects merge
+ * recursively, arrays and scalars replace the latest value, and deletion
+ * removes the latest value. Events outside a turn receive current live state.
+ */
+export interface ChannelEventContext<TState = JsonValue> {
+    channelId: string;
+    state: TState;
+    continuationToken: string | null;
+    setContinuationToken(token: string | null): Promise<void>;
+}
+/** Per-event session context shared by channel `events` handlers and hooks. */
+export interface SessionContext {
+    session: SessionInfo;
+    /**
+     * Shared host services (MCP / GitHub / Slack / kv / files). Same as
+     * tool `ctx.host`. `files` and `otel` are bound to this session, so a
+     * relative path cannot read another session's files.
+     */
+    host: HostContext;
+    /**
+     * Durable artifacts bound to this event's session and turn. `tag`
+     * auto-fills both ids and rejects a conflicting explicit `sessionId`.
+     */
+    artifacts: ArtifactsApi;
+}
+export type ChannelEventHandler<TState = JsonValue, TEvent extends SessionEvent = SessionEvent> = (event: TEvent, channel: ChannelEventContext<TState>, ctx: SessionContext) => void | Promise<void>;
+/** Handlers are keyed by event type and receive the narrowed event. */
+export type ChannelEventHandlers<TState = JsonValue> = {
+    [K in SessionEventType]?: ChannelEventHandler<TState, Extract<SessionEvent, {
+        type: K;
+    }>>;
+} & {
+    "*"?: ChannelEventHandler<TState, SessionEvent>;
+};
+/** Bound helpers passed to {@link ChannelConfig.onStart}. */
+export interface ChannelStartArgs {
+    send: SendMessageFn;
+    /**
+     * Hosted architecture from {@link AgentConfig.architecture}. Discovery
+     * fills `"v2"` when the author omits it. Host pipelines that call
+     * `send()` themselves (instead of letting the channel adapter stamp
+     * continuation) branch on this so v1 `continuationToken` and v2 `claim`
+     * stay mutually exclusive.
+     */
+    architecture?: AgentArchitecture;
+    getSession(sessionId: string): Promise<ChannelSession | null>;
+    receive(channel: ChannelDefinition | HttpChannelDefinition | string, input: ReceiveInput): Promise<ChannelSession>;
+    /** Call an authored server tool directly (no model turn). */
+    callTool: CallToolFn;
+    /**
+     * Append an assistant message to a session without a model turn and without
+     * a user `message.received` bubble. Prefer this over `send()` when a host
+     * task already produced the final text (e.g. after staged `callTool`s).
+     */
+    emitAssistantMessage(sessionId: string, text: string): Promise<void>;
+    /** Shared host services (MCP / GitHub / Slack). Same as {@link ChannelHandlerArgs.host}. */
+    host: HostContext;
+    waitUntil(promise: Promise<unknown>): void;
+    /**
+     * Whether a live session already exists for a continuation token on this
+     * channel (includes lazy restore from storage).
+     */
+    hasContinuationSession(continuationToken: string): Promise<boolean>;
+    /**
+     * Whether a model turn is in flight (or being admitted) for the session
+     * addressed by this continuation token.
+     */
+    isContinuationBusy(continuationToken: string): Promise<boolean>;
+    /**
+     * Slack warm-delta watermark: last agent reply ts recorded on the session's
+     * channel state (`lastBotMessageTs`), when present.
+     */
+    getContinuationLastBotMessageTs(continuationToken: string): Promise<string | undefined>;
+    /**
+     * Interrupt the in-flight turn for a continuation token and clear any
+     * coalesced follow-ups queued behind it. Returns whether work was active.
+     */
+    interruptContinuation(continuationToken: string): Promise<boolean>;
+    /**
+     * Approve or deny a parked {@link ToolConfig.needsApproval} tool call
+     * for a session on this channel. Channel packs (e.g. Slack Block Kit
+     * buttons) use this to unblock the turn without going through the HTTP
+     * approvals route.
+     */
+    resolveApproval(sessionId: string, callId: string, decision: ApprovalDecision, auth: AuthContext | null, options?: {
+        asSessionOwner?: boolean;
+    }): Promise<PendingApproval>;
+    /**
+     * Mark a parked MCP auth as connected or cancelled. Channel packs
+     * (Slack "Connected") use this; the public OAuth callback also
+     * resolves after `finishAuth`.
+     */
+    resolveAuth(sessionId: string, callId: string, decision: ApprovalDecision, auth: AuthContext | null, options?: {
+        asSessionOwner?: boolean;
+    }): Promise<PendingAuth>;
+    /**
+     * Server log sink (same as {@link ServeOptions.logger}). Channel packs
+     * should prefer this over `console.*` so CLI/eval hosts can redirect.
+     */
+    logger: (line: string) => void;
+    /**
+     * Durable artifacts (unbound, same facade as
+     * {@link ChannelHandlerArgs.artifacts}) — for host pipelines the channel
+     * drives outside any route handler.
+     */
+    artifacts: ArtifactsApi;
+}
+/**
+ * Metadata a channel pack attaches for discovery, `projectInfo`, and CLI
+ * helpers (e.g. `agent-sdk github forward`). Most fields are descriptive;
+ * explicitly documented protocol fields may also be consumed by the host.
+ */
+export interface ChannelMeta {
+    /** Well-known pack kind, e.g. `"github"` or `"slack"`. */
+    kind?: string;
+    /**
+     * For GitHub webhook packs: the webhook event names this channel is wired
+     * to dispatch on. Used to derive `gh webhook forward --events`.
+     */
+    githubWebhookEvents?: readonly string[];
+    /**
+     * For Origin webhook packs: the Origin event types this channel is wired
+     * to dispatch on. Used by `--cursor-events` to subscribe `provider: "origin"`.
+     */
+    originWebhookEvents?: readonly string[];
+    /**
+     * For GitLab webhook packs: the `object_kind`s this channel is wired to
+     * dispatch on (`merge_request`, `note`, `push`, `pipeline`, `tag_push`).
+     */
+    gitlabWebhookEvents?: readonly string[];
+    /**
+     * For Bitbucket webhook packs: the event keys this channel is wired to
+     * dispatch on, in the Cloud vocabulary (`pullrequest:created`, …).
+     */
+    bitbucketWebhookEvents?: readonly string[];
+    /**
+     * For deployments packs: the factory event types this channel is wired
+     * to dispatch on. Extracted into the deploy manifest as `eventTypes`.
+     */
+    deploymentEventTypes?: readonly string[];
+    /**
+     * For Change Monitor checkpoint and Factory issue packs: the factory
+     * event types this channel is wired to dispatch on. Extracted into the
+     * deploy manifest as `eventTypes`. Kept separate from
+     * `deploymentEventTypes`.
+     */
+    factoryEventTypes?: readonly string[];
+    /**
+     * For Slack packs: the Events API event types this channel dispatches on
+     * (`app_mention`, `message`), derived from `engagement`. Extracted into
+     * the deploy manifest as `eventTypes` so hosted v2 fanout subscribes to
+     * exactly these. Local Socket Mode ignores it (the socket delivers
+     * whatever the app manifest subscribed to).
+     */
+    slackEventTypes?: readonly string[];
+    /**
+     * Static agentic-reply protocol for hosted Slack ingress. Only literals
+     * belong here: the control plane persists this declaration at deploy time
+     * and may act before author code starts.
+     */
+    slackReply?: {
+        mode: "agentic";
+        ack: string;
+        placeholder?: string;
+    };
+    /**
+     * For Slack packs with the opt-in channel watch: the allowlisted channels
+     * (ids or `#names`) this channel dispatches on without a mention. Surfaced
+     * by `info` so watched channels are auditable.
+     */
+    slackChannelPosts?: readonly string[];
+    /**
+     * Author-facing notices about deprecated options the pack still honored.
+     * Discovery surfaces each one as a `validate` warning on the channel file.
+     */
+    deprecations?: readonly string[];
+}
+export interface ChannelConfig<TState = JsonValue> {
+    /**
+     * Route auth chain. Defaults to `[localDevStrict()]`. Include
+     * `publicEndpoint()` to serve this channel WITHOUT the platform alias
+     * token on Cursor hosting (for webhook senders that cannot attach custom
+     * headers — the handler must verify deliveries itself).
+     */
+    auth?: AuthPolicy[];
+    routes?: ChannelRoute[];
+    /**
+     * Descriptive metadata for tooling (kind, webhook events). Attached by
+     * channel packs; ignored by the router and session engine.
+     */
+    meta?: ChannelMeta;
+    /** Initial per-session channel state (JSON-serializable). */
+    state?: TState;
+    /**
+     * Owns inbound cross-channel hand-offs. When omitted, `receive` starts a
+     * fresh session with the input message.
+     */
+    receive?: (input: ReceiveInput, args: {
+        send: SendMessageFn;
+        artifacts: ArtifactsApi;
+    }) => Promise<ChannelSession | undefined | void> | ChannelSession | void;
+    /** Stream-event handlers for sessions owned by this channel. */
+    events?: ChannelEventHandlers<TState>;
+    /** Called once when the server mounts this channel. Optional stop via onStop. */
+    onStart?: (args: ChannelStartArgs) => void | Promise<void>;
+    /** Called when the server shuts down. */
+    onStop?: () => void | Promise<void>;
+}
+export type ChannelDefinition<TState = JsonValue> = ChannelConfig<TState> & BrandedDefinition<"channel">;
+/** Configuration for the built-in HTTP session channel. */
+export interface HttpChannelConfig {
+    /** Route auth chain. Defaults to `[localDevStrict()]`. */
+    auth?: AuthPolicy[];
+    /**
+     * Continuation selector. Omit this to inherit the agent architecture's
+     * default. Set it explicitly only when migrating persisted identities.
+     */
+    continuation?: ContinuationIdentity;
+    /**
+     * Transform the inbound message before the agent sees it (e.g. prepend
+     * request-specific context).
+     */
+    onMessage?: (message: string, info: {
+        auth: AuthContext | null;
+    }) => string | Promise<string>;
+    /**
+     * Bind host state after the control plane names this session's mailbox
+     * key and before `send()`.
+     */
+    onAdmit?: (info: HttpSessionAdmitInfo) => void | Promise<void>;
+    /** Stream-event handlers for sessions created over HTTP. */
+    events?: ChannelEventHandlers;
+}
+/** Subject of a hosted HTTP startSession, seen by {@link HttpChannelConfig.onAdmit}. */
+export type HttpSessionAdmitInfo = {
+    message: string;
+    sessionKey: string;
+    dryRun?: boolean;
+    asOf?: string;
+    host: HostContext;
+};
+/** Reject a hosted startSession subject from {@link HttpChannelConfig.onAdmit}. */
+export declare class HttpSessionAdmitError extends Error {
+    readonly status: 400;
+    constructor(message: string);
+}
+export type HttpChannelDefinition = HttpChannelConfig & BrandedDefinition<"http-channel">;
+export interface HookContext extends SessionContext {
+    agent: {
+        name: string;
+    };
+    channel: {
+        id: string;
+        continuationToken: string | null;
+    };
+    /**
+     * Durable channel state for this session (the turn snapshot when
+     * dispatching inside a turn). Same blob `send({ state })` stamped;
+     * survives process restart. Null when the session has none.
+     */
+    channelState: JsonValue | null;
+    /**
+     * Absolute path of the agent's durable state root (shared across every
+     * session of this agent). Hooks that maintain derived state (e.g. the
+     * memory journal) write here.
+     */
+    stateRoot: string;
+    /**
+     * Durable artifacts, bound to this hook's session: `tag` auto-fills
+     * `sessionId` (and `turnId` when known).
+     */
+    artifacts: ArtifactsApi;
+}
+export type HookHandler<TEvent extends SessionEvent = SessionEvent> = (event: TEvent, ctx: HookContext) => void | Promise<void>;
+/** Handlers are keyed by event type and receive the narrowed event. */
+export type HookEventHandlers = {
+    [K in SessionEventType]?: HookHandler<Extract<SessionEvent, {
+        type: K;
+    }>>;
+} & {
+    "*"?: HookHandler;
+};
+export interface HookConfig {
+    events: HookEventHandlers;
+}
+export type HookDefinition = HookConfig & BrandedDefinition<"hook">;
+/** One declared artifact kind (see {@link ArtifactsConfig.kinds}). */
+export interface ArtifactKindConfig {
+    /**
+     * What this kind holds. Also the model-facing prompt for the
+     * `tag_artifact` built-in tool when {@link ArtifactsConfig.agentTool}
+     * is enabled.
+     */
+    description: string;
+    /**
+     * Optional Zod schema; `tag` validates the payload against it and
+     * persists the parsed output (defaults and coercions applied), so
+     * the schema's output must stay JSON-serializable.
+     */
+    schema?: z.ZodType;
+}
+/** Input to `defineArtifacts` (authored at `agent/artifacts.ts`). */
+export interface ArtifactsConfig {
+    /**
+     * Declared artifact kinds. With kinds declared, `tag` only accepts
+     * these; with none, any kind string is accepted freeform.
+     */
+    kinds?: Record<string, ArtifactKindConfig>;
+    /**
+     * Expose the model-facing `tag_artifact` built-in tool generated from
+     * {@link kinds}. Requires at least one declared kind.
+     */
+    agentTool?: boolean;
+    /**
+     * Retention cap (default 1000). On insert past the cap, the
+     * oldest-updated artifact is evicted.
+     */
+    max?: number;
+}
+export type ArtifactsDefinition = ArtifactsConfig & BrandedDefinition<"artifacts">;
+/** Who tagged an artifact: host code, or the model via `tag_artifact`. */
+export type ArtifactSource = "host" | "model";
+/** One durable tagged artifact. */
+export interface ArtifactRecord {
+    /** Stable id: derived from {@link key} when present, else random. */
+    id: string;
+    kind: string;
+    /** Author-chosen upsert key (same key ⇒ same id ⇒ replaces the row). */
+    key?: string;
+    title?: string;
+    data: JsonValue;
+    /** Present when the artifact carries a file/blob payload (served at `GET /v1/artifacts/:id/content`). */
+    content?: {
+        size: number;
+        contentType?: string;
+    };
+    sessionId?: string;
+    turnId?: string;
+    source: ArtifactSource;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Input to {@link ArtifactsApi.tag}. */
+export interface ArtifactTagInput {
+    /** Defaults to `"artifact"` when no kinds are declared. */
+    kind?: string;
+    data: JsonValue;
+    title?: string;
+    /** Upsert key: tagging the same key again replaces the row. */
+    key?: string;
+    /**
+     * File/blob payload, served via `GET /v1/artifacts/:id/content`.
+     * Re-tagging a keyed artifact without `contents` keeps the existing payload.
+     */
+    contents?: string | Uint8Array;
+    /** MIME type reported when serving {@link contents}. */
+    contentType?: string;
+    /**
+     * Session to attribute (and stream an `artifact.tagged` event to). On
+     * session-bound facades ({@link ToolContext.artifacts},
+     * {@link HookContext.artifacts}) this is auto-filled and a different
+     * value is rejected; unbound facades
+     * ({@link ChannelHandlerArgs.artifacts}) accept it explicitly.
+     */
+    sessionId?: string;
+    turnId?: string;
+    /** Defaults to `"host"`. */
+    source?: ArtifactSource;
+}
+/** Filter for {@link ArtifactsApi.list} and {@link ArtifactsApi.page}. */
+export interface ArtifactListFilter {
+    kind?: string;
+    sessionId?: string;
+}
+/** Options for {@link ArtifactsApi.page}. */
+export interface ArtifactPageOptions extends ArtifactListFilter {
+    /** Page size, clamped to 1–1000. Default 200. */
+    limit?: number;
+    /**
+     * Opaque resume position from the previous page's
+     * {@link ArtifactPage.nextCursor}. Pass the same filter on every page of
+     * one walk; the cursor marks a position, not a query.
+     */
+    cursor?: string;
+}
+/** One page of {@link ArtifactsApi.page} results, newest-updated first. */
+export interface ArtifactPage {
+    records: ArtifactRecord[];
+    /**
+     * Present while rows remain to examine; pass back as
+     * {@link ArtifactPageOptions.cursor}. Each call reads a bounded number of
+     * rows, so with a sparse filter a page can carry fewer records than
+     * `limit` — even none — while `nextCursor` says the walk is not done.
+     */
+    nextCursor?: string;
+}
+/**
+ * The artifacts API, attached as `ctx.artifacts` on tools
+ * ({@link ToolContext}), hooks ({@link HookContext}), and channel handlers
+ * ({@link ChannelHandlerArgs}). Tool and hook facades are session-bound:
+ * `tag` auto-fills the session; the channel facade is unbound.
+ */
+export interface ArtifactsApi {
+    /** Tag (upsert) one artifact. See {@link ArtifactTagInput}. */
+    tag(input: ArtifactTagInput): Promise<ArtifactRecord>;
+    /**
+     * Tagged artifacts, newest-updated first — the newest page only (at most
+     * 200 records). Walk the full set with {@link ArtifactsApi.page}.
+     */
+    list(filter?: ArtifactListFilter): Promise<ArtifactRecord[]>;
+    /** Bounded, cursor-paginated artifacts, newest-updated first. */
+    page(options?: ArtifactPageOptions): Promise<ArtifactPage>;
+}
+export interface ScheduleHandlerArgs {
+    /** Hand the scheduled work to a channel. */
+    receive: (channel: ChannelDefinition | HttpChannelDefinition | string, input: ReceiveInput) => Promise<ChannelSession>;
+    /** Call an authored server tool directly (no model turn). */
+    callTool: CallToolFn;
+    /** Keep the dispatch alive past handler return. */
+    waitUntil(promise: Promise<unknown>): void;
+    /** Pre-built app principal for work the agent does on its own behalf. */
+    appAuth: AuthContext;
+    /** Shared host services (MCP / GitHub / Slack). Same as tool `ctx.host`. */
+    host: HostContext;
+    /**
+     * Durable artifacts (unbound — schedule handlers have no ambient session;
+     * pass `sessionId` explicitly to attribute).
+     */
+    artifacts: ArtifactsApi;
+}
+export interface ScheduleConfig {
+    /** Standard 5-field cron expression, evaluated in UTC. */
+    cron: string;
+    /** Fire-and-forget prompt (task mode). Mutually exclusive with `run`. */
+    markdown?: string;
+    /** Handler form: full control over dispatch. */
+    run?: (args: ScheduleHandlerArgs) => void | Promise<void>;
+}
+export type ScheduleDefinition = ScheduleConfig & BrandedDefinition<"schedule">;
+/**
+ * Authored at `agent/reminders/<name>.ts`. The registry name is the module
+ * stem. Pass the discovered definition to {@link ReminderCreateInput.handler}
+ * with serializable {@link ReminderCreateInput.args}; the engine persists the
+ * stem, not the function.
+ */
+export interface ReminderHandlerConfig {
+    /**
+     * Invoked on every fire with {@link ReminderFireContext} (including the
+     * create-time {@link ReminderFireContext.args} blob).
+     */
+    run: (ctx: ReminderFireContext) => Promise<ReminderFireResult>;
+}
+export type ReminderDefinition = ReminderHandlerConfig & BrandedDefinition<"reminder">;
+export interface DiscoveredReminder {
+    name: string;
+    definition: ReminderDefinition;
+}
+export type ReminderBusyPolicy = "skipIfBusy" | "queueBehindTurn";
+/** Public reminder status. Internal claim state (`firing`) is not exposed. */
+export type ReminderStatus = "armed" | "completed" | "cancelled" | "disarmed";
+export type ReminderScheduleKind = "every" | "cron" | "delay" | "at";
+export type ReminderFireResult = {
+    action: "skip";
+    reschedule?: ReminderReschedule;
+} | {
+    action: "delivered";
+    reschedule?: ReminderReschedule;
+} | {
+    action: "stop";
+};
+export interface ReminderReschedule {
+    delay?: string | number;
+    at?: Date | string;
+}
+export interface ReminderTarget {
+    channelId: string;
+    continuationToken: string;
+    [key: string]: unknown;
+}
+export interface ReminderUntilContext {
+    id: string;
+    purpose: string;
+    fireCount: number;
+    target: ReminderTarget;
+    host: HostContext;
+    mcp: HostMcpRegistry;
+}
+/**
+ * Send fields a reminder followup may carry onto the turn it starts, the
+ * subset of {@link SendMessageOptions} a host pipeline needs when the fire
+ * itself prepares the turn (channel state for a later host hook,
+ * a session title, a cloud-attach reset). Continuation addressing stays the
+ * reminder's stored binding and is not overridable here.
+ */
+export interface ReminderFollowupOptions {
+    /** Initial channel state when the followup creates the session. */
+    state?: JsonValue;
+    /** Shallow-merged into an existing session's channel state (see {@link SendMessageOptions.refreshState}). */
+    refreshState?: JsonValue;
+    /** Session display title (applied when creating a new session). */
+    title?: string;
+    /** See {@link SendMessageOptions.clearCloudOverride}. */
+    clearCloudOverride?: boolean;
+    /**
+     * Open a new session under this principal when the stored continuation
+     * has none anywhere (pod or durable storage) — the session an inbound
+     * delivery on that key would create, so later deliveries under the same
+     * principal keep joining it. A durable session that exists but cannot be
+     * materialized still throws, matching prompt fires: opening over it would
+     * shadow the record. Omitted, a missing session also keeps the existing
+     * behavior: the followup throws.
+     */
+    openAuth?: AuthContext;
+}
+export interface ReminderFireContext extends ReminderUntilContext {
+    appAuth: AuthContext;
+    /**
+     * Serializable args from {@link ReminderCreateInput.args} when the fire
+     * uses a named {@link ReminderCreateInput.handler}. Empty object otherwise.
+     */
+    args: JsonObject;
+    /**
+     * Wake the reminder's already-bound session (target is implicit). On a
+     * hosted architecture v2 deployment this resolves after the woken turn
+     * completes, because the pod may stop once the fire's outcome is applied;
+     * locally and on v1 it resolves as soon as the turn is admitted.
+     */
+    followup(args: {
+        message: string;
+    } & ReminderFollowupOptions): Promise<ChannelSession>;
+    cancel(reason?: string): Promise<void>;
+    /**
+     * Durable artifacts (unbound — the reminder is bound to a continuation
+     * token, not a resolved session; pass `sessionId` in `tag` input to
+     * attribute one).
+     */
+    artifacts: ArtifactsApi;
+}
+/**
+ * Create a durable wake bound to a channel continuation.
+ *
+ * Exactly one of `prompt` | `handler` | `run`, and exactly one of
+ * `every` | `cron` | `delay` | `at`. Prompt fires always follow up into the
+ * bound session. Named `handler` resolves `agent/reminders/<name>.ts` on
+ * every fire (survives restart). Anonymous `run` stays supported on local
+ * and hosted v1; hosted architecture v2 rejects it at create.
+ *
+ * @example Recurring (host policy)
+ * ```ts
+ * await host.reminders.create({
+ *   purpose: "merge_conflict_watch",
+ *   channelId: "drive",
+ *   continuationToken,
+ *   every: "30m",
+ *   async run({ followup, host }) {
+ *     if (await isPrClosed(host)) return { action: "stop" };
+ *     if (!(await isConflicted(host))) return { action: "skip" };
+ *     await followup({ message: "Merge conflict detected." });
+ *     return { action: "delivered" };
+ *   },
+ * });
+ * ```
+ *
+ * @example Named handler (durable across restart / hosted v2)
+ * ```ts
+ * // agent/reminders/verdict_recheck.ts
+ * export default defineReminder({
+ *   async run({ args, followup }) {
+ *     // ...
+ *     return { action: "delivered" };
+ *   },
+ * });
+ *
+ * import verdictRecheck from "./reminders/verdict_recheck.js";
+ *
+ * await host.reminders.create({
+ *   purpose: "verdict_recheck",
+ *   channelId: "origin",
+ *   continuationToken,
+ *   delay: "15m",
+ *   handler: verdictRecheck,
+ *   args: { headSha: "abc" },
+ * });
+ * ```
+ *
+ * @example One-shot (agent tool / prompt form)
+ * ```ts
+ * await host.reminders.create({
+ *   purpose: "ci_recheck",
+ *   channelId: "drive",
+ *   continuationToken,
+ *   delay: "2h",
+ *   prompt: "Re-check CI. Only act if still failing.",
+ *   until: "Cancel once CI is green or the PR is merged.",
+ * });
+ * ```
+ */
+export interface ReminderCreateInput {
+    purpose: string;
+    /** Channel that owns the session (e.g. `drive`). */
+    channelId: string;
+    /** Channel-local continuation key for the bound session. */
+    continuationToken: string;
+    /** Optional opaque metadata (e.g. `{ prUrl }`). */
+    target?: Record<string, unknown>;
+    /** Exactly one of prompt, handler, or run. */
+    prompt?: string;
+    /**
+     * A definition discovered from `agent/reminders/<name>.ts`, or its stem
+     * for compatibility. Mutually exclusive with `prompt` and `run`. The
+     * definition form avoids coupling callers to a filename string; discovery
+     * resolves it to the stable stem persisted by the control plane. Do not
+     * combine with {@link until}; encode stop conditions in {@link args} and
+     * the handler body.
+     */
+    handler?: ReminderDefinition | string;
+    /**
+     * Serializable args for {@link handler} (UTF-8 JSON capped at 32 KiB).
+     * Only valid with `handler`.
+     */
+    args?: JsonObject;
+    run?: (ctx: ReminderFireContext) => Promise<ReminderFireResult>;
+    /** Exactly one schedule shape. */
+    every?: string;
+    cron?: string;
+    delay?: string | number;
+    at?: Date | string | number;
+    /**
+     * Auto-cancel: function (host evaluates, true → cancel) XOR prompt string
+     * (agent-facing stop condition; platform does not interpret it).
+     * Valid with `prompt` (string until) and legacy `run` (function until on
+     * local / hosted v1). Not valid with named `handler`. Function until is
+     * rejected on hosted architecture v2.
+     */
+    until?: string | ((ctx: ReminderUntilContext) => Promise<boolean>);
+    /**
+     * Defaults: recurring → `skipIfBusy`; one-shot → `queueBehindTurn`.
+     */
+    busyPolicy?: ReminderBusyPolicy;
+}
+export interface ReminderInfo {
+    id: string;
+    purpose: string;
+    channelId: string;
+    continuationToken: string;
+    target?: Record<string, unknown>;
+    scheduleKind: ReminderScheduleKind;
+    scheduleValue: string;
+    prompt?: string;
+    /** Named handler stem when create used `handler`. */
+    handler?: string;
+    /** Serializable args when create used `handler`. */
+    args?: JsonObject;
+    untilPrompt?: string;
+    busyPolicy: ReminderBusyPolicy;
+    status: ReminderStatus;
+    disarmReason?: string;
+    fireCount: number;
+    nextFireAt: string;
+    createdAt: string;
+    updatedAt: string;
+    hasRunHandler: boolean;
+    hasUntilFn: boolean;
+}
+/** Host-facing reminder API attached to {@link HostContext.reminders}. */
+export interface ReminderHostApi {
+    /** Arm a reminder. See {@link ReminderCreateInput}. */
+    create(input: ReminderCreateInput): Promise<ReminderInfo>;
+    /** List reminders, optionally filtered. */
+    list(filter?: {
+        status?: ReminderStatus;
+        purpose?: string;
+        continuationToken?: string;
+    }): Promise<ReminderInfo[]>;
+    /** Cancel one reminder by id. No-op (returns undefined) if unknown. */
+    cancel(id: string, reason?: string): Promise<ReminderInfo | undefined>;
+    /** Cancel all armed reminders for a continuation token. Returns count. */
+    cancelForContinuation(continuationToken: string, reason: string): Promise<number>;
+    /**
+     * Re-key armed reminders after a channel rotates a session's continuation
+     * token, so earlier reminders keep waking the conversation. The engine
+     * calls this from `setContinuationToken`; channels rarely need to.
+     */
+    rekeyContinuation(channelId: string, oldToken: string, newToken: string): Promise<number>;
+    /**
+     * Fire immediately (dev / hillclimb).
+     * `outcome` is `"noop"` when already firing or not armed.
+     */
+    dispatch(id: string): Promise<{
+        reminderId: string;
+        outcome: "fired" | "noop";
+        reason?: string;
+    }>;
+}
+export interface Diagnostic {
+    severity: "error" | "warning";
+    /** Repo-relative or absolute path of the offending file. */
+    path?: string;
+    message: string;
+}
+export interface DiscoveredTool {
+    name: string;
+    description: string;
+    /** JSON Schema advertised to the model. */
+    inputSchema: JsonSchemaObject;
+    /** Output JSON Schema, advertised only when the tool declares one. */
+    outputSchema?: JsonSchemaObject;
+    /** Where the tool body runs. Defaults to `"server"`. */
+    execution: ToolExecution;
+    /**
+     * True when the tool may park for human approval (boolean true or a
+     * predicate). Runtime evaluation still runs the predicate per call.
+     */
+    needsApproval: boolean;
+    /**
+     * The tool's declared {@link ToolEffect} when it declares one statically, or
+     * `"dynamic"` when it declares a predicate resolved per call. Absent when it
+     * declares nothing, which a dry run treats as a write.
+     */
+    effect?: ToolEffect | "dynamic";
+    /**
+     * MCP spec tool annotations, present only on advertised MCP passthroughs
+     * whose server declared them (see {@link HostMcpToolInfo.annotations}).
+     * Authored tools declare {@link effect} instead. Untrusted hints,
+     * propagated so the harness listing carries them and so effect
+     * classification can read them; absent is the fail-closed state.
+     */
+    annotations?: McpToolAnnotations;
+    /**
+     * True for a 1:1 MCP passthrough synthesized from an advertised
+     * connection's listing. The policy treats these differently from authored
+     * tools when nothing declares an effect: an undeclared authored tool is
+     * stubbed as a write in a dry run, an unclassifiable advertised tool is
+     * refused — see `decideToolCall`.
+     */
+    advertised?: true;
+    /** Name of the advertising connection an advertised tool came from. */
+    connection?: string;
+    /** Mounted extension this tool came from; absent for `agent/tools/`. */
+    extension?: string;
+    /**
+     * Agent tools: script body materialized under
+     * `.agent-serve/tools/<name>.sh`.
+     */
+    script?: string;
+    definition: ToolDefinition;
+}
+/** A packaged-skill sibling file: inline contents or a file to copy. */
+export type SkillFileSource = {
+    contents: string;
+} | {
+    sourcePath: string;
+};
+export interface DiscoveredSkill {
+    name: string;
+    description: string;
+    /** SKILL.md body (without generated frontmatter). */
+    markdown: string;
+    /** Package-relative sibling files. */
+    files: Record<string, SkillFileSource>;
+    /** Mounted extension this skill came from; absent for `agent/skills/`. */
+    extension?: string;
+}
+export interface DiscoveredConnection {
+    name: string;
+    transport: ConnectionTransport;
+    description?: string;
+    /** Per-session auth from {@link ConnectionConfig.auth} (http/sse only). */
+    auth?: ConnectionAuthProvider;
+    /** Advertise-by-name from {@link ConnectionConfig.advertiseTools}. */
+    advertiseTools?: boolean;
+    /** Skip a listing failure instead of failing the turn. */
+    optional?: boolean;
+    /**
+     * Normalized intended effects from {@link ConnectionConfig.effects}.
+     * Absent means every listed tool is advertised.
+     */
+    effects?: readonly ToolEffect[];
+    /**
+     * Normalized tool-name allowlist from {@link ConnectionConfig.tools}.
+     * Absent means every listed tool is kept.
+     */
+    tools?: readonly string[];
+    /**
+     * Normalized tool-name denylist from
+     * {@link ConnectionConfig.disallowedTools}.
+     */
+    disallowedTools?: readonly string[];
+}
+export interface DiscoveredChannel {
+    id: string;
+    definition: ChannelDefinition;
+}
+export interface DiscoveredSchedule {
+    name: string;
+    cron: string;
+    kind: "markdown" | "run";
+    definition: ScheduleDefinition;
+}
+export interface DiscoveredHook {
+    name: string;
+    definition: HookDefinition;
+}
+export interface SeedFile {
+    /** Path inside the session workspace. */
+    relativePath: string;
+    /** Absolute path of the authored source file. */
+    sourcePath: string;
+}
+/** A fully resolved agent (the root agent or a subagent). */
+export interface ResolvedAgent {
+    name: string;
+    description?: string;
+    model?: ModelSetting;
+    /**
+     * Remaining models from {@link AgentConfig.fallbacks}, in order. The
+     * runner steps down this list when the primary model is rejected before
+     * the turn produces output (catalog refusal or capacity).
+     */
+    modelFallbacks?: readonly ModelSetting[];
+    /**
+     * Composed system prompt: identity preamble from {@link name}, then
+     * authored `instructions.md` / `.ts` / dir (or inline `agent.ts`).
+     */
+    instructions?: string;
+    /** Execution runtime. Root agents default to `"local"`. */
+    runtime: AgentRuntime;
+    /**
+     * Authored {@link AgentConfig.root}. The factory is persisted, not a
+     * serialized tree. A resumed session calls it again (or reuses the handle).
+     */
+    root?: FileSystem | ((ctx: RootContext) => FileSystem | Promise<FileSystem>);
+    /** Resolved {@link AgentConfig.cloud} for this agent. */
+    cloud?: AgentCloudOptions;
+    /**
+     * Resolved local harness options from {@link AgentConfig.local}
+     * (`cwd` is absolute — relative paths resolved against the project root).
+     */
+    local?: AgentLocalOptions;
+    /**
+     * Built-in harness tool allowlist from {@link AgentConfig.tools}, with
+     * the "mcp" transport grant injected. Named apart from {@link tools}
+     * (the authored `agent/tools/` list).
+     */
+    allowedTools?: ToolName[];
+    /** Managed-hosting declarations from {@link AgentConfig.hosting}. */
+    hosting?: AgentHostingOptions;
+    /** Validated turn admission limits from {@link AgentConfig.concurrency}. */
+    concurrency?: AgentConcurrencyOptions;
+    /**
+     * Validated architecture from {@link AgentConfig.architecture}.
+     * Omitted authors resolve to `"v2"`. `"v2"` deploys onto the v2
+     * control plane and stamps kind `/v2` continuation defaults onto
+     * channels that omitted a selector.
+     */
+    architecture?: AgentArchitecture;
+    persistent?: boolean;
+    tools: DiscoveredTool[];
+    skills: DiscoveredSkill[];
+    /**
+     * Mounted `agent/extensions/`. Their contributions are already merged
+     * into the agent and project lists; this records provenance.
+     */
+    extensions?: DiscoveredExtension[];
+    connections: DiscoveredConnection[];
+    /**
+     * MCP connections from `agent/host-connections/`. Host tools and
+     * `mcp oauth` see them; the model does not.
+     */
+    hostConnections?: DiscoveredConnection[];
+    subagents: ResolvedAgent[];
+    seedFiles: SeedFile[];
+}
+/** The compiled project manifest produced by `loadAgentProject`. */
+export interface AgentProject {
+    /** App root (the directory containing package.json / agent/). */
+    rootDir: string;
+    /** The authored agent directory. */
+    agentDir: string;
+    name: string;
+    agent: ResolvedAgent;
+    /** Built-in HTTP session channel. */
+    httpChannel: HttpChannelDefinition;
+    channels: DiscoveredChannel[];
+    schedules: DiscoveredSchedule[];
+    /** Named reminder handlers from `agent/reminders/*` (optional / additive). */
+    reminders?: DiscoveredReminder[];
+    hooks: DiscoveredHook[];
+    /** Optional `agent/storage.ts` (`defineStorage`). */
+    storage?: StorageDefinition;
+    /** Optional `agent/artifacts.ts` (`defineArtifacts`). */
+    artifacts?: ArtifactsDefinition;
+    /** Optional `agent/otel.ts` (`defineOtel`). */
+    otel?: OtelDefinition;
+    diagnostics: Diagnostic[];
+}
+/** JSON-safe projection of one channel HTTP route on `GET /v1/info`. */
+export interface AgentChannelRouteInfo {
+    method: RouteMethod;
+    /** Authored path (e.g. `"/findings"`), or the absolute path for built-in http. */
+    path: string;
+    /** Mount path including `/v1/channels/<id>` (or absolute for built-in http). */
+    url: string;
+    description?: string;
+    bodySchema?: JsonSchemaObject;
+    querySchema?: JsonSchemaObject;
+}
+/** JSON-safe projection of the manifest returned by `GET /v1/info`. */
+export interface AgentProjectInfo {
+    name: string;
+    /** Short agent description when authored on `defineAgent`. */
+    description?: string;
+    model?: ModelSetting;
+    runtime: AgentRuntime;
+    cloud?: AgentCloudPublicInfo;
+    /** Local harness options when authored (`cwd` absolute). */
+    local?: {
+        cwd?: string;
+    };
+    /** Managed-hosting declarations when authored (egress allowlist, expected secrets, container image). */
+    hosting?: {
+        egressDomains?: string[];
+        secretNames?: string[];
+        image?: string;
+    };
+    /** Turn admission limits when authored (`concurrency` on `agent.ts`). */
+    concurrency?: {
+        maxRunningTurns?: number;
+    };
+    /**
+     * The agent's own MCP surface (mounted at `<base>/v1/mcp`): other agents
+     * and MCP clients delegate to this agent through these tools.
+     */
+    mcp: {
+        path: string;
+        tools: string[];
+    };
+    instructions?: {
+        chars: number;
+        preview: string;
+    };
+    tools: Array<{
+        name: string;
+        description: string;
+        execution: ToolExecution;
+        needsApproval: boolean;
+        /**
+         * The tool's declared {@link ToolEffect} when static, `"dynamic"` when
+         * declared as a predicate. Absent when the author declared nothing —
+         * "unknown", not "mutates".
+         */
+        effect?: ToolEffect | "dynamic";
+        inputSchema: JsonSchemaObject;
+    }>;
+    skills: Array<{
+        name: string;
+        description: string;
+    }>;
+    /** Mounted extensions and the tool / skill names each contributed. */
+    extensions: DiscoveredExtension[];
+    connections: Array<{
+        name: string;
+        transport: string;
+        advertiseTools?: boolean;
+        optional?: boolean;
+        effects?: readonly ToolEffect[];
+        tools?: readonly string[];
+        disallowedTools?: readonly string[];
+        /**
+         * Present only for `cursorAccount` connections: the connector-name
+         * allowlist, or `"*"` for every connected server. Structured twin of the
+         * `cursor-account[:a,b]` transport label so consumers (e.g. the
+         * dashboard's connector scoping) never parse the display string.
+         */
+        cursorAccountServers?: string[] | "*";
+    }>;
+    subagents: Array<{
+        name: string;
+        description?: string;
+        model?: ModelSetting;
+    }>;
+    channels: Array<{
+        id: string;
+        routes: AgentChannelRouteInfo[];
+        /** Pack kind when the channel declares one (e.g. `"github"`). */
+        kind?: string;
+        /** GitHub webhook events the channel dispatches on, when declared. */
+        githubWebhookEvents?: readonly string[];
+        /** Origin webhook event types the channel dispatches on, when declared. */
+        originWebhookEvents?: readonly string[];
+        /** GitLab `object_kind`s the channel dispatches on, when declared. */
+        gitlabWebhookEvents?: readonly string[];
+        /** Bitbucket event keys (Cloud vocabulary) the channel dispatches on. */
+        bitbucketWebhookEvents?: readonly string[];
+        /** Factory deployment event types the channel dispatches on, when declared. */
+        deploymentEventTypes?: readonly string[];
+        /** Change Monitor checkpoint or Factory issue event types the channel dispatches on, when declared. */
+        factoryEventTypes?: readonly string[];
+        /** Slack Events API event types the channel dispatches on, when declared. */
+        slackEventTypes?: readonly string[];
+        /** Slack channels watched for posts (opt-in channel watch), when declared. */
+        slackChannelPosts?: readonly string[];
+    }>;
+    schedules: Array<{
+        name: string;
+        cron: string;
+        kind: "markdown" | "run";
+    }>;
+    /** Named reminder handlers (`agent/reminders/<name>.ts`) when present. */
+    reminders?: Array<{
+        name: string;
+    }>;
+    hooks: string[];
+    /** Project storage sink from `agent/storage.ts`, when authored. */
+    storage?: {
+        name?: string;
+    };
+    otel?: {
+        serviceName?: string;
+        enabled: true;
+    };
+    /** Declared artifact kinds from `agent/artifacts.ts`, when authored. */
+    artifacts?: {
+        kinds: string[];
+        agentTool: boolean;
+        max: number;
+    };
+    diagnostics: Diagnostic[];
+}
+/**
+ * A streaming update from the harness, re-exported from the Cursor SDK's
+ * delta vocabulary.
+ */
+export type RunnerUpdate = InteractionUpdate;
+export interface RunnerSubagent {
+    name: string;
+    description: string;
+    prompt: string;
+    model?: ModelSetting;
+}
+export interface RunnerTurnRequest {
+    sessionId: string;
+    /**
+     * Cursor SDK agent id to create/resume. Defaults to {@link sessionId}
+     * for local agents; cloud agents use the persisted `bc-…` id after
+     * the first turn.
+     */
+    sdkAgentId?: string;
+    /** Absolute path of the session's materialized workspace. */
+    workspaceDir: string;
+    /** Resolved FileSystem handle when {@link AgentConfig.root} is set. */
+    root?: FileSystem;
+    /** Run the local harness sandboxed ({@link AgentLocalOptions.sandbox}). */
+    sandbox?: boolean;
+    /** Built-in tool allowlist ({@link AgentConfig.tools}, resolved). */
+    tools?: ToolName[];
+    /**
+     * Native tools hidden on the Cursor SDK agent because synthesized
+     * FileSystem tools own those names. Host-default omitted `tools` only.
+     */
+    disallowedTools?: ToolName[];
+    /** Absolute path for runner-owned durable state (conversation store). */
+    runnerStateDir: string;
+    prompt: string;
+    isFirstTurn: boolean;
+    /**
+     * Base64 images for this turn (Cursor SDK `SDKUserMessage.images`).
+     * Set from {@link SendMessageOptions.images} / Slack attachments.
+     */
+    images?: Array<{
+        data: string;
+        mimeType: string;
+    }>;
+    model?: ModelSetting;
+    /**
+     * Models to open the turn on, in order, after {@link model} is rejected
+     * (catalog refusal or `resource_exhausted` / `[unavailable]`) and before
+     * any output was streamed.
+     */
+    modelFallbacks?: readonly ModelSetting[];
+    runtime: AgentRuntime;
+    /**
+     * The agent's display name. Grokbot turns address the caller's hosted
+     * Grok Bot agent of this name: every SDK session of one agent forwards
+     * into the same hosted agent and conversation.
+     */
+    agentName?: string;
+    /** Cloud attach options for this turn, when the engine attached. */
+    cloud?: AgentCloudOptions;
+    /**
+     * Composed instructions ({@link ResolvedAgent.instructions} plus identity
+     * and tool catalog) delivered as the harness system prompt.
+     */
+    instructions?: string;
+    /**
+     * defineAgent directory slug for personal-key cloud creates. Injected
+     * by the engine — not part of authored {@link AgentCloudOptions}.
+     */
+    agentServeAgent?: string;
+    /** In-process tools, already bound to the session's tool context. */
+    customTools: Record<string, SDKCustomTool>;
+    /** MCP servers from `agent/mcp-connections/`. */
+    mcpServers: Record<string, ConnectionTransport>;
+    /**
+     * Configure {@link mcpServers} on every send instead of once on the
+     * cached SDK agent handle. Set when an attached connection has
+     * per-session `auth`: its headers are re-evaluated at turn-build time,
+     * and a handle-pinned copy would keep the first turn's credentials until
+     * the handle recycles. The SDK builds the send's MCP session from exactly
+     * this set (fresh clients each turn — stdio servers respawn per turn),
+     * and the create/resume/prewarm options carry no `mcpServers` at all, so
+     * the local executor cache key stays stable while credentials rotate.
+     */
+    perSendMcpServers?: boolean;
+    subagents: RunnerSubagent[];
+    onUpdate: (update: RunnerUpdate) => void | Promise<void>;
+    /** Called once the SDK agent is open so the engine can persist its id. */
+    onSdkAgentId?: (sdkAgentId: string) => void | Promise<void>;
+    /**
+     * Called once the harness names the run, before it produces anything.
+     * Surfaces the request id while the turn is still running rather than at
+     * its end.
+     */
+    onRequestId?: (requestId: string) => void | Promise<void>;
+    /**
+     * Abort the in-flight run when signalled. The engine aborts this when a
+     * follow-up message preempts the current turn; the runner maps it to
+     * `run.cancel()`, which tears down execution and marks the SDK run terminal.
+     */
+    signal?: AbortSignal;
+    /**
+     * Expire any run still marked active on the SDK agent before starting this
+     * one (local runtime `force`). Set on follow-up turns so a preempted or
+     * crash-wedged run can never block the next send with "already has active
+     * run".
+     */
+    forceExpireActiveRun?: boolean;
+}
+export interface ServeOptions {
+    /** Port to listen on. Defaults to 3000 (0 picks an ephemeral port). */
+    port?: number;
+    /** Host to bind. Defaults to 127.0.0.1. */
+    host?: string;
+    /**
+     * Dev mode: mounts `POST /v1/dev/schedules/:scheduleId` and
+     * `POST /v1/dev/reminders/:reminderId`, and disables the cron / reminder
+     * auto-fire runners (dispatch by hand while iterating).
+     */
+    dev?: boolean;
+    /** Durable state directory. Defaults to `<rootDir>/.agent-serve`. */
+    stateRoot?: string;
+    /**
+     * Cursor API key for the SDK runner and Cursor account MCP connections.
+     * When omitted, falls back to `CURSOR_API_KEY`, then
+     * `CURSOR_API_KEY_FILE` (hosted default `/run/cursor/secrets/CURSOR_API_KEY`
+     * when unset), then `CURSOR_SERVICE_ACCOUNT_KEY`, then the credential
+     * stored by `agent-sdk login`. A bind file wins over
+     * `CURSOR_SERVICE_ACCOUNT_KEY`.
+     */
+    apiKey?: string;
+    /** Run schedules on their cron cadence. Defaults to `!dev`. */
+    schedules?: boolean;
+    /**
+     * Arm reminder deadline timers automatically. Defaults to `!dev`
+     * (same as schedules). Prompt-form reminders still persist on the
+     * control plane in `--dev`; fire them via `POST /v1/dev/reminders/:id`
+     * or `handle.dispatchReminder`.
+     */
+    reminders?: boolean;
+    /**
+     * Serve the bundled web playground at `/playground` (chat, streaming,
+     * tool calls, sessions, schedule dispatch). Defaults to true; the API
+     * routes it drives keep their normal auth chain either way.
+     */
+    playground?: boolean;
+    /**
+     * Serve the built documentation site at `/docs` ("docs" is a reserved
+     * slug). Defaults to true. The site is auto-built when missing and the
+     * vitepress toolchain is present; published installs ship it prebuilt.
+     */
+    docs?: boolean;
+    /**
+     * Replace the default `[localDevStrict()]` route auth with
+     * `[bearerAuth(authToken)]` on every channel that doesn't author its own
+     * auth chain. Use when exposing the server beyond loopback (e.g. through
+     * a tunnel, where every request arrives from 127.0.0.1 and loopback-only
+     * policies would admit everyone). Authored `auth` arrays still win.
+     */
+    authToken?: string;
+    /**
+     * Replace the default loopback-only route auth with `[allowAll()]` on every
+     * channel that doesn't author its own auth chain. For temporary demos behind
+     * a trusted network boundary (e.g. Tailscale) — do not combine with
+     * {@link authToken}. Authored `auth` arrays still win.
+     */
+    allowAnonymous?: boolean;
+    /**
+     * Allow {@link allowAnonymous} together with
+     * `githubChannel({ cursorAccount })`. Without this opt-in, `serve` refuses
+     * to start because every admitted anonymous caller could drive sessions
+     * that hold the signed-in account's repo-scoped GitHub credential. Set it
+     * only when the network boundary already authenticates callers (e.g. an
+     * SSO/Okta proxy in front of the host).
+     */
+    allowAnonymousCursorGithub?: boolean;
+    /**
+     * Allow `--allow-anonymous` together with a `runtime: "grokbot"` mount.
+     * Off by default: grokbot turns execute on the signed-in account's hosted
+     * Grok Bot computer, so an anonymous caller could drive Shell and other
+     * box tools there. Set it only when the network boundary already
+     * authenticates callers (e.g. an SSO/Okta proxy in front of the host).
+     */
+    allowAnonymousGrokbot?: boolean;
+    /**
+     * Allow {@link allowAnonymous} together with
+     * `defineConnection({ cursorAccount: true })`. Without this opt-in, `serve`
+     * refuses to start because every admitted anonymous caller could drive the
+     * signed-in account's MCP connectors. Set it only when the network boundary
+     * already authenticates callers (e.g. an SSO/Okta proxy, or the hosted
+     * agent-serve alias token).
+     */
+    allowAnonymousCursorAccountMcp?: boolean;
+    /**
+     * Public base URL where this server is reachable from outside the host
+     * (e.g. `https://agents.example.com`).
+     */
+    publicUrl?: string;
+    /**
+     * Hosting-injected HTTP MCP URL that proxies this deployment's
+     * `/v1/mcp/tools`. The resolved Cursor API key authenticates requests.
+     */
+    cloudToolsUrl?: string;
+    /**
+     * Pull SCM webhook events from `/v0/scm-events` (Cursor account auth).
+     * GitHub and Origin subscriptions are registered independently.
+     * The stream is read as the host's Cursor user, so this requires a signed-in
+     * host: `serve` throws when no key resolves from `apiKey` here,
+     * {@link ServeOptions.apiKey}, `CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`
+     * (hosted default `/run/cursor/secrets/CURSOR_API_KEY` when unset),
+     * `CURSOR_SERVICE_ACCOUNT_KEY`, or `agent-sdk login`.
+     */
+    cursorEvents?: {
+        repos: string[];
+        baseUrl?: string;
+        apiKey?: string;
+    };
+    logger?: (line: string) => void;
+    /**
+     * OpenTelemetry export. Pass a config object, or `false` to force-disable
+     * even when `OTEL_EXPORTER_OTLP_*` env vars / `agent/otel.ts` are set.
+     * When omitted, env + authored `defineOtel` still enable export.
+     */
+    otel?: OtelConfig | false;
+}
+/** One agent mounted on a server (its URL slug + compiled project). */
+export interface MountedAgentInfo {
+    /**
+     * URL slug the agent is mounted under. Empty string in single-agent mode
+     * (routes at `/v1/...`); the directory name in multi-agent mode (routes at
+     * `/<slug>/v1/...`).
+     */
+    slug: string;
+    project: AgentProject;
+    /** Absolute base URL for this agent (server URL + `/<slug>` when slugged). */
+    url: string;
+}
+export interface AgentServeHandle {
+    url: string;
+    port: number;
+    /**
+     * The single served agent's project. In multi-agent mode this is the first
+     * mounted agent; use {@link agents} for the full set.
+     */
+    project: AgentProject;
+    /** Every agent mounted on this server. One entry in single-agent mode. */
+    agents: MountedAgentInfo[];
+    /**
+     * Dispatch a schedule by name. In multi-agent mode pass the agent slug as
+     * the second argument to target a specific agent.
+     */
+    dispatchSchedule(name: string, slug?: string): Promise<{
+        sessionIds: string[];
+    }>;
+    /**
+     * Create a per-session reminder. In multi-agent mode pass `slug` in options.
+     */
+    createReminder(input: ReminderCreateInput, slug?: string): Promise<ReminderInfo>;
+    /** List reminders for an agent. */
+    listReminders(filter?: {
+        status?: ReminderStatus;
+        purpose?: string;
+        continuationToken?: string;
+    }, slug?: string): Promise<ReminderInfo[]>;
+    /** Cancel a reminder by id. */
+    cancelReminder(id: string, options?: {
+        reason?: string;
+        slug?: string;
+    }): Promise<ReminderInfo | undefined>;
+    /**
+     * Fire a reminder immediately (same path as the deadline timer / dev route).
+     * `outcome` is `"noop"` when the reminder was already firing or not armed.
+     */
+    dispatchReminder(id: string, slug?: string): Promise<{
+        reminderId: string;
+        outcome: "fired" | "noop";
+        reason?: string;
+    }>;
+    /**
+     * Call an authored server tool deterministically (no model turn). In
+     * multi-agent mode pass the agent slug in the options to target a
+     * specific agent.
+     */
+    callTool(toolName: string, input?: unknown, options?: CallToolOptions & {
+        slug?: string;
+    }): Promise<ToolCallOutcome>;
+    /**
+     * Vite HMR playground URL when `serve --dev` auto-started it (local
+     * checkout with the vite toolchain). Prefer this over the static
+     * `/playground` mount while iterating on the SPA. Multi-agent HMR serves
+     * the agents index at this URL and each SPA at `/<slug>/playground`.
+     */
+    playgroundDevUrl?: string;
+    /** Where the built documentation site is mounted (`<url>/docs`), when served. */
+    docsUrl?: string;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map