@github/copilot-sdk-win32-x64 1.0.15 → 1.0.16-preview.0

package/copilot-sdk/generated/session-events.d.ts

@@ -930,6 +930,14 @@ export type SystemNotificationWorkflowCompletedStatus =
  * Details of the permission being requested
  */
 export type PermissionRequest = PermissionRequestShell | PermissionRequestWrite | PermissionRequestRead | PermissionRequestMcp | PermissionRequestUrl | PermissionRequestMemory | PermissionRequestCustomTool | PermissionRequestHook | PermissionRequestExtensionManagement | PermissionRequestWorkflow | PermissionRequestExtensionPermissionAccess | PermissionRequestExtensionEnvAccess;
+/**
+ * Access a sandbox path grant confers
+ */
+export type PermissionSandboxPathGrantAccess = 
+/** Read access: the path is added to readonlyPaths. */
+"read"
+/** Read and write access: the path is added to readwritePaths. */
+ | "readWrite";
 /**
  * Advisory recommendation the runtime attaches to a permission request whose origin it can vouch for by construction. Unlike the auto-approval judge this does not depend on auto mode and does not evaluate what the tool call does; its absence simply means the runtime has no opinion and the request follows the host's normal approval flow.
  */
@@ -1028,7 +1036,7 @@ export type PermissionDecisionSource =
 /**
  * The result of the permission request
  */
-export type PermissionResult = PermissionApproved | PermissionApprovedForSession | PermissionApprovedForLocation | PermissionCancelled | PermissionDeniedByRules | PermissionDeniedNoApprovalRuleAndCouldNotRequestFromUser | PermissionDeniedInteractivelyByUser | PermissionDeniedByContentExclusionPolicy | PermissionDeniedByPermissionRequestHook;
+export type PermissionResult = PermissionApproved | PermissionApprovedReadOnlyForSession | PermissionApprovedForSession | PermissionApprovedForLocation | PermissionCancelled | PermissionDeniedByRules | PermissionDeniedNoApprovalRuleAndCouldNotRequestFromUser | PermissionDeniedInteractivelyByUser | PermissionDeniedByContentExclusionPolicy | PermissionDeniedByPermissionRequestHook;
 /**
  * The approval to add as a session-scoped rule
  */
@@ -8274,6 +8282,12 @@ export interface PermissionRequestShell {
      * @experimental
      */
     resolvedWorkingDirectory?: string;
+    /**
+     * Sandbox policy edit that would let the command run inside the sandbox. Only present when requestSandboxBypass is true.
+     *
+     * @experimental
+     */
+    sandboxPathGrant?: PermissionSandboxPathGrant;
     /**
      * Tool call ID that triggered this permission request
      */
@@ -8318,6 +8332,25 @@ export interface PermissionRequestShellPossibleUrl {
      */
     url: string;
 }
+/**
+ * A sandbox filesystem policy edit that would let a blocked operation run inside the sandbox instead of outside it. Offered only on a sandbox escalation request whose denial adding this path lifts, and only when managed policy permits the grant. A host accepts it with session.sandbox.grantPathForRequest, which adds the path to the session's sandbox policy and re-runs the operation sandboxed; a host that persists sandbox settings may also save the path there.
+ */
+/** @experimental */
+export interface PermissionSandboxPathGrant {
+    access: PermissionSandboxPathGrantAccess;
+    /**
+     * The path the sandbox refused, present only when it differs from path. That happens when a write under a read-only folder moves the folder to the read-write paths, when a path that does not exist yet is granted through its nearest existing folder, because the OS sandbox cannot grant a path before it exists, and when either is spelled through a symlink, because a grant covers its path as written, so path is then the resolved location. Hosts should then name path in the offer, since the denial names this one.
+     */
+    deniedPath?: string;
+    /**
+     * Absolute path to add to the sandbox filesystem policy
+     */
+    path: string;
+    /**
+     * readonlyPaths entries the grant removes, exactly as written in the policy, because a read-only entry for the same location would otherwise keep the path read-only. A host that persists the path must remove these entries from its stored readonlyPaths too.
+     */
+    removedReadonlyPaths?: string[];
+}
 /**
  * File write permission request
  */
@@ -8364,6 +8397,12 @@ export interface PermissionRequestWrite {
      * @experimental
      */
     resolvedPath?: string;
+    /**
+     * Sandbox policy edit that would let the write run inside the sandbox. Only present when requestSandboxBypass is true.
+     *
+     * @experimental
+     */
+    sandboxPathGrant?: PermissionSandboxPathGrant;
     /**
      * Tool call ID that triggered this permission request
      */
@@ -8403,6 +8442,12 @@ export interface PermissionRequestRead {
      * @experimental
      */
     resolvedPath?: string;
+    /**
+     * Sandbox policy edit that would let the read run inside the sandbox. Only present when requestSandboxBypass is true.
+     *
+     * @experimental
+     */
+    sandboxPathGrant?: PermissionSandboxPathGrant;
     /**
      * Tool call ID that triggered this permission request
      */
@@ -8880,6 +8925,12 @@ export interface PermissionPromptRequestCommands {
      * True when the escalation is a permissive retry that keeps the sandbox and network policy attached while recording file and process accesses instead of blocking them.
      */
     requestSandboxPermissive?: boolean;
+    /**
+     * Sandbox policy edit that would let the command run inside the sandbox. Only present when requestSandboxBypass is true.
+     *
+     * @experimental
+     */
+    sandboxPathGrant?: PermissionSandboxPathGrant;
     /**
      * Tool call ID that triggered this permission request
      */
@@ -9150,6 +9201,12 @@ export interface PermissionPromptRequestPath {
      * File paths that require explicit approval
      */
     paths: string[];
+    /**
+     * Canonical directory candidates that can be granted for file-tool read access in this logical session. Present only for read path prompts.
+     *
+     * @experimental
+     */
+    readOnlyDirectories?: string[];
     /**
      * Tool call ID that triggered this permission request
      */
@@ -9413,6 +9470,21 @@ export interface PermissionApproved {
      */
     managedApprovalHandled?: boolean;
 }
+/**
+ * Permission response variant that approves a request and records file-tool read authority for specific directories in this logical session.
+ */
+export interface PermissionApprovedReadOnlyForSession {
+    /**
+     * Canonical directories covered by the session read-only grant
+     *
+     * @minItems 1
+     */
+    directories: [string, ...string[]];
+    /**
+     * Approved with read-only directory authority for this session
+     */
+    kind: "approved-read-only-for-session";
+}
 /**
  * Permission response variant that approves a request and remembers the provided approval for the rest of the session.
  */
@@ -12084,10 +12156,18 @@ export interface McpServerStatusChangedEvent {
  * Payload of `session.mcp_server_status_changed` for one MCP server's status and optional failure error.
  */
 export interface McpServerStatusChangedData {
+    /**
+     * Runtime configuration provenance for a failed connection, or unknown when unavailable. Additional string values may be introduced.
+     */
+    configSource?: string;
     /**
      * Error message if the server entered a failed state
      */
     error?: string;
+    /**
+     * Runtime-produced classification for the final failed connection; unclassified means no classification was supplied. Additional string values may be introduced.
+     */
+    errorClassification?: string;
     /**
      * Name of the MCP server whose status changed
      */

package/copilot-sdk/host.d.ts

@@ -0,0 +1,86 @@
+import type { HostExitedNotification, HostPublishSessionResult, HostLocalServerOptions, HostGitHubEnvironmentOptions } from "./generated/rpc.js";
+import type { CopilotSession } from "./session.js";
+import type { SessionConfig, ResumeSessionConfig } from "./types.js";
+/** Host-selected defaults for a fresh application-owned session. @experimental */
+export interface AhpSessionCreateRequest {
+    /** Pass these settings to createSession, adding your prompt, tools and callbacks. */
+    config: Omit<SessionConfig, "onPermissionRequest">;
+    /** Aborted when participation ends, including timeout or owner disconnection. */
+    signal: AbortSignal;
+}
+/** Host-selected settings for resuming a durable application-owned AHP session. @experimental */
+export interface AhpSessionResumeRequest {
+    sessionId: string;
+    /** Pass to resumeSession, adding application tools, hooks and callbacks. */
+    config: Omit<ResumeSessionConfig, "onPermissionRequest">;
+    /** Aborted when participation ends; late results are still released exactly once. */
+    signal: AbortSignal;
+}
+/**
+ * A listener-task exit report, or an owner disconnect that cannot acknowledge cleanup.
+ * `reason: "exited"` means the hosting task failed, not that the runtime process died.
+ * In-process hosts have no process exit code (`exitCode` is absent).
+ * @experimental
+ */
+export type AhpHostExit = HostExitedNotification;
+/**
+ * Options for runtime-supervised AHP hosting. Select at least one transport.
+ * Callbacks are captured at startup;
+ * later changes to this options object do not reconfigure an existing host.
+ * @experimental
+ */
+export interface AhpHostOptions {
+    /** Enable a local WebSocket listener; an empty object selects loopback defaults. */
+    localServer?: HostLocalServerOptions;
+    /** Register a Mission Control environment and enable remote WPS connections. */
+    githubEnvironment?: HostGitHubEnvironmentOptions;
+    /** Called at most once when hosting ends, not on runtime process death. Local, never serialized. */
+    onExit?: (exit: AhpHostExit) => void;
+    /**
+     * Materialize a fresh session on this client. Preserve the supplied config
+     * (including its sessionId and workingDirectory); add your own prompt and tools.
+     * The callback and all tool/hook functions stay in the application.
+     */
+    createSession?: (request: AhpSessionCreateRequest) => Promise<CopilotSession>;
+    /**
+     * Resume a durable session previously created by an application factory.
+     * Return the original object from this client's resumeSession, or an existing
+     * attached original without reconfiguring it. Published resident sessions
+     * attach directly and never invoke this callback.
+     */
+    resumeSession?: (request: AhpSessionResumeRequest) => Promise<CopilotSession>;
+    /**
+     * Called once per handoff with the original returned object after AHP detaches
+     * or the handoff fails. The SDK never disconnects or destroys this object.
+     */
+    onSessionReleased?: (session: CopilotSession) => void | Promise<void>;
+}
+/**
+ * A connection-owned AHP listener supervised by the runtime.
+ *
+ * The runtime hosts the listener in-process, without a companion executable. Disconnecting
+ * the owning client also stops the host; reconnecting does not reclaim it.
+ * Stopping a host does not delete its underlying sessions.
+ * Its durable AHP catalog is shared by successive hosts in the runtime's
+ * effective Copilot home; a concurrent host for that catalog is rejected.
+ *
+ * @experimental
+ */
+export declare class AhpHost {
+    private readonly disposeHost;
+    private readonly publishHostSession;
+    readonly hostId: string;
+    /** Local WebSocket URL. Absent when only the GitHub environment is enabled. */
+    readonly url: string | undefined;
+    /** Mission Control environment ID, when GitHub hosting is enabled. */
+    readonly environmentId: string | undefined;
+    /** Connection token, when required by the listener. Treat this value as a secret. */
+    readonly token: string | undefined;
+    /** Legacy separate host process ID. Absent for in-process listeners; use dispose() to stop. */
+    readonly pid: number | undefined;
+    /** Ask the runtime to stop the listener and await its cleanup, on every call. */
+    dispose(): Promise<void>;
+    /** Publish an existing session attached to this client, until this listener stops. */
+    publishSession(sessionId: string): Promise<HostPublishSessionResult>;
+    [Symbol.asyncDispose](): Promise<void>;
+}

package/copilot-sdk/index.d.ts

@@ -4,6 +4,8 @@
  * JSON-RPC based SDK for programmatic control of GitHub Copilot CLI
  */
 export { CopilotClient } from "./client.js";
+export type { HostLocalServerOptions, HostGitHubEnvironmentOptions } from "./generated/rpc.js";
+export { AhpHost, type AhpHostExit, type AhpHostOptions, type AhpSessionCreateRequest, type AhpSessionResumeRequest, } from "./host.js";
 export { DisableBypassPermissionsModes, RuntimeConnection } from "./types.js";
 export { BuiltInTools, ToolSet } from "./toolSet.js";
 export { CopilotSession, type AssistantMessageEvent } from "./session.js";
@@ -11,5 +13,5 @@ export { defineWorkflow, WorkflowResumeError, isWorkflowRunTerminal } from "./wo
 export { Canvas, CanvasError, createCanvas, type CanvasAction, type CanvasDeclaration, type CanvasHostContext, type CanvasHostContextCapabilities, type CanvasJsonSchema, type CanvasOptions, } from "./canvas.js";
 export { defineTool, approveAll, createAttributedPermissionResult, convertMcpCallToolResult, createSessionFsAdapter, CopilotRequestHandler, CopilotWebSocketHandler, CopilotWebSocketCloseStatus, CopilotWebSocketForwarder, SessionFsSqliteTransactionFailure, SYSTEM_MESSAGE_SECTIONS, } from "./types.js";
 export type * from "./generated/session-events.js";
-export type { AskUserVariant, CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, ConnectorAccountRequest, ConnectorAvailability, ConnectorCapabilities, ConnectorCatalogEntry, ConnectorCatalogResult, ConnectorCatalogStatus, ConnectorConnectRequest, ConnectorConnectResult, ConnectorContinueRequest, ConnectorDisconnectResult, ConnectorMcpStatus, ConnectorReconcileRequest, ConnectorRuntimeStatus, ConnectorStatus, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, AgentStopHandler, AgentStopHookInput, AgentStopHookOutput, UserPromptTransformedHandler, UserPromptTransformedHookInput, UserPromptTransformedHookOutput, CopilotClientInfo, CopilotClientMode, CopilotClientOptions, InstallationConfirmationHandler, InstallationConfirmationRequest, InstallationConfirmationResponse, InstallationDecision, InstallationReview, McpInstallationReview, CopilotExpAssignmentResponse, StdioRuntimeConnection, InProcessRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, ChildProcessRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExpConfigEntry, ExpFlagValue, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ExtensionLaunchProfile, ExtensionLaunchProvider, ExtensionLaunchProviderResolveRequest, ExtensionLaunchProviderResolveResult, ExtensionInfo, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, GitHubMcpToolConfig, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, GitHubTokenAcquireReason, GitHubTokenAcquireResult, GitHubTokenProvider, GitHubTokenProviderArgs, GitHubTokenProviderResult, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, BearerTokenProvider, ExtensionContextAttachment, MessageOptions, ResponseSchema, MessageSource, ManagedSettings, ManagedSettingsPermissions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, AutoTier, CapiSessionOptions, CurrentModel, ModelSwitchAutoTierResult, ModelSwitchAutoTierStatus, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, NamedProviderConfig, PermissionHandler, PermissionRequest, PermissionRequestedData, PermissionRequestedEvent, PermissionRequestResult, AttributedPermissionResult, PermissionDecisionContext, PermissionDecisionOutcome, PermissionDecisionSource, PermissionDecisionSurface, PermissionResponseCapability, 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 { AskUserVariant, CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, ConnectorAccountRequest, ConnectorAvailability, ConnectorCapabilities, ConnectorCatalogEntry, ConnectorCatalogResult, ConnectorCatalogStatus, ConnectorConnectRequest, ConnectorConnectResult, ConnectorContinueRequest, ConnectorDisconnectResult, ConnectorMcpStatus, ConnectorReconcileRequest, ConnectorRuntimeStatus, ConnectorStatus, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, AgentStopHandler, AgentStopHookInput, AgentStopHookOutput, UserPromptTransformedHandler, UserPromptTransformedHookInput, UserPromptTransformedHookOutput, CopilotClientInfo, CopilotClientMode, CopilotClientOptions, InstallationConfirmationHandler, InstallationConfirmationRequest, InstallationConfirmationResponse, InstallationDecision, InstallationReview, McpInstallationReview, CopilotExpAssignmentResponse, StdioRuntimeConnection, InProcessRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, ChildProcessRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExpConfigEntry, ExpFlagValue, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ExtensionLaunchProfile, ExtensionLaunchProvider, ExtensionLaunchProviderResolveRequest, ExtensionLaunchProviderResolveResult, ExtensionInfo, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, GitHubMcpToolConfig, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, GitHubTokenAcquireReason, GitHubTokenAcquireResult, GitHubTokenProvider, GitHubTokenProviderArgs, GitHubTokenProviderResult, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, BearerTokenProvider, ExtensionContextAttachment, MessageOptions, ResponseSchema, MessageSource, ManagedSettings, ManagedSettingsPermissions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, AutoTier, CapiSessionOptions, CurrentModel, ModelSwitchAutoTierResult, ModelSwitchAutoTierStatus, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, NamedProviderConfig, PermissionHandler, PermissionRequest, PermissionRequestedData, PermissionRequestedEvent, PermissionRequestResult, AttributedPermissionResult, PermissionDecisionContext, PermissionDecisionOutcome, PermissionDecisionSource, PermissionDecisionSurface, PermissionResponseCapability, ProviderConfig, ProviderModelConfig, ProviderTokenArgs, RemoteSessionMode, SandboxConfigSource, 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 { JsonValue, WorkflowRunOptions, WorkflowResumeOptions, WorkflowLimitOverrides, WorkflowResumeErrorCode, SessionWorkflowApi, WorkflowAgentOptions, WorkflowContext, WorkflowDefinition, WorkflowHandle, WorkflowJsonSchema, WorkflowLimits, WorkflowMeta, WorkflowPipelineStage, WorkflowStepOptions, WorkflowRunResult, WorkflowRunStatus, WorkflowRunSummary, WorkflowListRunsOptions, WorkflowRunsPage, WorkflowRunDetail, WorkflowProgressPage, WorkflowProgressLine, WorkflowPhaseObservation, WorkflowPhaseStatus, WorkflowAgentSummary, } from "./workflow.js";