@github/copilot-sdk 1.0.8 → 1.0.9-preview.1

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 | ScheduleRearmedEvent | AutopilotObjectiveChangedEvent | InfoEvent | WarningEvent | ModelChangeEvent | ModeChangedEvent | SessionLimitsChangedEvent | PermissionsChangedEvent | PlanChangedEvent | TodosChangedEvent | WorkspaceFileChangedEvent | HandoffEvent | TruncationEvent | SnapshotRewindEvent | ShutdownEvent | UsageCheckpointEvent | ContextChangedEvent | UsageInfoEvent | CompactionStartEvent | CompactionCompleteEvent | TaskCompleteEvent | UserMessageEvent | PendingMessagesModifiedEvent | AssistantTurnStartEvent | AssistantTurnRetryEvent | AssistantIntentEvent | AssistantServerToolProgressEvent | AssistantReasoningEvent | AssistantReasoningDeltaEvent | AssistantToolCallDeltaEvent | AssistantStreamingDeltaEvent | AssistantMessageEvent | AssistantMessageStartEvent | AssistantMessageDeltaEvent | AssistantTurnEndEvent | AssistantIdleEvent | AssistantUsageEvent | ModelCallFailureEvent | ModelCallStartEvent | AbortEvent | ToolUserRequestedEvent | ToolExecutionStartEvent | ToolExecutionPartialResultEvent | ToolExecutionProgressEvent | ToolExecutionCompleteEvent | ToolSearchActivatedEvent | 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 | SessionLimitsExhaustedRequestedEvent | SessionLimitsExhaustedCompletedEvent | AutoModeResolvedEvent | ManagedSettingsResolvedEvent | ManagedSettingsEnforcedEvent | CommandsChangedEvent | CapabilitiesChangedEvent | ExitPlanModeRequestedEvent | ExitPlanModeCompletedEvent | ToolsUpdatedEvent | BackgroundTasksChangedEvent | SkillsLoadedEvent | CustomAgentsUpdatedEvent | McpServersLoadedEvent | McpServerStatusChangedEvent | McpToolsListChangedEvent | McpResourcesListChangedEvent | McpPromptsListChangedEvent | ExtensionsLoadedEvent | CanvasOpenedEvent | CanvasRegistryChangedEvent | CanvasClosedEvent | CanvasUnavailableEvent | CanvasRecordedEvent | CanvasRemovedEvent | ExtensionsAttachmentsPushedEvent | McpAppToolCallCompleteEvent;
+export type SessionEvent = StartEvent | ResumeEvent | RemoteSteerableChangedEvent | ErrorEvent | IdleEvent | TitleChangedEvent | ScheduleCreatedEvent | ScheduleCancelledEvent | ScheduleRearmedEvent | AutopilotObjectiveChangedEvent | InfoEvent | WarningEvent | ModelChangeEvent | ModeChangedEvent | SessionLimitsChangedEvent | PermissionsChangedEvent | PlanChangedEvent | TodosChangedEvent | WorkspaceFileChangedEvent | HandoffEvent | TruncationEvent | SnapshotRewindEvent | ShutdownEvent | UsageCheckpointEvent | ContextChangedEvent | UsageInfoEvent | CompactionStartEvent | CompactionCompleteEvent | TaskCompleteEvent | UserMessageEvent | PendingMessagesModifiedEvent | AssistantTurnStartEvent | AssistantTurnRetryEvent | AssistantIntentEvent | AssistantServerToolProgressEvent | AssistantReasoningEvent | AssistantReasoningDeltaEvent | AssistantToolCallDeltaEvent | AssistantStreamingDeltaEvent | AssistantMessageEvent | AssistantMessageStartEvent | AssistantMessageDeltaEvent | AssistantTurnEndEvent | AssistantIdleEvent | AssistantUsageEvent | ModelCallFailureEvent | ModelCallStartEvent | AbortEvent | ToolUserRequestedEvent | ToolExecutionStartEvent | ToolExecutionPartialResultEvent | ToolExecutionProgressEvent | ToolExecutionCompleteEvent | ToolSearchActivatedEvent | 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 | SessionLimitsExhaustedRequestedEvent | SessionLimitsExhaustedCompletedEvent | AutoModeResolvedEvent | ManagedSettingsResolvedEvent | ManagedSettingsEnforcedEvent | CommandsChangedEvent | CapabilitiesChangedEvent | ExitPlanModeRequestedEvent | ExitPlanModeCompletedEvent | ToolsUpdatedEvent | BackgroundTasksChangedEvent | FactoryRunUpdatedEvent | SkillsLoadedEvent | CustomAgentsUpdatedEvent | McpServersLoadedEvent | McpServerStatusChangedEvent | McpToolsListChangedEvent | McpResourcesListChangedEvent | McpPromptsListChangedEvent | ExtensionsLoadedEvent | CanvasOpenedEvent | CanvasRegistryChangedEvent | CanvasClosedEvent | CanvasUnavailableEvent | CanvasRecordedEvent | CanvasRemovedEvent | ExtensionsAttachmentsPushedEvent | McpAppToolCallCompleteEvent;
 /**
  * Hosting platform type of the repository (github or ado)
  */
@@ -42,6 +42,14 @@ export type Verbosity =
  | "medium"
 /** A more detailed response was requested. */
  | "high";
+/**
+ * Who created the schedule: `user` (an explicit user action such as `/every` or `/after`) or `model` (the agent via the `manage_schedule` tool). Gates whether a scheduled skill that opted out of model invocation may fire: only user-created schedules may.
+ */
+export type ScheduleOrigin = 
+/** The schedule was created by an explicit user action, such as `/every` or `/after`. */
+"user"
+/** The schedule was created by the agent via the `manage_schedule` tool. */
+ | "model";
 /**
  * The type of operation performed on the autopilot objective state file
  */
@@ -119,6 +127,30 @@ export type ShutdownType =
 "routine"
 /** The session ended because of a crash or fatal error. */
  | "error";
+/**
+ * What initiated a conversation compaction
+ */
+export type CompactionTrigger = 
+/** Background compaction started automatically because context utilization crossed the background threshold. */
+"threshold"
+/** Compaction forced by a context-limit model response (e.g. HTTP 413) before retrying the request. */
+ | "context_limit_retry"
+/** User-requested compaction, e.g. the /compact command or the history.compact API. */
+ | "manual"
+/** Emergency compaction triggered by high process memory usage. */
+ | "memory_pressure"
+/** Compaction requested while switching to a model with a smaller context window. */
+ | "model_switch";
+/**
+ * Semantic result of evaluating a task completion request
+ */
+export type TaskCompletionOutcome = 
+/** The completion request was accepted and the objective is complete. */
+"completed"
+/** The completion request was rejected because more work or validation remains. */
+ | "continue"
+/** Completion cannot proceed without intervention; the active objective is paused when one is identified. */
+ | "blocked";
 /**
  * The agent mode that was active when this message was sent
  */
@@ -333,7 +365,7 @@ export type SystemMessageRole =
 /**
  * Structured metadata identifying what triggered this notification
  */
-export type SystemNotification = SystemNotificationAgentCompleted | SystemNotificationAgentIdle | SystemNotificationNewInboxMessage | SystemNotificationShellCompleted | SystemNotificationShellDetachedCompleted | SystemNotificationInstructionDiscovered;
+export type SystemNotification = SystemNotificationAgentCompleted | SystemNotificationAgentIdle | SystemNotificationNewInboxMessage | SystemNotificationShellCompleted | SystemNotificationShellDetachedCompleted | SystemNotificationInstructionDiscovered | SystemNotificationUnclassified;
 /**
  * Whether the agent completed successfully or failed
  */
@@ -366,6 +398,21 @@ export type PermissionRequestMemoryDirection =
  * Derived user-facing permission prompt details for UI consumers
  */
 export type PermissionPromptRequest = PermissionPromptRequestCommands | PermissionPromptRequestWrite | PermissionPromptRequestRead | PermissionPromptRequestMcp | PermissionPromptRequestUrl | PermissionPromptRequestMemory | PermissionPromptRequestCustomTool | PermissionPromptRequestPath | PermissionPromptRequestHook | PermissionPromptRequestExtensionManagement | PermissionPromptRequestExtensionPermissionAccess;
+/**
+ * Why the auto-approval judge produced no usable recommendation. Present only alongside an `error` recommendation, where the human-readable reason is a fixed string and therefore cannot distinguish these cases. Intended to make a judge failure reportable by a consumer that has no access to the host's logs.
+ */
+/** @experimental */
+export type AutoApprovalJudgeFailureReason = 
+/** The judge model call exceeded its deadline. */
+"timeout"
+/** The judge model call was cancelled before it returned. */
+ | "abort"
+/** The judge model call completed but returned no content. */
+ | "empty_response"
+/** The judge model call failed (for example a transport, authentication, or rate-limit error). */
+ | "model_error"
+/** The judge model replied, but the reply carried no ALLOW/DENY verdict. */
+ | "parse_error";
 /**
  * Outcome of the auto-approval safety judge for a permission request. Present only when auto mode is enabled; its absence means the judge did not evaluate the request (auto mode was off).
  */
@@ -719,6 +766,10 @@ export interface WorkingDirectoryContext {
      */
     headCommit?: string;
     hostType?: WorkingDirectoryContextHostType;
+    /**
+     * Set on the immediate preliminary event of a working-directory change, before the git context is resolved. A settled follow-up event (enriched with git context, or cwd-only for a non-repository) is always emitted afterward, so observers may defer to it. Absent on standalone/final events (e.g. relay context changes).
+     */
+    pendingGitContext?: boolean;
     /**
      * Repository identifier derived from the git remote URL ("owner/name" for GitHub, "org/project/repo" for Azure DevOps)
      */
@@ -781,7 +832,7 @@ export interface ResumeData {
      */
     contextTier?: ContextTier | null;
     /**
-     * When true, tool calls and permission requests left in flight by the previous session lifetime remain pending after resume and the agentic loop awaits their results. User sends are queued behind the pending work until all such requests reach a terminal state. When false (the default), any such tool calls and permission requests are immediately marked as interrupted on resume.
+     * When true, tool calls and permission requests left in flight by the previous session lifetime remain pending after resume and the agentic loop awaits their results. User sends are queued behind the pending work until all such requests reach a terminal state. When false or omitted, pending work is normally marked as interrupted unless the resume passively joined live work owned by another client; sessionWasActive distinguishes that case.
      */
     continuePendingWork?: boolean;
     /**
@@ -814,7 +865,7 @@ export interface ResumeData {
      */
     sessionLimits?: SessionLimitsConfig | null;
     /**
-     * True when this resume attached to a session that the runtime already had running in-memory (for example, an extension joining a session another client was actively driving). False (or omitted) for cold resumes — the runtime had to reconstitute the session from its persisted event log.
+     * True when this resume passively joined a session that already had live work running in the runtime - an agent turn, a native queue run, a queued resume continuation, or an in-flight send (for example, an extension joining a session another client was actively driving). False (or omitted) when the session had no live work or when the resume explicitly abandoned pending work, including cold resumes and suspended sessions that remain resident in memory.
      */
     sessionWasActive?: boolean;
     verbosity?: Verbosity;
@@ -1061,6 +1112,7 @@ export interface ScheduleCreatedData {
      * Interval between ticks in milliseconds (relative-interval schedules)
      */
     intervalMs?: number;
+    origin?: ScheduleOrigin;
     /**
      * Prompt text that gets enqueued on every tick
      */
@@ -2145,6 +2197,10 @@ export interface CompactionStartData {
      * Token count from non-system messages (user, assistant, tool) at compaction start
      */
     conversationTokens?: number;
+    /**
+     * Total context tokens (system + conversation + tool definitions) at compaction start, when known
+     */
+    currentTokens?: number;
     /**
      * Model identifier used for compaction, when known
      */
@@ -2153,10 +2209,15 @@ export interface CompactionStartData {
      * Token count from system message(s) at compaction start
      */
     systemTokens?: number;
+    /**
+     * Model context window token limit the compaction is targeting, when known
+     */
+    tokenLimit?: number;
     /**
      * Token count from tool definitions at compaction start
      */
     toolDefinitionsTokens?: number;
+    trigger?: CompactionTrigger;
 }
 /**
  * Session event "session.compaction_complete". Conversation compaction results including success status, metrics, and optional error details
@@ -2253,6 +2314,10 @@ export interface CompactionCompleteData {
      * Token count from system message(s) after compaction
      */
     systemTokens?: number;
+    /**
+     * Model context window token limit the compaction was targeting, when known
+     */
+    tokenLimit?: number;
     /**
      * Number of tokens removed during compaction
      */
@@ -2261,6 +2326,7 @@ export interface CompactionCompleteData {
      * Token count from tool definitions after compaction
      */
     toolDefinitionsTokens?: number;
+    trigger?: CompactionTrigger;
 }
 /**
  * Token usage breakdown for the compaction LLM call (aligned with assistant.usage format)
@@ -2347,7 +2413,16 @@ export interface TaskCompleteEvent {
  */
 export interface TaskCompleteData {
     /**
-     * Whether the tool call succeeded. False when validation failed (e.g., invalid arguments)
+     * Active autopilot objective ID evaluated by the completion reviewer
+     */
+    objectiveId?: number;
+    outcome?: TaskCompletionOutcome;
+    /**
+     * Label-safe runtime rationale for the completion decision (e.g. a cancellation or pause/resume downgrade), when one applies. Reviewer-authored rationale is intentionally omitted here because this event has no IFC label channel; the reviewer's findings remain available through its own labeled sub-agent events
+     */
+    reason?: string;
+    /**
+     * Whether the task was accepted as complete. False when validation failed or completion was rejected or blocked by the reviewer
      */
     success?: boolean;
     /**
@@ -2416,7 +2491,7 @@ export interface UserMessageData {
      */
     parentAgentTaskId?: string;
     /**
-     * Origin of this message, used for timeline filtering (e.g., "skill-pdf" for skill-injected messages that should be hidden from the user)
+     * Origin of this message, used for timeline filtering and attribution (e.g., `skill-pdf` for hidden skill injection or `agent-<agent-id>` for an inter-agent prompt)
      */
     source?: string;
     /**
@@ -3095,6 +3170,7 @@ export interface AssistantReasoningData {
      * Unique identifier for this reasoning block
      */
     reasoningId: string;
+    rte?: boolean;
 }
 /**
  * Session event "assistant.reasoning_delta". Streaming reasoning delta for incremental extended thinking updates
@@ -3323,6 +3399,7 @@ export interface AssistantMessageData {
      * GitHub request tracing ID (x-github-request-id header) for correlating with server-side logs
      */
     requestId?: string;
+    rte?: boolean;
     serverTools?: AssistantMessageServerTools;
     /**
      * Copilot service request ID (x-copilot-service-request-id header) for CAPI log correlation
@@ -3767,6 +3844,10 @@ export interface AssistantUsageData {
      * Number of input tokens consumed
      */
     inputTokens?: number;
+    /**
+     * Coarse classification of the interaction that produced this call, mirroring the session's per-request agent context (e.g. `conversation-agent`, `conversation-subagent`, `conversation-sampling`, `conversation-background`, `conversation-compaction`, `conversation-user`). Non-billing; lets consumers attribute a model call to a call class (e.g. sub-agent/sidekick) independently of the billing initiator. Absent when the runtime did not classify the request.
+     */
+    interactionType?: string;
     /**
      * Average inter-token latency in milliseconds. Only available for streaming requests
      */
@@ -3796,6 +3877,7 @@ export interface AssistantUsageData {
      * Number of output tokens used for reasoning (e.g., chain-of-thought)
      */
     reasoningTokens?: number;
+    rte?: boolean;
     /**
      * Copilot service request ID (x-copilot-service-request-id header) for CAPI log correlation
      */
@@ -3925,6 +4007,7 @@ export interface ModelCallFailureData {
      */
     reasoningEffort?: string;
     requestFingerprint?: ModelCallFailureRequestFingerprint;
+    rte?: boolean;
     /**
      * Copilot service request ID (x-copilot-service-request-id header) for CAPI log correlation
      */
@@ -4128,6 +4211,7 @@ export interface ToolExecutionStartData {
      * Tool call ID of the parent tool invocation when this event originates from a sub-agent
      */
     parentToolCallId?: string;
+    rte?: boolean;
     shellToolInfo?: ToolExecutionStartShellToolInfo;
     /**
      * Unique identifier for this tool call
@@ -4336,6 +4420,7 @@ export interface ToolExecutionCompleteData {
      */
     parentToolCallId?: string;
     result?: ToolExecutionCompleteResult;
+    rte?: boolean;
     /**
      * Whether this tool execution ran inside a sandbox container
      */
@@ -5473,6 +5558,10 @@ export interface SystemMessageData {
      * The system or developer prompt text sent as model input
      */
     content: string;
+    /**
+     * Logical interaction identifier for the model run receiving this prompt
+     */
+    interactionId?: string;
     metadata?: SystemMessageMetadata;
     /**
      * Optional name identifier for the message source
@@ -5670,6 +5759,21 @@ export interface SystemNotificationInstructionDiscovered {
      */
     type: "instruction_discovered";
 }
+/**
+ * System notification metadata from an external host that does not match a runtime-owned notification kind.
+ */
+export interface SystemNotificationUnclassified {
+    /**
+     * Opaque metadata supplied by the external host, when present.
+     */
+    metadata?: {
+        [k: string]: unknown | undefined;
+    };
+    /**
+     * Type discriminator. Always "unclassified".
+     */
+    type: "unclassified";
+}
 /**
  * Session event "permission.requested". Permission request notification requiring client approval with request details
  */
@@ -5714,6 +5818,12 @@ export interface PermissionRequestedData {
      * When true, this permission was already resolved by a permissionRequest hook and requires no client action
      */
     resolvedByHook?: boolean;
+    /**
+     * Neutral risk metadata supplied by the tool host. Consumers may display this value but must not use it to bypass the permission decision.
+     */
+    riskAssessment?: {
+        [k: string]: unknown | undefined;
+    };
 }
 /**
  * Shell command permission request
@@ -5727,6 +5837,10 @@ export interface PermissionRequestShell {
      * Parsed command identifiers found in the command text
      */
     commands: PermissionRequestShellCommand[];
+    /**
+     * Parsed command segments, including arguments, used for managed policy matching
+     */
+    commandSegments?: PermissionRequestShellCommandSegment[];
     /**
      * The complete shell command text to be executed
      */
@@ -5743,6 +5857,10 @@ export interface PermissionRequestShell {
      * Permission kind discriminator
      */
     kind: "shell";
+    /**
+     * Whether managed policy requires a human response and forbids host auto-approval
+     */
+    managedApprovalRequired?: boolean;
     /**
      * File paths that may be read or written by the command
      */
@@ -5781,6 +5899,19 @@ export interface PermissionRequestShellCommand {
      */
     readOnly: boolean;
 }
+/**
+ * A parsed shell command segment used for argument-aware managed policy matching.
+ */
+export interface PermissionRequestShellCommandSegment {
+    /**
+     * Full text of this command segment, including arguments
+     */
+    fullCommandText: string;
+    /**
+     * Command identifier (e.g., executable name)
+     */
+    identifier: string;
+}
 /**
  * A URL that may be accessed by a command in a shell permission request.
  */
@@ -5814,6 +5945,10 @@ export interface PermissionRequestWrite {
      * Permission kind discriminator
      */
     kind: "write";
+    /**
+     * Whether managed policy requires a human response and forbids host auto-approval
+     */
+    managedApprovalRequired?: boolean;
     /**
      * Complete new file contents for newly created files
      */
@@ -5843,6 +5978,10 @@ export interface PermissionRequestRead {
      * Permission kind discriminator
      */
     kind: "read";
+    /**
+     * Whether managed policy requires a human response and forbids host auto-approval
+     */
+    managedApprovalRequired?: boolean;
     /**
      * Path of the file or directory being read
      */
@@ -5907,6 +6046,14 @@ export interface PermissionRequestUrl {
      * Permission kind discriminator
      */
     kind: "url";
+    /**
+     * Whether managed policy requires a human response and forbids host auto-approval
+     */
+    managedApprovalRequired?: boolean;
+    /**
+     * Immediately preceding URL when this request is for a redirect target
+     */
+    redirectedFrom?: string;
     /**
      * True when this URL fetch is requesting to bypass the sandbox network policy: either the model set requestSandboxBypass: true, or the tool re-issued the request as an interactive bypass after the network policy denied the approved URL (host opted in via sandbox.allowBypass). This is a request, not a grant: the fetch runs only if the user approves this permission request. Hosts should highlight the elevated risk in the approval UI.
      */
@@ -6081,6 +6228,10 @@ export interface PermissionPromptRequestCommands {
      * Prompt kind discriminator
      */
     kind: "commands";
+    /**
+     * Whether managed policy requires a human response and forbids host auto-approval
+     */
+    managedApprovalRequired?: boolean;
     /**
      * Tool call ID that triggered this permission request
      */
@@ -6095,6 +6246,11 @@ export interface PermissionPromptRequestCommands {
  */
 /** @experimental */
 export interface PermissionAutoApproval {
+    failureReason?: AutoApprovalJudgeFailureReason;
+    /**
+     * Model id that produced the recommendation, when the judge was consulted and reported one. Absent for `excluded` (the judge was not consulted) and for failures that occurred before a model was selected.
+     */
+    model?: string;
     /**
      * Human-readable reason for the judge's recommendation, when available.
      */
@@ -6131,6 +6287,10 @@ export interface PermissionPromptRequestWrite {
      * Prompt kind discriminator
      */
     kind: "write";
+    /**
+     * Whether managed policy requires a human response and forbids host auto-approval
+     */
+    managedApprovalRequired?: boolean;
     /**
      * Complete new file contents for newly created files
      */
@@ -6158,6 +6318,10 @@ export interface PermissionPromptRequestRead {
      * Prompt kind discriminator
      */
     kind: "read";
+    /**
+     * Whether managed policy requires a human response and forbids host auto-approval
+     */
+    managedApprovalRequired?: boolean;
     /**
      * Path of the file or directory being read
      */
@@ -6222,6 +6386,14 @@ export interface PermissionPromptRequestUrl {
      * Prompt kind discriminator
      */
     kind: "url";
+    /**
+     * Whether managed policy requires a human response and forbids host auto-approval
+     */
+    managedApprovalRequired?: boolean;
+    /**
+     * Immediately preceding URL when this prompt is for a redirect target
+     */
+    redirectedFrom?: string;
     /**
      * True when this URL fetch is requesting to bypass the sandbox network policy: either the model set requestSandboxBypass: true, or the tool re-issued the request as an interactive bypass after the network policy denied the approved URL (host opted in via sandbox.allowBypass). This is a request, not a grant: the fetch runs only if the user approves this permission request. Hosts should highlight the elevated risk in the approval UI.
      */
@@ -7787,6 +7959,10 @@ export interface AutoModeResolvedEvent {
  */
 /** @experimental */
 export interface AutoModeResolvedData {
+    /**
+     * Models offered to the router for this resolution
+     */
+    availableModels?: string[];
     /**
      * Ordered candidate model list the router returned, when not a fallback
      */
@@ -7801,15 +7977,47 @@ export interface AutoModeResolvedData {
      * The concrete model the session will use after any intent refinement
      */
     chosenModel: string;
+    /**
+     * The chosen model's score shortfall relative to the top candidate
+     */
+    chosenShortfall?: number;
     /**
      * Classifier confidence for the predicted label, when available
      */
     confidence?: number;
+    /**
+     * End-to-end client wait time for the router request in milliseconds
+     */
+    endToEndLatencyMs?: number;
+    /**
+     * Whether the router fell back to the standard Auto selection
+     */
+    fallback?: boolean;
+    /**
+     * Server-provided reason for falling back, when available
+     */
+    fallbackReason?: string;
+    /**
+     * Whether the routed prompt contained an image
+     */
+    hasImage?: boolean;
     /**
      * The predicted classifier label (e.g. `needs_reasoning`), when available
      */
     predictedLabel?: string;
     reasoningBucket?: AutoModeResolvedReasoningBucket;
+    /**
+     * Server-reported router processing time in milliseconds
+     */
+    routerLatencyMs?: number;
+    /**
+     * The routing method the server applied, when Auto Intent ran
+     */
+    routingMethod?: string;
+    /**
+     * Whether a sticky model choice overrode the router result
+     */
+    stickyOverride?: boolean;
 }
 /**
  * Session event "session.managed_settings_resolved". Enterprise managed-settings resolution: the effective managed settings the session applied and where they came from, so SDK clients can show users what is enterprise-managed and by which authority. Fires whenever managed policy is (re)applied — at session start, on resume, and on account switch. This is an ephemeral live snapshot (delivered to subscribers but not persisted to the session event log), because at session start it resolves before `session.start` is emitted; for a session-independent pull, use the SDK `getManagedSettings()` API, which returns the identical payload. Managed settings have a single authoritative source, so the highest-authority present layer (server > device) wins wholesale; `bypassPermissionsDisabled` is deny-wins across layers. Marked experimental while the managed-settings surface stabilizes.
@@ -7863,6 +8071,10 @@ export interface ManagedSettingsResolvedData {
      * The setting keys under enterprise management in the effective managed settings (e.g. `model`, `enabledPlugins`, `permissions`). Empty when no managed settings are in force.
      */
     managedKeys: string[];
+    /**
+     * Whether server and device each supplied a permission allowlist, so enforcement intersects them and the flattened settings payload omits `permissions.allow`.
+     */
+    permissionsAllowIntersected?: boolean;
     /**
      * Whether the server (account/org) managed-settings layer was present
      */
@@ -8209,6 +8421,48 @@ export interface BackgroundTasksChangedEvent {
  */
 export interface BackgroundTasksChangedData {
 }
+/**
+ * Session event "factory.run_updated". Ephemeral invalidation signal for a changed factory run.
+ */
+/** @experimental */
+export interface FactoryRunUpdatedEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: FactoryRunUpdatedData;
+    /**
+     * 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 "factory.run_updated".
+     */
+    type: "factory.run_updated";
+}
+/**
+ * Ephemeral invalidation signal for a changed factory run.
+ */
+/** @experimental */
+export interface FactoryRunUpdatedData {
+    /**
+     * Monotonic revision now available for the run.
+     */
+    revision: number;
+    runId: string;
+}
 /**
  * Session event "session.skills_loaded". Payload of `session.skills_loaded` listing resolved skill metadata.
  */

package/dist/index.d.ts

@@ -7,7 +7,9 @@ export { CopilotClient } from "./client.js";
 export { RuntimeConnection } from "./types.js";
 export { BuiltInTools, ToolSet } from "./toolSet.js";
 export { CopilotSession, type AssistantMessageEvent } from "./session.js";
+export { defineFactory, FactoryResumeError, isFactoryRunTerminal } from "./factory.js";
 export { Canvas, CanvasError, createCanvas, type CanvasAction, type CanvasDeclaration, type CanvasHostContext, type CanvasHostContextCapabilities, type CanvasJsonSchema, type CanvasOptions, } from "./canvas.js";
-export { defineTool, approveAll, convertMcpCallToolResult, createSessionFsAdapter, CopilotRequestHandler, CopilotWebSocketHandler, CopilotWebSocketCloseStatus, CopilotWebSocketForwarder, SYSTEM_MESSAGE_SECTIONS, } from "./types.js";
+export { defineTool, approveAll, convertMcpCallToolResult, createSessionFsAdapter, CopilotRequestHandler, CopilotWebSocketHandler, CopilotWebSocketCloseStatus, CopilotWebSocketForwarder, SessionFsSqliteTransactionFailure, SYSTEM_MESSAGE_SECTIONS, } from "./types.js";
 export type * from "./generated/session-events.js";
-export type { CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, CopilotClientMode, CopilotClientOptions, CopilotExpAssignmentResponse, StdioRuntimeConnection, InProcessRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, ChildProcessRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExpConfigEntry, ExpFlagValue, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ExtensionInfo, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, BearerTokenProvider, MessageOptions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, CapiSessionOptions, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, NamedProviderConfig, PermissionHandler, PermissionRequest, PermissionRequestResult, ProviderConfig, ProviderModelConfig, ProviderTokenArgs, RemoteSessionMode, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, CopilotRequestContext, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, CurrentToolMetadata, ToolTelemetry, ToolResultObject, ToolSearchConfig, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
+export type { CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, AgentStopHandler, AgentStopHookInput, AgentStopHookOutput, CopilotClientMode, CopilotClientOptions, CopilotExpAssignmentResponse, StdioRuntimeConnection, InProcessRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, ChildProcessRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExpConfigEntry, ExpFlagValue, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ExtensionInfo, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, FactoryLimits, FactoryMeta, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, BearerTokenProvider, MessageOptions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, CapiSessionOptions, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, NamedProviderConfig, PermissionHandler, PermissionRequest, PermissionRequestResult, ProviderConfig, ProviderModelConfig, ProviderTokenArgs, RemoteSessionMode, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionHooks, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, SessionFsSqliteStatement, SessionFsSqliteTransactionErrorClass, CopilotRequestContext, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, CurrentToolMetadata, ToolTelemetry, ToolResultObject, ToolSearchConfig, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
+export type { RunOptions, ResumeOptions, FactoryResumeErrorCode, SessionFactoryApi, FactoryAgentOptions, FactoryContext, FactoryDefinition, FactoryHandle, FactoryJsonSchema, JsonValue, FactoryPipelineStage, FactoryStepOptions, FactoryRunResult, FactoryRunStatus, FactoryRunSummary, FactoryRunDetail, FactoryProgressPage, FactoryProgressLine, FactoryPhaseObservation, FactoryPhaseStatus, FactoryAgentSummary, } from "./factory.js";

package/dist/index.js

@@ -2,6 +2,7 @@ import { CopilotClient } from "./client.js";
 import { RuntimeConnection } from "./types.js";
 import { BuiltInTools, ToolSet } from "./toolSet.js";
 import { CopilotSession } from "./session.js";
+import { defineFactory, FactoryResumeError, isFactoryRunTerminal } from "./factory.js";
 import {
   Canvas,
   CanvasError,
@@ -16,6 +17,7 @@ import {
   CopilotWebSocketHandler,
   CopilotWebSocketCloseStatus,
   CopilotWebSocketForwarder,
+  SessionFsSqliteTransactionFailure,
   SYSTEM_MESSAGE_SECTIONS
 } from "./types.js";
 export {
@@ -28,12 +30,16 @@ export {
   CopilotWebSocketCloseStatus,
   CopilotWebSocketForwarder,
   CopilotWebSocketHandler,
+  FactoryResumeError,
   RuntimeConnection,
   SYSTEM_MESSAGE_SECTIONS,
+  SessionFsSqliteTransactionFailure,
   ToolSet,
   approveAll,
   convertMcpCallToolResult,
   createCanvas,
   createSessionFsAdapter,
-  defineTool
+  defineFactory,
+  defineTool,
+  isFactoryRunTerminal
 };

package/dist/session.d.ts

@@ -1,6 +1,7 @@
 import { createSessionRpc } from "./generated/rpc.js";
 import type { OpenCanvasInstance } from "./generated/rpc.js";
 import type { MessageOptions, ContextTier, ReasoningEffort, ReasoningSummary, ModelCapabilitiesOverride, SessionCapabilities, SessionEvent, SessionEventHandler, SessionEventType, SessionUiApi, TypedSessionEventHandler } from "./types.js";
+import { type SessionFactoryApi } from "./factory.js";
 /** Assistant message event - the final response from the assistant. */
 export type AssistantMessageEvent = Extract<SessionEvent, {
     type: "assistant.message";
@@ -45,6 +46,8 @@ export declare class CopilotSession {
     private canvases;
     private bearerTokenProviders;
     private commandHandlers;
+    private factories;
+    private factoryAbortControllers;
     private permissionHandler?;
     private mcpAuthHandler?;
     private userInputHandler?;
@@ -58,6 +61,24 @@ export declare class CopilotSession {
     private _capabilities;
     private openCanvasInstances;
     private disconnected;
+    /**
+     * Friendly factory API for running registered factories by name or handle.
+     *
+     * @experimental Part of the experimental Agent Factories surface and may
+     * change or be removed in future SDK or CLI releases.
+     */
+    readonly factory: SessionFactoryApi;
+    /**
+     * Resolve when a factory run reaches a terminal status.
+     *
+     * The subscription is installed *before* the first read so a transition
+     * landing between the two cannot be missed, and re-reads are serialized so
+     * overlapping invalidation events cannot interleave — the run's revision
+     * advances once per operation, so a burst of events is common and must
+     * collapse into a single in-flight read. A bounded periodic re-read keeps a
+     * dropped invalidation from leaving the wait pending forever.
+     */
+    private waitForFactoryRun;
     /**
      * Typed session-scoped RPC methods.
      */