@github/copilot-sdk 0.1.33-unstable.1 → 0.2.1-preview.0

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, Tool, ToolHandler, ToolInvocation, ToolResultObject, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.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";

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,8 @@
  */
 import type { MessageConnection } from "vscode-jsonrpc/node.js";
 import { createSessionRpc } from "./generated/rpc.js";
-import type { MessageOptions, PermissionHandler, PermissionRequestResult, SessionEvent, SessionEventHandler, SessionEventType, SessionHooks, Tool, ToolHandler, TypedSessionEventHandler, UserInputHandler, UserInputResponse } from "./types.js";
+import type { CommandHandler, 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, {
     type: "assistant.message";
@@ -37,23 +38,28 @@ export type AssistantMessageEvent = Extract<SessionEvent, {
 export declare class CopilotSession {
     readonly sessionId: string;
     private connection;
-    private readonly _workspacePath?;
+    private _workspacePath?;
     private eventHandlers;
     private typedEventHandlers;
     private toolHandlers;
+    private commandHandlers;
     private permissionHandler?;
     private userInputHandler?;
     private hooks?;
+    private transformCallbacks?;
     private _rpc;
+    private traceContextProvider?;
+    private _capabilities;
     /**
      * Creates a new CopilotSession instance.
      *
      * @param sessionId - The unique identifier for this session
      * @param connection - The JSON-RPC message connection to the Copilot CLI
      * @param workspacePath - Path to the session workspace directory (when infinite sessions enabled)
+     * @param traceContextProvider - Optional callback to get W3C Trace Context for outbound RPCs
      * @internal This constructor is internal. Use {@link CopilotClient.createSession} to create sessions.
      */
-    constructor(sessionId: string, connection: MessageConnection, _workspacePath?: string | undefined);
+    constructor(sessionId: string, connection: MessageConnection, _workspacePath?: string | undefined, traceContextProvider?: TraceContextProvider);
     /**
      * Typed session-scoped RPC methods.
      */
@@ -64,6 +70,24 @@ export declare class CopilotSession {
      * Undefined if infinite sessions are disabled.
      */
     get workspacePath(): string | undefined;
+    /**
+     * Host capabilities reported when the session was created or resumed.
+     * Use this to check feature support before calling capability-gated APIs.
+     */
+    get capabilities(): SessionCapabilities;
+    /**
+     * Interactive UI methods for showing dialogs to the user.
+     * Only available when the CLI host supports elicitation
+     * (`session.capabilities.ui?.elicitation === true`).
+     *
+     * @example
+     * ```typescript
+     * if (session.capabilities.ui?.elicitation) {
+     *   const ok = await session.ui.confirm("Deploy to production?");
+     * }
+     * ```
+     */
+    get ui(): SessionUiApi;
     /**
      * Sends a message to this session and waits for the response.
      *
@@ -178,6 +202,11 @@ export declare class CopilotSession {
      * @internal
      */
     private _executePermissionAndRespond;
+    /**
+     * Executes a command handler and sends the result back via RPC.
+     * @internal
+     */
+    private _executeCommandAndRespond;
     /**
      * Registers custom tool handlers for this session.
      *
@@ -196,6 +225,28 @@ export declare class CopilotSession {
      * @internal This method is for internal use by the SDK.
      */
     getToolHandler(name: string): ToolHandler | undefined;
+    /**
+     * Registers command handlers for this session.
+     *
+     * @param commands - An array of command definitions with handlers, or undefined to clear
+     * @internal This method is typically called internally when creating/resuming a session.
+     */
+    registerCommands(commands?: {
+        name: string;
+        handler: CommandHandler;
+    }[]): void;
+    /**
+     * Sets the host capabilities for this session.
+     *
+     * @param capabilities - The capabilities object from the create/resume response
+     * @internal This method is typically called internally when creating/resuming a session.
+     */
+    setCapabilities(capabilities?: SessionCapabilities): void;
+    private assertElicitation;
+    private _elicitation;
+    private _confirm;
+    private _select;
+    private _input;
     /**
      * Registers a handler for permission requests.
      *
@@ -226,6 +277,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.
@@ -332,13 +405,17 @@ export declare class CopilotSession {
      * The new model takes effect for the next message. Conversation history is preserved.
      *
      * @param model - Model ID to switch to
+     * @param options - Optional settings for the new model
      *
      * @example
      * ```typescript
      * await session.setModel("gpt-4.1");
+     * await session.setModel("claude-sonnet-4.6", { reasoningEffort: "high" });
      * ```
      */
-    setModel(model: string): Promise<void>;
+    setModel(model: string, options?: {
+        reasoningEffort?: ReasoningEffort;
+    }): Promise<void>;
     /**
      * Log a message to the session timeline.
      * The message appears in the session event stream and is visible to SDK consumers

package/dist/session.js

@@ -1,5 +1,7 @@
 import { ConnectionError, ResponseError } from "vscode-jsonrpc/node.js";
 import { createSessionRpc } from "./generated/rpc.js";
+import { getTraceContext } from "./telemetry.js";
+const NO_RESULT_PERMISSION_V2_ERROR = "Permission handlers cannot return 'no-result' when connected to a protocol v2 server.";
 class CopilotSession {
   /**
    * Creates a new CopilotSession instance.
@@ -7,20 +9,26 @@ class CopilotSession {
    * @param sessionId - The unique identifier for this session
    * @param connection - The JSON-RPC message connection to the Copilot CLI
    * @param workspacePath - Path to the session workspace directory (when infinite sessions enabled)
+   * @param traceContextProvider - Optional callback to get W3C Trace Context for outbound RPCs
    * @internal This constructor is internal. Use {@link CopilotClient.createSession} to create sessions.
    */
-  constructor(sessionId, connection, _workspacePath) {
+  constructor(sessionId, connection, _workspacePath, traceContextProvider) {
     this.sessionId = sessionId;
     this.connection = connection;
     this._workspacePath = _workspacePath;
+    this.traceContextProvider = traceContextProvider;
   }
   eventHandlers = /* @__PURE__ */ new Set();
   typedEventHandlers = /* @__PURE__ */ new Map();
   toolHandlers = /* @__PURE__ */ new Map();
+  commandHandlers = /* @__PURE__ */ new Map();
   permissionHandler;
   userInputHandler;
   hooks;
+  transformCallbacks;
   _rpc = null;
+  traceContextProvider;
+  _capabilities = {};
   /**
    * Typed session-scoped RPC methods.
    */
@@ -38,6 +46,33 @@ class CopilotSession {
   get workspacePath() {
     return this._workspacePath;
   }
+  /**
+   * Host capabilities reported when the session was created or resumed.
+   * Use this to check feature support before calling capability-gated APIs.
+   */
+  get capabilities() {
+    return this._capabilities;
+  }
+  /**
+   * Interactive UI methods for showing dialogs to the user.
+   * Only available when the CLI host supports elicitation
+   * (`session.capabilities.ui?.elicitation === true`).
+   *
+   * @example
+   * ```typescript
+   * if (session.capabilities.ui?.elicitation) {
+   *   const ok = await session.ui.confirm("Deploy to production?");
+   * }
+   * ```
+   */
+  get ui() {
+    return {
+      elicitation: (params) => this._elicitation(params),
+      confirm: (message) => this._confirm(message),
+      select: (message, options) => this._select(message, options),
+      input: (message, options) => this._input(message, options)
+    };
+  }
   /**
    * Sends a message to this session and waits for the response.
    *
@@ -58,6 +93,7 @@ class CopilotSession {
    */
   async send(options) {
     const response = await this.connection.sendRequest("session.send", {
+      ...await getTraceContext(this.traceContextProvider),
       sessionId: this.sessionId,
       prompt: options.prompt,
       attachments: options.attachments,
@@ -187,28 +223,43 @@ class CopilotSession {
       const { requestId, toolName } = event.data;
       const args = event.data.arguments;
       const toolCallId = event.data.toolCallId;
+      const traceparent = event.data.traceparent;
+      const tracestate = event.data.tracestate;
       const handler = this.toolHandlers.get(toolName);
       if (handler) {
-        void this._executeToolAndRespond(requestId, toolName, toolCallId, args, handler);
+        void this._executeToolAndRespond(
+          requestId,
+          toolName,
+          toolCallId,
+          args,
+          handler,
+          traceparent,
+          tracestate
+        );
       }
     } else if (event.type === "permission.requested") {
       const { requestId, permissionRequest } = event.data;
       if (this.permissionHandler) {
         void this._executePermissionAndRespond(requestId, permissionRequest);
       }
+    } else if (event.type === "command.execute") {
+      const { requestId, commandName, command, args } = event.data;
+      void this._executeCommandAndRespond(requestId, commandName, command, args);
     }
   }
   /**
    * Executes a tool handler and sends the result back via RPC.
    * @internal
    */
-  async _executeToolAndRespond(requestId, toolName, toolCallId, args, handler) {
+  async _executeToolAndRespond(requestId, toolName, toolCallId, args, handler, traceparent, tracestate) {
     try {
       const rawResult = await handler(args, {
         sessionId: this.sessionId,
         toolCallId,
         toolName,
-        arguments: args
+        arguments: args,
+        traceparent,
+        tracestate
       });
       let result;
       if (rawResult == null) {
@@ -239,6 +290,9 @@ class CopilotSession {
       const result = await this.permissionHandler(permissionRequest, {
         sessionId: this.sessionId
       });
+      if (result.kind === "no-result") {
+        return;
+      }
       await this.rpc.permissions.handlePendingPermissionRequest({ requestId, result });
     } catch (_error) {
       try {
@@ -255,6 +309,39 @@ class CopilotSession {
       }
     }
   }
+  /**
+   * Executes a command handler and sends the result back via RPC.
+   * @internal
+   */
+  async _executeCommandAndRespond(requestId, commandName, command, args) {
+    const handler = this.commandHandlers.get(commandName);
+    if (!handler) {
+      try {
+        await this.rpc.commands.handlePendingCommand({
+          requestId,
+          error: `Unknown command: ${commandName}`
+        });
+      } catch (rpcError) {
+        if (!(rpcError instanceof ConnectionError || rpcError instanceof ResponseError)) {
+          throw rpcError;
+        }
+      }
+      return;
+    }
+    try {
+      await handler({ sessionId: this.sessionId, command, commandName, args });
+      await this.rpc.commands.handlePendingCommand({ requestId });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      try {
+        await this.rpc.commands.handlePendingCommand({ requestId, error: message });
+      } catch (rpcError) {
+        if (!(rpcError instanceof ConnectionError || rpcError instanceof ResponseError)) {
+          throw rpcError;
+        }
+      }
+    }
+  }
   /**
    * Registers custom tool handlers for this session.
    *
@@ -283,6 +370,99 @@ class CopilotSession {
   getToolHandler(name) {
     return this.toolHandlers.get(name);
   }
+  /**
+   * Registers command handlers for this session.
+   *
+   * @param commands - An array of command definitions with handlers, or undefined to clear
+   * @internal This method is typically called internally when creating/resuming a session.
+   */
+  registerCommands(commands) {
+    this.commandHandlers.clear();
+    if (!commands) {
+      return;
+    }
+    for (const cmd of commands) {
+      this.commandHandlers.set(cmd.name, cmd.handler);
+    }
+  }
+  /**
+   * Sets the host capabilities for this session.
+   *
+   * @param capabilities - The capabilities object from the create/resume response
+   * @internal This method is typically called internally when creating/resuming a session.
+   */
+  setCapabilities(capabilities) {
+    this._capabilities = capabilities ?? {};
+  }
+  assertElicitation() {
+    if (!this._capabilities.ui?.elicitation) {
+      throw new Error(
+        "Elicitation is not supported by the host. Check session.capabilities.ui?.elicitation before calling UI methods."
+      );
+    }
+  }
+  async _elicitation(params) {
+    this.assertElicitation();
+    return this.rpc.ui.elicitation({
+      message: params.message,
+      requestedSchema: params.requestedSchema
+    });
+  }
+  async _confirm(message) {
+    this.assertElicitation();
+    const result = await this.rpc.ui.elicitation({
+      message,
+      requestedSchema: {
+        type: "object",
+        properties: {
+          confirmed: { type: "boolean", default: true }
+        },
+        required: ["confirmed"]
+      }
+    });
+    return result.action === "accept" && result.content?.confirmed === true;
+  }
+  async _select(message, options) {
+    this.assertElicitation();
+    const result = await this.rpc.ui.elicitation({
+      message,
+      requestedSchema: {
+        type: "object",
+        properties: {
+          selection: { type: "string", enum: options }
+        },
+        required: ["selection"]
+      }
+    });
+    if (result.action === "accept" && result.content?.selection != null) {
+      return result.content.selection;
+    }
+    return null;
+  }
+  async _input(message, options) {
+    this.assertElicitation();
+    const field = { type: "string" };
+    if (options?.title) field.title = options.title;
+    if (options?.description) field.description = options.description;
+    if (options?.minLength != null) field.minLength = options.minLength;
+    if (options?.maxLength != null) field.maxLength = options.maxLength;
+    if (options?.format) field.format = options.format;
+    if (options?.default != null) field.default = options.default;
+    const result = await this.rpc.ui.elicitation({
+      message,
+      requestedSchema: {
+        type: "object",
+        properties: {
+          value: field
+        },
+        required: ["value"]
+      }
+    });
+    if (result.action === "accept" && result.content?.value != null) {
+      return result.content.value;
+    }
+    return null;
+  }
   /**
    * Registers a handler for permission requests.
    *
@@ -319,6 +499,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.
@@ -335,8 +549,14 @@ class CopilotSession {
       const result = await this.permissionHandler(request, {
         sessionId: this.sessionId
       });
+      if (result.kind === "no-result") {
+        throw new Error(NO_RESULT_PERMISSION_V2_ERROR);
+      }
       return result;
-    } catch (_error) {
+    } catch (error) {
+      if (error instanceof Error && error.message === NO_RESULT_PERMISSION_V2_ERROR) {
+        throw error;
+      }
       return { kind: "denied-no-approval-rule-and-could-not-request-from-user" };
     }
   }
@@ -492,14 +712,16 @@ class CopilotSession {
    * The new model takes effect for the next message. Conversation history is preserved.
    *
    * @param model - Model ID to switch to
+   * @param options - Optional settings for the new model
    *
    * @example
    * ```typescript
    * await session.setModel("gpt-4.1");
+   * await session.setModel("claude-sonnet-4.6", { reasoningEffort: "high" });
    * ```
    */
-  async setModel(model) {
-    await this.rpc.model.switchTo({ modelId: model });
+  async setModel(model, options) {
+    await this.rpc.model.switchTo({ modelId: model, ...options });
   }
   /**
    * Log a message to the session timeline.
@@ -522,5 +744,6 @@ class CopilotSession {
   }
 }
 export {
-  CopilotSession
+  CopilotSession,
+  NO_RESULT_PERMISSION_V2_ERROR
 };

package/dist/telemetry.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Trace-context helpers.
+ *
+ * The SDK does not depend on any OpenTelemetry packages.  Instead, users
+ * provide an {@link TraceContextProvider} callback via client options.
+ *
+ * @module telemetry
+ */
+import type { TraceContext, TraceContextProvider } from "./types.js";
+/**
+ * Calls the user-provided {@link TraceContextProvider} to obtain the current
+ * W3C Trace Context.  Returns `{}` when no provider is configured.
+ */
+export declare function getTraceContext(provider?: TraceContextProvider): Promise<TraceContext>;

package/dist/telemetry.js

@@ -0,0 +1,11 @@
+async function getTraceContext(provider) {
+  if (!provider) return {};
+  try {
+    return await provider() ?? {};
+  } catch {
+    return {};
+  }
+}
+export {
+  getTraceContext
+};