@github/copilot-sdk 0.1.33-preview.3 → 0.1.33-preview.4

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

@@ -208,6 +208,10 @@ export type SessionEvent = {
          * GitHub request tracing ID (x-github-request-id header) for correlating with server-side logs
          */
         providerCallId?: string;
+        /**
+         * Optional URL associated with this error that the user can open in a browser
+         */
+        url?: string;
     };
 } | {
     /**
@@ -318,6 +322,10 @@ export type SessionEvent = {
          * Human-readable informational message for display in the timeline
          */
         message: string;
+        /**
+         * Optional URL associated with this message that the user can open in a browser
+         */
+        url?: string;
     };
 } | {
     /**
@@ -349,6 +357,10 @@ export type SessionEvent = {
          * Human-readable warning message for display in the timeline
          */
         message: string;
+        /**
+         * Optional URL associated with this warning that the user can open in a browser
+         */
+        url?: string;
     };
 } | {
     /**
@@ -725,6 +737,22 @@ export type SessionEvent = {
          * Model that was selected at the time of shutdown
          */
         currentModel?: string;
+        /**
+         * Total tokens in context window at shutdown
+         */
+        currentTokens?: number;
+        /**
+         * System message token count at shutdown
+         */
+        systemTokens?: number;
+        /**
+         * Non-system message token count at shutdown
+         */
+        conversationTokens?: number;
+        /**
+         * Tool definitions token count at shutdown
+         */
+        toolDefinitionsTokens?: number;
     };
 } | {
     /**
@@ -808,6 +836,22 @@ export type SessionEvent = {
          * Current number of messages in the conversation
          */
         messagesLength: number;
+        /**
+         * Token count from system message(s)
+         */
+        systemTokens?: number;
+        /**
+         * Token count from non-system messages (user, assistant, tool)
+         */
+        conversationTokens?: number;
+        /**
+         * Token count from tool definitions
+         */
+        toolDefinitionsTokens?: number;
+        /**
+         * Whether this is the first usage_info event emitted in this session
+         */
+        isInitial?: boolean;
     };
 } | {
     /**
@@ -828,9 +872,22 @@ export type SessionEvent = {
     ephemeral?: boolean;
     type: "session.compaction_start";
     /**
-     * Empty payload; the event signals that LLM-powered conversation compaction has begun
+     * Context window breakdown at the start of LLM-powered conversation compaction
      */
-    data: {};
+    data: {
+        /**
+         * Token count from system message(s) at compaction start
+         */
+        systemTokens?: number;
+        /**
+         * Token count from non-system messages (user, assistant, tool) at compaction start
+         */
+        conversationTokens?: number;
+        /**
+         * Token count from tool definitions at compaction start
+         */
+        toolDefinitionsTokens?: number;
+    };
 } | {
     /**
      * Unique event identifier (UUID v4), generated when the event is emitted
@@ -914,6 +971,18 @@ export type SessionEvent = {
          * GitHub request tracing ID (x-github-request-id header) for the compaction LLM call
          */
         requestId?: string;
+        /**
+         * Token count from system message(s) after compaction
+         */
+        systemTokens?: number;
+        /**
+         * Token count from non-system messages (user, assistant, tool) after compaction
+         */
+        conversationTokens?: number;
+        /**
+         * Token count from tool definitions after compaction
+         */
+        toolDefinitionsTokens?: number;
     };
 } | {
     /**
@@ -934,13 +1003,17 @@ export type SessionEvent = {
     ephemeral?: boolean;
     type: "session.task_complete";
     /**
-     * Task completion notification with optional summary from the agent
+     * Task completion notification with summary from the agent
      */
     data: {
         /**
-         * Optional summary of the completed task, provided by the agent
+         * Summary of the completed task, provided by the agent
          */
         summary?: string;
+        /**
+         * Whether the tool call succeeded. False when validation failed (e.g., invalid arguments)
+         */
+        success?: boolean;
     };
 } | {
     /**
@@ -960,9 +1033,6 @@ export type SessionEvent = {
      */
     ephemeral?: boolean;
     type: "user.message";
-    /**
-     * User message content with optional attachments, source information, and interaction metadata
-     */
     data: {
         /**
          * The user's message text as displayed in the timeline
@@ -1106,9 +1176,9 @@ export type SessionEvent = {
             displayName?: string;
         })[];
         /**
-         * Origin of this message, used for timeline filtering and telemetry (e.g., "user", "autopilot", "skill", or "command")
+         * Origin of this message, used for timeline filtering (e.g., "skill-pdf" for skill-injected messages that should be hidden from the user)
          */
-        source?: "user" | "autopilot" | "skill" | "system" | "command" | "immediate-prompt" | "jit-instruction" | "snippy-blocking" | "thinking-exhausted-continuation" | "other";
+        source?: string;
         /**
          * The agent mode that was active when this message was sent
          */
@@ -2359,6 +2429,20 @@ export type SessionEvent = {
              * The full prompt given to the background agent
              */
             prompt?: string;
+        } | {
+            type: "agent_idle";
+            /**
+             * Unique identifier of the background agent
+             */
+            agentId: string;
+            /**
+             * Type of the agent (e.g., explore, task, general-purpose)
+             */
+            agentType: string;
+            /**
+             * Human-readable description of the agent task
+             */
+            description?: string;
         } | {
             type: "shell_completed";
             /**
@@ -2693,6 +2777,10 @@ export type SessionEvent = {
          * Whether the user can provide a free-form text response in addition to predefined choices
          */
         allowFreeform?: boolean;
+        /**
+         * The LLM-assigned tool call ID that triggered this request; used by remote UIs to correlate responses
+         */
+        toolCallId?: string;
     };
 } | {
     /**
@@ -2734,25 +2822,33 @@ export type SessionEvent = {
     ephemeral: true;
     type: "elicitation.requested";
     /**
-     * Structured form elicitation request with JSON schema definition for form fields
+     * Elicitation request; may be form-based (structured input) or URL-based (browser redirect)
      */
     data: {
         /**
          * Unique identifier for this elicitation request; used to respond via session.respondToElicitation()
          */
         requestId: string;
+        /**
+         * Tool call ID from the LLM completion; used to correlate with CompletionChunk.toolCall.id for remote UIs
+         */
+        toolCallId?: string;
+        /**
+         * The source that initiated the request (MCP server name, or absent for agent-initiated)
+         */
+        elicitationSource?: string;
         /**
          * Message describing what information is needed from the user
          */
         message: string;
         /**
-         * Elicitation mode; currently only "form" is supported. Defaults to "form" when absent.
+         * Elicitation mode; "form" for structured input, "url" for browser-based. Defaults to "form" when absent.
          */
-        mode?: "form";
+        mode?: "form" | "url";
         /**
-         * JSON Schema describing the form fields to present to the user
+         * JSON Schema describing the form fields to present to the user (form mode only)
          */
-        requestedSchema: {
+        requestedSchema?: {
             /**
              * Schema type indicator (always 'object')
              */
@@ -2768,6 +2864,10 @@ export type SessionEvent = {
              */
             required?: string[];
         };
+        /**
+         * URL to open in the user's browser (url mode only)
+         */
+        url?: string;
         [k: string]: unknown;
     };
 } | {
@@ -2794,6 +2894,75 @@ 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: "mcp.oauth_required";
+    /**
+     * OAuth authentication request for an MCP server
+     */
+    data: {
+        /**
+         * Unique identifier for this OAuth request; used to respond via session.respondToMcpOAuth()
+         */
+        requestId: string;
+        /**
+         * Display name of the MCP server that requires OAuth
+         */
+        serverName: string;
+        /**
+         * URL of the MCP server that requires OAuth
+         */
+        serverUrl: string;
+        /**
+         * Static OAuth client configuration, if the server specifies one
+         */
+        staticClientConfig?: {
+            /**
+             * OAuth client ID for the server
+             */
+            clientId: string;
+            /**
+             * Whether this is a public OAuth client
+             */
+            publicClient?: 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;
+    ephemeral: true;
+    type: "mcp.oauth_completed";
+    /**
+     * MCP OAuth request completion notification
+     */
+    data: {
+        /**
+         * Request ID of the resolved OAuth request
+         */
+        requestId: string;
+    };
 } | {
     /**
      * Unique event identifier (UUID v4), generated when the event is emitted
@@ -2896,6 +3065,42 @@ export type SessionEvent = {
          */
         command: 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: "command.execute";
+    /**
+     * Registered command dispatch request routed to the owning client
+     */
+    data: {
+        /**
+         * Unique identifier; used to respond via session.commands.handlePendingCommand()
+         */
+        requestId: string;
+        /**
+         * The full command text (e.g., /deploy production)
+         */
+        command: string;
+        /**
+         * Command name without leading /
+         */
+        commandName: string;
+        /**
+         * Raw argument string after the command name
+         */
+        args: string;
+    };
 } | {
     /**
      * Unique event identifier (UUID v4), generated when the event is emitted
@@ -2920,6 +3125,33 @@ 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: "commands.changed";
+    /**
+     * SDK command registration change notification
+     */
+    data: {
+        /**
+         * Current list of registered SDK commands
+         */
+        commands: {
+            name: string;
+            description?: string;
+        }[];
+    };
 } | {
     /**
      * Unique event identifier (UUID v4), generated when the event is emitted
@@ -3018,4 +3250,151 @@ export type SessionEvent = {
     ephemeral: true;
     type: "session.background_tasks_changed";
     data: {};
+} | {
+    /**
+     * 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: "session.skills_loaded";
+    data: {
+        /**
+         * Array of resolved skill metadata
+         */
+        skills: {
+            /**
+             * Unique identifier for the skill
+             */
+            name: string;
+            /**
+             * Description of what the skill does
+             */
+            description: string;
+            /**
+             * Source location type of the skill (e.g., project, personal, plugin)
+             */
+            source: string;
+            /**
+             * Whether the skill can be invoked by the user as a slash command
+             */
+            userInvocable: boolean;
+            /**
+             * Whether the skill is currently enabled
+             */
+            enabled: boolean;
+            /**
+             * Absolute path to the skill file, if available
+             */
+            path?: 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: "session.mcp_servers_loaded";
+    data: {
+        /**
+         * Array of MCP server status summaries
+         */
+        servers: {
+            /**
+             * Server name (config key)
+             */
+            name: string;
+            /**
+             * Connection status: connected, failed, pending, disabled, or not_configured
+             */
+            status: "connected" | "failed" | "pending" | "disabled" | "not_configured";
+            /**
+             * Configuration source: user, workspace, plugin, or builtin
+             */
+            source?: string;
+            /**
+             * Error message if the server failed to connect
+             */
+            error?: 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: "session.mcp_server_status_changed";
+    data: {
+        /**
+         * Name of the MCP server whose status changed
+         */
+        serverName: string;
+        /**
+         * New connection status: connected, failed, pending, disabled, or not_configured
+         */
+        status: "connected" | "failed" | "pending" | "disabled" | "not_configured";
+    };
+} | {
+    /**
+     * 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: "session.extensions_loaded";
+    data: {
+        /**
+         * Array of discovered extensions and their status
+         */
+        extensions: {
+            /**
+             * Source-qualified extension ID (e.g., 'project:my-ext', 'user:auth-helper')
+             */
+            id: string;
+            /**
+             * Extension name (directory name)
+             */
+            name: string;
+            /**
+             * Discovery source
+             */
+            source: "project" | "user";
+            /**
+             * Current status: running, disabled, failed, or starting
+             */
+            status: "running" | "disabled" | "failed" | "starting";
+        }[];
+    };
 };

package/dist/index.d.ts

@@ -5,5 +5,5 @@
  */
 export { CopilotClient } from "./client.js";
 export { CopilotSession, type AssistantMessageEvent } from "./session.js";
-export { defineTool, approveAll } from "./types.js";
-export type { ConnectionState, CopilotClientOptions, CustomAgentConfig, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, InfiniteSessionConfig, MCPLocalServerConfig, MCPRemoteServerConfig, MCPServerConfig, MessageOptions, ModelBilling, ModelCapabilities, ModelInfo, ModelPolicy, PermissionHandler, PermissionRequest, PermissionRequestResult, ResumeSessionConfig, SessionConfig, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventType, SessionLifecycleHandler, SessionContext, SessionListFilter, SessionMetadata, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageReplaceConfig, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, ToolResultObject, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
+export { defineTool, approveAll, SYSTEM_PROMPT_SECTIONS } from "./types.js";
+export type { ConnectionState, CopilotClientOptions, CustomAgentConfig, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, InfiniteSessionConfig, MCPLocalServerConfig, MCPRemoteServerConfig, MCPServerConfig, MessageOptions, ModelBilling, ModelCapabilities, ModelInfo, ModelPolicy, PermissionHandler, PermissionRequest, PermissionRequestResult, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionConfig, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventType, SessionLifecycleHandler, SessionContext, SessionListFilter, SessionMetadata, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemPromptSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, ToolResultObject, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";

package/dist/index.js

@@ -1,9 +1,10 @@
 import { CopilotClient } from "./client.js";
 import { CopilotSession } from "./session.js";
-import { defineTool, approveAll } from "./types.js";
+import { defineTool, approveAll, SYSTEM_PROMPT_SECTIONS } from "./types.js";
 export {
   CopilotClient,
   CopilotSession,
+  SYSTEM_PROMPT_SECTIONS,
   approveAll,
   defineTool
 };

package/dist/session.d.ts

@@ -4,7 +4,7 @@
  */
 import type { MessageConnection } from "vscode-jsonrpc/node.js";
 import { createSessionRpc } from "./generated/rpc.js";
-import type { MessageOptions, PermissionHandler, PermissionRequestResult, ReasoningEffort, SessionEvent, SessionEventHandler, SessionEventType, SessionHooks, Tool, ToolHandler, TraceContextProvider, TypedSessionEventHandler, UserInputHandler, UserInputResponse } from "./types.js";
+import type { MessageOptions, PermissionHandler, PermissionRequestResult, ReasoningEffort, SectionTransformFn, SessionEvent, SessionEventHandler, SessionEventType, SessionHooks, 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,6 +45,7 @@ export declare class CopilotSession {
     private permissionHandler?;
     private userInputHandler?;
     private hooks?;
+    private transformCallbacks?;
     private _rpc;
     private traceContextProvider?;
     /**
@@ -229,6 +230,28 @@ export declare class CopilotSession {
      * @internal This method is typically called internally when creating a session.
      */
     registerHooks(hooks?: SessionHooks): void;
+    /**
+     * Registers transform callbacks for system message sections.
+     *
+     * @param callbacks - Map of section ID to transform callback, or undefined to clear
+     * @internal This method is typically called internally when creating a session.
+     */
+    registerTransformCallbacks(callbacks?: Map<string, SectionTransformFn>): void;
+    /**
+     * Handles a systemMessage.transform request from the runtime.
+     * Dispatches each section to its registered transform callback.
+     *
+     * @param sections - Map of section IDs to their current rendered content
+     * @returns A promise that resolves with the transformed sections
+     * @internal This method is for internal use by the SDK.
+     */
+    _handleSystemMessageTransform(sections: Record<string, {
+        content: string;
+    }>): Promise<{
+        sections: Record<string, {
+            content: string;
+        }>;
+    }>;
     /**
      * Handles a permission request in the v2 protocol format (synchronous RPC).
      * Used as a back-compat adapter when connected to a v2 server.

package/dist/session.js

@@ -24,6 +24,7 @@ class CopilotSession {
   permissionHandler;
   userInputHandler;
   hooks;
+  transformCallbacks;
   _rpc = null;
   traceContextProvider;
   /**
@@ -340,6 +341,40 @@ class CopilotSession {
   registerHooks(hooks) {
     this.hooks = hooks;
   }
+  /**
+   * Registers transform callbacks for system message sections.
+   *
+   * @param callbacks - Map of section ID to transform callback, or undefined to clear
+   * @internal This method is typically called internally when creating a session.
+   */
+  registerTransformCallbacks(callbacks) {
+    this.transformCallbacks = callbacks;
+  }
+  /**
+   * Handles a systemMessage.transform request from the runtime.
+   * Dispatches each section to its registered transform callback.
+   *
+   * @param sections - Map of section IDs to their current rendered content
+   * @returns A promise that resolves with the transformed sections
+   * @internal This method is for internal use by the SDK.
+   */
+  async _handleSystemMessageTransform(sections) {
+    const result = {};
+    for (const [sectionId, { content }] of Object.entries(sections)) {
+      const callback = this.transformCallbacks?.get(sectionId);
+      if (callback) {
+        try {
+          const transformed = await callback(content);
+          result[sectionId] = { content: transformed };
+        } catch (_error) {
+          result[sectionId] = { content };
+        }
+      } else {
+        result[sectionId] = { content };
+      }
+    }
+    return { sections: result };
+  }
   /**
    * Handles a permission request in the v2 protocol format (synchronous RPC).
    * Used as a back-compat adapter when connected to a v2 server.