@github/copilot-sdk 1.0.7-preview.2 → 1.0.7

package/dist/generated/rpc.d.ts

@@ -784,6 +784,18 @@ export type McpHeadersHandlePendingHeadersRefreshRequest = {
 } | {
     kind: "none";
 };
+/**
+ * Consumer allowed to call an MCP tool.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "McpToolUiVisibility".
+ */
+/** @experimental */
+export type McpToolUiVisibility = 
+/** The model may call the tool. */
+"model"
+/** An MCP App view may call the tool. */
+ | "app";
 /**
  * Host response to the pending OAuth request.
  *
@@ -3214,6 +3226,10 @@ export interface DiscoveredCanvas {
      * Short, single-sentence description shown to the agent in canvas catalogs.
      */
     description: string;
+    /**
+     * Host-local PNG path for the canvas icon, when supplied
+     */
+    icon?: string;
     inputSchema?: CanvasJsonSchema;
     /**
      * Actions the agent or host may invoke on an open instance
@@ -3269,6 +3285,10 @@ export interface OpenCanvasInstance {
      * Provider-local canvas identifier
      */
     canvasId: string;
+    /**
+     * Host-local PNG path for the canvas icon, when supplied
+     */
+    icon?: string;
     /**
      * Rendered title
      */
@@ -5791,27 +5811,24 @@ export interface McpAppsListToolsResult {
     }[];
 }
 /**
- * @deprecated
- * Deprecated/obsolete MCP Apps alias for `McpResourcesReadRequest`; use `session.mcp.resources.read` instead.
+ * MCP server and resource URI to fetch.
  *
  * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
  * via the `definition` "McpAppsReadResourceRequest".
  */
 /** @experimental */
-/** @deprecated */
 export interface McpAppsReadResourceRequest {
     /**
      * Name of the MCP server hosting the resource
      */
     serverName: string;
     /**
-     * Resource URI
+     * Resource URI (typically ui://...)
      */
     uri: string;
 }
 /**
- * @deprecated
- * Deprecated/obsolete MCP Apps alias for `McpResourcesReadResult`; use `session.mcp.resources.read` instead.
+ * Resource contents returned by the MCP server.
  *
  * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
  * via the `definition` "McpAppsReadResourceResult".
@@ -5824,8 +5841,7 @@ export interface McpAppsReadResourceResult {
     contents: McpAppsResourceContent[];
 }
 /**
- * @deprecated
- * Deprecated/obsolete MCP Apps alias for `McpResourceContent`; use `session.mcp.resources.read` instead.
+ * MCP Apps resource content with URI, optional MIME type, text or base64 blob, and resource metadata.
  *
  * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
  * via the `definition` "McpAppsResourceContent".
@@ -5833,7 +5849,7 @@ export interface McpAppsReadResourceResult {
 /** @experimental */
 export interface McpAppsResourceContent {
     /**
-     * The resource URI
+     * The resource URI (typically ui://...)
      */
     uri: string;
     /**
@@ -5849,7 +5865,7 @@ export interface McpAppsResourceContent {
      */
     blob?: string;
     /**
-     * Resource-level metadata
+     * Resource-level metadata (CSP, permissions, etc.)
      */
     _meta?: {
         [k: string]: unknown | undefined;
@@ -6388,7 +6404,7 @@ export interface McpListToolsResult {
     tools: McpTools[];
 }
 /**
- * MCP tool metadata with tool name and optional description.
+ * MCP tool metadata with tool name, optional description, and normalized MCP Apps discovery metadata.
  *
  * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
  * via the `definition` "McpTools".
@@ -6403,6 +6419,24 @@ export interface McpTools {
      * Tool description, when provided.
      */
     description?: string;
+    ui?: McpToolUi;
+}
+/**
+ * Normalized MCP Apps discovery metadata from a tool's `_meta.ui` block.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "McpToolUi".
+ */
+/** @experimental */
+export interface McpToolUi {
+    /**
+     * URI of the tool's MCP App resource, typically a `ui://` resource identifier. Use `session.mcp.resources.read` to fetch its HTML and resource metadata.
+     */
+    resourceUri?: string;
+    /**
+     * Tool visibility advertised by the server. When absent, MCP Apps defaults apply.
+     */
+    visibility?: McpToolUiVisibility[];
 }
 /**
  * Pending MCP OAuth request ID and host-provided token or cancellation response.
@@ -7107,7 +7141,7 @@ export interface SessionWorkingDirectoryContext {
 export interface MetadataRecordContextChangeResult {
 }
 /**
- * Absolute path to set as the session's new working directory.
+ * Absolute path to set as the session's new working directory. For local sessions the path must be absolute and exist on disk: it is validated before any session state changes, and a failing validation rejects the call with nothing mutated, persisted, or emitted. Remote sessions record the path as-is.
  *
  * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
  * via the `definition` "MetadataSetWorkingDirectoryRequest".
@@ -7120,7 +7154,7 @@ export interface MetadataSetWorkingDirectoryRequest {
     workingDirectory: string;
 }
 /**
- * Update the session's working directory. Used by the host when the user explicitly changes cwd (e.g., the `/cd` slash command). The host is responsible for `process.chdir` and any related side-effects (file index, etc.); this method only updates the session's own recorded path.
+ * Update the session's working directory. Used by the host when the user explicitly changes cwd (e.g., the `/cd` slash command). The host is responsible for any related side-effects (file index, etc.); it does NOT change the process working directory (a session's cwd is per-session, not process-global). For local sessions the runtime validates the target first (an absolute path that exists on disk) and re-bases the permission primary directory; a rejected validation fails the call before anything is mutated, persisted, or emitted. Location-scoped permission rules are then re-keyed to the new directory (best-effort). Remote sessions only record the path.
  *
  * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
  * via the `definition` "MetadataSetWorkingDirectoryResult".
@@ -7305,6 +7339,7 @@ export interface ModelBilling {
      * Whole-number percentage discount (0-100) applied to usage billed through this model. Populated for the synthetic `auto` model, where requests routed by auto-mode are billed at a reduced rate; absent for concrete models.
      */
     discountPercent?: number;
+    promo?: ModelBillingPromo;
 }
 /**
  * Token-level pricing information for this model
@@ -7389,6 +7424,31 @@ export interface ModelBillingTokenPricesLongContext {
      */
     maxPromptTokens?: number;
 }
+/**
+ * Active server-driven promotion for a model, including its discount and expiry.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "ModelBillingPromo".
+ */
+/** @experimental */
+export interface ModelBillingPromo {
+    /**
+     * Stable identifier for the promotion campaign.
+     */
+    id?: string;
+    /**
+     * Percentage discount (0-100) applied while the promotion is active. May be fractional.
+     */
+    discountPercent?: number;
+    /**
+     * UTC ISO 8601 timestamp marking when the promotion ends. Always present: the API only surfaces a promo whose expiry parses and is in the future. Consumers should treat a past value as expired.
+     */
+    endsAt: string;
+    /**
+     * Human-readable promotion message. Does not include the expiry timestamp; consumers may format endsAt and append it.
+     */
+    message?: string;
+}
 /**
  * Optional capability overrides (vision, tool_calls, reasoning, etc.).
  *
@@ -9272,7 +9332,7 @@ export interface PluginsInstallRequest {
     workingDirectory?: string;
 }
 /**
- * Marketplace source to register.
+ * Marketplace source and optional working directory for relative-path resolution.
  *
  * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
  * via the `definition` "PluginsMarketplacesAddRequest".
@@ -9283,6 +9343,10 @@ export interface PluginsMarketplacesAddRequest {
      * Marketplace source. Accepts the same forms as the CLI: "owner/repo" or "owner/repo#ref" (GitHub), an http/https/ssh URL (optionally with #ref), a git scp-style URL (user@host:path), or a local path. The marketplace's own name (from its manifest) is used as the registration key.
      */
     source: string;
+    /**
+     * Working directory used to resolve relative local paths in `source`. Defaults to the server's current working directory.
+     */
+    workingDirectory?: string;
 }
 /**
  * Name of the marketplace whose plugin catalog to fetch.
@@ -10185,7 +10249,7 @@ export interface QueueRemoveMostRecentResult {
 /** @experimental */
 export interface RegisterEventInterestParams {
     /**
-     * The event type the consumer wants the runtime to treat as 'observed' for behavior-switching gating. Some runtime code paths inspect whether any consumer is interested in a specific event type and choose a different implementation accordingly (e.g. `mcp.oauth_required`: when interest is registered the runtime delegates OAuth token acquisition to the consumer; when no interest is registered OAuth-required servers become needs-auth). SDK clients that long-poll events do NOT automatically appear as listeners to these gating checks — they must explicitly call `registerInterest` for each event type they want the runtime to count as having a consumer. Multiple registrations for the same event type from the same or different consumers are tracked independently and must each be released. See: `mcp.oauth_required`, `sampling.requested`, `auto_mode_switch.requested`, `session_limits_exhausted.requested`, `user_input.requested`, `elicitation.requested`, `command.queued`, `exit_plan_mode.requested`.
+     * The event type the consumer wants the runtime to treat as 'observed' for behavior-switching gating. Some runtime code paths inspect whether any consumer is interested in a specific event type and choose a different implementation accordingly (e.g. `mcp.oauth_required`: when interest is registered the runtime delegates interactive OAuth token acquisition to the consumer via `mcp.oauth_required` events; when no interest is registered the runtime still attempts non-interactive reconnect from cached or refreshable tokens, and only marks the server `needs-auth` if usable credentials are unavailable — it does not open a browser or start interactive OAuth without a consumer). SDK clients that long-poll events do NOT automatically appear as listeners to these gating checks — they must explicitly call `registerInterest` for each event type they want the runtime to count as having a consumer. Multiple registrations for the same event type from the same or different consumers are tracked independently and must each be released. See: `mcp.oauth_required`, `sampling.requested`, `auto_mode_switch.requested`, `session_limits_exhausted.requested`, `user_input.requested`, `elicitation.requested`, `command.queued`, `exit_plan_mode.requested`.
      */
     eventType: string;
 }
@@ -11715,6 +11779,10 @@ export interface SessionModelList {
      * Available models, ordered with the most preferred default first. Includes both Copilot (CAPI) models and any registry BYOK models; a BYOK model appears under its provider-qualified selection id (`provider/id`).
      */
     list: unknown[];
+    /**
+     * Cost categories for the full CAPI catalog, including picker-disabled models that Auto may select. Metadata only; entries absent from `list` are not manually selectable.
+     */
+    modelPriceCategories?: SessionModelPriceCategory[];
     /**
      * Per-quota snapshots returned alongside the model list, keyed by quota type.
      */
@@ -11722,6 +11790,17 @@ export interface SessionModelList {
         [k: string]: unknown | undefined;
     };
 }
+/**
+ * Cost-category metadata for a CAPI model.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "SessionModelPriceCategory".
+ */
+/** @experimental */
+export interface SessionModelPriceCategory {
+    id: string;
+    priceCategory: ModelPickerPriceCategory;
+}
 /**
  * Session construction options.
  *
@@ -11826,6 +11905,10 @@ export interface SessionOpenOptions {
      * Denylist of tool names.
      */
     excludedTools?: string[];
+    /**
+     * Built-in subagent names to include in this session. When specified, only these built-ins are available, subject to runtime availability and exclusions. Custom agents with the same name remain available.
+     */
+    includedBuiltinAgents?: string[];
     /**
      * Built-in subagent names to exclude from this session. Excluded built-ins are hidden from agent discovery and cannot be dispatched unless a custom agent with the same name is available.
      */
@@ -12896,6 +12979,10 @@ export interface SessionUpdateOptionsParams {
      * Denylist of tool names for this session.
      */
     excludedTools?: string[];
+    /**
+     * Built-in subagent names to include in this session. When specified, only these built-ins are available, subject to runtime availability and exclusions. Custom agents with the same name remain available. Set to null to remove the allowlist restriction.
+     */
+    includedBuiltinAgents?: string[] | null;
     /**
      * Built-in subagent names to exclude from this session. Excluded built-ins are hidden from agent discovery and cannot be dispatched unless a custom agent with the same name is available.
      */
@@ -13055,6 +13142,10 @@ export interface SessionUpdateOptionsResult {
      * Whether the operation succeeded
      */
     success: boolean;
+    /**
+     * Number of hooks loaded from installed plugins, returned when installedPlugins is updated
+     */
+    pluginHookCount?: number;
 }
 /**
  * User-requested shell execution cancellation handle.
@@ -13384,7 +13475,7 @@ export interface SkillsLoadDiagnostics {
     errors: string[];
 }
 /**
- * Slash-command invocation result that submits an agent prompt, with display prompt, optional mode, and settings-change flag.
+ * Slash-command invocation result that submits an agent prompt, with display prompt, optional mode, optional user-facing notice, and settings-change flag.
  *
  * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
  * via the `definition` "SlashCommandAgentPromptResult".
@@ -13404,6 +13495,10 @@ export interface SlashCommandAgentPromptResult {
      */
     displayPrompt: string;
     mode?: SessionMode;
+    /**
+     * Optional user-facing notice to show before the prompt is submitted
+     */
+    notice?: string;
     /**
      * True when the invocation mutated user runtime settings; consumers caching settings should refresh
      */
@@ -15435,7 +15530,7 @@ export declare function createServerRpc(connection: MessageConnection): {
             /**
              * Registers a new marketplace from a source (owner/repo, URL, or local path).
              *
-             * @param params Marketplace source to register.
+             * @param params Marketplace source and optional working directory for relative-path resolution.
              *
              * @returns Result of registering a new marketplace.
              */
@@ -16275,7 +16370,7 @@ export declare function createSessionRpc(connection: MessageConnection, sessionI
          */
         list: () => Promise<McpServerList>;
         /**
-         * Lists the tools exposed by a connected MCP server on this session's host.
+         * Lists the tools exposed by a connected MCP server on this session's host. This performs a live `tools/list` request. Tool UI metadata is returned independently of whether MCP Apps rendering is enabled for the session.
          *
          * @param params Server name whose tool list should be returned.
          *
@@ -16387,13 +16482,11 @@ export declare function createSessionRpc(connection: MessageConnection, sessionI
         /** @experimental */
         apps: {
             /**
-             * Deprecated/obsolete alias for `session.mcp.resources.read`; retained for backwards compatibility with earlier MCP Apps host integrations.
+             * Fetch an MCP resource (typically a `ui://` MCP App bundle, per SEP-1865) from a connected server. Requires the `mcp-apps` session capability.
              *
-             * @param params Deprecated/obsolete MCP Apps alias for `McpResourcesReadRequest`; use `session.mcp.resources.read` instead.
-             *
-             * @returns Deprecated/obsolete MCP Apps alias for `McpResourcesReadResult`; use `session.mcp.resources.read` instead.
+             * @param params MCP server and resource URI to fetch.
              *
-             * @deprecated
+             * @returns Resource contents returned by the MCP server.
              */
             readResource: (params: McpAppsReadResourceRequest) => Promise<McpAppsReadResourceResult>;
             /**
@@ -16960,11 +17053,11 @@ export declare function createSessionRpc(connection: MessageConnection, sessionI
          */
         recordContextChange: (params: MetadataRecordContextChangeRequest) => Promise<MetadataRecordContextChangeResult>;
         /**
-         * Updates the session's recorded working directory.
+         * Updates the session's working directory. For local sessions the target is validated first (an absolute path that exists on disk) and the permission primary directory is re-based; a rejected validation fails the call before any session state changes.
          *
-         * @param params Absolute path to set as the session's new working directory.
+         * @param params Absolute path to set as the session's new working directory. For local sessions the path must be absolute and exist on disk: it is validated before any session state changes, and a failing validation rejects the call with nothing mutated, persisted, or emitted. Remote sessions record the path as-is.
          *
-         * @returns Update the session's working directory. Used by the host when the user explicitly changes cwd (e.g., the `/cd` slash command). The host is responsible for `process.chdir` and any related side-effects (file index, etc.); this method only updates the session's own recorded path.
+         * @returns Update the session's working directory. Used by the host when the user explicitly changes cwd (e.g., the `/cd` slash command). The host is responsible for any related side-effects (file index, etc.); it does NOT change the process working directory (a session's cwd is per-session, not process-global). For local sessions the runtime validates the target first (an absolute path that exists on disk) and re-bases the permission primary directory; a rejected validation fails the call before anything is mutated, persisted, or emitted. Location-scoped permission rules are then re-keyed to the new directory (best-effort). Remote sessions only record the path.
          */
         setWorkingDirectory: (params: MetadataSetWorkingDirectoryRequest) => Promise<MetadataSetWorkingDirectoryResult>;
         /**
@@ -17318,6 +17411,18 @@ export interface ClientSessionApiHandlers {
  * function uses `getHandlers` to resolve the session's handlers.
  */
 export declare function registerClientSessionApiHandlers(connection: MessageConnection, getHandlers: (sessionId: string) => ClientSessionApiHandlers): void;
+/** Handler for `hooks` client global API methods. */
+/** @experimental */
+export interface HooksHandler {
+    /**
+     * Dispatches one SDK callback hook from the runtime to the connection that registered it. Internal transport plumbing: clients opt in through session initialization and the Rust hook processor owns ordering, policy, timeout, and callback routing.
+     *
+     * @param params Runtime-owned wire payload for a server-to-client hook callback invocation.
+     *
+     * @returns Optional output returned by an SDK callback hook.
+     */
+    invoke(params: HookInvokeRequest): Promise<HookInvokeResponse>;
+}
 /** Handler for `llmInference` client global API methods. */
 /** @experimental */
 export interface LlmInferenceHandler {
@@ -17350,6 +17455,7 @@ export interface GitHubTelemetryHandler {
 }
 /** All client global API handler groups. */
 export interface ClientGlobalApiHandlers {
+    hooks?: HooksHandler;
     llmInference?: LlmInferenceHandler;
     gitHubTelemetry?: GitHubTelemetryHandler;
 }

package/dist/generated/rpc.js

@@ -195,7 +195,7 @@ function createServerRpc(connection) {
         /**
          * Registers a new marketplace from a source (owner/repo, URL, or local path).
          *
-         * @param params Marketplace source to register.
+         * @param params Marketplace source and optional working directory for relative-path resolution.
          *
          * @returns Result of registering a new marketplace.
          */
@@ -1091,7 +1091,7 @@ function createSessionRpc(connection, sessionId) {
        */
       list: async () => connection.sendRequest("session.mcp.list", { sessionId }),
       /**
-       * Lists the tools exposed by a connected MCP server on this session's host.
+       * Lists the tools exposed by a connected MCP server on this session's host. This performs a live `tools/list` request. Tool UI metadata is returned independently of whether MCP Apps rendering is enabled for the session.
        *
        * @param params Server name whose tool list should be returned.
        *
@@ -1203,13 +1203,11 @@ function createSessionRpc(connection, sessionId) {
       /** @experimental */
       apps: {
         /**
-         * Deprecated/obsolete alias for `session.mcp.resources.read`; retained for backwards compatibility with earlier MCP Apps host integrations.
+         * Fetch an MCP resource (typically a `ui://` MCP App bundle, per SEP-1865) from a connected server. Requires the `mcp-apps` session capability.
          *
-         * @param params Deprecated/obsolete MCP Apps alias for `McpResourcesReadRequest`; use `session.mcp.resources.read` instead.
-         *
-         * @returns Deprecated/obsolete MCP Apps alias for `McpResourcesReadResult`; use `session.mcp.resources.read` instead.
+         * @param params MCP server and resource URI to fetch.
          *
-         * @deprecated
+         * @returns Resource contents returned by the MCP server.
          */
         readResource: async (params) => connection.sendRequest("session.mcp.apps.readResource", { sessionId, ...params }),
         /**
@@ -1776,11 +1774,11 @@ function createSessionRpc(connection, sessionId) {
        */
       recordContextChange: async (params) => connection.sendRequest("session.metadata.recordContextChange", { sessionId, ...params }),
       /**
-       * Updates the session's recorded working directory.
+       * Updates the session's working directory. For local sessions the target is validated first (an absolute path that exists on disk) and the permission primary directory is re-based; a rejected validation fails the call before any session state changes.
        *
-       * @param params Absolute path to set as the session's new working directory.
+       * @param params Absolute path to set as the session's new working directory. For local sessions the path must be absolute and exist on disk: it is validated before any session state changes, and a failing validation rejects the call with nothing mutated, persisted, or emitted. Remote sessions record the path as-is.
        *
-       * @returns Update the session's working directory. Used by the host when the user explicitly changes cwd (e.g., the `/cd` slash command). The host is responsible for `process.chdir` and any related side-effects (file index, etc.); this method only updates the session's own recorded path.
+       * @returns Update the session's working directory. Used by the host when the user explicitly changes cwd (e.g., the `/cd` slash command). The host is responsible for any related side-effects (file index, etc.); it does NOT change the process working directory (a session's cwd is per-session, not process-global). For local sessions the runtime validates the target first (an absolute path that exists on disk) and re-bases the permission primary directory; a rejected validation fails the call before anything is mutated, persisted, or emitted. Location-scoped permission rules are then re-keyed to the new directory (best-effort). Remote sessions only record the path.
        */
       setWorkingDirectory: async (params) => connection.sendRequest("session.metadata.setWorkingDirectory", { sessionId, ...params }),
       /**
@@ -2119,6 +2117,11 @@ function registerClientSessionApiHandlers(connection, getHandlers) {
   });
 }
 function registerClientGlobalApiHandlers(connection, handlers) {
+  connection.onRequest("hooks.invoke", async (params) => {
+    const handler = handlers.hooks;
+    if (!handler) throw new Error("No hooks client-global handler registered");
+    return handler.invoke(params);
+  });
   connection.onRequest("llmInference.httpRequestStart", async (params) => {
     const handler = handlers.llmInference;
     if (!handler) throw new Error("No llmInference client-global handler registered");