@github/copilot-sdk 0.1.10-preview.0 → 0.1.10

package/dist/{generated → nodejs/src/generated}/session-events.d.ts

@@ -3,7 +3,7 @@
  *
  * Generated from: @github/copilot/session-events.schema.json
  * Generated by: scripts/generate-session-types.ts
- * Generated at: 2026-01-08T23:59:19.905Z
+ * Generated at: 2026-01-13T00:08:20.716Z
  *
  * To update these types:
  * 1. Update the schema in copilot-agent-runtime
@@ -121,6 +121,13 @@ export type SessionEvent = {
         }[];
         source?: string;
     };
+} | {
+    id: string;
+    timestamp: string;
+    parentId: string | null;
+    ephemeral: true;
+    type: "pending_messages.modified";
+    data: {};
 } | {
     id: string;
     timestamp: string;

package/dist/nodejs/src/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copilot SDK - TypeScript/Node.js Client
+ *
+ * JSON-RPC based SDK for programmatic control of GitHub Copilot CLI
+ */
+export { CopilotClient } from "./client.js";
+export { CopilotSession } from "./session.js";
+export { defineTool } from "./types.js";
+export type { ConnectionState, CopilotClientOptions, CustomAgentConfig, MCPLocalServerConfig, MCPRemoteServerConfig, MCPServerConfig, MessageOptions, PermissionHandler, PermissionRequest, PermissionRequestResult, ResumeSessionConfig, SessionConfig, SessionEvent, SessionEventHandler, SessionMetadata, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageReplaceConfig, Tool, ToolHandler, ToolInvocation, ToolResultObject, ZodSchema, } from "./types.js";

package/dist/nodejs/src/sdkProtocolVersion.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Gets the SDK protocol version from sdk-protocol-version.json.
+ * @returns The protocol version number
+ */
+export declare function getSdkProtocolVersion(): number;

package/dist/nodejs/src/session.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Copilot Session - represents a single conversation session with the Copilot CLI.
+ * @module session
+ */
+import type { MessageConnection } from "vscode-jsonrpc/node";
+import type { MessageOptions, PermissionHandler, PermissionRequestResult, SessionEvent, SessionEventHandler, Tool, ToolHandler } from "./types.js";
+/**
+ * Represents a single conversation session with the Copilot CLI.
+ *
+ * A session maintains conversation state, handles events, and manages tool execution.
+ * Sessions are created via {@link CopilotClient.createSession} or resumed via
+ * {@link CopilotClient.resumeSession}.
+ *
+ * @example
+ * ```typescript
+ * const session = await client.createSession({ model: "gpt-4" });
+ *
+ * // Subscribe to events
+ * const unsubscribe = session.on((event) => {
+ *   if (event.type === "assistant.message") {
+ *     console.log(event.data.content);
+ *   }
+ * });
+ *
+ * // Send a message
+ * await session.send({ prompt: "Hello, world!" });
+ *
+ * // Clean up
+ * unsubscribe();
+ * await session.destroy();
+ * ```
+ */
+export declare class CopilotSession {
+    readonly sessionId: string;
+    private connection;
+    private eventHandlers;
+    private toolHandlers;
+    private permissionHandler?;
+    /**
+     * Creates a new CopilotSession instance.
+     *
+     * @param sessionId - The unique identifier for this session
+     * @param connection - The JSON-RPC message connection to the Copilot CLI
+     * @internal This constructor is internal. Use {@link CopilotClient.createSession} to create sessions.
+     */
+    constructor(sessionId: string, connection: MessageConnection);
+    /**
+     * Sends a message to this session and waits for the response.
+     *
+     * The message is processed asynchronously. Subscribe to events via {@link on}
+     * to receive streaming responses and other session events.
+     *
+     * @param options - The message options including the prompt and optional attachments
+     * @returns A promise that resolves with the message ID of the response
+     * @throws Error if the session has been destroyed or the connection fails
+     *
+     * @example
+     * ```typescript
+     * const messageId = await session.send({
+     *   prompt: "Explain this code",
+     *   attachments: [{ type: "file", path: "./src/index.ts" }]
+     * });
+     * ```
+     */
+    send(options: MessageOptions): Promise<string>;
+    /**
+     * Subscribes to events from this session.
+     *
+     * Events include assistant messages, tool executions, errors, and session state changes.
+     * Multiple handlers can be registered and will all receive events.
+     *
+     * @param handler - A callback function that receives session events
+     * @returns A function that, when called, unsubscribes the handler
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = session.on((event) => {
+     *   switch (event.type) {
+     *     case "assistant.message":
+     *       console.log("Assistant:", event.data.content);
+     *       break;
+     *     case "session.error":
+     *       console.error("Error:", event.data.message);
+     *       break;
+     *   }
+     * });
+     *
+     * // Later, to stop receiving events:
+     * unsubscribe();
+     * ```
+     */
+    on(handler: SessionEventHandler): () => void;
+    /**
+     * Dispatches an event to all registered handlers.
+     *
+     * @param event - The session event to dispatch
+     * @internal This method is for internal use by the SDK.
+     */
+    _dispatchEvent(event: SessionEvent): void;
+    /**
+     * Registers custom tool handlers for this session.
+     *
+     * Tools allow the assistant to execute custom functions. When the assistant
+     * invokes a tool, the corresponding handler is called with the tool arguments.
+     *
+     * @param tools - An array of tool definitions with their handlers, or undefined to clear all tools
+     * @internal This method is typically called internally when creating a session with tools.
+     */
+    registerTools(tools?: Tool[]): void;
+    /**
+     * Retrieves a registered tool handler by name.
+     *
+     * @param name - The name of the tool to retrieve
+     * @returns The tool handler if found, or undefined
+     * @internal This method is for internal use by the SDK.
+     */
+    getToolHandler(name: string): ToolHandler | undefined;
+    /**
+     * Registers a handler for permission requests.
+     *
+     * When the assistant needs permission to perform certain actions (e.g., file operations),
+     * this handler is called to approve or deny the request.
+     *
+     * @param handler - The permission handler function, or undefined to remove the handler
+     * @internal This method is typically called internally when creating a session.
+     */
+    registerPermissionHandler(handler?: PermissionHandler): void;
+    /**
+     * Handles a permission request from the Copilot CLI.
+     *
+     * @param request - The permission request data from the CLI
+     * @returns A promise that resolves with the permission decision
+     * @internal This method is for internal use by the SDK.
+     */
+    _handlePermissionRequest(request: unknown): Promise<PermissionRequestResult>;
+    /**
+     * Retrieves all events and messages from this session's history.
+     *
+     * This returns the complete conversation history including user messages,
+     * assistant responses, tool executions, and other session events.
+     *
+     * @returns A promise that resolves with an array of all session events
+     * @throws Error if the session has been destroyed or the connection fails
+     *
+     * @example
+     * ```typescript
+     * const events = await session.getMessages();
+     * for (const event of events) {
+     *   if (event.type === "assistant.message") {
+     *     console.log("Assistant:", event.data.content);
+     *   }
+     * }
+     * ```
+     */
+    getMessages(): Promise<SessionEvent[]>;
+    /**
+     * Destroys this session and releases all associated resources.
+     *
+     * After calling this method, the session can no longer be used. All event
+     * handlers and tool handlers are cleared. To continue the conversation,
+     * use {@link CopilotClient.resumeSession} with the session ID.
+     *
+     * @returns A promise that resolves when the session is destroyed
+     * @throws Error if the connection fails
+     *
+     * @example
+     * ```typescript
+     * // Clean up when done
+     * await session.destroy();
+     * ```
+     */
+    destroy(): Promise<void>;
+    /**
+     * Aborts the currently processing message in this session.
+     *
+     * Use this to cancel a long-running request. The session remains valid
+     * and can continue to be used for new messages.
+     *
+     * @returns A promise that resolves when the abort request is acknowledged
+     * @throws Error if the session has been destroyed or the connection fails
+     *
+     * @example
+     * ```typescript
+     * // Start a long-running request
+     * const messagePromise = session.send({ prompt: "Write a very long story..." });
+     *
+     * // Abort after 5 seconds
+     * setTimeout(async () => {
+     *   await session.abort();
+     * }, 5000);
+     * ```
+     */
+    abort(): Promise<void>;
+}

package/dist/{types.d.ts → nodejs/src/types.d.ts}

@@ -151,6 +151,105 @@ export interface SystemMessageReplaceConfig {
  * - Replace mode: Full control, caller provides entire system message
  */
 export type SystemMessageConfig = SystemMessageAppendConfig | SystemMessageReplaceConfig;
+/**
+ * Permission request types from the server
+ */
+export interface PermissionRequest {
+    kind: "shell" | "write" | "mcp" | "read" | "url";
+    toolCallId?: string;
+    [key: string]: unknown;
+}
+export interface PermissionRequestResult {
+    kind: "approved" | "denied-by-rules" | "denied-no-approval-rule-and-could-not-request-from-user" | "denied-interactively-by-user";
+    rules?: unknown[];
+}
+export type PermissionHandler = (request: PermissionRequest, invocation: {
+    sessionId: string;
+}) => Promise<PermissionRequestResult> | PermissionRequestResult;
+/**
+ * Base interface for MCP server configuration.
+ */
+interface MCPServerConfigBase {
+    /**
+     * List of tools to include from this server. [] means none. "*" means all.
+     */
+    tools: string[];
+    /**
+     * Indicates "remote" or "local" server type.
+     * If not specified, defaults to "local".
+     */
+    type?: string;
+    /**
+     * Optional timeout in milliseconds for tool calls to this server.
+     */
+    timeout?: number;
+}
+/**
+ * Configuration for a local/stdio MCP server.
+ */
+export interface MCPLocalServerConfig extends MCPServerConfigBase {
+    type?: "local" | "stdio";
+    command: string;
+    args: string[];
+    /**
+     * Environment variables to pass to the server.
+     */
+    env?: Record<string, string>;
+    cwd?: string;
+}
+/**
+ * Configuration for a remote MCP server (HTTP or SSE).
+ */
+export interface MCPRemoteServerConfig extends MCPServerConfigBase {
+    type: "http" | "sse";
+    /**
+     * URL of the remote server.
+     */
+    url: string;
+    /**
+     * Optional HTTP headers to include in requests.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Union type for MCP server configurations.
+ */
+export type MCPServerConfig = MCPLocalServerConfig | MCPRemoteServerConfig;
+/**
+ * Configuration for a custom agent.
+ */
+export interface CustomAgentConfig {
+    /**
+     * Unique name of the custom agent.
+     */
+    name: string;
+    /**
+     * Display name for UI purposes.
+     */
+    displayName?: string;
+    /**
+     * Description of what the agent does.
+     */
+    description?: string;
+    /**
+     * List of tool names the agent can use.
+     * Use null or undefined for all tools.
+     */
+    tools?: string[] | null;
+    /**
+     * The prompt content for the agent.
+     */
+    prompt: string;
+    /**
+     * MCP servers specific to this agent.
+     */
+    mcpServers?: Record<string, MCPServerConfig>;
+    /**
+     * Whether the agent should be available for model inference.
+     * @default true
+     */
+    infer?: boolean;
+}
 export interface SessionConfig {
     /**
      * Optional custom session ID
@@ -186,18 +285,25 @@ export interface SessionConfig {
      */
     provider?: ProviderConfig;
     /**
-     * Enable streaming of assistant message and reasoning chunks.
-     * When true, ephemeral assistant.message_delta and assistant.reasoning_delta
-     * events are sent as the response is generated. Clients should accumulate
-     * deltaContent values to build the full response.
-     * @default false
+     * Handler for permission requests from the server.
+     * When provided, the server will call this handler to request permission for operations.
      */
+    onPermissionRequest?: PermissionHandler;
     streaming?: boolean;
+    /**
+     * MCP server configurations for the session.
+     * Keys are server names, values are server configurations.
+     */
+    mcpServers?: Record<string, MCPServerConfig>;
+    /**
+     * Custom agent configurations for the session.
+     */
+    customAgents?: CustomAgentConfig[];
 }
 /**
  * Configuration for resuming a session
  */
-export type ResumeSessionConfig = Pick<SessionConfig, "tools" | "provider" | "streaming">;
+export type ResumeSessionConfig = Pick<SessionConfig, "tools" | "provider" | "streaming" | "onPermissionRequest" | "mcpServers" | "customAgents">;
 /**
  * Configuration for a custom API provider.
  */
@@ -275,3 +381,4 @@ export interface SessionMetadata {
     summary?: string;
     isRemote: boolean;
 }
+export {};

package/dist/sdkProtocolVersion.js

@@ -0,0 +1,7 @@
+import sdkProtocolVersion from "../../sdk-protocol-version.json";
+function getSdkProtocolVersion() {
+  return sdkProtocolVersion.version;
+}
+export {
+  getSdkProtocolVersion
+};

package/dist/session.js

@@ -1,12 +1,35 @@
 class CopilotSession {
+  /**
+   * Creates a new CopilotSession instance.
+   *
+   * @param sessionId - The unique identifier for this session
+   * @param connection - The JSON-RPC message connection to the Copilot CLI
+   * @internal This constructor is internal. Use {@link CopilotClient.createSession} to create sessions.
+   */
   constructor(sessionId, connection) {
     this.sessionId = sessionId;
     this.connection = connection;
   }
   eventHandlers = /* @__PURE__ */ new Set();
   toolHandlers = /* @__PURE__ */ new Map();
+  permissionHandler;
   /**
-   * Send a message to this session
+   * Sends a message to this session and waits for the response.
+   *
+   * The message is processed asynchronously. Subscribe to events via {@link on}
+   * to receive streaming responses and other session events.
+   *
+   * @param options - The message options including the prompt and optional attachments
+   * @returns A promise that resolves with the message ID of the response
+   * @throws Error if the session has been destroyed or the connection fails
+   *
+   * @example
+   * ```typescript
+   * const messageId = await session.send({
+   *   prompt: "Explain this code",
+   *   attachments: [{ type: "file", path: "./src/index.ts" }]
+   * });
+   * ```
    */
   async send(options) {
     const response = await this.connection.sendRequest("session.send", {
@@ -18,8 +41,30 @@ class CopilotSession {
     return response.messageId;
   }
   /**
-   * Subscribe to events from this session
-   * @returns Unsubscribe function
+   * Subscribes to events from this session.
+   *
+   * Events include assistant messages, tool executions, errors, and session state changes.
+   * Multiple handlers can be registered and will all receive events.
+   *
+   * @param handler - A callback function that receives session events
+   * @returns A function that, when called, unsubscribes the handler
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = session.on((event) => {
+   *   switch (event.type) {
+   *     case "assistant.message":
+   *       console.log("Assistant:", event.data.content);
+   *       break;
+   *     case "session.error":
+   *       console.error("Error:", event.data.message);
+   *       break;
+   *   }
+   * });
+   *
+   * // Later, to stop receiving events:
+   * unsubscribe();
+   * ```
    */
   on(handler) {
     this.eventHandlers.add(handler);
@@ -28,7 +73,10 @@ class CopilotSession {
     };
   }
   /**
-   * Internal: dispatch an event to all handlers
+   * Dispatches an event to all registered handlers.
+   *
+   * @param event - The session event to dispatch
+   * @internal This method is for internal use by the SDK.
    */
   _dispatchEvent(event) {
     for (const handler of this.eventHandlers) {
@@ -38,6 +86,15 @@ class CopilotSession {
       }
     }
   }
+  /**
+   * Registers custom tool handlers for this session.
+   *
+   * Tools allow the assistant to execute custom functions. When the assistant
+   * invokes a tool, the corresponding handler is called with the tool arguments.
+   *
+   * @param tools - An array of tool definitions with their handlers, or undefined to clear all tools
+   * @internal This method is typically called internally when creating a session with tools.
+   */
   registerTools(tools) {
     this.toolHandlers.clear();
     if (!tools) {
@@ -47,11 +104,66 @@ class CopilotSession {
       this.toolHandlers.set(tool.name, tool.handler);
     }
   }
+  /**
+   * Retrieves a registered tool handler by name.
+   *
+   * @param name - The name of the tool to retrieve
+   * @returns The tool handler if found, or undefined
+   * @internal This method is for internal use by the SDK.
+   */
   getToolHandler(name) {
     return this.toolHandlers.get(name);
   }
   /**
-   * Get all events/messages from this session
+   * Registers a handler for permission requests.
+   *
+   * When the assistant needs permission to perform certain actions (e.g., file operations),
+   * this handler is called to approve or deny the request.
+   *
+   * @param handler - The permission handler function, or undefined to remove the handler
+   * @internal This method is typically called internally when creating a session.
+   */
+  registerPermissionHandler(handler) {
+    this.permissionHandler = handler;
+  }
+  /**
+   * Handles a permission request from the Copilot CLI.
+   *
+   * @param request - The permission request data from the CLI
+   * @returns A promise that resolves with the permission decision
+   * @internal This method is for internal use by the SDK.
+   */
+  async _handlePermissionRequest(request) {
+    if (!this.permissionHandler) {
+      return { kind: "denied-no-approval-rule-and-could-not-request-from-user" };
+    }
+    try {
+      const result = await this.permissionHandler(request, {
+        sessionId: this.sessionId
+      });
+      return result;
+    } catch (_error) {
+      return { kind: "denied-no-approval-rule-and-could-not-request-from-user" };
+    }
+  }
+  /**
+   * Retrieves all events and messages from this session's history.
+   *
+   * This returns the complete conversation history including user messages,
+   * assistant responses, tool executions, and other session events.
+   *
+   * @returns A promise that resolves with an array of all session events
+   * @throws Error if the session has been destroyed or the connection fails
+   *
+   * @example
+   * ```typescript
+   * const events = await session.getMessages();
+   * for (const event of events) {
+   *   if (event.type === "assistant.message") {
+   *     console.log("Assistant:", event.data.content);
+   *   }
+   * }
+   * ```
    */
   async getMessages() {
     const response = await this.connection.sendRequest("session.getMessages", {
@@ -60,7 +172,20 @@ class CopilotSession {
     return response.events;
   }
   /**
-   * Destroy this session and free resources
+   * Destroys this session and releases all associated resources.
+   *
+   * After calling this method, the session can no longer be used. All event
+   * handlers and tool handlers are cleared. To continue the conversation,
+   * use {@link CopilotClient.resumeSession} with the session ID.
+   *
+   * @returns A promise that resolves when the session is destroyed
+   * @throws Error if the connection fails
+   *
+   * @example
+   * ```typescript
+   * // Clean up when done
+   * await session.destroy();
+   * ```
    */
   async destroy() {
     await this.connection.sendRequest("session.destroy", {
@@ -68,9 +193,27 @@ class CopilotSession {
     });
     this.eventHandlers.clear();
     this.toolHandlers.clear();
+    this.permissionHandler = void 0;
   }
   /**
-   * Abort the currently processing message in this session
+   * Aborts the currently processing message in this session.
+   *
+   * Use this to cancel a long-running request. The session remains valid
+   * and can continue to be used for new messages.
+   *
+   * @returns A promise that resolves when the abort request is acknowledged
+   * @throws Error if the session has been destroyed or the connection fails
+   *
+   * @example
+   * ```typescript
+   * // Start a long-running request
+   * const messagePromise = session.send({ prompt: "Write a very long story..." });
+   *
+   * // Abort after 5 seconds
+   * setTimeout(async () => {
+   *   await session.abort();
+   * }, 5000);
+   * ```
    */
   async abort() {
     await this.connection.sendRequest("session.abort", {

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/github/copilot-sdk.git"
   },
-  "version": "0.1.10-preview.0",
+  "version": "0.1.10",
   "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -26,6 +26,7 @@
     "lint:fix": "eslint --fix \"src/**/*.ts\" \"test/**/*.ts\"",
     "typecheck": "tsc --noEmit",
     "generate:session-types": "tsx scripts/generate-session-types.ts",
+    "update:protocol-version": "tsx scripts/generate-protocol-version.ts",
     "prepublishOnly": "npm run build",
     "package": "npm run clean && npm run build && node scripts/set-version.js && npm pack && npm version 0.1.0 --no-git-tag-version --allow-same-version"
   },
@@ -39,12 +40,12 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
-    "@github/copilot": "^0.0.377",
+    "@github/copilot": "^0.0.382-0",
     "vscode-jsonrpc": "^8.2.1",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^22.19.6",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",
     "esbuild": "^0.27.0",