@github/copilot-sdk 0.1.19 → 0.1.21

package/dist/client.js

@@ -28,6 +28,10 @@ class CopilotClient {
   options;
   isExternalServer = false;
   forceStopping = false;
+  modelsCache = null;
+  modelsCacheLock = Promise.resolve();
+  sessionLifecycleHandlers = /* @__PURE__ */ new Set();
+  typedLifecycleHandlers = /* @__PURE__ */ new Map();
   /**
    * Creates a new CopilotClient instance.
    *
@@ -53,6 +57,11 @@ class CopilotClient {
     if (options.cliUrl && (options.useStdio === true || options.cliPath)) {
       throw new Error("cliUrl is mutually exclusive with useStdio and cliPath");
     }
+    if (options.cliUrl && (options.githubToken || options.useLoggedInUser !== void 0)) {
+      throw new Error(
+        "githubToken and useLoggedInUser cannot be used with cliUrl (external server manages its own auth)"
+      );
+    }
     if (options.cliUrl) {
       const { host, port } = this.parseCliUrl(options.cliUrl);
       this.actualHost = host;
@@ -70,7 +79,10 @@ class CopilotClient {
       logLevel: options.logLevel || "debug",
       autoStart: options.autoStart ?? true,
       autoRestart: options.autoRestart ?? true,
-      env: options.env ?? process.env
+      env: options.env ?? process.env,
+      githubToken: options.githubToken,
+      // Default useLoggedInUser to false when githubToken is provided, otherwise true
+      useLoggedInUser: options.useLoggedInUser ?? (options.githubToken ? false : true)
     };
   }
   /**
@@ -188,6 +200,7 @@ class CopilotClient {
       }
       this.connection = null;
     }
+    this.modelsCache = null;
     if (this.socket) {
       try {
         this.socket.end();
@@ -251,6 +264,7 @@ class CopilotClient {
       }
       this.connection = null;
     }
+    this.modelsCache = null;
     if (this.socket) {
       try {
         this.socket.destroy();
@@ -307,6 +321,7 @@ class CopilotClient {
     const response = await this.connection.sendRequest("session.create", {
       model: config.model,
       sessionId: config.sessionId,
+      reasoningEffort: config.reasoningEffort,
       tools: config.tools?.map((tool) => ({
         name: tool.name,
         description: tool.description,
@@ -317,6 +332,9 @@ class CopilotClient {
       excludedTools: config.excludedTools,
       provider: config.provider,
       requestPermission: !!config.onPermissionRequest,
+      requestUserInput: !!config.onUserInputRequest,
+      hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
+      workingDirectory: config.workingDirectory,
       streaming: config.streaming,
       mcpServers: config.mcpServers,
       customAgents: config.customAgents,
@@ -331,6 +349,12 @@ class CopilotClient {
     if (config.onPermissionRequest) {
       session.registerPermissionHandler(config.onPermissionRequest);
     }
+    if (config.onUserInputRequest) {
+      session.registerUserInputHandler(config.onUserInputRequest);
+    }
+    if (config.hooks) {
+      session.registerHooks(config.hooks);
+    }
     this.sessions.set(sessionId, session);
     return session;
   }
@@ -367,6 +391,7 @@ class CopilotClient {
     }
     const response = await this.connection.sendRequest("session.resume", {
       sessionId,
+      reasoningEffort: config.reasoningEffort,
       tools: config.tools?.map((tool) => ({
         name: tool.name,
         description: tool.description,
@@ -374,11 +399,15 @@ class CopilotClient {
       })),
       provider: config.provider,
       requestPermission: !!config.onPermissionRequest,
+      requestUserInput: !!config.onUserInputRequest,
+      hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
+      workingDirectory: config.workingDirectory,
       streaming: config.streaming,
       mcpServers: config.mcpServers,
       customAgents: config.customAgents,
       skillDirectories: config.skillDirectories,
-      disabledSkills: config.disabledSkills
+      disabledSkills: config.disabledSkills,
+      disableResume: config.disableResume
     });
     const { sessionId: resumedSessionId, workspacePath } = response;
     const session = new CopilotSession(resumedSessionId, this.connection, workspacePath);
@@ -386,6 +415,12 @@ class CopilotClient {
     if (config.onPermissionRequest) {
       session.registerPermissionHandler(config.onPermissionRequest);
     }
+    if (config.onUserInputRequest) {
+      session.registerUserInputHandler(config.onUserInputRequest);
+    }
+    if (config.hooks) {
+      session.registerHooks(config.hooks);
+    }
     this.sessions.set(resumedSessionId, session);
     return session;
   }
@@ -445,16 +480,34 @@ class CopilotClient {
     return result;
   }
   /**
-   * List available models with their metadata
+   * List available models with their metadata.
+   *
+   * Results are cached after the first successful call to avoid rate limiting.
+   * The cache is cleared when the client disconnects.
+   *
    * @throws Error if not authenticated
    */
   async listModels() {
     if (!this.connection) {
       throw new Error("Client not connected");
     }
-    const result = await this.connection.sendRequest("models.list", {});
-    const response = result;
-    return response.models;
+    await this.modelsCacheLock;
+    let resolveLock;
+    this.modelsCacheLock = new Promise((resolve) => {
+      resolveLock = resolve;
+    });
+    try {
+      if (this.modelsCache !== null) {
+        return [...this.modelsCache];
+      }
+      const result = await this.connection.sendRequest("models.list", {});
+      const response = result;
+      const models = response.models;
+      this.modelsCache = models;
+      return [...models];
+    } finally {
+      resolveLock();
+    }
   }
   /**
    * Verify that the server's protocol version matches the SDK's expected version
@@ -556,6 +609,77 @@ class CopilotClient {
       isRemote: s.isRemote
     }));
   }
+  /**
+   * Gets the foreground session ID in TUI+server mode.
+   *
+   * This returns the ID of the session currently displayed in the TUI.
+   * Only available when connecting to a server running in TUI+server mode (--ui-server).
+   *
+   * @returns A promise that resolves with the foreground session ID, or undefined if none
+   * @throws Error if the client is not connected
+   *
+   * @example
+   * ```typescript
+   * const sessionId = await client.getForegroundSessionId();
+   * if (sessionId) {
+   *   console.log(`TUI is displaying session: ${sessionId}`);
+   * }
+   * ```
+   */
+  async getForegroundSessionId() {
+    if (!this.connection) {
+      throw new Error("Client not connected");
+    }
+    const response = await this.connection.sendRequest("session.getForeground", {});
+    return response.sessionId;
+  }
+  /**
+   * Sets the foreground session in TUI+server mode.
+   *
+   * This requests the TUI to switch to displaying the specified session.
+   * Only available when connecting to a server running in TUI+server mode (--ui-server).
+   *
+   * @param sessionId - The ID of the session to display in the TUI
+   * @returns A promise that resolves when the session is switched
+   * @throws Error if the client is not connected or if the operation fails
+   *
+   * @example
+   * ```typescript
+   * // Switch the TUI to display a specific session
+   * await client.setForegroundSessionId("session-123");
+   * ```
+   */
+  async setForegroundSessionId(sessionId) {
+    if (!this.connection) {
+      throw new Error("Client not connected");
+    }
+    const response = await this.connection.sendRequest("session.setForeground", { sessionId });
+    const result = response;
+    if (!result.success) {
+      throw new Error(result.error || "Failed to set foreground session");
+    }
+  }
+  on(eventTypeOrHandler, handler) {
+    if (typeof eventTypeOrHandler === "string" && handler) {
+      const eventType = eventTypeOrHandler;
+      if (!this.typedLifecycleHandlers.has(eventType)) {
+        this.typedLifecycleHandlers.set(eventType, /* @__PURE__ */ new Set());
+      }
+      const storedHandler = handler;
+      this.typedLifecycleHandlers.get(eventType).add(storedHandler);
+      return () => {
+        const handlers = this.typedLifecycleHandlers.get(eventType);
+        if (handlers) {
+          handlers.delete(storedHandler);
+        }
+      };
+    }
+    const wildcardHandler = eventTypeOrHandler;
+    this.sessionLifecycleHandlers.add(wildcardHandler);
+    return () => {
+      this.sessionLifecycleHandlers.delete(wildcardHandler);
+    };
+  }
   /**
    * Start the CLI server process
    */
@@ -563,7 +687,7 @@ class CopilotClient {
     return new Promise((resolve, reject) => {
       const args = [
         ...this.options.cliArgs,
-        "--server",
+        "--headless",
         "--log-level",
         this.options.logLevel
       ];
@@ -572,8 +696,17 @@ class CopilotClient {
       } else if (this.options.port > 0) {
         args.push("--port", this.options.port.toString());
       }
+      if (this.options.githubToken) {
+        args.push("--auth-token-env", "COPILOT_SDK_AUTH_TOKEN");
+      }
+      if (!this.options.useLoggedInUser) {
+        args.push("--no-auto-login");
+      }
       const envWithoutNodeDebug = { ...this.options.env };
       delete envWithoutNodeDebug.NODE_DEBUG;
+      if (this.options.githubToken) {
+        envWithoutNodeDebug.COPILOT_SDK_AUTH_TOKEN = this.options.githubToken;
+      }
       const isJsFile = this.options.cliPath.endsWith(".js");
       const isAbsolutePath = this.options.cliPath.startsWith("/") || /^[a-zA-Z]:/.test(this.options.cliPath);
       let command;
@@ -699,6 +832,9 @@ class CopilotClient {
     this.connection.onNotification("session.event", (notification) => {
       this.handleSessionEventNotification(notification);
     });
+    this.connection.onNotification("session.lifecycle", (notification) => {
+      this.handleSessionLifecycleNotification(notification);
+    });
     this.connection.onRequest(
       "tool.call",
       async (params) => await this.handleToolCallRequest(params)
@@ -707,6 +843,14 @@ class CopilotClient {
       "permission.request",
       async (params) => await this.handlePermissionRequest(params)
     );
+    this.connection.onRequest(
+      "userInput.request",
+      async (params) => await this.handleUserInputRequest(params)
+    );
+    this.connection.onRequest(
+      "hooks.invoke",
+      async (params) => await this.handleHooksInvoke(params)
+    );
     this.connection.onClose(() => {
       if (this.state === "connected" && this.options.autoRestart) {
         void this.reconnect();
@@ -724,6 +868,27 @@ class CopilotClient {
       session._dispatchEvent(notification.event);
     }
   }
+  handleSessionLifecycleNotification(notification) {
+    if (typeof notification !== "object" || !notification || !("type" in notification) || typeof notification.type !== "string" || !("sessionId" in notification) || typeof notification.sessionId !== "string") {
+      return;
+    }
+    const event = notification;
+    const typedHandlers = this.typedLifecycleHandlers.get(event.type);
+    if (typedHandlers) {
+      for (const handler of typedHandlers) {
+        try {
+          handler(event);
+        } catch {
+        }
+      }
+    }
+    for (const handler of this.sessionLifecycleHandlers) {
+      try {
+        handler(event);
+      } catch {
+      }
+    }
+  }
   async handleToolCallRequest(params) {
     if (!params || typeof params.sessionId !== "string" || typeof params.toolCallId !== "string" || typeof params.toolName !== "string") {
       throw new Error("Invalid tool call payload");
@@ -780,6 +945,32 @@ class CopilotClient {
       };
     }
   }
+  async handleUserInputRequest(params) {
+    if (!params || typeof params.sessionId !== "string" || typeof params.question !== "string") {
+      throw new Error("Invalid user input request payload");
+    }
+    const session = this.sessions.get(params.sessionId);
+    if (!session) {
+      throw new Error(`Session not found: ${params.sessionId}`);
+    }
+    const result = await session._handleUserInputRequest({
+      question: params.question,
+      choices: params.choices,
+      allowFreeform: params.allowFreeform
+    });
+    return result;
+  }
+  async handleHooksInvoke(params) {
+    if (!params || typeof params.sessionId !== "string" || typeof params.hookType !== "string") {
+      throw new Error("Invalid hooks invoke payload");
+    }
+    const session = this.sessions.get(params.sessionId);
+    if (!session) {
+      throw new Error(`Session not found: ${params.sessionId}`);
+    }
+    const output = await session._handleHooksInvoke(params.hookType, params.input);
+    return { output };
+  }
   normalizeToolResult(result) {
     if (result === void 0 || result === null) {
       return {

package/dist/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-26T18:08:33.710Z
+ * Generated at: 2026-02-03T20:40:49.167Z
  *
  * To update these types:
  * 1. Update the schema in copilot-agent-runtime
@@ -55,6 +55,8 @@ export type SessionEvent = {
         errorType: string;
         message: string;
         stack?: string;
+        statusCode?: number;
+        providerCallId?: string;
     };
 } | {
     id: string;
@@ -127,6 +129,39 @@ export type SessionEvent = {
         upToEventId: string;
         eventsRemoved: number;
     };
+} | {
+    id: string;
+    timestamp: string;
+    parentId: string | null;
+    ephemeral: true;
+    type: "session.shutdown";
+    data: {
+        shutdownType: "routine" | "error";
+        errorReason?: string;
+        totalPremiumRequests: number;
+        totalApiDurationMs: number;
+        sessionStartTime: number;
+        codeChanges: {
+            linesAdded: number;
+            linesRemoved: number;
+            filesModified: string[];
+        };
+        modelMetrics: {
+            [k: string]: {
+                requests: {
+                    count: number;
+                    cost: number;
+                };
+                usage: {
+                    inputTokens: number;
+                    outputTokens: number;
+                    cacheReadTokens: number;
+                    cacheWriteTokens: number;
+                };
+            };
+        };
+        currentModel?: string;
+    };
 } | {
     id: string;
     timestamp: string;
@@ -160,6 +195,8 @@ export type SessionEvent = {
         messagesRemoved?: number;
         tokensRemoved?: number;
         summaryContent?: string;
+        checkpointNumber?: number;
+        checkpointPath?: string;
         compactionTokensUsed?: {
             input: number;
             output: number;
@@ -261,6 +298,9 @@ export type SessionEvent = {
             arguments?: unknown;
             type?: "function" | "custom";
         }[];
+        reasoningOpaque?: string;
+        reasoningText?: string;
+        encryptedContent?: string;
         parentToolCallId?: string;
     };
 } | {
@@ -291,7 +331,7 @@ export type SessionEvent = {
     ephemeral: true;
     type: "assistant.usage";
     data: {
-        model?: string;
+        model: string;
         inputTokens?: number;
         outputTokens?: number;
         cacheReadTokens?: number;
@@ -301,6 +341,7 @@ export type SessionEvent = {
         initiator?: string;
         apiCallId?: string;
         providerCallId?: string;
+        parentToolCallId?: string;
         quotaSnapshots?: {
             [k: string]: {
                 isUnlimitedEntitlement: boolean;
@@ -391,6 +432,18 @@ export type SessionEvent = {
         };
         parentToolCallId?: string;
     };
+} | {
+    id: string;
+    timestamp: string;
+    parentId: string | null;
+    ephemeral?: boolean;
+    type: "skill.invoked";
+    data: {
+        name: string;
+        path: string;
+        content: string;
+        allowedTools?: string[];
+    };
 } | {
     id: string;
     timestamp: string;

package/dist/index.d.ts

@@ -6,4 +6,4 @@
 export { CopilotClient } from "./client.js";
 export { CopilotSession, type AssistantMessageEvent } from "./session.js";
 export { defineTool } from "./types.js";
-export type { ConnectionState, CopilotClientOptions, CustomAgentConfig, GetAuthStatusResponse, GetStatusResponse, InfiniteSessionConfig, MCPLocalServerConfig, MCPRemoteServerConfig, MCPServerConfig, MessageOptions, ModelBilling, ModelCapabilities, ModelInfo, ModelPolicy, PermissionHandler, PermissionRequest, PermissionRequestResult, ResumeSessionConfig, SessionConfig, SessionEvent, SessionEventHandler, SessionMetadata, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageReplaceConfig, Tool, ToolHandler, ToolInvocation, ToolResultObject, ZodSchema, } 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, SessionMetadata, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageReplaceConfig, Tool, ToolHandler, ToolInvocation, ToolResultObject, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";

package/dist/session.d.ts

@@ -3,7 +3,7 @@
  * @module session
  */
 import type { MessageConnection } from "vscode-jsonrpc/node";
-import type { MessageOptions, PermissionHandler, PermissionRequestResult, SessionEvent, SessionEventHandler, Tool, ToolHandler } from "./types.js";
+import type { MessageOptions, PermissionHandler, PermissionRequestResult, SessionEvent, SessionEventHandler, SessionEventType, SessionHooks, Tool, ToolHandler, TypedSessionEventHandler, UserInputHandler, UserInputResponse } from "./types.js";
 /** Assistant message event - the final response from the assistant. */
 export type AssistantMessageEvent = Extract<SessionEvent, {
     type: "assistant.message";
@@ -38,8 +38,11 @@ export declare class CopilotSession {
     private connection;
     private readonly _workspacePath?;
     private eventHandlers;
+    private typedEventHandlers;
     private toolHandlers;
     private permissionHandler?;
+    private userInputHandler?;
+    private hooks?;
     /**
      * Creates a new CopilotSession instance.
      *
@@ -104,7 +107,26 @@ export declare class CopilotSession {
      * 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
+     * @param eventType - The specific event type to listen for (e.g., "assistant.message", "session.idle")
+     * @param handler - A callback function that receives events of the specified type
+     * @returns A function that, when called, unsubscribes the handler
+     *
+     * @example
+     * ```typescript
+     * // Listen for a specific event type
+     * const unsubscribe = session.on("assistant.message", (event) => {
+     *   console.log("Assistant:", event.data.content);
+     * });
+     *
+     * // Later, to stop receiving events:
+     * unsubscribe();
+     * ```
+     */
+    on<K extends SessionEventType>(eventType: K, handler: TypedSessionEventHandler<K>): () => void;
+    /**
+     * Subscribes to all events from this session.
+     *
+     * @param handler - A callback function that receives all session events
      * @returns A function that, when called, unsubscribes the handler
      *
      * @example
@@ -160,6 +182,26 @@ export declare class CopilotSession {
      * @internal This method is typically called internally when creating a session.
      */
     registerPermissionHandler(handler?: PermissionHandler): void;
+    /**
+     * Registers a user input handler for ask_user requests.
+     *
+     * When the agent needs input from the user (via ask_user tool),
+     * this handler is called to provide the response.
+     *
+     * @param handler - The user input handler function, or undefined to remove the handler
+     * @internal This method is typically called internally when creating a session.
+     */
+    registerUserInputHandler(handler?: UserInputHandler): void;
+    /**
+     * Registers hook handlers for session lifecycle events.
+     *
+     * Hooks allow custom logic to be executed at various points during
+     * the session lifecycle (before/after tool use, session start/end, etc.).
+     *
+     * @param hooks - The hook handlers object, or undefined to remove all hooks
+     * @internal This method is typically called internally when creating a session.
+     */
+    registerHooks(hooks?: SessionHooks): void;
     /**
      * Handles a permission request from the Copilot CLI.
      *
@@ -168,6 +210,23 @@ export declare class CopilotSession {
      * @internal This method is for internal use by the SDK.
      */
     _handlePermissionRequest(request: unknown): Promise<PermissionRequestResult>;
+    /**
+     * Handles a user input request from the Copilot CLI.
+     *
+     * @param request - The user input request data from the CLI
+     * @returns A promise that resolves with the user's response
+     * @internal This method is for internal use by the SDK.
+     */
+    _handleUserInputRequest(request: unknown): Promise<UserInputResponse>;
+    /**
+     * Handles a hooks invocation from the Copilot CLI.
+     *
+     * @param hookType - The type of hook being invoked
+     * @param input - The input data for the hook
+     * @returns A promise that resolves with the hook output, or undefined
+     * @internal This method is for internal use by the SDK.
+     */
+    _handleHooksInvoke(hookType: string, input: unknown): Promise<unknown>;
     /**
      * Retrieves all events and messages from this session's history.
      *