@cursor/bdk 0.2.24 → 0.2.26

package/dist/types.d.ts

@@ -8,14 +8,18 @@
  * SDK as the execution harness.
  */
 import type { InteractionUpdate, LocalSubagentInherit, SDKCustomTool, ToolName } from "@cursor/sdk";
-import type { z } from "zod/v3";
+import type * as z3 from "zod/v3";
+import type * as z4 from "zod/v4";
+import type * as z4core from "zod/v4/core";
+import type * as z4mini from "zod/v4/mini";
 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";
 import type { Octokit } from "@octokit/rest";
 import type { WebClient } from "@slack/web-api";
 import type { HostEvalsApi } from "./evals.js";
+export type { HostEvalsApi };
+export type { StorageDefinition };
 export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | JsonValue[] | JsonObject;
 export type JsonObject = {
@@ -23,11 +27,25 @@ export type JsonObject = {
 };
 /** A plain JSON Schema object (already-serialized tool input schema). */
 export type JsonSchemaObject = Record<string, unknown>;
+/**
+ * A `zod/v4` schema, classic (`zod/v4`) or mini (`zod/v4/mini`), with
+ * output `TOutput` and input `TInput`. Both kinds have `parse`/`safeParse`.
+ */
+export type ZodV4Schema<TOutput = unknown, TInput = unknown> = z4.ZodType<TOutput, TInput> | z4mini.ZodMiniType<TOutput, TInput>;
+/**
+ * A zod schema that the public API accepts: a `zod/v3` schema or a
+ * {@link ZodV4Schema}. zod 3.25 and later ship both entry points.
+ */
+export type ZodSchema = z3.ZodTypeAny | ZodV4Schema;
+/** The parsed (output) type of a {@link ZodSchema}. */
+export type ZodSchemaOutput<TSchema> = TSchema extends z3.ZodTypeAny ? z3.output<TSchema> : TSchema extends z4core.$ZodType ? z4core.output<TSchema> : never;
+/** The accepted (input) type of a {@link ZodSchema}, before defaults and transforms. */
+export type ZodSchemaInput<TSchema> = TSchema extends z3.ZodTypeAny ? z3.input<TSchema> : TSchema extends z4core.$ZodType ? z4core.input<TSchema> : never;
 /**
  * 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 type DefinitionKind = "agent" | "instructions" | "tool" | "skill" | "extension" | "disabled-tool" | "disabled-connection" | "disabled" | "connection" | "channel" | "http-channel" | "schedule" | "reminder" | "hook" | "eval" | "storage" | "artifacts";
 export interface BrandedDefinition<K extends DefinitionKind> {
     readonly __agentServe: K;
 }
@@ -555,6 +573,9 @@ export interface HostContext {
      * 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.
+     *
+     * @deprecated Set `OTEL_*` variables and use `metrics.getMeter` or
+     * `trace.getTracer` from `@opentelemetry/api`.
      */
     otel: HostOtelApi;
 }
@@ -680,6 +701,12 @@ export interface HostFilesCapabilities {
  * never filesystem paths — {@link materializedPath} is the one place a real
  * path appears, and it is `undefined` whenever the sink keeps no local copy.
  */
+/**
+ * Text encodings {@link HostFilesApi.read} accepts. The same set Node calls
+ * `BufferEncoding`, written out so the public signature does not name a
+ * Node global.
+ */
+export type HostFileTextEncoding = "ascii" | "utf8" | "utf-8" | "utf16le" | "utf-16le" | "ucs2" | "ucs-2" | "base64" | "base64url" | "latin1" | "binary" | "hex";
 export interface HostFilesApi {
     /** What the configured sink supports. */
     readonly capabilities: HostFilesCapabilities;
@@ -687,7 +714,7 @@ export interface HostFilesApi {
     forSession(sessionId: string): HostFilesApi;
     /** Read as text. Miss → `undefined`. */
     read(path: string, options?: HostFilesCallOptions & {
-        encoding?: BufferEncoding;
+        encoding?: HostFileTextEncoding;
     }): Promise<string | undefined>;
     /** Read as bytes. Miss → `undefined`. */
     readBytes(path: string, options?: HostFilesCallOptions): Promise<Uint8Array | undefined>;
@@ -717,6 +744,10 @@ export type HostOtelAttributes = Record<string, string | number | boolean | unde
 /**
  * Author-facing OpenTelemetry surface on {@link HostContext.otel}.
  *
+ * @deprecated Set `OTEL_*` variables and use `metrics.getMeter` or
+ * `trace.getTracer` from `@opentelemetry/api`. This helper still runs
+ * for this release and emits one deprecation warning per process.
+ *
  * 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`,
@@ -744,6 +775,14 @@ export interface ToolContext {
     toolCallId?: string;
     /** The session this tool call runs inside. */
     session: SessionInfo;
+    /**
+     * Who approved this call when its tool sets `needsApproval`, as the same
+     * kind of auth context as `session.auth`. On Slack, `attributes.user_id` is
+     * the person who clicked Approve, who can differ from the person who
+     * started the session. Absent when the call needed no approval or the
+     * approver is unknown.
+     */
+    approvedBy?: AuthContext;
     /** Absolute path of the session's materialized workspace directory. */
     workspaceDir: string;
     /**
@@ -858,14 +897,14 @@ export interface ToolConfig<TInput> {
      * object (forwarded to the model as-is, unvalidated). Omit to accept any
      * JSON object.
      */
-    inputSchema?: z.ZodType<TInput> | JsonSchemaObject;
+    inputSchema?: z3.ZodType<TInput> | ZodV4Schema<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;
+    outputSchema?: ZodSchema | JsonSchemaObject;
     /**
      * When true (or when the predicate returns true), the host parks the
      * in-flight tool call until a human approves or denies via
@@ -914,8 +953,8 @@ export interface ToolConfig<TInput> {
 export interface ToolDefinition extends BrandedDefinition<"tool"> {
     readonly description: string;
     readonly execution?: ToolExecution;
-    readonly inputSchema?: z.ZodTypeAny | JsonSchemaObject;
-    readonly outputSchema?: z.ZodTypeAny | JsonSchemaObject;
+    readonly inputSchema?: ZodSchema | JsonSchemaObject;
+    readonly outputSchema?: ZodSchema | JsonSchemaObject;
     readonly needsApproval?: ToolNeedsApproval<never>;
     readonly effect?: ToolEffectDeclaration<never>;
     readonly timeArgs?: readonly string[];
@@ -942,8 +981,12 @@ export interface ExtensionOptions<TConfig, TInput = TConfig> {
     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>;
+    /**
+     * Mount configuration schema (`zod/v3` or classic `zod/v4`). A consumer's
+     * settings are validated at mount. A `zod/v4/mini` member here would break
+     * the inference of `TConfig`.
+     */
+    config?: z3.ZodType<TConfig, z3.ZodTypeDef, TInput> | z4.ZodType<TConfig, TInput>;
     /** Choose which contribution groups this mount includes. */
     contributions?: (config: TConfig) => ExtensionContributionSelection;
     /**
@@ -1140,9 +1183,9 @@ export declare function isSymbolicConnectionTransport(transport: ConnectionTrans
 /** One TypeScript tool on `defineConnection({ tools })`. */
 export type InlineStdioToolConfig = {
     description: string;
-    inputSchema?: z.ZodTypeAny | JsonSchemaObject;
+    inputSchema?: ZodSchema | JsonSchemaObject;
     /** Output JSON Schema (zod converted, never validated); advertised when declared. */
-    outputSchema?: z.ZodTypeAny | JsonSchemaObject;
+    outputSchema?: ZodSchema | JsonSchemaObject;
     execute: (input: JsonObject) => unknown | Promise<unknown>;
 };
 /** `defineConnection({ tools })`. TypeScript in; stdio MCP out. */
@@ -1247,6 +1290,9 @@ export type ConnectionConfig = (((Exclude<ConnectionTransport, {
      * 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`.
+     *
+     * A turn never waits to authorize an optional connection, also in the
+     * playground. Authorize it ahead of time with `bdk mcp oauth <name>`.
      */
     optional?: boolean;
     /**
@@ -1361,6 +1407,7 @@ export interface ActionResult {
     stubbed?: true;
     parentCallId?: string;
     modelCallId?: string;
+    completedAt?: string;
 }
 /** Human decision for a parked {@link ToolConfig.needsApproval} tool call. */
 export type ApprovalDecision = "approve" | "deny";
@@ -1398,6 +1445,13 @@ export type SessionEventPayload = {
     type: "message.received";
     data: {
         text: string;
+        /**
+         * {@link ChannelSession.deliveryId} of each `send()` this prompt
+         * carries, in arrival order. One for a direct send or a steer;
+         * several when coalesced follow-ups drain into one turn. Omitted on
+         * prompts no `send()` produced and on legacy stored events.
+         */
+        deliveryIds?: string[];
     };
 } | {
     /**
@@ -1487,8 +1541,13 @@ export type SessionEventPayload = {
     };
 } | {
     /**
-     * A host MCP call/list needs OAuth. The turn stays running until
-     * the human completes the `authUrl` and the runtime retries.
+     * A host MCP call/list needs OAuth, and a person can authorize it: a
+     * playground or HTTP chat turn, or a Slack message on a channel that
+     * handles this event (`slackChannel({ toolApprovals: true })` or
+     * `buildToolApprovalEvents` in `events`). The turn waits until
+     * the person completes the `authUrl`, the turn is interrupted, or 10
+     * minutes pass. Other turns (schedules, reminders, webhooks, evals) do
+     * not emit this event. They fail the call with a "Reconnect" message.
      */
     type: "action.auth_requested";
     data: {
@@ -1525,6 +1584,7 @@ export type SessionEventPayload = {
         parentCallId?: string;
         /** Same id as the matching {@link ActionCall.modelCallId}. */
         modelCallId?: string;
+        completedAt?: string;
     };
 } | {
     /**
@@ -1619,13 +1679,20 @@ export type SessionEventPayload = {
     };
 } | {
     /**
-     * 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.
+     * A follow-up sent mid-turn reached the running agent. Channels use
+     * this to reposition a live progress message below the follow-up,
+     * which Slack cannot do any other way.
+     *
+     * `deliveryId` is set when a coalesced `send()` was steered into the
+     * turn and names that send's {@link ChannelSession.deliveryId}. It is
+     * absent when the Slack nudge carrier delivered the follow-up from its
+     * file store at a tool boundary, which does not know which send it
+     * carried.
      */
     type: "nudge.delivered";
-    data: Record<string, never>;
+    data: {
+        deliveryId?: string;
+    };
 } | {
     type: "session.waiting";
     data: Record<string, never>;
@@ -1875,6 +1942,22 @@ export interface ChannelSession {
      * in-flight turn instead of starting immediately (Slack busy path).
      */
     readonly coalesced?: boolean;
+    /**
+     * Identifies this `send()` on the session's events: {@link SendMessageOptions.deliveryId}
+     * when the caller passed one, otherwise a fresh `dlv_…` id. The message
+     * reaches the agent exactly one of two ways, and the id is on that event:
+     *
+     * - `nudge.delivered` `{ deliveryId }` — a coalesced send steered into
+     *   the running turn.
+     * - `message.received` `{ deliveryIds }` — the prompt of a turn: a send
+     *   that started one, or coalesced sends that fell back to the next turn
+     *   instead of steering.
+     *
+     * Set on every handle `send()` returns, including the one a hosted-admission
+     * `send()` returns before the session exists. Absent on handles looked up
+     * by session id, which no send produced.
+     */
+    readonly deliveryId?: string;
     readonly info: SessionInfo;
     /**
      * Replay recorded events from `startIndex`, then follow live (NDJSON).
@@ -2020,6 +2103,15 @@ export interface SendMessageOptions {
      * mid-turn nudge already delivered this `sourceTs`, boundary resume skips it.
      */
     coalesceSourceTs?: string;
+    /**
+     * Caller-chosen id for this send, returned as {@link ChannelSession.deliveryId}
+     * and stamped on the event where the message reaches the agent. Use one
+     * you already hold (a webhook delivery or message id) to correlate without
+     * keeping the returned handle. Opaque, compared verbatim; at most 256
+     * characters. Omit for a fresh `dlv_…` id. Keep it unique per session:
+     * two sends with the same id cannot be told apart.
+     */
+    deliveryId?: string;
 }
 export type SendMessageFn = (message: string, options?: SendMessageOptions) => Promise<ChannelSession>;
 /**
@@ -2149,7 +2241,7 @@ export type ChannelRouteHandler = (request: Request, args: ChannelHandlerArgs) =
  * Channel HTTP routes must declare a Zod schema (plain JSON Schema objects
  * are not accepted — TypeScript will reject them).
  */
-export type ChannelRouteSchema = z.ZodTypeAny;
+export type ChannelRouteSchema = ZodSchema;
 /** Handler args with a required, schema-inferred `query`. */
 export type ChannelHandlerArgsWithQuery<TQuery> = ChannelHandlerArgs & {
     query: TQuery;
@@ -2167,25 +2259,25 @@ export type ChannelHandlerArgsWithBodyAndQuery<TBody, TQuery> = ChannelHandlerAr
  * 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> {
+export interface ChannelGetRouteSpec<TQuery extends ChannelRouteSchema = ChannelRouteSchema> {
     description?: string;
     querySchema: TQuery;
-    handler: (request: Request, args: ChannelHandlerArgsWithQuery<z.infer<TQuery>>) => Response | Promise<Response>;
+    handler: (request: Request, args: ChannelHandlerArgsWithQuery<ZodSchemaOutput<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> {
+export interface ChannelBodyRouteSpec<TBody extends ChannelRouteSchema = ChannelRouteSchema, TQuery extends ChannelRouteSchema | 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>;
+    handler: (request: Request, args: TQuery extends ChannelRouteSchema ? ChannelHandlerArgsWithBodyAndQuery<ZodSchemaOutput<TBody>, ZodSchemaOutput<TQuery>> : ChannelHandlerArgsWithBody<ZodSchemaOutput<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> {
+export interface ChannelDeleteRouteSpec<TBody extends ChannelRouteSchema | undefined = undefined, TQuery extends ChannelRouteSchema | undefined = undefined> {
     description?: string;
     bodySchema?: TBody;
     querySchema?: TQuery;
@@ -2345,6 +2437,11 @@ export interface ChannelMeta {
      * dispatch on, in the Cloud vocabulary (`pullrequest:created`, …).
      */
     bitbucketWebhookEvents?: readonly string[];
+    /**
+     * For PagerDuty webhook packs: the v3 `event_type`s this channel is wired
+     * to dispatch on (`incident.triggered`, `incident.annotated`, …).
+     */
+    pagerdutyWebhookEvents?: readonly string[];
     /**
      * For deployments packs: the factory event types this channel is wired
      * to dispatch on. Extracted into the deploy manifest as `eventTypes`.
@@ -2512,7 +2609,7 @@ export interface ArtifactKindConfig {
      * persists the parsed output (defaults and coercions applied), so
      * the schema's output must stay JSON-serializable.
      */
-    schema?: z.ZodType;
+    schema?: ZodSchema;
 }
 /** Input to `defineArtifacts` (authored at `agent/artifacts.ts`). */
 export interface ArtifactsConfig {
@@ -2910,10 +3007,25 @@ export interface ReminderHostApi {
         reason?: string;
     }>;
 }
+export type DiagnosticCode = "module_not_found" | "module_load_failed" | "invalid_definition" | "config_error" | "other";
 export interface Diagnostic {
     severity: "error" | "warning";
-    /** Repo-relative or absolute path of the offending file. */
+    /**
+     * Closed classification. Absent means `other`, so a diagnostic written
+     * before codes existed still has a code.
+     */
+    code?: DiagnosticCode;
+    /** Path of the offending file, relative to the project root directory. */
     path?: string;
+    /**
+     * Bare npm package name when `code` is `module_not_found` and the missing
+     * specifier is a package name. Absent for relative and absolute paths.
+     * Consumers must work from `code` alone.
+     */
+    package?: string;
+    /**
+     * Customer text. Consumers must not forward this string.
+     */
     message: string;
 }
 export interface DiscoveredTool {
@@ -3112,8 +3224,6 @@ export interface AgentProject {
     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`. */
@@ -3127,121 +3237,191 @@ export interface AgentChannelRouteInfo {
     bodySchema?: JsonSchemaObject;
     querySchema?: JsonSchemaObject;
 }
+export interface ProjectToolInfo {
+    name: string;
+    description: string;
+    /** @experimental */
+    execution: ToolExecution;
+    /**
+     * `true` or `false` when the author set a boolean. `"dynamic"` when
+     * the author set a function.
+     */
+    needsApproval: boolean | "dynamic";
+    /**
+     * 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;
+}
+export interface ProjectConnectionInfo {
+    name: string;
+    transport: string;
+    /** @experimental */
+    advertiseTools?: boolean;
+    /** @experimental */
+    optional?: boolean;
+    /** @experimental */
+    effects?: readonly ToolEffect[];
+    /** @experimental */
+    tools?: readonly string[];
+    /** @experimental */
+    disallowedTools?: readonly string[];
+    /**
+     * Present only for `cursorAccount` connections. A connector-name
+     * allowlist, or `"*"` for every connected server.
+     * @experimental
+     */
+    cursorAccountServers?: string[] | "*";
+}
+export interface ProjectChannelInfo {
+    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.
+     * @experimental
+     */
+    githubWebhookEvents?: readonly string[];
+    /**
+     * Origin webhook event types the channel dispatches on, when declared.
+     * @experimental
+     */
+    originWebhookEvents?: readonly string[];
+    /**
+     * GitLab `object_kind`s the channel dispatches on, when declared.
+     * @experimental
+     */
+    gitlabWebhookEvents?: readonly string[];
+    /**
+     * Bitbucket event keys (Cloud vocabulary) the channel dispatches on.
+     * @experimental
+     */
+    bitbucketWebhookEvents?: readonly string[];
+    /**
+     * PagerDuty v3 event types the channel dispatches on, when declared.
+     * @experimental
+     */
+    pagerdutyWebhookEvents?: readonly string[];
+    /**
+     * Factory deployment event types the channel dispatches on, when declared.
+     * @experimental
+     */
+    deploymentEventTypes?: readonly string[];
+    /**
+     * Change Monitor checkpoint or Factory issue event types the channel dispatches on, when declared.
+     * @experimental
+     */
+    factoryEventTypes?: readonly string[];
+    /**
+     * Slack Events API event types the channel dispatches on, when declared.
+     * @experimental
+     */
+    slackEventTypes?: readonly string[];
+    /**
+     * Slack channels watched for posts (opt-in channel watch), when declared.
+     * @experimental
+     */
+    slackChannelPosts?: readonly string[];
+}
 /** JSON-safe projection of the manifest returned by `GET /v1/info`. */
-export interface AgentProjectInfo {
+export interface ProjectInfo {
+    /** Projection shape. Bump only when a stable field changes meaning. */
+    schemaVersion: 1;
     name: string;
     /** Short agent description when authored on `defineAgent`. */
     description?: string;
     model?: ModelSetting;
+    /**
+     * Resolved runtime architecture. Omitted authors are `"v2"`.
+     */
+    architecture: AgentArchitecture;
+    /** @experimental */
     runtime: AgentRuntime;
+    /** @experimental */
     cloud?: AgentCloudPublicInfo;
-    /** Local harness options when authored (`cwd` absolute). */
+    /**
+     * Local harness options when authored (`cwd` absolute).
+     * @experimental
+     */
     local?: {
         cwd?: string;
     };
-    /** Managed-hosting declarations when authored or declared by a mounted extension (egress allowlist, expected secrets, container image). */
+    /**
+     * Managed-hosting declarations when authored or declared by a mounted extension (egress allowlist, expected secrets, container image).
+     * @experimental
+     */
     hosting?: {
         egressDomains?: string[];
         secretNames?: string[];
         image?: string;
     };
-    /** Turn admission limits when authored (`concurrency` on `agent.ts`). */
+    /**
+     * Turn admission limits when authored (`concurrency` on `agent.ts`).
+     * @experimental
+     */
     concurrency?: {
         maxRunningTurns?: number;
     };
     /**
-     * The agent's own MCP surface (mounted at `<base>/v1/mcp`): other agents
+     * The agent's own MCP surface (mounted at `<base>/v1/mcp`). Other agents
      * and MCP clients delegate to this agent through these tools.
+     * @experimental
      */
     mcp: {
         path: string;
         tools: string[];
     };
+    /**
+     * @experimental
+     */
     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;
-    }>;
+    tools: ProjectToolInfo[];
     skills: Array<{
         name: string;
         description: string;
     }>;
-    /** Mounted extensions and the tool / skill names each contributed. */
+    /**
+     * Mounted extensions and the tool / skill names each contributed.
+     * @experimental
+     */
     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[] | "*";
-    }>;
+    connections: ProjectConnectionInfo[];
     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[];
-    }>;
+    channels: ProjectChannelInfo[];
     schedules: Array<{
         name: string;
         cron: string;
         kind: "markdown" | "run";
     }>;
-    /** Named reminder handlers (`agent/reminders/<name>.ts`) when present. */
+    /**
+     * Named reminder handlers (`agent/reminders/<name>.ts`) when present.
+     * @experimental
+     */
     reminders?: Array<{
         name: string;
     }>;
     hooks: string[];
-    /** Project storage sink from `agent/storage.ts`, when authored. */
+    /**
+     * Project storage sink from `agent/storage.ts`, when authored.
+     * @experimental
+     */
     storage?: {
         name?: string;
     };
-    otel?: {
-        serviceName?: string;
-        enabled: true;
-    };
-    /** Declared artifact kinds from `agent/artifacts.ts`, when authored. */
+    /**
+     * Declared artifact kinds from `agent/artifacts.ts`, when authored.
+     * @experimental
+     */
     artifacts?: {
         kinds: string[];
         agentTool: boolean;
@@ -3250,10 +3430,16 @@ export interface AgentProjectInfo {
     /**
      * Eval cases a hosted architecture v2 release runs as its own sessions.
      * Set only in that release's deploy manifest.
+     * @experimental
      */
     evals?: AgentProjectEvalsInfo;
     diagnostics: Diagnostic[];
 }
+/** @deprecated Use {@link ProjectInfo}. */
+export type AgentProjectInfo = ProjectInfo;
+export interface Project {
+    readonly info: ProjectInfo;
+}
 export interface AgentProjectEvalsInfo {
     /** Hosted eval-case protocol this release speaks. */
     protocol: 1;
@@ -3506,14 +3692,8 @@ export interface ServeOptions {
         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). */
+/** One agent mounted on a server (its URL slug and public project info). */
 export interface MountedAgentInfo {
     /**
      * URL slug the agent is mounted under. Empty string in single-agent mode
@@ -3521,18 +3701,20 @@ export interface MountedAgentInfo {
      * `/<slug>/v1/...`).
      */
     slug: string;
-    project: AgentProject;
     /** Absolute base URL for this agent (server URL + `/<slug>` when slugged). */
     url: string;
+    /** Same projection as `GET /v1/info` for this agent. */
+    info: ProjectInfo;
 }
 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.
+     * The first mounted agent's {@link Project}. In multi-agent mode use
+     * {@link agents} for the full set.
+     * @deprecated Use `agents[0].info`.
      */
-    project: AgentProject;
+    project: Project;
     /** Every agent mounted on this server. One entry in single-agent mode. */
     agents: MountedAgentInfo[];
     /**