@github/copilot-sdk 0.1.19 → 0.1.21

package/dist/session.js

@@ -13,8 +13,11 @@ class CopilotSession {
     this._workspacePath = _workspacePath;
   }
   eventHandlers = /* @__PURE__ */ new Set();
+  typedEventHandlers = /* @__PURE__ */ new Map();
   toolHandlers = /* @__PURE__ */ new Map();
   permissionHandler;
+  userInputHandler;
+  hooks;
   /**
    * Path to the session workspace directory when infinite sessions are enabled.
    * Contains checkpoints/, plan.md, and files/ subdirectories.
@@ -111,36 +114,25 @@ class CopilotSession {
       unsubscribe();
     }
   }
-  /**
-   * 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);
+  on(eventTypeOrHandler, handler) {
+    if (typeof eventTypeOrHandler === "string" && handler) {
+      const eventType = eventTypeOrHandler;
+      if (!this.typedEventHandlers.has(eventType)) {
+        this.typedEventHandlers.set(eventType, /* @__PURE__ */ new Set());
+      }
+      const storedHandler = handler;
+      this.typedEventHandlers.get(eventType).add(storedHandler);
+      return () => {
+        const handlers = this.typedEventHandlers.get(eventType);
+        if (handlers) {
+          handlers.delete(storedHandler);
+        }
+      };
+    }
+    const wildcardHandler = eventTypeOrHandler;
+    this.eventHandlers.add(wildcardHandler);
     return () => {
-      this.eventHandlers.delete(handler);
+      this.eventHandlers.delete(wildcardHandler);
     };
   }
   /**
@@ -150,6 +142,15 @@ class CopilotSession {
    * @internal This method is for internal use by the SDK.
    */
   _dispatchEvent(event) {
+    const typedHandlers = this.typedEventHandlers.get(event.type);
+    if (typedHandlers) {
+      for (const handler of typedHandlers) {
+        try {
+          handler(event);
+        } catch (_error) {
+        }
+      }
+    }
     for (const handler of this.eventHandlers) {
       try {
         handler(event);
@@ -197,6 +198,30 @@ class CopilotSession {
   registerPermissionHandler(handler) {
     this.permissionHandler = handler;
   }
+  /**
+   * 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) {
+    this.userInputHandler = handler;
+  }
+  /**
+   * 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) {
+    this.hooks = hooks;
+  }
   /**
    * Handles a permission request from the Copilot CLI.
    *
@@ -217,6 +242,57 @@ class CopilotSession {
       return { kind: "denied-no-approval-rule-and-could-not-request-from-user" };
     }
   }
+  /**
+   * 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.
+   */
+  async _handleUserInputRequest(request) {
+    if (!this.userInputHandler) {
+      throw new Error("User input requested but no handler registered");
+    }
+    try {
+      const result = await this.userInputHandler(request, {
+        sessionId: this.sessionId
+      });
+      return result;
+    } catch (error) {
+      throw error;
+    }
+  }
+  /**
+   * 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.
+   */
+  async _handleHooksInvoke(hookType, input) {
+    if (!this.hooks) {
+      return void 0;
+    }
+    const handlerMap = {
+      preToolUse: this.hooks.onPreToolUse,
+      postToolUse: this.hooks.onPostToolUse,
+      userPromptSubmitted: this.hooks.onUserPromptSubmitted,
+      sessionStart: this.hooks.onSessionStart,
+      sessionEnd: this.hooks.onSessionEnd,
+      errorOccurred: this.hooks.onErrorOccurred
+    };
+    const handler = handlerMap[hookType];
+    if (!handler) {
+      return void 0;
+    }
+    try {
+      const result = await handler(input, { sessionId: this.sessionId });
+      return result;
+    } catch (_error) {
+      return void 0;
+    }
+  }
   /**
    * Retrieves all events and messages from this session's history.
    *
@@ -263,6 +339,7 @@ class CopilotSession {
       sessionId: this.sessionId
     });
     this.eventHandlers.clear();
+    this.typedEventHandlers.clear();
     this.toolHandlers.clear();
     this.permissionHandler = void 0;
   }

package/dist/types.d.ts

@@ -58,6 +58,19 @@ export interface CopilotClientOptions {
      * Environment variables to pass to the CLI process. If not set, inherits process.env.
      */
     env?: Record<string, string | undefined>;
+    /**
+     * GitHub token to use for authentication.
+     * When provided, the token is passed to the CLI server via environment variable.
+     * This takes priority over other authentication methods.
+     */
+    githubToken?: string;
+    /**
+     * Whether to use the logged-in user for authentication.
+     * When true, the CLI server will attempt to use stored OAuth tokens or gh CLI auth.
+     * When false, only explicit tokens (githubToken or environment variables) are used.
+     * @default true (but defaults to false when githubToken is provided)
+     */
+    useLoggedInUser?: boolean;
 }
 /**
  * Configuration for creating a session
@@ -166,6 +179,209 @@ export interface PermissionRequestResult {
 export type PermissionHandler = (request: PermissionRequest, invocation: {
     sessionId: string;
 }) => Promise<PermissionRequestResult> | PermissionRequestResult;
+/**
+ * Request for user input from the agent (enables ask_user tool)
+ */
+export interface UserInputRequest {
+    /**
+     * The question to ask the user
+     */
+    question: string;
+    /**
+     * Optional choices for multiple choice questions
+     */
+    choices?: string[];
+    /**
+     * Whether to allow freeform text input in addition to choices
+     * @default true
+     */
+    allowFreeform?: boolean;
+}
+/**
+ * Response to a user input request
+ */
+export interface UserInputResponse {
+    /**
+     * The user's answer
+     */
+    answer: string;
+    /**
+     * Whether the answer was freeform (not from choices)
+     */
+    wasFreeform: boolean;
+}
+/**
+ * Handler for user input requests from the agent
+ */
+export type UserInputHandler = (request: UserInputRequest, invocation: {
+    sessionId: string;
+}) => Promise<UserInputResponse> | UserInputResponse;
+/**
+ * Base interface for all hook inputs
+ */
+export interface BaseHookInput {
+    timestamp: number;
+    cwd: string;
+}
+/**
+ * Input for pre-tool-use hook
+ */
+export interface PreToolUseHookInput extends BaseHookInput {
+    toolName: string;
+    toolArgs: unknown;
+}
+/**
+ * Output for pre-tool-use hook
+ */
+export interface PreToolUseHookOutput {
+    permissionDecision?: "allow" | "deny" | "ask";
+    permissionDecisionReason?: string;
+    modifiedArgs?: unknown;
+    additionalContext?: string;
+    suppressOutput?: boolean;
+}
+/**
+ * Handler for pre-tool-use hook
+ */
+export type PreToolUseHandler = (input: PreToolUseHookInput, invocation: {
+    sessionId: string;
+}) => Promise<PreToolUseHookOutput | void> | PreToolUseHookOutput | void;
+/**
+ * Input for post-tool-use hook
+ */
+export interface PostToolUseHookInput extends BaseHookInput {
+    toolName: string;
+    toolArgs: unknown;
+    toolResult: ToolResultObject;
+}
+/**
+ * Output for post-tool-use hook
+ */
+export interface PostToolUseHookOutput {
+    modifiedResult?: ToolResultObject;
+    additionalContext?: string;
+    suppressOutput?: boolean;
+}
+/**
+ * Handler for post-tool-use hook
+ */
+export type PostToolUseHandler = (input: PostToolUseHookInput, invocation: {
+    sessionId: string;
+}) => Promise<PostToolUseHookOutput | void> | PostToolUseHookOutput | void;
+/**
+ * Input for user-prompt-submitted hook
+ */
+export interface UserPromptSubmittedHookInput extends BaseHookInput {
+    prompt: string;
+}
+/**
+ * Output for user-prompt-submitted hook
+ */
+export interface UserPromptSubmittedHookOutput {
+    modifiedPrompt?: string;
+    additionalContext?: string;
+    suppressOutput?: boolean;
+}
+/**
+ * Handler for user-prompt-submitted hook
+ */
+export type UserPromptSubmittedHandler = (input: UserPromptSubmittedHookInput, invocation: {
+    sessionId: string;
+}) => Promise<UserPromptSubmittedHookOutput | void> | UserPromptSubmittedHookOutput | void;
+/**
+ * Input for session-start hook
+ */
+export interface SessionStartHookInput extends BaseHookInput {
+    source: "startup" | "resume" | "new";
+    initialPrompt?: string;
+}
+/**
+ * Output for session-start hook
+ */
+export interface SessionStartHookOutput {
+    additionalContext?: string;
+    modifiedConfig?: Record<string, unknown>;
+}
+/**
+ * Handler for session-start hook
+ */
+export type SessionStartHandler = (input: SessionStartHookInput, invocation: {
+    sessionId: string;
+}) => Promise<SessionStartHookOutput | void> | SessionStartHookOutput | void;
+/**
+ * Input for session-end hook
+ */
+export interface SessionEndHookInput extends BaseHookInput {
+    reason: "complete" | "error" | "abort" | "timeout" | "user_exit";
+    finalMessage?: string;
+    error?: string;
+}
+/**
+ * Output for session-end hook
+ */
+export interface SessionEndHookOutput {
+    suppressOutput?: boolean;
+    cleanupActions?: string[];
+    sessionSummary?: string;
+}
+/**
+ * Handler for session-end hook
+ */
+export type SessionEndHandler = (input: SessionEndHookInput, invocation: {
+    sessionId: string;
+}) => Promise<SessionEndHookOutput | void> | SessionEndHookOutput | void;
+/**
+ * Input for error-occurred hook
+ */
+export interface ErrorOccurredHookInput extends BaseHookInput {
+    error: string;
+    errorContext: "model_call" | "tool_execution" | "system" | "user_input";
+    recoverable: boolean;
+}
+/**
+ * Output for error-occurred hook
+ */
+export interface ErrorOccurredHookOutput {
+    suppressOutput?: boolean;
+    errorHandling?: "retry" | "skip" | "abort";
+    retryCount?: number;
+    userNotification?: string;
+}
+/**
+ * Handler for error-occurred hook
+ */
+export type ErrorOccurredHandler = (input: ErrorOccurredHookInput, invocation: {
+    sessionId: string;
+}) => Promise<ErrorOccurredHookOutput | void> | ErrorOccurredHookOutput | void;
+/**
+ * Configuration for session hooks
+ */
+export interface SessionHooks {
+    /**
+     * Called before a tool is executed
+     */
+    onPreToolUse?: PreToolUseHandler;
+    /**
+     * Called after a tool is executed
+     */
+    onPostToolUse?: PostToolUseHandler;
+    /**
+     * Called when the user submits a prompt
+     */
+    onUserPromptSubmitted?: UserPromptSubmittedHandler;
+    /**
+     * Called when a session starts
+     */
+    onSessionStart?: SessionStartHandler;
+    /**
+     * Called when a session ends
+     */
+    onSessionEnd?: SessionEndHandler;
+    /**
+     * Called when an error occurs
+     */
+    onErrorOccurred?: ErrorOccurredHandler;
+}
 /**
  * Base interface for MCP server configuration.
  */
@@ -274,6 +490,10 @@ export interface InfiniteSessionConfig {
      */
     bufferExhaustionThreshold?: number;
 }
+/**
+ * Valid reasoning effort levels for models that support it.
+ */
+export type ReasoningEffort = "low" | "medium" | "high" | "xhigh";
 export interface SessionConfig {
     /**
      * Optional custom session ID
@@ -284,6 +504,12 @@ export interface SessionConfig {
      * Model to use for this session
      */
     model?: string;
+    /**
+     * Reasoning effort level for models that support it.
+     * Only valid for models where capabilities.supports.reasoningEffort is true.
+     * Use client.listModels() to check supported values for each model.
+     */
+    reasoningEffort?: ReasoningEffort;
     /**
      * Override the default configuration directory location.
      * When specified, the session will use this directory for storing config and state.
@@ -318,6 +544,21 @@ export interface SessionConfig {
      * When provided, the server will call this handler to request permission for operations.
      */
     onPermissionRequest?: PermissionHandler;
+    /**
+     * Handler for user input requests from the agent.
+     * When provided, enables the ask_user tool allowing the agent to ask questions.
+     */
+    onUserInputRequest?: UserInputHandler;
+    /**
+     * Hook handlers for intercepting session lifecycle events.
+     * When provided, enables hooks callback allowing custom logic at various points.
+     */
+    hooks?: SessionHooks;
+    /**
+     * Working directory for the session.
+     * Tool operations will be relative to this directory.
+     */
+    workingDirectory?: string;
     streaming?: boolean;
     /**
      * MCP server configurations for the session.
@@ -346,7 +587,14 @@ export interface SessionConfig {
 /**
  * Configuration for resuming a session
  */
-export type ResumeSessionConfig = Pick<SessionConfig, "tools" | "provider" | "streaming" | "onPermissionRequest" | "mcpServers" | "customAgents" | "skillDirectories" | "disabledSkills">;
+export type ResumeSessionConfig = Pick<SessionConfig, "tools" | "provider" | "streaming" | "reasoningEffort" | "onPermissionRequest" | "onUserInputRequest" | "hooks" | "workingDirectory" | "mcpServers" | "customAgents" | "skillDirectories" | "disabledSkills"> & {
+    /**
+     * When true, skips emitting the session.resume event.
+     * Useful for reconnecting to a session without triggering resume-related side effects.
+     * @default false
+     */
+    disableResume?: boolean;
+};
 /**
  * Configuration for a custom API provider.
  */
@@ -407,7 +655,21 @@ export interface MessageOptions {
     mode?: "enqueue" | "immediate";
 }
 /**
- * Event handler callback type
+ * All possible event type strings from SessionEvent
+ */
+export type SessionEventType = SessionEvent["type"];
+/**
+ * Extract the specific event payload for a given event type
+ */
+export type SessionEventPayload<T extends SessionEventType> = Extract<SessionEvent, {
+    type: T;
+}>;
+/**
+ * Event handler for a specific event type
+ */
+export type TypedSessionEventHandler<T extends SessionEventType> = (event: SessionEventPayload<T>) => void;
+/**
+ * Event handler callback type (for all events)
  */
 export type SessionEventHandler = (event: SessionEvent) => void;
 /**
@@ -454,6 +716,8 @@ export interface GetAuthStatusResponse {
 export interface ModelCapabilities {
     supports: {
         vision: boolean;
+        /** Whether this model supports reasoning effort configuration */
+        reasoningEffort: boolean;
     };
     limits: {
         max_prompt_tokens?: number;
@@ -492,5 +756,48 @@ export interface ModelInfo {
     policy?: ModelPolicy;
     /** Billing information */
     billing?: ModelBilling;
+    /** Supported reasoning effort levels (only present if model supports reasoning effort) */
+    supportedReasoningEfforts?: ReasoningEffort[];
+    /** Default reasoning effort level (only present if model supports reasoning effort) */
+    defaultReasoningEffort?: ReasoningEffort;
+}
+/**
+ * Types of session lifecycle events
+ */
+export type SessionLifecycleEventType = "session.created" | "session.deleted" | "session.updated" | "session.foreground" | "session.background";
+/**
+ * Session lifecycle event notification
+ * Sent when sessions are created, deleted, updated, or change foreground/background state
+ */
+export interface SessionLifecycleEvent {
+    /** Type of lifecycle event */
+    type: SessionLifecycleEventType;
+    /** ID of the session this event relates to */
+    sessionId: string;
+    /** Session metadata (not included for deleted sessions) */
+    metadata?: {
+        startTime: string;
+        modifiedTime: string;
+        summary?: string;
+    };
+}
+/**
+ * Handler for session lifecycle events
+ */
+export type SessionLifecycleHandler = (event: SessionLifecycleEvent) => void;
+/**
+ * Typed handler for specific session lifecycle event types
+ */
+export type TypedSessionLifecycleHandler<K extends SessionLifecycleEventType> = (event: SessionLifecycleEvent & {
+    type: K;
+}) => void;
+/**
+ * Information about the foreground session in TUI+server mode
+ */
+export interface ForegroundSessionInfo {
+    /** ID of the foreground session, or undefined if none */
+    sessionId?: string;
+    /** 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.1.19",
+  "version": "0.1.21",
   "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -40,15 +40,15 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
-    "@github/copilot": "^0.0.394",
+    "@github/copilot": "^0.0.402",
     "vscode-jsonrpc": "^8.2.1",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@types/node": "^22.19.6",
-    "@typescript-eslint/eslint-plugin": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.0",
-    "esbuild": "^0.27.0",
+    "@types/node": "^25.2.0",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "esbuild": "^0.27.2",
     "eslint": "^9.0.0",
     "glob": "^11.0.0",
     "json-schema": "^0.4.0",
@@ -59,7 +59,7 @@
     "semver": "^7.7.3",
     "tsx": "^4.20.6",
     "typescript": "^5.0.0",
-    "vitest": "^4.0.16"
+    "vitest": "^4.0.18"
   },
   "engines": {
     "node": ">=18.0.0"