@github/copilot-sdk 1.0.28 → 1.0.29-preview.1

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  * JSON-RPC based SDK for programmatic control of GitHub Copilot CLI
  */
 export { CopilotClient } from "./client.js";
-export type { HostLocalServerOptions, HostGitHubEnvironmentOptions, ModelGetReasoningSummariesRequest, ModelGetReasoningSummariesResult, SandboxConfig, AutopilotOptions, } from "./generated/rpc.js";
+export type { HostLocalServerOptions, HostGitHubEnvironmentOptions, Model, ModelGetReasoningSummariesRequest, ModelGetReasoningSummariesResult, SandboxConfig, AutopilotOptions, } from "./generated/rpc.js";
 export { AhpHost, type AhpHostExit, type AhpHostOptions, type AhpHostAuthentication, type AhpSessionAuthentication, type AhpSessionCreateRequest, type AhpSessionResumeRequest, } from "./host.js";
 export { DisableBypassPermissionsModes, RuntimeConnection } from "./types.js";
 export { BuiltInTools, ToolSet } from "./toolSet.js";
@@ -13,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, SessionFsWriteFailure, SYSTEM_MESSAGE_SECTIONS, } from "./types.js";
 export type * from "./generated/session-events.js";
-export type { AskUserVariant, CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AuthIdentityMetadata, AuthInfoType, ConnectorAccountRequest, ConnectorAvailability, ConnectorCapabilities, ConnectorCatalogEntry, ConnectorCatalogResult, ConnectorCatalogStatus, ConnectorConnectRequest, ConnectorConnectResult, ConnectorContinueRequest, ConnectorDisconnectResult, ConnectorMcpStatus, ConnectorReconcileRequest, ConnectorRuntimeStatus, ConnectorSessionAccount, ConnectorSessionAccountResult, ConnectorStatus, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, AgentStopHandler, AgentStopHookInput, AgentStopHookOutput, SubagentStartHandler, SubagentStartHookInput, SubagentStartHookOutput, SubagentStopHandler, SubagentStopHookInput, SubagentStopHookOutput, UserPromptTransformedHandler, UserPromptTransformedHookInput, UserPromptTransformedHookOutput, CopilotClientInfo, CopilotClientMode, CopilotClientOptions, EntraAuthConfig, 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, ProviderConfigModelProvider, ProviderModelConfig, ProviderTokenArgs, RemoteSessionMode, SandboxConfigSource, ResumeSessionConfig, TranscriptRecovery, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, WorkingDirectoryTrust, 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, SkillProvider, SkillProviderCallOptions, SkillProviderDescriptor, CopilotRequestContext, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, ToolNamespace, CurrentToolMetadata, ToolTelemetry, ToolResultObject, ToolSearchConfig, ImageGenerationConfig, 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";
+export type { AskUserVariant, CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AuthIdentityMetadata, AuthInfoType, ConnectorAccountRequest, ConnectorAvailability, ConnectorCapabilities, ConnectorCatalogEntry, ConnectorCatalogResult, ConnectorCatalogStatus, ConnectorConnectRequest, ConnectorConnectResult, ConnectorContinueRequest, ConnectorDisconnectResult, ConnectorMcpStatus, ConnectorReconcileRequest, ConnectorRuntimeStatus, ConnectorSessionAccount, ConnectorSessionAccountResult, ConnectorStatus, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, AgentStopHandler, AgentStopHookInput, AgentStopHookOutput, SubagentStartHandler, SubagentStartHookInput, SubagentStartHookOutput, SubagentStopHandler, SubagentStopHookInput, SubagentStopHookOutput, UserPromptTransformedHandler, UserPromptTransformedHookInput, UserPromptTransformedHookOutput, CopilotClientInfo, CopilotClientMode, CopilotClientOptions, EntraAuthConfig, EntraAuthOptions, EntraTokenProvider, EntraTokenProviderArgs, EntraTokenProviderResult, 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, KerberosAuthAcquireRequest, KerberosAuthConfig, KerberosAuthMode, KerberosAuthScope, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, HostDiagnostics, HostErrorReportingStatus, 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, ProviderConfigModelProvider, ProviderModelConfig, ProviderTokenArgs, RemoteSessionMode, SandboxConfigSource, ResumeSessionConfig, TranscriptRecovery, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, WorkingDirectoryTrust, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionHooks, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsByteRange, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, SessionFsSqliteStatement, SessionFsSqliteTransactionErrorClass, SkillProvider, SkillProviderCallOptions, SkillProviderDescriptor, CopilotRequestContext, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, ToolNamespace, CurrentToolMetadata, ToolTelemetry, ToolResultObject, ToolSearchConfig, ImageGenerationConfig, 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, WorkflowAgentContextObservation, WorkflowAgentModelObservation, WorkflowAgentReasoningEffortObservation, WorkflowAgentSummary, } from "./workflow.js";

package/dist/installationConfirmation.d.ts

@@ -1,4 +1,4 @@
-import { type CancellationToken, type MessageConnection } from "vscode-jsonrpc/node.js";
+import type { CancellationToken, MessageConnection } from "./jsonrpcTypes.js";
 import type { InstallationConfirmationRequest, InstallationDecision, InstallationsConfirmResult } from "./generated/rpc.js";
 /** The `installations.confirm` receiver, invoked with the transport's request cancellation. */
 export interface InstallationConfirmationReceiver {

package/dist/installationConfirmation.js

@@ -1,7 +1,4 @@
-import {
-  CancellationTokenSource,
-  ResponseError
-} from "vscode-jsonrpc/node.js";
+import { CancellationTokenSource, ResponseError } from "vscode-jsonrpc/node";
 function createInstallationConfirmationAdapter(connection, handler) {
   const closed = new CancellationTokenSource();
   const closeSubscription = connection.onClose(() => closed.cancel());

package/dist/jsonrpcTypes.d.ts

@@ -0,0 +1,14 @@
+export interface Disposable {
+    dispose(): void;
+}
+export interface CancellationToken {
+    readonly isCancellationRequested: boolean;
+    readonly onCancellationRequested: <T>(listener: (event: T) => unknown, thisArgs?: unknown, disposables?: Disposable[]) => Disposable;
+}
+export interface MessageConnection {
+    sendRequest<R>(method: string, params?: unknown): Promise<R>;
+    onRequest<P, R>(method: string, handler: (params: P, token: CancellationToken) => R | Promise<R>): Disposable;
+    onNotification<P>(method: string, handler: (params: P) => void | Promise<void>): Disposable;
+    onClose(listener: () => void): Disposable;
+    onDispose(listener: () => void): Disposable;
+}

package/dist/sdkProtocolVersion.d.ts

@@ -1,6 +1,6 @@
 /**
  * The SDK protocol version.
- * This must match the version expected by the copilot-agent-runtime server.
+ * This must match the version expected by the Copilot runtime server.
  */
 export declare const SDK_PROTOCOL_VERSION = 3;
 /**

package/dist/session.js

@@ -4,7 +4,7 @@ import {
   ConnectionError,
   ErrorCodes,
   ResponseError
-} from "vscode-jsonrpc/node.js";
+} from "vscode-jsonrpc/node";
 import { createInternalSessionRpc, createSessionRpc } from "./generated/rpc.js";
 import { CanvasError } from "./canvas.js";
 import { getTraceContext } from "./telemetry.js";
@@ -245,6 +245,15 @@ function isWorkflowAbortError(error) {
 function isWorkflowFatalError(error) {
   return isWorkflowAbortError(error) || error instanceof ResponseError || error instanceof ConnectionError;
 }
+const MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
+function setLongTimeout(callback, delayMs) {
+  let timer;
+  const arm = (remainingMs) => {
+    timer = remainingMs > MAX_TIMER_DELAY_MS ? setTimeout(() => arm(remainingMs - MAX_TIMER_DELAY_MS), MAX_TIMER_DELAY_MS) : setTimeout(callback, remainingMs);
+  };
+  arm(delayMs);
+  return () => clearTimeout(timer);
+}
 const TOOL_SEARCH_TOOL_NAME = "tool_search_tool";
 class CopilotSession {
   /**
@@ -655,11 +664,11 @@ class CopilotSession {
       else resolveOutcome({ kind: "error", error });
     };
     this.pendingResponseWaits.add(fail);
-    let timeoutId;
+    let cancelTimeout;
     let waiting = true;
     try {
       const timeoutPromise = new Promise((_, reject) => {
-        timeoutId = setTimeout(
+        cancelTimeout = setLongTimeout(
           () => reject(
             new Error(
               `Timeout after ${effectiveTimeout}ms waiting for response completion`
@@ -687,9 +696,7 @@ class CopilotSession {
       return outcome.message;
     } finally {
       waiting = false;
-      if (timeoutId !== void 0) {
-        clearTimeout(timeoutId);
-      }
+      cancelTimeout?.();
       unsubscribe();
       buffered.length = 0;
       this.pendingResponseWaits.delete(fail);
@@ -723,7 +730,7 @@ class CopilotSession {
       fail = reject;
     });
     this.pendingResponseWaits.add(fail);
-    const timer = setTimeout(
+    const cancelTimeout = setLongTimeout(
       () => fail(new Error(`Timeout after ${timeout}ms waiting for session.idle`)),
       timeout
     );
@@ -762,7 +769,7 @@ class CopilotSession {
     try {
       return await Promise.race([operation(), stopped]);
     } finally {
-      clearTimeout(timer);
+      cancelTimeout();
       unsubscribe();
       this.pendingResponseWaits.delete(fail);
       resolveDispatched();
@@ -820,7 +827,7 @@ class CopilotSession {
     });
     this.pendingStructuredWaits.add(fail);
     let waiting = true;
-    const timer = setTimeout(
+    const cancelTimeout = setLongTimeout(
       () => fail(new Error(`Timeout after ${timeout}ms waiting for the structured response`)),
       timeout
     );
@@ -847,7 +854,7 @@ class CopilotSession {
       return outcome.message;
     } finally {
       waiting = false;
-      clearTimeout(timer);
+      cancelTimeout();
       buffered.length = 0;
       unsubscribe();
       this.pendingStructuredWaits.delete(fail);
@@ -1004,12 +1011,23 @@ class CopilotSession {
         }
       }
     } else if (event.type === "permission.requested") {
-      const { requestId, permissionRequest, promptRequest, resolvedByHook } = event.data;
+      const {
+        requestId,
+        permissionRequest,
+        promptRequest,
+        assistedApprovalAssessment,
+        resolvedByHook
+      } = event.data;
       if (resolvedByHook) {
         return;
       }
       if (this.permissionHandler) {
-        void this._executePermissionAndRespond(requestId, permissionRequest, promptRequest);
+        void this._executePermissionAndRespond(
+          requestId,
+          permissionRequest,
+          promptRequest,
+          assistedApprovalAssessment
+        );
       }
     } else if (event.type === "mcp.oauth_required") {
       const data = event.data;
@@ -1028,15 +1046,7 @@ class CopilotSession {
       void this._executeCommandAndRespond(requestId, commandName, command, args);
     } else if (event.type === "elicitation.requested") {
       if (this.elicitationHandler) {
-        const {
-          message,
-          requestedSchema,
-          mode,
-          elicitationSource,
-          elicitationSourceDisplayName,
-          url,
-          requestId
-        } = event.data;
+        const { message, requestedSchema, mode, elicitationSource, url, requestId } = event.data;
         void this._handleElicitationRequest(
           {
             sessionId: this.sessionId,
@@ -1044,14 +1054,17 @@ class CopilotSession {
             requestedSchema,
             mode,
             elicitationSource,
-            elicitationSourceDisplayName,
             url
           },
           requestId
         );
       }
     } else if (event.type === "capabilities.changed") {
-      this._capabilities = { ...this._capabilities, ...event.data };
+      const { ui, ...changed } = event.data;
+      this._capabilities = { ...this._capabilities, ...changed };
+      if (ui) {
+        this._capabilities.ui = { ...this._capabilities.ui, ...ui };
+      }
     } else if (event.type === "session.canvas.opened") {
       this.upsertOpenCanvasFromEvent(event.data);
     } else if (event.type === "session.canvas.closed") {
@@ -1177,12 +1190,13 @@ class CopilotSession {
    * Executes a permission handler and sends the result back via RPC.
    * @internal
    */
-  async _executePermissionAndRespond(requestId, permissionRequest, promptRequest) {
+  async _executePermissionAndRespond(requestId, permissionRequest, promptRequest, assistedApprovalAssessment) {
     try {
       const invocation = {
         sessionId: this.sessionId,
         managedSettingsEnabled: this.managedSettingsEnabled,
-        ...promptRequest === void 0 ? {} : { promptRequest }
+        ...promptRequest === void 0 ? {} : { promptRequest },
+        ...assistedApprovalAssessment === void 0 ? {} : { assistedApprovalAssessment }
       };
       const handlerResult = await this.permissionHandler(permissionRequest, invocation);
       const isAttributed = isAttributedPermissionResult(handlerResult);

package/dist/sessionFsProvider.d.ts

@@ -6,6 +6,13 @@ export type { SessionFsSqliteQueryType, SessionFsSqliteTransactionErrorClass };
  * `error` field, since providers signal errors by throwing.
  */
 export type SessionFsFileInfo = Omit<SessionFsStatResult, "error">;
+/** Raw bytes and the authoritative total file byte length captured by the same read. */
+export interface SessionFsByteRange {
+    /** Requested bytes; boundaries may split UTF-8 characters. */
+    content: Uint8Array;
+    /** Total file byte length, independent of the requested range. */
+    byteLength: number;
+}
 /**
  * Result of a SQLite query execution via {@link SessionFsSqliteProvider.query}.
  * Same shape as the generated {@link GeneratedSqliteQueryResult} but without the
@@ -84,6 +91,14 @@ export interface SessionFsProvider {
     readFile(path: string): Promise<string>;
     /** Read exact file bytes. Required when capabilities.binary is enabled. */
     readFileBytes?(path: string): Promise<Uint8Array>;
+    /**
+     * Reads raw bytes starting at a non-negative safe integer byte offset.
+     * Omit length to read through EOF; zero returns only byte length.
+     * At or beyond EOF, content is empty. Advertise capabilities.readFileRange
+     * only when every provider implements bounded reads without full-file downloads.
+     * This capability is independent of binary reads and writes.
+     */
+    readFileRange?(path: string, offset: number, length?: number): Promise<SessionFsByteRange>;
     /** Write exact file bytes. Required when capabilities.binary is enabled. */
     writeFileBytes?(path: string, content: Uint8Array, mode?: number): Promise<void>;
     /** Writes content to a file, creating parent directories if needed. Throw {@link SessionFsWriteFailure} if a failed write changed the target. */

package/dist/sessionFsProvider.js

@@ -26,6 +26,34 @@ function normalizeSqliteParams(params) {
 }
 function createSessionFsAdapter(provider) {
   return {
+    readFileRange: async ({ path, offset, length }) => {
+      try {
+        if (!Number.isSafeInteger(offset) || offset < 0 || length !== void 0 && (!Number.isSafeInteger(length) || length < 0)) {
+          throw new RangeError(
+            "SessionFs byte offset and length must be non-negative safe integers"
+          );
+        }
+        if (!provider.readFileRange) {
+          throw new Error(
+            "Byte-range reads are not supported by this SessionFs provider"
+          );
+        }
+        const result = await provider.readFileRange(path, offset, length);
+        if (!Number.isSafeInteger(result.byteLength) || result.byteLength < 0) {
+          throw new Error("SessionFs byte length must be a non-negative safe integer");
+        }
+        const available = Math.max(0, result.byteLength - offset);
+        if (result.content.byteLength !== Math.min(length ?? available, available)) {
+          throw new Error("SessionFs returned an incorrect byte range length");
+        }
+        return {
+          content: Buffer.from(result.content).toString("base64"),
+          byteLength: result.byteLength
+        };
+      } catch (err) {
+        return { content: "", byteLength: 0, error: toSessionFsError(err) };
+      }
+    },
     readFile: async ({ path }) => {
       try {
         const content = await provider.readFile(path);

package/dist/types.d.ts

@@ -6,16 +6,17 @@ import type { SessionFsProvider } from "./sessionFsProvider.js";
 import type { CopilotRequestHandler } from "./copilotRequestHandler.js";
 import type { InstallationConfirmationHandler } from "./installationConfirmation.js";
 export type { InstallationConfirmationHandler } from "./installationConfirmation.js";
-import type { AgentModelPolicy, AttachmentExtensionContext as GeneratedExtensionContextAttachment, AutoTier, PermissionRequest as GeneratedPermissionRequest, PermissionRequestedData as GeneratedPermissionRequestedData, PermissionRequestedEvent as GeneratedPermissionRequestedEvent, ReasoningSummary, SessionLimitsConfig, SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
+import type { AgentModelPolicy, AttachmentExtensionContext as GeneratedExtensionContextAttachment, AutoTier, ModelProviderRef, PermissionRequest as GeneratedPermissionRequest, PermissionRequestedData as GeneratedPermissionRequestedData, PermissionRequestedEvent as GeneratedPermissionRequestedEvent, ReasoningSummary, SessionLimitsConfig, SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
 import type { CopilotSession } from "./session.js";
 import type { JsonValue } from "./workflow.js";
-import type { ExtensionLaunchProviderHandler as GeneratedExtensionLaunchProvider, AutopilotOptions, GitHubTokenAcquireRequest, GitHubTokenAcquireResult, GitHubTelemetryNotification, ModelBillingTokenPrices, DiagnosticsConfiguration, OpenCanvasInstance, ProtocolExternalToolNamespace, CurrentToolMetadata, SandboxConfig } from "./generated/rpc.js";
+import type { ExtensionLaunchProviderHandler as GeneratedExtensionLaunchProvider, AutopilotOptions, GitHubTokenAcquireRequest, GitHubTokenAcquireResult, GitHubTelemetryNotification, HostDiagnostics, ModelBillingTokenPrices, DiagnosticsConfiguration, OpenCanvasInstance, ProtocolExternalToolNamespace, CurrentToolMetadata, KerberosAuthAcquireRequest, KerberosAuthMode, KerberosAuthScope, SandboxConfig } from "./generated/rpc.js";
 import type { ToolSet } from "./toolSet.js";
+export type { KerberosAuthAcquireRequest, KerberosAuthMode, KerberosAuthScope, } from "./generated/rpc.js";
 export type { RemoteSessionMode } from "./generated/rpc.js";
 export type { AutopilotOptions } from "./generated/rpc.js";
 export type { CurrentToolMetadata } from "./generated/rpc.js";
 export type { SandboxConfig, SandboxConfigSource } from "./generated/rpc.js";
-export type { AuthIdentityMetadata, AuthInfoType, ConnectorAccountRequest, ConnectorAvailability, ConnectorCapabilities, ConnectorCatalogEntry, ConnectorCatalogResult, ConnectorCatalogStatus, ConnectorConnectRequest, ConnectorConnectResult, ConnectorContinueRequest, ConnectorDisconnectResult, ConnectorMcpStatus, ConnectorReconcileRequest, ConnectorRuntimeStatus, ConnectorSessionAccount, ConnectorSessionAccountResult, ConnectorStatus, ExtensionLaunchProfile, ExtensionLaunchProviderResolveRequest, ExtensionLaunchProviderResolveResult, GitHubTokenAcquireReason, GitHubTokenAcquireResult, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, InstallationConfirmationRequest, InstallationConfirmationResponse, InstallationDecision, InstallationReview, McpInstallationReview, } from "./generated/rpc.js";
+export type { AuthIdentityMetadata, AuthInfoType, ConnectorAccountRequest, ConnectorAvailability, ConnectorCapabilities, ConnectorCatalogEntry, ConnectorCatalogResult, ConnectorCatalogStatus, ConnectorConnectRequest, ConnectorConnectResult, ConnectorContinueRequest, ConnectorDisconnectResult, ConnectorMcpStatus, ConnectorReconcileRequest, ConnectorRuntimeStatus, ConnectorSessionAccount, ConnectorSessionAccountResult, ConnectorStatus, ExtensionLaunchProfile, ExtensionLaunchProviderResolveRequest, ExtensionLaunchProviderResolveResult, GitHubTokenAcquireReason, GitHubTokenAcquireResult, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, HostDiagnostics, HostErrorReportingStatus, InstallationConfirmationRequest, InstallationConfirmationResponse, InstallationDecision, InstallationReview, McpInstallationReview, } from "./generated/rpc.js";
 /**
  * Arguments passed to a session's {@link GitHubTokenProvider}.
  *
@@ -43,6 +44,7 @@ export type { CurrentModel, ModelSwitchAutoTierResult, ModelSwitchAutoTierStatus
 export type { SessionFsProvider } from "./sessionFsProvider.js";
 export { createSessionFsAdapter } from "./sessionFsProvider.js";
 export type { SessionFsFileInfo } from "./sessionFsProvider.js";
+export type { SessionFsByteRange } from "./sessionFsProvider.js";
 export type { SessionFsSqliteQueryResult } from "./sessionFsProvider.js";
 export type { SessionFsSqliteQueryType } from "./sessionFsProvider.js";
 export type { SessionFsSqliteProvider } from "./sessionFsProvider.js";
@@ -91,7 +93,7 @@ export interface TelemetryConfig {
     exporterType?: string;
     /** Instrumentation scope name. Sets COPILOT_OTEL_SOURCE_NAME. */
     sourceName?: string;
-    /** Whether to capture message content (prompts, responses). Sets OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT. */
+    /** Whether to capture span content. Sets OTEL_INSTRUMENTATION_GENAI_CAPTURE_CONTENT and its legacy boolean alias. */
     captureContent?: boolean;
 }
 /**
@@ -150,7 +152,6 @@ export interface InProcessRuntimeConnection {
      * Required for OneAuth interactive authentication on macOS. This general-purpose
      * scheduler may also be used for other runtime-owned native UI operations.
      * Temporary OneAuth workaround; this API may be removed if no longer needed.
-     * See https://github.com/github/copilot-agent-runtime/issues/27032.
      * @experimental
      */
     readonly runOnUiThread?: (action: () => void) => void | Promise<void>;
@@ -265,14 +266,31 @@ export interface CopilotClientInfo {
      */
     integrationVersion?: string;
 }
-export type EntraAuthConfig = import("./generated/rpc.js").EntraAuthConfig;
+/** Host application's Microsoft Entra registration. @experimental */
+export type EntraAuthConfig = Pick<import("./generated/rpc.js").EntraAuthConfig, "clientId" | "matsAppName">;
+/** Host-owned Entra identity or resource acquisition. @experimental */
+export type EntraTokenProviderArgs = import("./generated/rpc.js").EntraTokenAcquireRequest;
+/** Response matching the requested acquisition kind and pinned account. @experimental */
+export type EntraTokenProviderResult = import("./generated/rpc.js").EntraTokenAcquireResult;
+/**
+ * Selects/revalidates an identity or acquires its resource token. Renewal must be
+ * silent and account-pinned. Cancellation and unavailability never open runtime sign-in.
+ * The cancellation token fires when the request or original connection ends.
+ * @experimental
+ */
+export type EntraTokenProvider = (request: EntraTokenProviderArgs, cancellation: import("./jsonrpcTypes.js").CancellationToken) => EntraTokenProviderResult | Promise<EntraTokenProviderResult>;
+/** Entra application and optional host-owned acquisition. @experimental */
+export interface EntraAuthOptions extends EntraAuthConfig {
+    /** Host-owned acquisition; omission retains built-in runtime authentication. @experimental */
+    tokenProvider?: EntraTokenProvider;
+}
 export interface CopilotClientOptions {
     /**
      * Host application's Microsoft Entra registration, shared by its sessions.
      * Required for built-in Entra sign-in and token renewal; other authentication methods remain available.
      * @experimental
      */
-    entra?: EntraAuthConfig;
+    entra?: EntraAuthOptions;
     /**
      * How to connect to the Copilot runtime. When omitted, defaults to
      * {@link RuntimeConnection.forStdio} with the bundled runtime.
@@ -317,6 +335,10 @@ export interface CopilotClientOptions {
      * @experimental
      */
     extensionLaunchProvider?: ExtensionLaunchProvider;
+    /**
+     * Supplies Kerberos credentials from the SDK host. Registered before sessions start.
+     */
+    kerberosAuth?: KerberosAuthConfig;
     /**
      * Connection-global human review for experimental installation operations.
      * Does not register or enable installation capabilities on the runtime.
@@ -341,7 +363,8 @@ export interface CopilotClientOptions {
     /**
      * Whether to use the logged-in user for authentication.
      * When true, the runtime will attempt to use stored OAuth tokens or gh CLI auth.
-     * When false, only explicit tokens (gitHubToken or environment variables) are used.
+     * When false, only explicit tokens such as gitHubToken are used; environment variable
+     * tokens (COPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKEN) are ignored.
      * @default true (but defaults to false when gitHubToken is provided)
      */
     useLoggedInUser?: boolean;
@@ -444,6 +467,26 @@ export interface CopilotClientOptions {
 }
 /** Resolves launch profiles for extension entrypoints discovered by the runtime. */
 export type ExtensionLaunchProvider = GeneratedExtensionLaunchProvider;
+/** Supplies Kerberos credentials from the SDK host for a requested service principal. */
+export interface KerberosAuthConfig {
+    /** `fallback` uses the callback only when native lookup fails; `always` never attempts native lookup. */
+    mode: KerberosAuthMode;
+    /**
+     * `connection` (the default) authenticates only requests made for sessions this client creates or resumes;
+     * `runtime` also authenticates the runtime's shared background traffic. Only one connection at a time can
+     * hold `runtime` scope, so startup fails if another client holds it. The registration ends when the
+     * connection closes.
+     */
+    scope?: KerberosAuthScope;
+    /**
+     * Returns a fresh, single-use base64 SPNEGO token without the `Negotiate ` prefix, or `undefined` when unavailable.
+     * The SPN uses the platform-independent `service/host[@REALM]` form; validate it before issuing credentials.
+     * `signal` aborts when the runtime stops waiting: it cancels the request (for example when its wait times
+     * out) or the connection closes. The SDK then stops awaiting the callback and ignores any later result,
+     * so pass `signal` to credential lookups that support cancellation.
+     */
+    callback: (request: KerberosAuthAcquireRequest, signal: AbortSignal) => Promise<string | undefined>;
+}
 /**
  * Configuration for creating a session
  */
@@ -854,7 +897,7 @@ export interface ElicitationResult {
     /** User action: "accept" (submitted), "decline" (rejected), or "cancel" (dismissed). */
     action: "accept" | "decline" | "cancel";
     /** Form values submitted by the user (present when action is "accept"). */
-    content?: Record<string, ElicitationFieldValue>;
+    content?: Record<string, ElicitationFieldValue | undefined>;
 }
 /**
  * Parameters for a raw elicitation request.
@@ -880,8 +923,6 @@ export interface ElicitationContext {
     mode?: "form" | "url";
     /** The source that initiated the request (e.g. MCP server name). */
     elicitationSource?: string;
-    /** Trusted display label of a Connector-owned MCP server that initiated the request, such as "Work IQ". */
-    elicitationSourceDisplayName?: string;
     /** URL to open in the user's browser (url mode only). */
     url?: string;
 }
@@ -1098,6 +1139,16 @@ export declare function createAttributedPermissionResult(result: PermissionReque
 export interface PermissionHandlerInvocation {
     sessionId: string;
     managedSettingsEnabled?: boolean;
+    /**
+     * Canonical runtime-owned Assisted Permissions assessment.
+     *
+     * This explains the assisted review only; `permission.completed` remains
+     * authoritative for the final permission result. It is absent with older
+     * runtimes and legacy direct permission callbacks.
+     *
+     * @experimental
+     */
+    assistedApprovalAssessment?: PermissionRequestedData["assistedApprovalAssessment"];
     /**
      * Derived user-facing prompt context when supplied by the runtime.
      *
@@ -1210,9 +1261,13 @@ export interface BaseHookInput {
     agentType?: string;
     /** Immediate parent actor ID, when available. */
     parentAgentId?: string;
+    /** W3C trace context for the runtime span associated with this hook, when available. */
+    traceparent?: string;
+    /** W3C vendor trace state associated with traceparent, when available. */
+    tracestate?: string;
     /** The runtime session ID associated with the hook. Child tool hooks use
      * the child session ID; sub-agent lifecycle hooks use the parent session ID,
-     * matching `invocation.sessionId`. */
+     * which can differ from `invocation.sessionId`. */
     sessionId: string;
     /** Time at which the hook event was emitted by the runtime. */
     timestamp: Date;
@@ -1222,6 +1277,8 @@ export interface BaseHookInput {
  * Input for pre-tool-use hook
  */
 export interface PreToolUseHookInput extends BaseHookInput {
+    /** Existing tool-call ID; correlate using (sessionId, toolCallId). Absent on older runtimes. */
+    toolCallId?: string;
     toolName: string;
     toolArgs: unknown;
 }
@@ -1273,6 +1330,8 @@ export type PreMcpToolCallHandler = (input: PreMcpToolCallHookInput, invocation:
  * Input for post-tool-use hook
  */
 export interface PostToolUseHookInput extends BaseHookInput {
+    /** Existing tool-call ID; correlate using (sessionId, toolCallId). Absent on older runtimes. */
+    toolCallId?: string;
     toolName: string;
     toolArgs: unknown;
     toolResult: ToolResultObject;
@@ -1300,6 +1359,8 @@ export type PostToolUseHandler = (input: PostToolUseHookInput, invocation: {
  * stringified failure message extracted from the tool's result, is provided.
  */
 export interface PostToolUseFailureHookInput extends BaseHookInput {
+    /** Existing tool-call ID; correlate using (sessionId, toolCallId). Absent on older runtimes. */
+    toolCallId?: string;
     toolName: string;
     toolArgs: unknown;
     /**
@@ -2312,10 +2373,10 @@ export interface SessionConfigBase {
     models?: ProviderModelConfig[];
     /**
      * Enables or disables internal session telemetry for this session.
-     * When `false`, disables session telemetry. When omitted (the default) or `true`,
-     * telemetry is enabled for GitHub-authenticated sessions.
-     * When a custom {@link provider} (BYOK) is configured, session telemetry is always
-     * disabled regardless of this setting.
+     * `false` disables it; `true` enables it for eligible GitHub-authenticated sessions,
+     * including custom {@link provider} (BYOK) sessions. Omission preserves a resident
+     * session's choice; otherwise defaults to enabled. Host and account policies still
+     * determine whether telemetry can be uploaded.
      * This is independent of the OpenTelemetry configuration in {@link CopilotClientOptions.telemetry}.
      */
     enableSessionTelemetry?: boolean;
@@ -2365,7 +2426,7 @@ export interface SessionConfigBase {
     customAgentsLocalOnly?: boolean;
     /**
      * When true, the runtime instructs the agent to include a `Co-authored-by`
-     * trailer in commit messages it composes.
+     * trailer in commit messages it composes. Subagents inherit this setting.
      *
      * Defaults to `true`. Under {@link CopilotClientOptions.mode} = `"empty"`,
      * defaults to `false`; apps can pass `true` here to opt back in.
@@ -2822,10 +2883,10 @@ export interface ResumeSessionConfig extends SessionConfigBase {
      * runtime treats pending work as interrupted on resume. Completed tool results
      * already durably recorded by the runtime are preserved.
      *
-     * For permission requests, the runtime re-emits `permission.requested` so the
-     * registered `onPermissionRequest` handler can re-prompt; for external tool calls,
-     * the consumer is expected to supply the result via the corresponding low-level
-     * RPC method.
+     * When true, pending permission requests and external tool calls wait for
+     * caller-supplied results via the corresponding low-level RPC methods. Resuming
+     * does not re-emit restored permission requests or re-invoke permission handlers
+     * or already-dispatched external tool callbacks.
      * @default false
      */
     continuePendingWork?: boolean;
@@ -2913,7 +2974,9 @@ export interface ProviderConfig {
     transport?: "http" | "websockets";
     /**
      * Product serving the model, such as "ollama" or "lm_studio", reported in
-     * telemetry as `model_provider`. Only affects telemetry.
+     * telemetry as `model_provider`. "azure_openai" also omits explicit
+     * prompt-cache breakpoints, which limit cross-turn cache reuse on Azure; set
+     * it for a proxy or custom domain in front of Azure OpenAI.
      */
     modelProvider?: ProviderConfigModelProvider;
     /**
@@ -3017,7 +3080,9 @@ export interface NamedProviderConfig {
     wireApi?: "completions" | "responses";
     /**
      * Product serving this provider's models, such as "ollama" or "lm_studio",
-     * reported in telemetry as `model_provider`. Only affects telemetry.
+     * reported in telemetry as `model_provider`. "azure_openai" also omits
+     * explicit prompt-cache breakpoints, which limit cross-turn cache reuse on
+     * Azure; set it for a proxy or custom domain in front of Azure OpenAI.
      */
     modelProvider?: ProviderConfigModelProvider;
     /**
@@ -3267,6 +3332,8 @@ export interface SessionFsConfig {
          * @default false
          */
         binary?: boolean;
+        /** Whether every session provider supports bounded byte-range reads, independently of binary support. */
+        readFileRange?: boolean;
     };
 }
 /**
@@ -3302,6 +3369,8 @@ export interface GetStatusResponse {
     version: string;
     /** Protocol version for SDK compatibility */
     protocolVersion: number;
+    /** Host diagnostics, when supplied by the runtime. */
+    hostDiagnostics?: HostDiagnostics;
 }
 /**
  * Response from auth.getStatus
@@ -3368,6 +3437,8 @@ export interface ModelInfo {
     id: string;
     /** Display name */
     name: string;
+    /** Native serving provider, when attributed by the runtime. Absent for configured BYOK models. */
+    provider?: ModelProviderRef;
     /** Model capabilities and limits */
     capabilities: ModelCapabilities;
     /** Policy state */

package/dist/workflow.d.ts

@@ -6,7 +6,7 @@ export type { WorkflowRunResult };
 export type JsonValue = null | boolean | number | string | JsonValue[] | {
     [key: string]: JsonValue;
 };
-export type { WorkflowAgentSummary, WorkflowPhaseStatus, WorkflowPhaseObservation, WorkflowProgressLine, WorkflowProgressPage, WorkflowRunDetail, WorkflowRunStatus, WorkflowRunSummary, } from "./generated/rpc.js";
+export type { WorkflowAgentContextObservation, WorkflowAgentModelObservation, WorkflowAgentReasoningEffortObservation, WorkflowAgentSummary, WorkflowPhaseStatus, WorkflowPhaseObservation, WorkflowProgressLine, WorkflowProgressPage, WorkflowRunDetail, WorkflowRunStatus, WorkflowRunSummary, } from "./generated/rpc.js";
 /**
  * Options for paging durable workflow runs.
  *

package/docs/agent-author.md

@@ -19,8 +19,8 @@ For user-scoped extensions (persist across all repos), add `location: "user"`.
 
 Modify the generated `extension.mjs` using `edit` or `create` tools. The file must:
 
-- Be named `extension.mjs` (only `.mjs` is supported)
-- Use ES module syntax (`import`/`export`)
+- Be named `extension.mjs`, `extension.cjs` or `extension.js` (the scaffold creates `extension.mjs`)
+- Use ES module syntax (`import`/`export`) in `.mjs` files, or CommonJS (`require`) in `.cjs` files
 - Call `joinSession({ ... })`
 
 ### Step 3: Reload extensions
@@ -53,7 +53,7 @@ Discovery rules:
 - The CLI scans `.github/extensions/` relative to the git root
 - It also scans the user's copilot config extensions directory
 - Only immediate subdirectories are checked (not recursive)
-- Each subdirectory must contain a file named `extension.mjs`
+- Each subdirectory must contain a file named `extension.mjs`, `extension.cjs` or `extension.js`
 - Project extensions shadow user extensions on name collision
 
 ---
@@ -320,5 +320,5 @@ Low-level typed RPC access to all session APIs (model, mode, plan, workspace, et
 - **Tool name collisions are fatal.** If two extensions register the same tool name, the second extension fails to initialize.
 - **Don't call `session.send()` synchronously from `onUserPromptSubmitted`.** Use `setTimeout(() => session.send(...), 0)` to avoid infinite loops.
 - **Extensions are reloaded on `/clear`.** Any in-memory state is lost between sessions.
-- **Only `.mjs` is supported.** TypeScript (`.ts`) is not yet supported.
+- **The entry file must be `.mjs`, `.cjs` or `.js`.** TypeScript (`.ts`) is not yet supported.
 - **The handler's return value is the tool result.** Returning `undefined` sends an empty success. Throwing sends a failure with the error message.