@cursor/july 0.1.1

package/src/types.ts

@@ -0,0 +1,1848 @@
+/**
+ * Public types for @anysphere/agent-serve.
+ *
+ * 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 } from "@cursor/sdk";
+import type { z } from "zod";
+import type { ABConfigFile } from "./ab.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"
+  | "connection"
+  | "channel"
+  | "http-channel"
+  | "schedule"
+  | "reminder"
+  | "hook"
+  | "eval"
+  | "ab";
+
+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" },
+  ],
+};
+
+/**
+ * Where turns execute. `"local"` (default) uses the Cursor SDK local
+ * harness on this machine; `"cloud"` runs on Cursor cloud agents.
+ */
+export type AgentRuntime = "local" | "cloud";
+
+/**
+ * Cloud-only options forwarded to the Cursor SDK's `cloud` field on
+ * `Agent.create` / `Agent.resume`. Ignored when {@link AgentConfig.runtime}
+ * is `"local"` (the default).
+ */
+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 } : {}),
+  };
+}
+
+/** 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;
+  /**
+   * 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"`. Use `"cloud"` to run turns
+   * on Cursor cloud agents (see {@link cloud}).
+   */
+  runtime?: AgentRuntime;
+  /**
+   * Cloud agent defaults. Used when {@link runtime} is `"cloud"`, and as
+   * the base merged under per-session {@link SendMessageOptions.cloud}
+   * (so a local agent can still open cloud-attached sessions from a
+   * channel or tool handoff). In-process `agent/tools` are only available
+   * on local turns; cloud sessions should prefer MCP / workspace tools.
+   */
+  cloud?: AgentCloudOptions;
+  /**
+   * Local harness defaults (ignored for cloud turns). Counterpart to
+   * {@link cloud}.
+   */
+  local?: AgentLocalOptions;
+}
+
+/**
+ * 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. Prefer a path
+   * outside large monorepos so Cursor `project` settings do not inherit
+   * ambient `AGENTS.md` / `.cursor` rules.
+   */
+  cwd?: string;
+}
+
+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 };
+
+/** 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>;
+}
+
+export interface HostMcpToolInfo {
+  name: string;
+  description?: string;
+  inputSchema?: JsonObject;
+}
+
+export interface HostMcpCallResult {
+  content: Array<
+    | { type: "text"; text: string }
+    | { type: "image"; data: string; mimeType?: string }
+    | { type: string; [key: string]: unknown }
+  >;
+  isError?: boolean;
+  structuredContent?: JsonObject;
+}
+
+/**
+ * Shared host services available on every tool / 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/*`). 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;
+}
+
+/** Runtime context handed to a tool's `execute`. */
+export interface ToolContext {
+  /** Correlates with `actions.requested` / `action.result` stream events. */
+  toolCallId?: string;
+  /** The session this tool call runs inside. */
+  session: SessionInfo;
+  /** Absolute path of the session's materialized workspace directory. */
+  workspaceDir: string;
+  /** 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
+   * — e.g. a chat tool that opens a `drive` cloud session for a PR.
+   * `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>;
+}
+
+/**
+ * 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 (local harness or cloud VM). 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>);
+
+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;
+  /**
+   * 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>;
+  /**
+   * 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 needsApproval?: ToolNeedsApproval<never>;
+  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">;
+
+// ============================================================================
+// 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>;
+    }
+  | {
+      /** 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 (as they appear in the Cursor
+       * account's MCP config, e.g. `["Linear", "Notion"]`). Omit to expose
+       * every connected HTTP/SSE server on the account.
+       */
+      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;
+}
+
+/**
+ * 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)
+  );
+}
+
+export type ConnectionConfig = ConnectionTransport & {
+  /** Documentation only; shown in `info` output. */
+  description?: string;
+};
+
+/**
+ * An MCP connection is always available in three places:
+ * - the Cursor agent (SDK `mcpServers`, local or cloud)
+ * - the agent-serve host (`ctx.host.mcp` on in-process tools)
+ * - channel / schedule handlers (`args.host.mcp`)
+ */
+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;
+}
+
+/** 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;
+}
+
+export type SessionEventPayload =
+  | { type: "session.started"; data: { channelId: string } }
+  | {
+      /**
+       * Sticky A/B enrollment for one experiment (`defineAB` under `agent/ab`).
+       * Appended at session creation (before the first turn). `variant` is a
+       * key of the experiment's `variants`, or `null` for sticky skip.
+       */
+      type: "ab.assigned";
+      data: { experiment: string; variant: string | null };
+    }
+  | {
+      /** 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 } }
+  | { 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 } }
+  | { type: "reasoning.completed"; data: { durationMs?: number } }
+  | { type: "message.appended"; data: { delta: string; text: string } }
+  | {
+      type: "message.completed";
+      data: { text: string; finishReason: "stop" | "tool_call" };
+    }
+  | { type: "actions.requested"; data: { calls: ActionCall[] } }
+  | {
+      /**
+       * 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;
+      };
+    }
+  | {
+      type: "action.approval_resolved";
+      data: {
+        callId: string;
+        toolName: string;
+        decision: ApprovalDecision;
+        by?: string;
+      };
+    }
+  | {
+      type: "action.result";
+      data: {
+        callId: string;
+        toolName: string;
+        output?: unknown;
+        isError: boolean;
+      };
+    }
+  | {
+      type: "subagent.called";
+      data: { callId: string; name?: string; description?: string };
+    }
+  | { type: "subagent.completed"; data: { callId: string; name?: string } }
+  | {
+      type: "turn.completed";
+      data: { result?: string; usage?: TurnUsage };
+    }
+  | { type: "turn.failed"; data: { message: string } }
+  | { 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;
+}
+
+// ============================================================================
+// Sessions
+// ============================================================================
+
+export type SessionMode = "chat" | "task";
+
+/**
+ * Why the session exists. `"eval"` is regression traffic (`defineEval` /
+ * `agent-serve eval` / playground Evals) and is excluded from live A/B
+ * enrollment. 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;
+  auth: AuthContext | null;
+  title?: string;
+  /**
+   * Sticky A/B arms for this session (`defineAB`): experiment name → variant
+   * key, or `null` for sticky skip. Present after enrollment at session
+   * create (live traffic only). Tools/hooks/harness overlays read this.
+   */
+  abs?: Readonly<Record<string, string | null>>;
+  /**
+   * 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 (cloud: `bc-…`, local: session id).
+   * Cloud 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 — skipped by {@link defineAB} enrollment.
+   * Older records omit this (treated as `"live"`).
+   */
+  purpose?: SessionPurpose;
+  /**
+   * Denormalized sticky A/B arms (mirrors durable `ab.assigned` events) so
+   * the agent loop / tools can read arms without re-folding the log. Source
+   * of truth for stickiness remains the event stream.
+   */
+  abs?: Record<string, string | null>;
+  /** Channel-local continuation key; null when the session is not addressable. */
+  continuationKey: string | null;
+  auth: AuthContext | null;
+  title?: string;
+  channelState?: JsonValue;
+  /**
+   * Cursor SDK agent id for this session. Local agents use the
+   * framework session id; cloud agents use a `bc-…` id (especially when
+   * `cloud.envVars` forces the server to mint).
+   */
+  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 to write into the harness cwd before the next turn
+   * (see {@link SendMessageOptions.workspaceFiles}). Cleared after apply.
+   */
+  pendingWorkspaceFiles?: Record<string, string>;
+  /**
+   * Per-session cloud options captured at session creation, merged over the
+   * agent's static `cloud` config on every turn of this session. Lets a
+   * cloud agent target a per-session repo/PR (see {@link SendMessageOptions.cloud}).
+   */
+  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[];
+  turnCount: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface TurnOutcome {
+  status: "finished" | "error" | "cancelled";
+  result?: string;
+  errorMessage?: string;
+  usage?: TurnUsage;
+}
+
+/**
+ * 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. */
+  running: boolean;
+  createdAt: string;
+  updatedAt: string;
+  /** `<channelId>:<key>` wire token, or null when not addressable. */
+  continuationToken: string | null;
+  /**
+   * Optional deep link to the external conversation (e.g. Slack thread).
+   * Populated for channel-driven sessions when the principal carries enough
+   * attributes to build a permalink.
+   */
+  externalUrl?: string;
+}
+
+/**
+ * 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;
+  readonly info: SessionInfo;
+  /** Replay recorded events from `startIndex`, then follow live (NDJSON). */
+  getEventStream(options?: {
+    startIndex?: number;
+  }): Promise<ReadableStream<Uint8Array>>;
+  /** Resolves when the currently running turn reaches a terminal event. */
+  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.
+   */
+  continuationToken?: string;
+  /** Initial channel state for newly created sessions. */
+  state?: JsonValue;
+  /** Session display title (applied when creating a new session). */
+  title?: string;
+  /**
+   * Session purpose at create time. `"eval"` skips sticky A/B enrollment
+   * (`defineAB`) so regression runs do not mix into live metrics.
+   */
+  purpose?: SessionPurpose;
+  /**
+   * 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 → contents written into the session harness cwd after
+   * scaffold materialize and before the next turn. On create, queued for
+   * the first turn; on resume, replaces any pending files. Prefer this
+   * over {@link workspaceDir} when you only need to inject a few
+   * host-prepared files (skills/AGENTS.md still land in the normal
+   * session workspace).
+   */
+  workspaceFiles?: Record<string, string>;
+  /**
+   * Per-session cloud options, merged over the agent's static `cloud`
+   * config (new sessions only). When set, this session runs as cloud even
+   * if the agent's default {@link AgentConfig.runtime} is `"local"` —
+   * so chat can stay local (server tools) while a handoff attaches a PR
+   * to a cloud VM. Ignored when the agent has no cloud capability and
+   * runtime is forced local with no override path.
+   */
+  cloud?: AgentCloudOptions;
+  /**
+   * Seed the Cursor SDK agent id for a **new** session (ignored when the
+   * continuation token matches an existing session). For cloud agents this
+   * reattaches the session to an existing cloud conversation (`bc-…`): the
+   * first turn resumes that agent instead of creating a new one, so
+   * follow-ups keep landing on the same bcId even after the local session
+   * store is gone.
+   */
+  sdkAgentId?: 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;
+  /**
+   * 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;
+}
+
+/**
+ * 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 };
+}
+
+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;
+}
+
+/** @deprecated Prefer {@link ChannelGetRouteSpec} / {@link ChannelBodyRouteSpec}. */
+export type ChannelRouteSpec =
+  | ChannelGetRouteSpec
+  | ChannelBodyRouteSpec
+  | ChannelDeleteRouteSpec;
+
+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: live (persisted) state plus session ops. */
+export interface ChannelEventContext<TState = JsonValue> {
+  channelId: string;
+  state: TState;
+  continuationToken: string | null;
+  setContinuationToken(token: string | null): Promise<void>;
+}
+
+export interface SessionContext {
+  session: SessionInfo;
+}
+
+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;
+  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;
+  /**
+   * 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>;
+  /**
+   * 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;
+}
+
+/**
+ * Descriptive metadata a channel pack attaches for tooling. Read by
+ * discovery / `projectInfo` and CLI helpers (e.g. `agent-serve github
+ * forward`) — it never affects routing or dispatch.
+ */
+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 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[];
+  /**
+   * For Slack packs riding the signed-in Cursor account's Slack connection
+   * (`slackChannel({ cursorAccount: true })`): inbound relays from
+   * `/v0/slack-events` instead of Socket Mode.
+   */
+  slackCursorAccount?: boolean;
+}
+
+export interface ChannelConfig<TState = JsonValue> {
+  /** Route auth chain. Defaults to `[localDevStrict()]`. */
+  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 }
+    // 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[];
+  /**
+   * 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>;
+  /** Stream-event handlers for sessions created over HTTP. */
+  events?: ChannelEventHandlers;
+}
+
+export type HttpChannelDefinition = HttpChannelConfig &
+  BrandedDefinition<"http-channel">;
+
+// ============================================================================
+// Hooks (agent/hooks/*.ts)
+// ============================================================================
+
+export interface HookContext {
+  agent: { name: string };
+  channel: { id: string; continuationToken: string | null };
+  session: SessionInfo;
+}
+
+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">;
+
+// ============================================================================
+// 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;
+}
+
+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">;
+
+// ============================================================================
+// Reminders (runtime per-session wakes)
+// ============================================================================
+
+export type ReminderBusyPolicy = "skipIfBusy" | "queueBehindTurn";
+
+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;
+}
+
+export interface ReminderFireContext extends ReminderUntilContext {
+  appAuth: AuthContext;
+  /** Wake the reminder's already-bound session (target is implicit). */
+  followup(args: { message: string }): Promise<ChannelSession>;
+  cancel(reason?: string): Promise<void>;
+}
+
+/**
+ * Create a durable wake bound to a channel continuation.
+ *
+ * Exactly one of `prompt` | `run`, and exactly one of
+ * `every` | `cron` | `delay` | `at`. Prompt fires always follow up into the
+ * bound session.
+ *
+ * @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 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 or run. */
+  prompt?: string;
+  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).
+   */
+  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;
+  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>;
+  /**
+   * 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;
+  /** 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;
+  /**
+   * 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>;
+}
+
+export interface DiscoveredConnection {
+  name: string;
+  transport: ConnectionTransport;
+  description?: 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;
+}
+
+/** Live A/B metrics experiment (`agent/ab.ts` or `agent/ab/<name>.ts`). */
+export interface DiscoveredAB {
+  name: string;
+  /** Branded `defineAB({ ... })` config (see `@anysphere/agent-serve/ab`). */
+  definition: BrandedDefinition<"ab">;
+}
+
+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;
+  /** Composed system prompt (instructions.md / instructions.ts / agent.ts). */
+  instructions?: string;
+  /** Execution runtime. Root agents default to `"local"`. */
+  runtime: AgentRuntime;
+  /** Cloud options when {@link runtime} is `"cloud"`. */
+  cloud?: AgentCloudOptions;
+  /**
+   * Resolved local harness options from {@link AgentConfig.local}
+   * (`cwd` is absolute — relative paths resolved against the project root).
+   */
+  local?: AgentLocalOptions;
+  tools: DiscoveredTool[];
+  skills: DiscoveredSkill[];
+  connections: 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 channel config (authored override or default). */
+  httpChannel: HttpChannelDefinition;
+  channels: DiscoveredChannel[];
+  schedules: DiscoveredSchedule[];
+  hooks: DiscoveredHook[];
+  /** Live A/B metric experiments (`defineAB`). */
+  abs: DiscoveredAB[];
+  /** Optional `agent/ab.config.ts` (`defineABConfig`). */
+  abConfig?: ABConfigFile;
+  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;
+  model?: ModelSetting;
+  runtime: AgentRuntime;
+  cloud?: AgentCloudPublicInfo;
+  /** Local harness options when authored (`cwd` absolute). */
+  local?: { cwd?: string };
+  /**
+   * 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;
+    inputSchema: JsonSchemaObject;
+  }>;
+  skills: Array<{ name: string; description: string }>;
+  connections: Array<{ name: string; transport: 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[];
+    /** Slack channels watched for posts (opt-in channel watch), when declared. */
+    slackChannelPosts?: readonly string[];
+  }>;
+  schedules: Array<{ name: string; cron: string; kind: "markdown" | "run" }>;
+  hooks: string[];
+  /** Live A/B experiment names (`defineAB` under `agent/ab`). */
+  abs: string[];
+  /** Playground fold / persistence meta from `agent/ab.config.ts`. */
+  abConfig?: {
+    maxPlaygroundSessions?: number;
+    durableSamples: boolean;
+    durableSnapshots: boolean;
+  };
+  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;
+  /** Absolute path for runner-owned durable state (conversation store). */
+  runnerStateDir: string;
+  prompt: string;
+  isFirstTurn: boolean;
+  model?: ModelSetting;
+  runtime: AgentRuntime;
+  /** Cloud options when {@link runtime} is `"cloud"`. */
+  cloud?: AgentCloudOptions;
+  /** 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>;
+  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>;
+  /**
+   * 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 to the credential
+   * stored by `agent-serve login`.
+   */
+  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 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;
+  /**
+   * Public base URL where this server is reachable from outside the host
+   * (e.g. `https://agents.example.com`). Used to resolve peer
+   * connections (`defineConnection({ agent })`) for **cloud-runtime** turns:
+   * a cloud VM cannot reach this host's loopback address, so without a
+   * public URL peer tools are omitted from cloud turns (with a warning).
+   * Local turns always use the loopback URL.
+   */
+  publicUrl?: string;
+  /**
+   * Pull GitHub webhook metadata from `/v0/scm-events` (Cursor account auth).
+   * 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`, or `agent-serve login`.
+   */
+  cursorEvents?: {
+    repos: string[];
+    baseUrl?: string;
+    apiKey?: string;
+  };
+  logger?: (line: string) => void;
+}
+
+/** 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>;
+}