@github/copilot-sdk 1.0.3 → 1.0.5-preview.0

package/dist/generated/session-events.d.ts

@@ -5,7 +5,7 @@
 /**
  * Union of all session event variants emitted by the Copilot CLI runtime.
  */
-export type SessionEvent = StartEvent | ResumeEvent | RemoteSteerableChangedEvent | ErrorEvent | IdleEvent | TitleChangedEvent | ScheduleCreatedEvent | ScheduleCancelledEvent | AutopilotObjectiveChangedEvent | InfoEvent | WarningEvent | ModelChangeEvent | ModeChangedEvent | PermissionsChangedEvent | PlanChangedEvent | TodosChangedEvent | WorkspaceFileChangedEvent | HandoffEvent | TruncationEvent | SnapshotRewindEvent | ShutdownEvent | ContextChangedEvent | UsageInfoEvent | CompactionStartEvent | CompactionCompleteEvent | TaskCompleteEvent | UserMessageEvent | PendingMessagesModifiedEvent | AssistantTurnStartEvent | AssistantIntentEvent | AssistantReasoningEvent | AssistantReasoningDeltaEvent | AssistantStreamingDeltaEvent | AssistantMessageEvent | AssistantMessageStartEvent | AssistantMessageDeltaEvent | AssistantTurnEndEvent | AssistantUsageEvent | ModelCallFailureEvent | AbortEvent | ToolUserRequestedEvent | ToolExecutionStartEvent | ToolExecutionPartialResultEvent | ToolExecutionProgressEvent | ToolExecutionCompleteEvent | SkillInvokedEvent | SubagentStartedEvent | SubagentCompletedEvent | SubagentFailedEvent | SubagentSelectedEvent | SubagentDeselectedEvent | HookStartEvent | HookEndEvent | HookProgressEvent | BinaryAssetEvent | SystemMessageEvent | SystemNotificationEvent | PermissionRequestedEvent | PermissionCompletedEvent | UserInputRequestedEvent | UserInputCompletedEvent | ElicitationRequestedEvent | ElicitationCompletedEvent | SamplingRequestedEvent | SamplingCompletedEvent | McpOauthRequiredEvent | McpOauthCompletedEvent | CustomNotificationEvent | ExternalToolRequestedEvent | ExternalToolCompletedEvent | CommandQueuedEvent | CommandExecuteEvent | CommandCompletedEvent | AutoModeSwitchRequestedEvent | AutoModeSwitchCompletedEvent | CommandsChangedEvent | CapabilitiesChangedEvent | ExitPlanModeRequestedEvent | ExitPlanModeCompletedEvent | ToolsUpdatedEvent | BackgroundTasksChangedEvent | SkillsLoadedEvent | CustomAgentsUpdatedEvent | McpServersLoadedEvent | McpServerStatusChangedEvent | ExtensionsLoadedEvent | CanvasOpenedEvent | CanvasRegistryChangedEvent | CanvasClosedEvent | ExtensionsAttachmentsPushedEvent | McpAppToolCallCompleteEvent;
+export type SessionEvent = StartEvent | ResumeEvent | RemoteSteerableChangedEvent | ErrorEvent | IdleEvent | TitleChangedEvent | ScheduleCreatedEvent | ScheduleCancelledEvent | ScheduleRearmedEvent | AutopilotObjectiveChangedEvent | InfoEvent | WarningEvent | ModelChangeEvent | ModeChangedEvent | PermissionsChangedEvent | PlanChangedEvent | TodosChangedEvent | WorkspaceFileChangedEvent | HandoffEvent | TruncationEvent | SnapshotRewindEvent | ShutdownEvent | ContextChangedEvent | UsageInfoEvent | CompactionStartEvent | CompactionCompleteEvent | TaskCompleteEvent | UserMessageEvent | PendingMessagesModifiedEvent | AssistantTurnStartEvent | AssistantIntentEvent | AssistantReasoningEvent | AssistantReasoningDeltaEvent | AssistantStreamingDeltaEvent | AssistantMessageEvent | AssistantMessageStartEvent | AssistantMessageDeltaEvent | AssistantTurnEndEvent | AssistantIdleEvent | AssistantUsageEvent | ModelCallFailureEvent | AbortEvent | ToolUserRequestedEvent | ToolExecutionStartEvent | ToolExecutionPartialResultEvent | ToolExecutionProgressEvent | ToolExecutionCompleteEvent | SkillInvokedEvent | SubagentStartedEvent | SubagentCompletedEvent | SubagentFailedEvent | SubagentSelectedEvent | SubagentDeselectedEvent | HookStartEvent | HookEndEvent | HookProgressEvent | BinaryAssetEvent | SystemMessageEvent | SystemNotificationEvent | PermissionRequestedEvent | PermissionCompletedEvent | UserInputRequestedEvent | UserInputCompletedEvent | ElicitationRequestedEvent | ElicitationCompletedEvent | SamplingRequestedEvent | SamplingCompletedEvent | McpOauthRequiredEvent | McpOauthCompletedEvent | McpHeadersRefreshRequiredEvent | McpHeadersRefreshCompletedEvent | CustomNotificationEvent | ExternalToolRequestedEvent | ExternalToolCompletedEvent | CommandQueuedEvent | CommandExecuteEvent | CommandCompletedEvent | AutoModeSwitchRequestedEvent | AutoModeSwitchCompletedEvent | CommandsChangedEvent | CapabilitiesChangedEvent | ExitPlanModeRequestedEvent | ExitPlanModeCompletedEvent | ToolsUpdatedEvent | BackgroundTasksChangedEvent | SkillsLoadedEvent | CustomAgentsUpdatedEvent | McpServersLoadedEvent | McpServerStatusChangedEvent | ExtensionsLoadedEvent | CanvasOpenedEvent | CanvasRegistryChangedEvent | CanvasClosedEvent | CanvasUnavailableEvent | CanvasRecordedEvent | CanvasRemovedEvent | ExtensionsAttachmentsPushedEvent | McpAppToolCallCompleteEvent;
 /**
  * Hosting platform type of the repository (github or ado)
  */
@@ -111,9 +111,9 @@ export type UserMessageAgentMode =
 /** The agent is in shell-focused UI mode. */
  | "shell";
 /**
- * A user message attachment — a file, directory, code selection, blob, GitHub reference, or extension-supplied context payload
+ * A user message attachment — a file, directory, code selection, blob, GitHub reference, GitHub-anchored pointer, or extension-supplied context payload
  */
-export type Attachment = AttachmentFile | AttachmentDirectory | AttachmentSelection | AttachmentGitHubReference | AttachmentBlob | AttachmentExtensionContext;
+export type Attachment = AttachmentFile | AttachmentDirectory | AttachmentSelection | AttachmentGitHubReference | AttachmentGitHubCommit | AttachmentGitHubRelease | AttachmentGitHubActionsJob | AttachmentGitHubRepository | AttachmentGitHubFileDiff | AttachmentGitHubTreeComparison | AttachmentGitHubUrl | AttachmentGitHubFile | AttachmentGitHubSnippet | AttachmentBlob | AttachmentExtensionContext;
 /**
  * Why the binary data is absent: it exceeded the inline size limit, or its asset was unavailable
  */
@@ -132,6 +132,16 @@ export type AttachmentGitHubReferenceType =
  | "pr"
 /** GitHub discussion reference. */
  | "discussion";
+/**
+ * How this user message was delivered to the agentic loop, relative to whether the loop was already running. This is the timing axis only; the message's origin (human vs. system/command/schedule/skill/etc.) is carried separately by `source`. A system-injected message has a delivery too — e.g. a background-task notification waking an idle agent is `idle`, the same mechanism as a human starting a fresh turn.
+ */
+export type UserMessageDelivery = 
+/** Delivered while the loop was idle; starts its own run immediately (a human's fresh turn, or a system notification waking an idle agent). */
+"idle"
+/** Injected into the current in-flight run while the agent was busy (immediate mode). */
+ | "steering"
+/** Enqueued while the agent was busy; processed as its own run afterward. */
+ | "queued";
 /**
  * The system that produced a citation.
  */
@@ -355,6 +365,18 @@ export type ElicitationCompletedAction =
  | "decline"
 /** The user dismissed the request. */
  | "cancel";
+/**
+ * Reason the runtime is requesting host-provided MCP OAuth credentials
+ */
+export type McpOauthRequestReason = 
+/** Initial credentials are required before connecting to the MCP server. */
+"initial"
+/** The current host-provided credential was rejected and a replacement is requested. */
+ | "refresh"
+/** The server requires a new host authorization flow before continuing. */
+ | "reauth"
+/** The server requires a credential with additional scope or audience. */
+ | "upscope";
 /**
  * How the pending MCP OAuth request was completed
  */
@@ -363,6 +385,26 @@ export type McpOauthCompletionOutcome =
 "token"
 /** The request completed without an OAuth provider. */
  | "cancelled";
+/**
+ * Why dynamic headers are being requested.
+ */
+export type McpHeadersRefreshRequiredReason = 
+/** The transport is making its first dynamic header request for this server. */
+"startup"
+/** The previously cached dynamic headers expired. */
+ | "ttl-expired"
+/** The server returned 401 and stale dynamic headers were invalidated. */
+ | "auth-failed";
+/**
+ * How the pending MCP headers refresh request resolved.
+ */
+export type McpHeadersRefreshCompletedOutcome = 
+/** The host supplied dynamic headers. */
+"headers"
+/** The host responded with no dynamic headers. */
+ | "none"
+/** No response arrived within the bounded window. */
+ | "timeout";
 /**
  * The user's auto-mode-switch choice
  */
@@ -467,14 +509,6 @@ export type ExtensionsLoadedExtensionStatus =
  | "failed"
 /** The extension process is starting. */
  | "starting";
-/**
- * Runtime-controlled routing state for the instance. "ready" when the provider connection is live; "stale" when the provider has gone away and the instance is awaiting rebinding.
- */
-export type CanvasOpenedAvailability = 
-/** Provider connection is live; actions can be invoked. */
-"ready"
-/** Provider has gone away; the instance is awaiting rebinding. */
- | "stale";
 /**
  * Session event "session.start". Session initialization metadata including context and configuration
  */
@@ -539,6 +573,7 @@ export interface StartData {
      * Whether this session supports remote steering via GitHub
      */
     remoteSteerable?: boolean;
+    responseBudget?: ResponseBudgetConfig;
     /**
      * Model selected at session creation time, if any
      */
@@ -590,6 +625,19 @@ export interface WorkingDirectoryContext {
      */
     repositoryHost?: string;
 }
+/**
+ * Optional response budget limits.
+ */
+export interface ResponseBudgetConfig {
+    /**
+     * Maximum AI Credits allowed while responding to one top-level user message.
+     */
+    maxAiCredits?: number;
+    /**
+     * Maximum model-call iterations allowed while responding to one top-level user message.
+     */
+    maxModelIterations?: number;
+}
 /**
  * Session event "session.resume". Session resume metadata including current context and event count
  */
@@ -654,6 +702,10 @@ export interface ResumeData {
      * Whether this session supports remote steering via GitHub
      */
     remoteSteerable?: boolean;
+    /**
+     * Response budget limits currently configured at resume time; null when no budget is active
+     */
+    responseBudget?: ResponseBudgetConfig | null;
     /**
      * ISO 8601 timestamp when the session was resumed
      */
@@ -917,6 +969,10 @@ export interface ScheduleCreatedData {
      * Whether the schedule re-arms after each tick (`/every`) or fires once (`/after`)
      */
     recurring?: boolean;
+    /**
+     * True for a self-paced (`dynamic`) schedule: no fixed cadence; the model arms each next run via the `manage_schedule` `wakeup` action. `nextRunAt` is model-controlled rather than auto-computed.
+     */
+    selfPaced?: boolean;
     /**
      * IANA timezone the `cron` expression is evaluated in
      */
@@ -961,6 +1017,49 @@ export interface ScheduleCancelledData {
      */
     id: number;
 }
+/**
+ * Session event "session.schedule_rearmed". Self-paced schedule re-armed for its next run
+ */
+export interface ScheduleRearmedEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: ScheduleRearmedData;
+    /**
+     * When true, the event is transient and not persisted to the session event log on disk
+     */
+    ephemeral?: boolean;
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * Type discriminator. Always "session.schedule_rearmed".
+     */
+    type: "session.schedule_rearmed";
+}
+/**
+ * Self-paced schedule re-armed for its next run
+ */
+export interface ScheduleRearmedData {
+    /**
+     * Id of the self-paced schedule that was re-armed
+     */
+    id: number;
+    /**
+     * Absolute time (epoch milliseconds) the model armed the next run to fire
+     */
+    nextRunAt: number;
+}
 /**
  * Session event "session.autopilot_objective_changed". Autopilot objective state file operation details indicating what changed
  */
@@ -1942,6 +2041,10 @@ export interface CompactionCompleteData {
      * Copilot service request ID (x-copilot-service-request-id header) for the compaction LLM call
      */
     serviceRequestId?: string;
+    /**
+     * For failed compaction only: the HTTP status code of the compaction LLM call failure, when it carried one. Absent for successful compaction and for failures without an HTTP status (e.g. an empty model response or a transport error).
+     */
+    statusCode?: number;
     /**
      * Whether compaction completed successfully
      */
@@ -2099,6 +2202,7 @@ export interface UserMessageData {
      * The user's message text as displayed in the timeline
      */
     content: string;
+    delivery?: UserMessageDelivery;
     /**
      * CAPI interaction ID for correlating this user message with its turn
      */
@@ -2154,6 +2258,10 @@ export interface AttachmentFile {
      * Absolute file path
      */
     path: string;
+    /**
+     * Frozen rendered line this attachment contributed to the <tagged_files> prompt block (e.g. "* /path (123 lines)"). Captured at send time so resumed history reproduces the exact text the model saw, independent of later filesystem changes. Present only for attachments routed to <tagged_files> (mutually exclusive with assetId, which marks bytes sent natively).
+     */
+    taggedFilesEntry?: string;
     /**
      * Attachment type discriminator
      */
@@ -2184,6 +2292,10 @@ export interface AttachmentDirectory {
      * Absolute directory path
      */
     path: string;
+    /**
+     * Frozen rendered line this attachment contributed to the <tagged_files> prompt block (e.g. "* /path (12 items)"). Captured at send time so resumed history reproduces the exact text the model saw, independent of later filesystem changes.
+     */
+    taggedFilesEntry?: string;
     /**
      * Attachment type discriminator
      */
@@ -2270,6 +2382,231 @@ export interface AttachmentGitHubReference {
      */
     url: string;
 }
+/**
+ * Pointer to a GitHub commit.
+ */
+export interface AttachmentGitHubCommit {
+    /**
+     * First line of the commit message
+     */
+    message: string;
+    /**
+     * Full commit SHA
+     */
+    oid: string;
+    repo: GitHubRepoRef;
+    /**
+     * Attachment type discriminator
+     */
+    type: "github_commit";
+    /**
+     * URL to the commit on GitHub
+     */
+    url: string;
+}
+/**
+ * Pointer to a GitHub repository.
+ */
+export interface GitHubRepoRef {
+    /**
+     * Numeric GitHub repository id
+     */
+    id?: number;
+    /**
+     * Repository name (without owner)
+     */
+    name: string;
+    /**
+     * Repository owner login (user or organization)
+     */
+    owner: string;
+}
+/**
+ * Pointer to a GitHub release.
+ */
+export interface AttachmentGitHubRelease {
+    /**
+     * Human-readable release name
+     */
+    name: string;
+    repo: GitHubRepoRef;
+    /**
+     * Git tag the release is anchored to
+     */
+    tagName: string;
+    /**
+     * Attachment type discriminator
+     */
+    type: "github_release";
+    /**
+     * URL to the release on GitHub
+     */
+    url: string;
+}
+/**
+ * Pointer to a GitHub Actions job.
+ */
+export interface AttachmentGitHubActionsJob {
+    /**
+     * Terminal conclusion of the job when finished (e.g., success, failure, cancelled). Absent for in-progress jobs.
+     */
+    conclusion?: string;
+    /**
+     * Job id within the workflow run
+     */
+    jobId: number;
+    /**
+     * Display name of the job
+     */
+    jobName: string;
+    repo: GitHubRepoRef;
+    /**
+     * Attachment type discriminator
+     */
+    type: "github_actions_job";
+    /**
+     * URL to the job on GitHub
+     */
+    url: string;
+    /**
+     * Display name of the workflow the job ran in
+     */
+    workflowName: string;
+}
+/**
+ * Pointer to a GitHub repository.
+ */
+export interface AttachmentGitHubRepository {
+    /**
+     * Short description of the repository
+     */
+    description?: string;
+    /**
+     * Git ref this attachment is anchored at (branch, tag, or commit). When absent the default branch is implied.
+     */
+    ref?: string;
+    repo: GitHubRepoRef;
+    /**
+     * Attachment type discriminator
+     */
+    type: "github_repository";
+    /**
+     * URL to the repository on GitHub
+     */
+    url: string;
+}
+/**
+ * Pointer to a single-file diff. At least one of `head` and `base` must be present.
+ */
+export interface AttachmentGitHubFileDiff {
+    base?: AttachmentGitHubFileDiffSide;
+    head?: AttachmentGitHubFileDiffSide;
+    /**
+     * Attachment type discriminator
+     */
+    type: "github_file_diff";
+    /**
+     * URL to the diff on GitHub (e.g., a commit, compare, or PR-file URL)
+     */
+    url: string;
+}
+/**
+ * One side of a file diff (head or base)
+ */
+export interface AttachmentGitHubFileDiffSide {
+    /**
+     * Repository-relative path to the file
+     */
+    path: string;
+    /**
+     * Git ref (branch, tag, or commit SHA) the file is read at
+     */
+    ref: string;
+    repo: GitHubRepoRef;
+}
+/**
+ * Pointer to a comparison between two git revisions.
+ */
+export interface AttachmentGitHubTreeComparison {
+    base: AttachmentGitHubTreeComparisonSide;
+    head: AttachmentGitHubTreeComparisonSide;
+    /**
+     * Attachment type discriminator
+     */
+    type: "github_tree_comparison";
+    /**
+     * URL to the comparison on GitHub
+     */
+    url: string;
+}
+/**
+ * One side of a tree comparison (head or base)
+ */
+export interface AttachmentGitHubTreeComparisonSide {
+    repo: GitHubRepoRef;
+    /**
+     * Git revision (branch, tag, or commit SHA)
+     */
+    revision: string;
+}
+/**
+ * Generic GitHub URL reference.
+ */
+export interface AttachmentGitHubUrl {
+    /**
+     * Attachment type discriminator
+     */
+    type: "github_url";
+    /**
+     * URL to the GitHub resource
+     */
+    url: string;
+}
+/**
+ * Pointer to a file in a GitHub repository at a specific ref.
+ */
+export interface AttachmentGitHubFile {
+    /**
+     * Repository-relative path to the file
+     */
+    path: string;
+    /**
+     * Git ref the file is read at (branch, tag, or commit SHA)
+     */
+    ref: string;
+    repo: GitHubRepoRef;
+    /**
+     * Attachment type discriminator
+     */
+    type: "github_file";
+    /**
+     * URL to the file on GitHub
+     */
+    url: string;
+}
+/**
+ * Pointer to a line range inside a file in a GitHub repository.
+ */
+export interface AttachmentGitHubSnippet {
+    lineRange: AttachmentFileLineRange;
+    /**
+     * Repository-relative path to the file
+     */
+    path: string;
+    /**
+     * Git ref the file is read at (branch, tag, or commit SHA)
+     */
+    ref: string;
+    repo: GitHubRepoRef;
+    /**
+     * Attachment type discriminator
+     */
+    type: "github_snippet";
+    /**
+     * URL to the snippet on GitHub (with line anchor)
+     */
+    url: string;
+}
 /**
  * Blob attachment with inline base64-encoded data
  */
@@ -2989,6 +3326,45 @@ export interface AssistantTurnEndData {
      */
     turnId: string;
 }
+/**
+ * Session event "assistant.idle". Payload emitted whenever the main agent's processing loop goes idle, including while related background work (running agents or in-flight attached shell commands) is still pending and the session-level idle event is therefore deferred
+ */
+export interface AssistantIdleEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: AssistantIdleData;
+    /**
+     * Always true for events that are transient and not persisted to the session event log on disk.
+     */
+    ephemeral: true;
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * Type discriminator. Always "assistant.idle".
+     */
+    type: "assistant.idle";
+}
+/**
+ * Payload emitted whenever the main agent's processing loop goes idle, including while related background work (running agents or in-flight attached shell commands) is still pending and the session-level idle event is therefore deferred
+ */
+export interface AssistantIdleData {
+    /**
+     * True when the preceding agentic loop was cancelled via abort signal
+     */
+    aborted?: boolean;
+}
 /**
  * Session event "assistant.usage". LLM API call usage metrics including tokens, costs, quotas, and billing information
  */
@@ -3198,6 +3574,7 @@ export interface ModelCallFailureData {
      * GitHub request tracing ID (x-github-request-id header) for server-side log correlation
      */
     providerCallId?: string;
+    requestFingerprint?: ModelCallFailureRequestFingerprint;
     /**
      * Copilot service request ID (x-copilot-service-request-id header) for CAPI log correlation
      */
@@ -3208,6 +3585,39 @@ export interface ModelCallFailureData {
      */
     statusCode?: number;
 }
+/**
+ * Content-free structural summary of the failing request for diagnosing malformed 4xx calls
+ */
+export interface ModelCallFailureRequestFingerprint {
+    /**
+     * Total number of image content parts
+     */
+    imagePartCount: number;
+    /**
+     * Image parts whose media type cannot be determined (rejected by strict providers)
+     */
+    imagePartsMissingMediaType: number;
+    /**
+     * Role of the final message in the request
+     */
+    lastMessageRole?: string;
+    /**
+     * Total number of messages in the request
+     */
+    messageCount: number;
+    /**
+     * Tool calls whose name is missing or empty (rejected by strict providers)
+     */
+    namelessToolCallCount: number;
+    /**
+     * Total number of tool calls across assistant messages
+     */
+    toolCallCount: number;
+    /**
+     * Number of "tool" result messages in the request
+     */
+    toolResultMessageCount: number;
+}
 /**
  * Session event "abort". Turn abort information including the reason for termination
  */
@@ -3354,6 +3764,7 @@ export interface ToolExecutionStartData {
      * Tool call ID of the parent tool invocation when this event originates from a sub-agent
      */
     parentToolCallId?: string;
+    shellToolInfo?: ToolExecutionStartShellToolInfo;
     /**
      * Unique identifier for this tool call
      */
@@ -3368,6 +3779,19 @@ export interface ToolExecutionStartData {
      */
     turnId?: string;
 }
+/**
+ * Shell-aware path hints for a shell tool's command, captured at start time so consumers can snapshot a file's pre-image before the tool runs.
+ */
+export interface ToolExecutionStartShellToolInfo {
+    /**
+     * Whether the command includes a file write redirection (e.g., > or >>).
+     */
+    hasWriteFileRedirection: boolean;
+    /**
+     * File paths the command may read or write, derived from the command at start time. Produced by the same shell-aware extractor as PermissionRequestShell.possiblePaths, so it is present even when the command is auto-approved and no permission request fires.
+     */
+    possiblePaths: string[];
+}
 /**
  * Tool definition metadata, present for MCP tools with MCP Apps support
  */
@@ -4870,6 +5294,14 @@ export interface PermissionRequestShell {
      * URLs that may be accessed by the command
      */
     possibleUrls: PermissionRequestShellPossibleUrl[];
+    /**
+     * True when the model has requested to run this command outside the sandbox (it set requestSandboxBypass: true and the host opted in via sandbox.allowBypass). This is a request, not a grant: the command runs unsandboxed only if the user approves this permission request. Hosts should highlight the elevated risk in the approval UI.
+     */
+    requestSandboxBypass?: boolean;
+    /**
+     * Model-provided justification for the sandbox-bypass request. Only meaningful when requestSandboxBypass is true.
+     */
+    requestSandboxBypassReason?: string;
     /**
      * Tool call ID that triggered this permission request
      */
@@ -6046,6 +6478,7 @@ export interface McpOauthRequiredEvent {
  * OAuth authentication request for an MCP server
  */
 export interface McpOauthRequiredData {
+    reason: McpOauthRequestReason;
     /**
      * Unique identifier for this OAuth request; used to respond via session.mcp.oauth.handlePendingRequest
      */
@@ -6073,6 +6506,10 @@ export interface McpOauthRequiredStaticClientConfig {
      * OAuth client ID for the server
      */
     clientId: string;
+    /**
+     * Optional OAuth client secret for confidential static clients, when the runtime can resolve one
+     */
+    clientSecret?: string;
     /**
      * Optional non-default OAuth grant type. When set to 'client_credentials', the OAuth flow runs headlessly using the client_id + keychain-stored secret (no browser, no callback server).
      */
@@ -6091,9 +6528,9 @@ export interface McpOauthWWWAuthenticateParams {
      */
     error?: string;
     /**
-     * Protected resource metadata URL from the WWW-Authenticate resource_metadata parameter
+     * Protected resource metadata URL from the WWW-Authenticate resource_metadata parameter, if present
      */
-    resourceMetadataUrl: string;
+    resourceMetadataUrl?: string;
     /**
      * Requested OAuth scopes from the WWW-Authenticate scope parameter, if present
      */
@@ -6139,6 +6576,94 @@ export interface McpOauthCompletedData {
      */
     requestId: string;
 }
+/**
+ * Session event "mcp.headers_refresh_required". Dynamic headers refresh request for a remote MCP server
+ */
+export interface McpHeadersRefreshRequiredEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: McpHeadersRefreshRequiredData;
+    /**
+     * Always true for events that are transient and not persisted to the session event log on disk.
+     */
+    ephemeral: true;
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * Type discriminator. Always "mcp.headers_refresh_required".
+     */
+    type: "mcp.headers_refresh_required";
+}
+/**
+ * Dynamic headers refresh request for a remote MCP server
+ */
+export interface McpHeadersRefreshRequiredData {
+    reason: McpHeadersRefreshRequiredReason;
+    /**
+     * Unique identifier for this headers refresh request; used to respond via session.mcp.headers.handlePendingHeadersRefreshRequest()
+     */
+    requestId: string;
+    /**
+     * Display name of the remote MCP server requesting headers
+     */
+    serverName: string;
+    /**
+     * URL of the remote MCP server requesting headers
+     */
+    serverUrl: string;
+}
+/**
+ * Session event "mcp.headers_refresh_completed". MCP headers refresh request completion notification
+ */
+export interface McpHeadersRefreshCompletedEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: McpHeadersRefreshCompletedData;
+    /**
+     * Always true for events that are transient and not persisted to the session event log on disk.
+     */
+    ephemeral: true;
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * Type discriminator. Always "mcp.headers_refresh_completed".
+     */
+    type: "mcp.headers_refresh_completed";
+}
+/**
+ * MCP headers refresh request completion notification
+ */
+export interface McpHeadersRefreshCompletedData {
+    outcome: McpHeadersRefreshCompletedOutcome;
+    /**
+     * Request ID of the resolved headers refresh request
+     */
+    requestId: string;
+}
 /**
  * Session event "session.custom_notification". Opaque custom notification data. Consumers may branch on source and name, but payload semantics are source-defined.
  */
@@ -6854,6 +7379,10 @@ export interface SkillsLoadedData {
  * Schema for the `SkillsLoadedSkill` type.
  */
 export interface SkillsLoadedSkill {
+    /**
+     * Optional freeform hint describing the skill's expected arguments, from the `argument-hint` frontmatter field
+     */
+    argumentHint?: string;
     /**
      * Description of what the skill does
      */
@@ -7124,6 +7653,7 @@ export interface ExtensionsLoadedExtension {
 /**
  * Session event "session.canvas.opened".
  */
+/** @experimental */
 export interface CanvasOpenedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -7154,8 +7684,8 @@ export interface CanvasOpenedEvent {
 /**
  * Schema for the `CanvasOpenedData` type.
  */
+/** @experimental */
 export interface CanvasOpenedData {
-    availability: CanvasOpenedAvailability;
     /**
      * Provider-local canvas identifier
      */
@@ -7178,10 +7708,6 @@ export interface CanvasOpenedData {
      * Stable caller-supplied canvas instance identifier
      */
     instanceId: string;
-    /**
-     * Whether this notification represents an idempotent reopen
-     */
-    reopen: boolean;
     /**
      * Provider-supplied status text
      */
@@ -7198,6 +7724,7 @@ export interface CanvasOpenedData {
 /**
  * Session event "session.canvas.registry_changed".
  */
+/** @experimental */
 export interface CanvasRegistryChangedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -7228,6 +7755,7 @@ export interface CanvasRegistryChangedEvent {
 /**
  * Schema for the `CanvasRegistryChangedData` type.
  */
+/** @experimental */
 export interface CanvasRegistryChangedData {
     /**
      * Canvas declarations currently available
@@ -7237,6 +7765,7 @@ export interface CanvasRegistryChangedData {
 /**
  * Schema for the `CanvasRegistryChangedCanvas` type.
  */
+/** @experimental */
 export interface CanvasRegistryChangedCanvas {
     /**
      * Actions the agent or host may invoke
@@ -7272,6 +7801,7 @@ export interface CanvasRegistryChangedCanvas {
 /**
  * Schema for the `CanvasRegistryChangedCanvasAction` type.
  */
+/** @experimental */
 export interface CanvasRegistryChangedCanvasAction {
     /**
      * Action description
@@ -7291,6 +7821,7 @@ export interface CanvasRegistryChangedCanvasAction {
 /**
  * Session event "session.canvas.closed".
  */
+/** @experimental */
 export interface CanvasClosedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -7321,6 +7852,7 @@ export interface CanvasClosedEvent {
 /**
  * Schema for the `CanvasClosedData` type.
  */
+/** @experimental */
 export interface CanvasClosedData {
     /**
      * Provider-local canvas identifier
@@ -7335,6 +7867,163 @@ export interface CanvasClosedData {
      */
     instanceId: string;
 }
+/**
+ * Session event "session.canvas.unavailable". Transient signal that an open canvas instance's provider has dropped (for example the extension is reloading mid-session). The host should keep the panel mounted and surface a reconnecting affordance rather than tearing it down; a subsequent `session.canvas.opened` for the same instanceId clears the affordance once the provider reconnects with a fresh url. Ephemeral and never persisted, so it is never replayed on cold resume.
+ */
+/** @experimental */
+export interface CanvasUnavailableEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: CanvasUnavailableData;
+    /**
+     * Always true for events that are transient and not persisted to the session event log on disk.
+     */
+    ephemeral: true;
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * Type discriminator. Always "session.canvas.unavailable".
+     */
+    type: "session.canvas.unavailable";
+}
+/**
+ * Transient signal that an open canvas instance's provider has dropped (for example the extension is reloading mid-session). The host should keep the panel mounted and surface a reconnecting affordance rather than tearing it down; a subsequent `session.canvas.opened` for the same instanceId clears the affordance once the provider reconnects with a fresh url. Ephemeral and never persisted, so it is never replayed on cold resume.
+ */
+/** @experimental */
+export interface CanvasUnavailableData {
+    /**
+     * Provider-local canvas identifier
+     */
+    canvasId: string;
+    /**
+     * Owning provider identifier
+     */
+    extensionId: string;
+    /**
+     * Stable caller-supplied identifier of the canvas instance whose provider became unavailable
+     */
+    instanceId: string;
+}
+/**
+ * Session event "session.canvas.recorded". Durable record that a canvas instance is open, used to restore open canvases on cold session resume. Intentionally omits the transient url and availability.
+ */
+/** @experimental */
+export interface CanvasRecordedEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: CanvasRecordedData;
+    /**
+     * When true, the event is transient and not persisted to the session event log on disk
+     */
+    ephemeral?: boolean;
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * Type discriminator. Always "session.canvas.recorded".
+     */
+    type: "session.canvas.recorded";
+}
+/**
+ * Durable record that a canvas instance is open, used to restore open canvases on cold session resume. Intentionally omits the transient url and availability.
+ */
+/** @experimental */
+export interface CanvasRecordedData {
+    /**
+     * Provider-local canvas identifier
+     */
+    canvasId: string;
+    /**
+     * Owning provider identifier
+     */
+    extensionId: string;
+    /**
+     * Input supplied when the instance was opened
+     */
+    input?: {
+        [k: string]: unknown | undefined;
+    };
+    /**
+     * Stable caller-supplied canvas instance identifier
+     */
+    instanceId: string;
+    /**
+     * Rendered title
+     */
+    title?: string;
+}
+/**
+ * Session event "session.canvas.removed". Durable record that a canvas instance was closed, superseding a prior instance_recorded during resume replay.
+ */
+/** @experimental */
+export interface CanvasRemovedEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: CanvasRemovedData;
+    /**
+     * When true, the event is transient and not persisted to the session event log on disk
+     */
+    ephemeral?: boolean;
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * Type discriminator. Always "session.canvas.removed".
+     */
+    type: "session.canvas.removed";
+}
+/**
+ * Durable record that a canvas instance was closed, superseding a prior instance_recorded during resume replay.
+ */
+/** @experimental */
+export interface CanvasRemovedData {
+    /**
+     * Provider-local canvas identifier
+     */
+    canvasId: string;
+    /**
+     * Owning provider identifier
+     */
+    extensionId: string;
+    /**
+     * Stable caller-supplied identifier of the canvas instance that was closed
+     */
+    instanceId: string;
+}
 /**
  * Session event "session.extensions.attachments_pushed".
  */