@github/copilot-sdk 0.2.1-preview.1 → 0.2.1-preview.2

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

@@ -92,7 +92,7 @@ export type SessionEvent = {
         /**
          * Whether this session supports remote steering via Mission Control
          */
-        steerable?: boolean;
+        remoteSteerable?: boolean;
     };
 } | {
     /**
@@ -169,6 +169,37 @@ export type SessionEvent = {
          * Whether the session was already in use by another client at resume time
          */
         alreadyInUse?: boolean;
+        /**
+         * Whether this session supports remote steering via Mission Control
+         */
+        remoteSteerable?: boolean;
+    };
+} | {
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    /**
+     * When true, the event is transient and not persisted to the session event log on disk
+     */
+    ephemeral?: boolean;
+    type: "session.remote_steerable_changed";
+    /**
+     * Notifies Mission Control that the session's remote steering capability has changed
+     */
+    data: {
+        /**
+         * Whether this session now supports remote steering via Mission Control
+         */
+        remoteSteerable: boolean;
     };
 } | {
     /**
@@ -271,6 +302,10 @@ export type SessionEvent = {
                 description?: string;
             }[];
         };
+        /**
+         * True when the preceding agentic loop was cancelled via abort signal
+         */
+        aborted?: boolean;
     };
 } | {
     /**
@@ -1550,7 +1585,15 @@ export type SessionEvent = {
          */
         duration?: number;
         /**
-         * What initiated this API call (e.g., "sub-agent"); absent for user-initiated calls
+         * Time to first token in milliseconds. Only available for streaming requests
+         */
+        ttftMs?: number;
+        /**
+         * Average inter-token latency in milliseconds. Only available for streaming requests
+         */
+        interTokenLatencyMs?: number;
+        /**
+         * What initiated this API call (e.g., "sub-agent", "mcp-sampling"); absent for user-initiated calls
          */
         initiator?: string;
         /**
@@ -2938,6 +2981,63 @@ export type SessionEvent = {
          */
         requestId: string;
     };
+} | {
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    ephemeral: true;
+    type: "sampling.requested";
+    /**
+     * Sampling request from an MCP server; contains the server name and a requestId for correlation
+     */
+    data: {
+        /**
+         * Unique identifier for this sampling request; used to respond via session.respondToSampling()
+         */
+        requestId: string;
+        /**
+         * Name of the MCP server that initiated the sampling request
+         */
+        serverName: string;
+        /**
+         * The JSON-RPC request ID from the MCP protocol
+         */
+        mcpRequestId: string | number;
+        [k: string]: unknown;
+    };
+} | {
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    ephemeral: true;
+    type: "sampling.completed";
+    /**
+     * Sampling request completion notification signaling UI dismissal
+     */
+    data: {
+        /**
+         * Request ID of the resolved sampling request; clients should dismiss any UI for this request
+         */
+        requestId: string;
+    };
 } | {
     /**
      * Unique event identifier (UUID v4), generated when the event is emitted
@@ -3196,6 +3296,35 @@ export type SessionEvent = {
             description?: string;
         }[];
     };
+} | {
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    ephemeral: true;
+    type: "capabilities.changed";
+    /**
+     * Session capability change notification
+     */
+    data: {
+        /**
+         * UI capability changes
+         */
+        ui?: {
+            /**
+             * Whether elicitation is now supported
+             */
+            elicitation?: boolean;
+        };
+    };
 } | {
     /**
      * Unique event identifier (UUID v4), generated when the event is emitted
@@ -3427,9 +3556,9 @@ export type SessionEvent = {
              */
             name: string;
             /**
-             * Connection status: connected, failed, pending, disabled, or not_configured
+             * Connection status: connected, failed, needs-auth, pending, disabled, or not_configured
              */
-            status: "connected" | "failed" | "pending" | "disabled" | "not_configured";
+            status: "connected" | "failed" | "needs-auth" | "pending" | "disabled" | "not_configured";
             /**
              * Configuration source: user, workspace, plugin, or builtin
              */
@@ -3461,9 +3590,9 @@ export type SessionEvent = {
          */
         serverName: string;
         /**
-         * New connection status: connected, failed, pending, disabled, or not_configured
+         * New connection status: connected, failed, needs-auth, pending, disabled, or not_configured
          */
-        status: "connected" | "failed" | "pending" | "disabled" | "not_configured";
+        status: "connected" | "failed" | "needs-auth" | "pending" | "disabled" | "not_configured";
     };
 } | {
     /**

package/dist/index.d.ts

@@ -6,4 +6,4 @@
 export { CopilotClient } from "./client.js";
 export { CopilotSession, type AssistantMessageEvent } from "./session.js";
 export { defineTool, approveAll, SYSTEM_PROMPT_SECTIONS } from "./types.js";
-export type { CommandContext, CommandDefinition, CommandHandler, ConnectionState, CopilotClientOptions, CustomAgentConfig, ElicitationFieldValue, ElicitationParams, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, InfiniteSessionConfig, InputOptions, MCPLocalServerConfig, MCPRemoteServerConfig, MCPServerConfig, MessageOptions, ModelBilling, ModelCapabilities, ModelInfo, ModelPolicy, PermissionHandler, PermissionRequest, PermissionRequestResult, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventType, SessionLifecycleHandler, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemPromptSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, ToolResultObject, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
+export type { CommandContext, CommandDefinition, CommandHandler, ConnectionState, CopilotClientOptions, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationRequest, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, InfiniteSessionConfig, InputOptions, MCPLocalServerConfig, MCPRemoteServerConfig, MCPServerConfig, MessageOptions, ModelBilling, ModelCapabilities, ModelInfo, ModelPolicy, PermissionHandler, PermissionRequest, PermissionRequestResult, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventType, SessionLifecycleHandler, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsHandler, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemPromptSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, ToolResultObject, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";

package/dist/session.d.ts

@@ -4,7 +4,8 @@
  */
 import type { MessageConnection } from "vscode-jsonrpc/node.js";
 import { createSessionRpc } from "./generated/rpc.js";
-import type { CommandHandler, MessageOptions, PermissionHandler, PermissionRequestResult, ReasoningEffort, SectionTransformFn, SessionCapabilities, SessionEvent, SessionEventHandler, SessionEventType, SessionHooks, SessionUiApi, Tool, ToolHandler, TraceContextProvider, TypedSessionEventHandler, UserInputHandler, UserInputResponse } from "./types.js";
+import type { ClientSessionApiHandlers } from "./generated/rpc.js";
+import type { CommandHandler, ElicitationHandler, ElicitationRequest, MessageOptions, PermissionHandler, PermissionRequestResult, ReasoningEffort, SectionTransformFn, SessionCapabilities, SessionEvent, SessionEventHandler, SessionEventType, SessionHooks, SessionUiApi, Tool, ToolHandler, TraceContextProvider, TypedSessionEventHandler, UserInputHandler, UserInputResponse } from "./types.js";
 export declare const NO_RESULT_PERMISSION_V2_ERROR = "Permission handlers cannot return 'no-result' when connected to a protocol v2 server.";
 /** Assistant message event - the final response from the assistant. */
 export type AssistantMessageEvent = Extract<SessionEvent, {
@@ -45,11 +46,14 @@ export declare class CopilotSession {
     private commandHandlers;
     private permissionHandler?;
     private userInputHandler?;
+    private elicitationHandler?;
     private hooks?;
     private transformCallbacks?;
     private _rpc;
     private traceContextProvider?;
     private _capabilities;
+    /** @internal Client session API handlers, populated by CopilotClient during create/resume. */
+    clientSessionApis: ClientSessionApiHandlers;
     /**
      * Creates a new CopilotSession instance.
      *
@@ -235,6 +239,19 @@ export declare class CopilotSession {
         name: string;
         handler: CommandHandler;
     }[]): void;
+    /**
+     * Registers the elicitation handler for this session.
+     *
+     * @param handler - The handler to invoke when the server dispatches an elicitation request
+     * @internal This method is typically called internally when creating/resuming a session.
+     */
+    registerElicitationHandler(handler?: ElicitationHandler): void;
+    /**
+     * Handles an elicitation.requested broadcast event.
+     * Invokes the registered handler and responds via handlePendingElicitation RPC.
+     * @internal
+     */
+    _handleElicitationRequest(request: ElicitationRequest, requestId: string): Promise<void>;
     /**
      * Sets the host capabilities for this session.
      *

package/dist/session.js

@@ -24,11 +24,14 @@ class CopilotSession {
   commandHandlers = /* @__PURE__ */ new Map();
   permissionHandler;
   userInputHandler;
+  elicitationHandler;
   hooks;
   transformCallbacks;
   _rpc = null;
   traceContextProvider;
   _capabilities = {};
+  /** @internal Client session API handlers, populated by CopilotClient during create/resume. */
+  clientSessionApis = {};
   /**
    * Typed session-scoped RPC methods.
    */
@@ -245,6 +248,22 @@ class CopilotSession {
     } else if (event.type === "command.execute") {
       const { requestId, commandName, command, args } = event.data;
       void this._executeCommandAndRespond(requestId, commandName, command, args);
+    } else if (event.type === "elicitation.requested") {
+      if (this.elicitationHandler) {
+        const { message, requestedSchema, mode, elicitationSource, url, requestId } = event.data;
+        void this._handleElicitationRequest(
+          {
+            message,
+            requestedSchema,
+            mode,
+            elicitationSource,
+            url
+          },
+          requestId
+        );
+      }
+    } else if (event.type === "capabilities.changed") {
+      this._capabilities = { ...this._capabilities, ...event.data };
     }
   }
   /**
@@ -266,6 +285,8 @@ class CopilotSession {
         result = "";
       } else if (typeof rawResult === "string") {
         result = rawResult;
+      } else if (isToolResultObject(rawResult)) {
+        result = rawResult;
       } else {
         result = JSON.stringify(rawResult);
       }
@@ -385,6 +406,40 @@ class CopilotSession {
       this.commandHandlers.set(cmd.name, cmd.handler);
     }
   }
+  /**
+   * Registers the elicitation handler for this session.
+   *
+   * @param handler - The handler to invoke when the server dispatches an elicitation request
+   * @internal This method is typically called internally when creating/resuming a session.
+   */
+  registerElicitationHandler(handler) {
+    this.elicitationHandler = handler;
+  }
+  /**
+   * Handles an elicitation.requested broadcast event.
+   * Invokes the registered handler and responds via handlePendingElicitation RPC.
+   * @internal
+   */
+  async _handleElicitationRequest(request, requestId) {
+    if (!this.elicitationHandler) {
+      return;
+    }
+    try {
+      const result = await this.elicitationHandler(request, { sessionId: this.sessionId });
+      await this.rpc.ui.handlePendingElicitation({ requestId, result });
+    } catch {
+      try {
+        await this.rpc.ui.handlePendingElicitation({
+          requestId,
+          result: { action: "cancel" }
+        });
+      } catch (rpcError) {
+        if (!(rpcError instanceof ConnectionError || rpcError instanceof ResponseError)) {
+          throw rpcError;
+        }
+      }
+    }
+  }
   /**
    * Sets the host capabilities for this session.
    *
@@ -743,6 +798,25 @@ class CopilotSession {
     await this.rpc.log({ message, ...options });
   }
 }
+function isToolResultObject(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  if (!("textResultForLlm" in value) || typeof value.textResultForLlm !== "string") {
+    return false;
+  }
+  if (!("resultType" in value) || typeof value.resultType !== "string") {
+    return false;
+  }
+  const allowedResultTypes = [
+    "success",
+    "failure",
+    "rejected",
+    "denied",
+    "timeout"
+  ];
+  return allowedResultTypes.includes(value.resultType);
+}
 export {
   CopilotSession,
   NO_RESULT_PERMISSION_V2_ERROR

package/dist/types.d.ts

@@ -1,8 +1,11 @@
 /**
  * Type definitions for the Copilot SDK
  */
+import type { SessionFsHandler } from "./generated/rpc.js";
 import type { SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
+import type { CopilotSession } from "./session.js";
 export type SessionEvent = GeneratedSessionEvent;
+export type { SessionFsHandler } from "./generated/rpc.js";
 /**
  * Options for creating a CopilotClient
  */
@@ -146,11 +149,18 @@ export interface CopilotClientOptions {
      * ```
      */
     onGetTraceContext?: TraceContextProvider;
+    /**
+     * Custom session filesystem provider.
+     * When provided, the client registers as the session filesystem provider
+     * on connection, routing all session-scoped file I/O through these callbacks
+     * instead of the server's default local filesystem storage.
+     */
+    sessionFs?: SessionFsConfig;
 }
 /**
  * Configuration for creating a session
  */
-export type ToolResultType = "success" | "failure" | "rejected" | "denied";
+export type ToolResultType = "success" | "failure" | "rejected" | "denied" | "timeout";
 export type ToolBinaryResult = {
     data: string;
     mimeType: string;
@@ -353,6 +363,29 @@ export interface ElicitationParams {
     /** JSON Schema describing the form fields to present. */
     requestedSchema: ElicitationSchema;
 }
+/**
+ * Request payload passed to an elicitation handler callback.
+ * Extends ElicitationParams with optional metadata fields.
+ */
+export interface ElicitationRequest {
+    /** Message describing what information is needed from the user. */
+    message: string;
+    /** JSON Schema describing the form fields to present. */
+    requestedSchema?: ElicitationSchema;
+    /** Elicitation mode: "form" for structured input, "url" for browser redirect. */
+    mode?: "form" | "url";
+    /** The source that initiated the request (e.g. MCP server name). */
+    elicitationSource?: string;
+    /** URL to open in the user's browser (url mode only). */
+    url?: string;
+}
+/**
+ * Handler invoked when the server dispatches an elicitation request to this client.
+ * Return an {@link ElicitationResult} with the user's response.
+ */
+export type ElicitationHandler = (request: ElicitationRequest, invocation: {
+    sessionId: string;
+}) => Promise<ElicitationResult> | ElicitationResult;
 /**
  * Options for the `input()` convenience method.
  */
@@ -892,6 +925,12 @@ export interface SessionConfig {
      * When provided, enables the ask_user tool allowing the agent to ask questions.
      */
     onUserInputRequest?: UserInputHandler;
+    /**
+     * Handler for elicitation requests from the agent.
+     * When provided, the server calls back to this client for form-based UI dialogs.
+     * Also enables the `elicitation` capability on the session.
+     */
+    onElicitationRequest?: ElicitationHandler;
     /**
      * Hook handlers for intercepting session lifecycle events.
      * When provided, enables hooks callback allowing custom logic at various points.
@@ -942,11 +981,16 @@ export interface SessionConfig {
      * but executes earlier in the lifecycle so no events are missed.
      */
     onEvent?: SessionEventHandler;
+    /**
+     * Supplies a handler for session filesystem operations. This takes effect
+     * only if {@link CopilotClientOptions.sessionFs} is configured.
+     */
+    createSessionFsHandler?: (session: CopilotSession) => SessionFsHandler;
 }
 /**
  * Configuration for resuming a session
  */
-export type ResumeSessionConfig = Pick<SessionConfig, "clientName" | "model" | "tools" | "commands" | "systemMessage" | "availableTools" | "excludedTools" | "provider" | "streaming" | "reasoningEffort" | "onPermissionRequest" | "onUserInputRequest" | "hooks" | "workingDirectory" | "configDir" | "mcpServers" | "customAgents" | "agent" | "skillDirectories" | "disabledSkills" | "infiniteSessions" | "onEvent"> & {
+export type ResumeSessionConfig = Pick<SessionConfig, "clientName" | "model" | "tools" | "commands" | "systemMessage" | "availableTools" | "excludedTools" | "provider" | "streaming" | "reasoningEffort" | "onPermissionRequest" | "onUserInputRequest" | "onElicitationRequest" | "hooks" | "workingDirectory" | "configDir" | "mcpServers" | "customAgents" | "agent" | "skillDirectories" | "disabledSkills" | "infiniteSessions" | "onEvent" | "createSessionFsHandler"> & {
     /**
      * When true, skips emitting the session.resume event.
      * Useful for reconnecting to a session without triggering resume-related side effects.
@@ -1072,6 +1116,24 @@ export interface SessionContext {
     /** Current git branch */
     branch?: string;
 }
+/**
+ * Configuration for a custom session filesystem provider.
+ */
+export interface SessionFsConfig {
+    /**
+     * Initial working directory for sessions (user's project directory).
+     */
+    initialCwd: string;
+    /**
+     * Path within each session's SessionFs where the runtime stores
+     * session-scoped files (events, workspace, checkpoints, etc.).
+     */
+    sessionStatePath: string;
+    /**
+     * Path conventions used by this filesystem provider.
+     */
+    conventions: "windows" | "posix";
+}
 /**
  * Filter options for listing sessions
  */
@@ -1211,4 +1273,3 @@ export interface ForegroundSessionInfo {
     /** Workspace path of the foreground session */
     workspacePath?: string;
 }
-export {};

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/github/copilot-sdk.git"
   },
-  "version": "0.2.1-preview.1",
+  "version": "0.2.1-preview.2",
   "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
   "main": "./dist/cjs/index.js",
   "types": "./dist/index.d.ts",
@@ -56,11 +56,12 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
-    "@github/copilot": "^1.0.12-0",
+    "@github/copilot": "^1.0.15-2",
     "vscode-jsonrpc": "^8.2.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@platformatic/vfs": "^0.3.0",
     "@types/node": "^25.2.0",
     "@typescript-eslint/eslint-plugin": "^8.54.0",
     "@typescript-eslint/parser": "^8.54.0",