@github/copilot-sdk 1.0.13-preview.1 → 1.0.13-preview.3

package/dist/index.d.ts

@@ -11,5 +11,5 @@ export { defineFactory, FactoryResumeError, isFactoryRunTerminal } from "./facto
 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 { CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, AgentStopHandler, AgentStopHookInput, AgentStopHookOutput, UserPromptTransformedHandler, UserPromptTransformedHookInput, UserPromptTransformedHookOutput, 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, GitHubMcpToolConfig, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, FactoryLimits, FactoryMeta, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, BearerTokenProvider, MessageOptions, ManagedSettings, ManagedSettingsPermissions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, CapiSessionOptions, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, NamedProviderConfig, PermissionHandler, PermissionRequest, PermissionRequestedData, PermissionRequestedEvent, PermissionRequestResult, AttributedPermissionResult, PermissionDecisionContext, PermissionDecisionOutcome, PermissionDecisionSource, PermissionDecisionSurface, 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";
+export type { AskUserVariant, CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, AgentStopHandler, AgentStopHookInput, AgentStopHookOutput, UserPromptTransformedHandler, UserPromptTransformedHookInput, UserPromptTransformedHookOutput, 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, GitHubMcpToolConfig, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, GitHubTokenAcquireReason, GitHubTokenAcquireResult, GitHubTokenProvider, GitHubTokenProviderArgs, GitHubTokenProviderResult, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, FactoryLimits, FactoryMeta, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, BearerTokenProvider, MessageOptions, ManagedSettings, ManagedSettingsPermissions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, CapiSessionOptions, 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 { RunOptions, ResumeOptions, FactoryResumeErrorCode, SessionFactoryApi, FactoryAgentOptions, FactoryContext, FactoryDefinition, FactoryHandle, FactoryJsonSchema, JsonValue, FactoryPipelineStage, FactoryStepOptions, FactoryRunResult, FactoryRunStatus, FactoryRunSummary, FactoryListRunsOptions, FactoryRunsPage, FactoryRunDetail, FactoryProgressPage, FactoryProgressLine, FactoryPhaseObservation, FactoryPhaseStatus, FactoryAgentSummary, } from "./factory.js";

package/dist/session.d.ts

@@ -62,6 +62,7 @@ export declare class CopilotSession {
     private _capabilities;
     private openCanvasInstances;
     private disconnected;
+    private onDisconnected?;
     /**
      * Friendly factory API for running registered factories by name or handle.
      *

package/dist/session.js

@@ -223,6 +223,7 @@ class CopilotSession {
     this.traceContextProvider = traceContextProvider;
     this.mcpAuthHandler = options?.mcpAuthHandler;
     this.managedSettingsEnabled = options?.managedSettingsEnabled === true;
+    this.onDisconnected = options?.onDisconnected;
   }
   sessionId;
   connection;
@@ -249,6 +250,7 @@ class CopilotSession {
   _capabilities = {};
   openCanvasInstances = [];
   disconnected = false;
+  onDisconnected;
   /** @internal Client session API handlers, populated by CopilotClient during create/resume. */
   clientSessionApis = {};
   /**
@@ -263,14 +265,18 @@ class CopilotSession {
       const name = typeof nameOrHandle === "string" ? nameOrHandle : getFactoryDefinition(nameOrHandle).meta.name;
       if (options?.resumeFromRunId !== void 0) {
         return this.factory.resume(options.resumeFromRunId, {
-          limits: options.limits
+          limits: options.limits,
+          notifyOnComplete: options.notifyOnComplete,
+          logPhaseNames: options.logPhaseNames
         });
       }
       const envelope = await this.rpc.factory.run({
         name,
         args: options?.args === void 0 ? {} : options.args,
         options: {
-          limits: options?.limits
+          limits: options?.limits,
+          notifyOnComplete: options?.notifyOnComplete,
+          logPhaseNames: options?.logPhaseNames
         }
       });
       return this.settleFactoryRun(envelope);
@@ -281,7 +287,9 @@ class CopilotSession {
       try {
         response = await this.rpc.factory.resume({
           runId,
-          limits: options?.limits
+          limits: options?.limits,
+          notifyOnComplete: options?.notifyOnComplete,
+          logPhaseNames: options?.logPhaseNames
         });
       } catch (error) {
         if (error instanceof ResponseError && typeof error.data === "object" && error.data !== null) {
@@ -296,7 +304,10 @@ class CopilotSession {
     }),
     getRun: async (runId) => this.rpc.factory.getRun({ runId }),
     waitForRun: (runId, options) => this.waitForFactoryRun(runId, options?.signal),
-    listRuns: async () => (await this.rpc.factory.listRuns({})).runs,
+    listRuns: (async (options) => {
+      const page = await this.rpc.factory.listRuns(options ?? {});
+      return options === void 0 ? page.runs : page;
+    }),
     getRunDetail: (runId) => this.rpc.factory.getRunDetail({ runId }),
     getRunProgress: (runId, options = {}) => this.rpc.factory.getRunProgress({ runId, ...options }),
     cancel: async (runId) => this.rpc.factory.cancel({ runId })
@@ -457,7 +468,7 @@ class CopilotSession {
     const unsubscribe = this.on((event) => {
       if (event.type === "assistant.message") {
         lastAssistantMessage = event;
-      } else if (event.type === "session.idle") {
+      } else if (event.type === "session.idle" && event.data.mode !== "autopilot") {
         resolveOutcome({ kind: "idle" });
       } else if (event.type === "session.error") {
         const error = new Error(event.data.message);
@@ -492,7 +503,11 @@ class CopilotSession {
   }
   /** @internal */
   _markDisconnected() {
+    if (this.disconnected) {
+      return;
+    }
     this.disconnected = true;
+    this._runOnDisconnected();
     this.eventHandlers.clear();
     this.typedEventHandlers.clear();
     this.toolHandlers.clear();
@@ -512,6 +527,15 @@ class CopilotSession {
     this.factoryAbortControllers.clear();
     this.transformCallbacks?.clear();
   }
+  /** @internal */
+  _runOnDisconnected() {
+    this.onDisconnected?.();
+    this.onDisconnected = void 0;
+  }
+  /** @internal */
+  _setOnDisconnected(callback) {
+    this.onDisconnected = callback;
+  }
   on(eventTypeOrHandler, handler) {
     if (typeof eventTypeOrHandler === "string" && handler) {
       const eventType = eventTypeOrHandler;

package/dist/types.d.ts

@@ -7,11 +7,29 @@ import type { CopilotRequestHandler } from "./copilotRequestHandler.js";
 import type { 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 { FactoryJsonSchema, JsonValue } from "./factory.js";
-import type { GitHubTelemetryNotification, ModelBillingTokenPrices, OpenCanvasInstance, RemoteSessionMode, CurrentToolMetadata } from "./generated/rpc.js";
+import type { GitHubTokenAcquireRequest, GitHubTokenAcquireResult, GitHubTelemetryNotification, ModelBillingTokenPrices, OpenCanvasInstance, RemoteSessionMode, CurrentToolMetadata } from "./generated/rpc.js";
 import type { ToolSet } from "./toolSet.js";
 export type { RemoteSessionMode } from "./generated/rpc.js";
 export type { CurrentToolMetadata } from "./generated/rpc.js";
-export type { GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, } from "./generated/rpc.js";
+export type { GitHubTokenAcquireReason, GitHubTokenAcquireResult, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, } from "./generated/rpc.js";
+/**
+ * Arguments passed to a session's {@link GitHubTokenProvider}.
+ *
+ * The callback registration identifier is intentionally kept inside the SDK.
+ */
+export type GitHubTokenProviderArgs = Pick<GitHubTokenAcquireRequest, "host" | "sessionId" | "reason">;
+/** Tagged token or cancellation returned by a {@link GitHubTokenProvider}. */
+export type GitHubTokenProviderResult = GitHubTokenAcquireResult;
+/**
+ * Acquires a GitHub token for one session.
+ *
+ * A token result must include `expiresIn`: the positive number of seconds of
+ * remaining lifetime when the callback completes. Production GitHub tokens
+ * typically last eight hours. Initial cancellation, callback errors, and
+ * invalid token responses reject session creation or resume instead of falling
+ * back to ambient authentication.
+ */
+export type GitHubTokenProvider = (args: GitHubTokenProviderArgs) => GitHubTokenProviderResult | Promise<GitHubTokenProviderResult>;
 export type { ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, } from "./generated/rpc.js";
 export type SessionEvent = Exclude<GeneratedSessionEvent, {
     type: "permission.requested";
@@ -27,7 +45,7 @@ export type { SessionFsSqliteStatement } from "./sessionFsProvider.js";
 export type { SessionFsSqliteTransactionErrorClass } from "./sessionFsProvider.js";
 export { SessionFsSqliteTransactionFailure } from "./sessionFsProvider.js";
 export type { LlmInferenceHeaders } from "./generated/rpc.js";
-export type { PermissionDecisionContext, PermissionDecisionOutcome, PermissionDecisionSource, PermissionDecisionSurface, } from "./generated/rpc.js";
+export type { PermissionDecisionContext, PermissionDecisionOutcome, PermissionDecisionSource, PermissionDecisionSurface, PermissionResponseCapability, } from "./generated/rpc.js";
 export type { CopilotRequestContext } from "./copilotRequestHandler.js";
 export { CopilotRequestHandler, CopilotWebSocketHandler, CopilotWebSocketCloseStatus, CopilotWebSocketForwarder, } from "./copilotRequestHandler.js";
 /**
@@ -925,7 +943,7 @@ export type PermissionHandler = (request: PermissionRequest, invocation: {
 export declare const approveAll: PermissionHandler;
 export declare const defaultJoinSessionPermissionHandler: PermissionHandler;
 /**
- * Request for user input from the agent (enables ask_user tool)
+ * Legacy question-and-answer request from the `ask_user` tool.
  */
 export interface UserInputRequest {
     /**
@@ -1795,6 +1813,8 @@ export interface ManagedSettings {
     /** Managed permission policy for the session. */
     permissions?: ManagedSettingsPermissions;
 }
+/** Selects the model-facing shape of the built-in `ask_user` tool. */
+export type AskUserVariant = "legacy" | "elicitation";
 /**
  * Shared configuration fields used by both {@link SessionConfig} (for
  * creating a new session) and {@link ResumeSessionConfig} (for resuming
@@ -2067,9 +2087,18 @@ export interface SessionConfigBase {
     onMcpAuthRequest?: McpAuthHandler;
     /**
      * Handler for user input requests from the agent.
-     * When provided, enables the ask_user tool allowing the agent to ask questions.
+     * When provided with the default `legacy` {@link AskUserVariant}, enables the
+     * question-and-answer form of the `ask_user` tool.
      */
     onUserInputRequest?: UserInputHandler;
+    /**
+     * Selects the model-facing shape of the built-in `ask_user` tool.
+     *
+     * The default is `"legacy"`. To use `"elicitation"`, also provide
+     * {@link onElicitationRequest} so the host can answer structured forms.
+     * The runtime resolves this option when it creates or cold-resumes the session.
+     */
+    askUserVariant?: AskUserVariant;
     /**
      * Handler for elicitation requests from the agent.
      * When provided, the server calls back to this client for form-based UI dialogs.
@@ -2237,6 +2266,15 @@ export interface SessionConfigBase {
      * the identity used for content exclusion, model routing, and quota checks.
      */
     gitHubToken?: string;
+    /**
+     * Acquires short-lived GitHub credentials for this session on demand.
+     *
+     * Mutually exclusive with {@link SessionConfigBase.gitHubToken}. The
+     * callback receives the effective GitHub host, the session ID when known,
+     * and whether this is the initial acquisition or a refresh. Its opaque
+     * registration ID remains internal to the SDK.
+     */
+    gitHubTokenProvider?: GitHubTokenProvider;
     /**
      * Opt-in: when true, the runtime self-fetches enterprise managed settings
      * (bypass-permissions policy) at session bootstrap using the session's

package/docs/factories.md

@@ -139,6 +139,8 @@ Run by registered name or handle:
 const run = await session.factory.run("review-changed", {
     args: { files: ["src/a.ts"] },
     limits: { maxAiCredits: 3 },
+    notifyOnComplete: true,
+    logPhaseNames: true,
 });
 
 if (run.status === "completed") {
@@ -153,7 +155,12 @@ The name overload is:
 ```ts
 session.factory.run(
     name: string,
-    options?: { args?: JsonValue; limits?: FactoryLimits },
+    options?: {
+        args?: JsonValue;
+        limits?: FactoryLimits;
+        notifyOnComplete?: boolean;
+        logPhaseNames?: boolean;
+    },
 ): Promise<FactoryRunResult>;
 ```
 
@@ -162,6 +169,8 @@ Resume by run ID without resending the name or arguments:
 ```ts
 const run = await session.factory.resume(runId, {
     limits: { maxAiCredits: 6 },
+    notifyOnComplete: true,
+    logPhaseNames: true,
 });
 ```
 
@@ -170,10 +179,16 @@ The signature is:
 ```ts
 session.factory.resume(
     runId: string,
-    options?: { limits?: FactoryLimits },
+    options?: {
+        limits?: FactoryLimits;
+        notifyOnComplete?: boolean;
+        logPhaseNames?: boolean;
+    },
 ): Promise<FactoryRunResult>;
 ```
 
+Set `notifyOnComplete` to `true` for factories that are likely to be invoked by an agent, so the originating session is notified when the factory completes. Set it to `false` for factories intended to be invoked programmatically, where the caller awaits the result directly. Set `logPhaseNames` to emit factory phase names to the session transcript. Both options apply to new and resumed runs.
+
 Both resolve with the run envelope (`FactoryRunResult`) for **every** outcome — `completed`, `error`, `halted`, and `cancelled` alike. Inspect `status` and read `result` only when the run completed; a limit breach carries a typed `failure`. SDK-initiated `run` and `resume` do not request permission, so they have no declined outcome. The model's `run_factory` tool requests permission before the durable row exists; declining it creates no run row. An SDK-initiated run is refused only when the session already has its maximum number of active top-level runs. Pre-execution resume failures throw `FactoryResumeError`, whose `code` is one of `not_found`, `non_resumable`, `already_active`, `factory_already_running`, `factory_limits_invalid`, `factory_session_disposed`, `factory_storage_unavailable`, or `factory_storage_corrupt`.
 
 An agent that no longer has a prior run's ID in context can recover it with `factories_manage` and `operation: "runs"`, which lists the session's factory runs with their IDs and statuses. This matters for resume: a run that reached a limit keeps its journal, so resuming it replays completed work for free, while restarting it from scratch pays for that work twice.
@@ -219,8 +234,13 @@ The calling session can inspect its own factory runs:
 
 ```ts
 const runs = await session.factory.listRuns();
+const runsPage = await session.factory.listRuns({
+    afterSeq,
+    beforeSeq,
+    limit,
+});
 const detail = await session.factory.getRunDetail(runId);
-const page = await session.factory.getRunProgress(runId, {
+const progressPage = await session.factory.getRunProgress(runId, {
     phaseId,
     afterSeq,
     beforeSeq,
@@ -228,7 +248,8 @@ const page = await session.factory.getRunProgress(runId, {
 });
 ```
 
-- `listRuns()` returns the newest default page of this session's durable factory runs.
+- `listRuns()` returns only the runs array from the newest default page of this session's durable factory runs. This overload preserves the original convenience API.
+- `listRuns({ afterSeq, beforeSeq, limit })` returns the full page. Its `oldestSeq`, `newestSeq`, `hasMoreNewer`, and `omittedOlder` fields let callers continue paging without raw RPC calls.
 - `getRunDetail(runId)` returns phases, prompt-safe agent summaries, and the latest progress page.
 - `getRunProgress(runId, options?)` pages progress forward, backward, by phase, or from the latest tail.
 

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/github/copilot-sdk.git"
   },
-  "version": "1.0.13-preview.1",
+  "version": "1.0.13-preview.3",
   "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
   "main": "./dist/cjs/index.js",
   "types": "./dist/index.d.ts",
@@ -56,7 +56,7 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
-    "@github/copilot": "^1.0.81-10",
+    "@github/copilot": "^1.0.83-0",
     "koffi": "^3.1.0",
     "vscode-jsonrpc": "^8.2.1",
     "zod": "^4.3.6"