@cursor/bdk 0.2.2 → 0.2.4

package/src/types.ts

@@ -1,3766 +0,0 @@
-/**
- * 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";
-
-// ============================================================================
-// JSON
-// ============================================================================
-
-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>;
-
-// ============================================================================
-// Definition branding
-// ============================================================================
-
-/**
- * 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;
-}
-
-// ============================================================================
-// Agent config (agent.ts)
-// ============================================================================
-
-/**
- * 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 const DEFAULT_MODEL: ModelSetting = {
-  id: "grok-4.5",
-  params: [
-    { id: "effort", value: "high" },
-    { id: "fast", value: "true" },
-  ],
-};
-
-/** 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;
-};
-
-function redactHttpUrlCredentials(url: string): string {
-  try {
-    const parsed = new URL(url);
-    if (parsed.username !== "" || parsed.password !== "") {
-      parsed.username = "";
-      parsed.password = "";
-    }
-    return parsed.toString();
-  } catch {
-    return url.replace(/^(https?:\/\/)[^@/]+@/i, "$1");
-  }
-}
-
-export function toPublicCloudInfo(cloud: AgentCloudOptions): AgentCloudPublicInfo {
-  const { envVars, repos, ...rest } = cloud;
-  const hasEnvVars = envVars !== undefined && Object.keys(envVars).length > 0;
-  return {
-    ...rest,
-    ...(repos !== undefined
-      ? {
-          repos: repos.map(repo => ({
-            ...repo,
-            url: redactHttpUrlCredentials(repo.url),
-            ...(repo.prUrl !== undefined ? { prUrl: redactHttpUrlCredentials(repo.prUrl) } : {}),
-          })),
-        }
-      : {}),
-    ...(hasEnvVars ? { envVarsConfigured: true } : {}),
-  };
-}
-
-/**
- * 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 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">;
-
-// ============================================================================
-// Tools (agent/tools/*.ts)
-// ============================================================================
-
-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 function supportsKvCas(kv: HostKvApi): kv is HostKvCasApi {
-  const candidate = kv as Partial<HostKvCasApi>;
-  return (
-    typeof candidate.getWithVersion === "function" &&
-    typeof candidate.putIfAbsent === "function" &&
-    typeof candidate.putIfVersion === "function" &&
-    typeof candidate.listKeys === "function"
-  );
-}
-
-/**
- * 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` / `actions.completed` 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[];
-
-const TOOL_EFFECTS: readonly ToolEffect[] = ["read", "write"];
-
-export function isToolEffect(value: unknown): value is ToolEffect {
-  return value === "read" || value === "write";
-}
-
-/**
- * Normalize authored {@link ConnectionConfig.effects} to a unique list.
- * Invalid values are left for discovery to reject — this only collapses
- * `"read"` / `["read"]` / duplicates.
- */
-export function normalizeConnectionEffects(effects: ConnectionEffects): ToolEffect[] {
-  const list = typeof effects === "string" ? [effects] : [...effects];
-  const unique: ToolEffect[] = [];
-  for (const effect of TOOL_EFFECTS) {
-    if (list.includes(effect)) {
-      unique.push(effect);
-    }
-  }
-  return unique;
-}
-
-/**
- * Trim, drop blanks, and unique-preserve authored
- * {@link ConnectionConfig.tools} name lists. Invalid shapes are left
- * for discovery.
- */
-export function normalizeConnectionTools(tools: readonly string[]): string[] {
-  const unique: string[] = [];
-  const seen = new Set<string>();
-  for (const raw of tools) {
-    const name = raw.trim();
-    if (name === "" || seen.has(name)) {
-      continue;
-    }
-    seen.add(name);
-    unique.push(name);
-  }
-  return unique;
-}
-
-/** True when `toolName` passes the connection's `tools` / `disallowedTools` filter. */
-export function connectionAllowsTool(
-  filter: {
-    tools?: readonly string[];
-    disallowedTools?: readonly string[];
-  },
-  toolName: string,
-): boolean {
-  if (filter.tools !== undefined && !filter.tools.includes(toolName)) {
-    return false;
-  }
-  return filter.disallowedTools === undefined || !filter.disallowedTools.includes(toolName);
-}
-
-/**
- * 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;
-}
-
-// ============================================================================
-// Skills (agent/skills/*)
-// ============================================================================
-
-/** 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">;
-
-// ============================================================================
-// Extensions (agent/extensions/<ns>.ts | agent/extensions/<ns>/extension.ts)
-// ============================================================================
-
-/**
- * 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[];
-}
-
-// ============================================================================
-// MCP connections (agent/mcp-connections/*.ts)
-// ============================================================================
-
-/**
- * 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 function isPeerConnectionTransport(
-  transport: ConnectionTransport,
-): transport is { agent: string } {
-  return "agent" in transport;
-}
-
-/** True for the Cursor account transport variant (`{ cursorAccount: true }`). */
-export function isCursorAccountTransport(
-  transport: ConnectionTransport,
-): transport is { cursorAccount: true; servers?: string[] } {
-  return "cursorAccount" in transport && transport.cursorAccount === true;
-}
-
-/**
- * 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 function normalizeCursorAccountServers(
-  servers: string[] | "*" | undefined,
-): string[] | undefined {
-  if (servers === undefined || servers === "*") {
-    return undefined;
-  }
-  const trimmed = servers.map(server => server.trim());
-  if (trimmed.length === 1 && trimmed[0] === "*") {
-    return undefined;
-  }
-  return [...servers];
-}
-
-/** True when an authored allowlist mixes `"*"` with other connector names. */
-export function cursorAccountServersHasMixedWildcard(servers: string[] | "*" | undefined): boolean {
-  if (servers === undefined || servers === "*") {
-    return false;
-  }
-  const trimmed = servers.map(server => server.trim());
-  return trimmed.includes("*") && trimmed.some(server => server !== "*");
-}
-
-/**
- * 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 function isHostOauthConnectionTransport(
-  transport: ConnectionTransport,
-): transport is Extract<ConnectionTransport, { url: string }> & {
-  oauth: true;
-} {
-  return "url" in transport && transport.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 function isSymbolicConnectionTransport(transport: ConnectionTransport): boolean {
-  return isPeerConnectionTransport(transport) || isCursorAccountTransport(transport);
-}
-
-/** 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 function isInlineStdioConnection(
-  connection: ConnectionConfig,
-): connection is InlineStdioConnectionConfig & {
-  description?: string;
-} {
-  return (
-    "tools" in connection && connection.tools !== undefined && !Array.isArray(connection.tools)
-  );
-}
-
-/**
- * An MCP connection is available to the agent (SDK `mcpServers`), host
- * (`ctx.host.mcp`), and channel/schedule handlers.
- */
-export type ConnectionDefinition = ConnectionConfig & BrandedDefinition<"connection">;
-
-// ============================================================================
-// Auth
-// ============================================================================
-
-/** 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>;
-
-// ============================================================================
-// Session events (the NDJSON stream vocabulary)
-// ============================================================================
-
-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;
-  /**
-   * Model generation that requested this call. Every tool from one
-   * `runStep` shares the same id (the step's invocation id).
-   */
-  modelCallId?: string;
-}
-
-/** One tool result inside an {@link SessionEventPayload} `actions.completed` batch. */
-export interface ActionResult {
-  callId: string;
-  toolName: string;
-  output?: unknown;
-  isError: boolean;
-  stubbed?: true;
-  parentCallId?: string;
-  modelCallId?: 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;
-        /**
-         * Same id as {@link ActionCall.modelCallId} on every call.
-         * One envelope per model step (a single tool is a batch of one)
-         * once that step has finished listing tools.
-         */
-        modelCallId?: 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;
-        /** Same id as the matching {@link ActionCall.modelCallId}. */
-        modelCallId?: string;
-      };
-    }
-  | {
-      /**
-       * Every result for one {@link SessionEventPayload} `actions.requested`
-       * batch. Pair these two events; `action.result` stays the live
-       * per-call envelope for chips and spans.
-       */
-      type: "actions.completed";
-      data: {
-        results: ActionResult[];
-        parentCallId?: string;
-        modelCallId?: 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;
-}
-
-// ============================================================================
-// Sessions
-// ============================================================================
-
-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>;
-
-// ============================================================================
-// Direct tool calls (deterministic invocation, no model turn)
-// ============================================================================
-
-/**
- * Channel id recorded on the synthetic session info handed to tools invoked
- * directly (outside any existing session).
- */
-export 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>;
-
-// ============================================================================
-// Channels (agent/channels/*.ts)
-// ============================================================================
-
-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 },
-    // biome-ignore lint/suspicious/noConfusingVoidType: hooks may return a session, nothing, or an async nothing
-  ) => 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 class HttpSessionAdmitError extends Error {
-  readonly status = 400 as const;
-  constructor(message: string) {
-    super(message);
-    this.name = "HttpSessionAdmitError";
-  }
-}
-
-export type HttpChannelDefinition = HttpChannelConfig & BrandedDefinition<"http-channel">;
-
-// ============================================================================
-// Hooks (agent/hooks/*.ts)
-// ============================================================================
-
-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">;
-
-// ============================================================================
-// Artifacts (agent/artifacts.ts)
-// ============================================================================
-
-/** 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). Architecture v1 and self-hosted v2
-   * evict the oldest-updated artifact on insert past the cap. Hosted
-   * architecture v2 does not evict; the installation store keeps every row.
-   */
-  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>;
-}
-
-// ============================================================================
-// Schedules (agent/schedules/*)
-// ============================================================================
-
-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">;
-
-// ============================================================================
-// Reminder handlers (agent/reminders/*) — named durable fire policies
-// ============================================================================
-
-/**
- * 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;
-}
-
-// ============================================================================
-// Reminders (runtime per-session wakes)
-// ============================================================================
-
-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;
-  }>;
-}
-
-// ============================================================================
-// Discovery / manifest
-// ============================================================================
-
-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[];
-}
-
-// ============================================================================
-// Runner (the Cursor SDK seam)
-// ============================================================================
-
-/**
- * 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;
-}
-
-// ============================================================================
-// Serving
-// ============================================================================
-
-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>;
-}