@github/copilot-sdk 0.1.20 → 0.1.22

package/README.md

@@ -86,8 +86,9 @@ Create a new conversation session.
 
 **Config:**
 
-- `sessionId?: string` - Custom session ID
+- `sessionId?: string` - Custom session ID.
 - `model?: string` - Model to use ("gpt-5", "claude-sonnet-4.5", etc.). **Required when using custom provider.**
+- `reasoningEffort?: "low" | "medium" | "high" | "xhigh"` - Reasoning effort level for models that support it. Use `listModels()` to check which models support this option.
 - `tools?: Tool[]` - Custom tools exposed to the CLI
 - `systemMessage?: SystemMessageConfig` - System message customization (see below)
 - `infiniteSessions?: InfiniteSessionConfig` - Configure automatic context compaction (see below)
@@ -115,6 +116,41 @@ List all available sessions.
 
 Delete a session and its data from disk.
 
+##### `getForegroundSessionId(): Promise<string | undefined>`
+
+Get the ID of the session currently displayed in the TUI. Only available when connecting to a server running in TUI+server mode (`--ui-server`).
+
+##### `setForegroundSessionId(sessionId: string): Promise<void>`
+
+Request the TUI to switch to displaying the specified session. Only available in TUI+server mode.
+
+##### `on(eventType: SessionLifecycleEventType, handler): () => void`
+
+Subscribe to a specific session lifecycle event type. Returns an unsubscribe function.
+
+```typescript
+const unsubscribe = client.on("session.foreground", (event) => {
+    console.log(`Session ${event.sessionId} is now in foreground`);
+});
+```
+
+##### `on(handler: SessionLifecycleHandler): () => void`
+
+Subscribe to all session lifecycle events. Returns an unsubscribe function.
+
+```typescript
+const unsubscribe = client.on((event) => {
+    console.log(`${event.type}: ${event.sessionId}`);
+});
+```
+
+**Lifecycle Event Types:**
+- `session.created` - A new session was created
+- `session.deleted` - A session was deleted
+- `session.updated` - A session was updated (e.g., new messages)
+- `session.foreground` - A session became the foreground session in TUI
+- `session.background` - A session is no longer the foreground session
+
 ---
 
 ### CopilotSession
@@ -511,12 +547,12 @@ const session = await client.createSession({
         // request.question - The question to ask
         // request.choices - Optional array of choices for multiple choice
         // request.allowFreeform - Whether freeform input is allowed (default: true)
-        
+
         console.log(`Agent asks: ${request.question}`);
         if (request.choices) {
             console.log(`Choices: ${request.choices.join(", ")}`);
         }
-        
+
         // Return the user's response
         return {
             answer: "User's answer here",
@@ -544,7 +580,7 @@ const session = await client.createSession({
                 additionalContext: "Extra context for the model",
             };
         },
-        
+
         // Called after each tool execution
         onPostToolUse: async (input, invocation) => {
             console.log(`Tool ${input.toolName} completed`);
@@ -553,7 +589,7 @@ const session = await client.createSession({
                 additionalContext: "Post-execution notes",
             };
         },
-        
+
         // Called when user submits a prompt
         onUserPromptSubmitted: async (input, invocation) => {
             console.log(`User prompt: ${input.prompt}`);
@@ -561,7 +597,7 @@ const session = await client.createSession({
                 modifiedPrompt: input.prompt, // Optionally modify the prompt
             };
         },
-        
+
         // Called when session starts
         onSessionStart: async (input, invocation) => {
             console.log(`Session started from: ${input.source}`); // "startup", "resume", "new"
@@ -569,12 +605,12 @@ const session = await client.createSession({
                 additionalContext: "Session initialization context",
             };
         },
-        
+
         // Called when session ends
         onSessionEnd: async (input, invocation) => {
             console.log(`Session ended: ${input.reason}`);
         },
-        
+
         // Called when an error occurs
         onErrorOccurred: async (input, invocation) => {
             console.error(`Error in ${input.errorContext}: ${input.error}`);

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { CopilotSession } from "./session.js";
-import type { ConnectionState, CopilotClientOptions, GetAuthStatusResponse, GetStatusResponse, ModelInfo, ResumeSessionConfig, SessionConfig, SessionMetadata } from "./types.js";
+import type { ConnectionState, CopilotClientOptions, GetAuthStatusResponse, GetStatusResponse, ModelInfo, ResumeSessionConfig, SessionConfig, SessionLifecycleEventType, SessionLifecycleHandler, SessionMetadata, TypedSessionLifecycleHandler } from "./types.js";
 /**
  * Main client for interacting with the Copilot CLI.
  *
@@ -44,6 +44,10 @@ export declare class CopilotClient {
     private options;
     private isExternalServer;
     private forceStopping;
+    private modelsCache;
+    private modelsCacheLock;
+    private sessionLifecycleHandlers;
+    private typedLifecycleHandlers;
     /**
      * Creates a new CopilotClient instance.
      *
@@ -229,7 +233,11 @@ export declare class CopilotClient {
      */
     getAuthStatus(): Promise<GetAuthStatusResponse>;
     /**
-     * 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
      */
     listModels(): Promise<ModelInfo[]>;
@@ -288,6 +296,87 @@ export declare class CopilotClient {
      * ```
      */
     listSessions(): Promise<SessionMetadata[]>;
+    /**
+     * 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}`);
+     * }
+     * ```
+     */
+    getForegroundSessionId(): Promise<string | undefined>;
+    /**
+     * 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");
+     * ```
+     */
+    setForegroundSessionId(sessionId: string): Promise<void>;
+    /**
+     * Subscribes to a specific session lifecycle event type.
+     *
+     * Lifecycle events are emitted when sessions are created, deleted, updated,
+     * or change foreground/background state (in TUI+server mode).
+     *
+     * @param eventType - The specific event type to listen for
+     * @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 when a session becomes foreground in TUI
+     * const unsubscribe = client.on("session.foreground", (event) => {
+     *   console.log(`Session ${event.sessionId} is now displayed in TUI`);
+     * });
+     *
+     * // Later, to stop receiving events:
+     * unsubscribe();
+     * ```
+     */
+    on<K extends SessionLifecycleEventType>(eventType: K, handler: TypedSessionLifecycleHandler<K>): () => void;
+    /**
+     * Subscribes to all session lifecycle events.
+     *
+     * @param handler - A callback function that receives all lifecycle events
+     * @returns A function that, when called, unsubscribes the handler
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = client.on((event) => {
+     *   switch (event.type) {
+     *     case "session.foreground":
+     *       console.log(`Session ${event.sessionId} is now in foreground`);
+     *       break;
+     *     case "session.created":
+     *       console.log(`New session created: ${event.sessionId}`);
+     *       break;
+     *   }
+     * });
+     *
+     * // Later, to stop receiving events:
+     * unsubscribe();
+     * ```
+     */
+    on(handler: SessionLifecycleHandler): () => void;
     /**
      * Start the CLI server process
      */
@@ -306,6 +395,7 @@ export declare class CopilotClient {
     private connectViaTcp;
     private attachConnectionHandlers;
     private handleSessionEventNotification;
+    private handleSessionLifecycleNotification;
     private handleToolCallRequest;
     private executeToolCall;
     private handlePermissionRequest;

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.
    *
@@ -196,6 +200,7 @@ class CopilotClient {
       }
       this.connection = null;
     }
+    this.modelsCache = null;
     if (this.socket) {
       try {
         this.socket.end();
@@ -259,6 +264,7 @@ class CopilotClient {
       }
       this.connection = null;
     }
+    this.modelsCache = null;
     if (this.socket) {
       try {
         this.socket.destroy();
@@ -315,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,
@@ -384,6 +391,11 @@ class CopilotClient {
     }
     const response = await this.connection.sendRequest("session.resume", {
       sessionId,
+      model: config.model,
+      reasoningEffort: config.reasoningEffort,
+      systemMessage: config.systemMessage,
+      availableTools: config.availableTools,
+      excludedTools: config.excludedTools,
       tools: config.tools?.map((tool) => ({
         name: tool.name,
         description: tool.description,
@@ -394,11 +406,13 @@ class CopilotClient {
       requestUserInput: !!config.onUserInputRequest,
       hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
       workingDirectory: config.workingDirectory,
+      configDir: config.configDir,
       streaming: config.streaming,
       mcpServers: config.mcpServers,
       customAgents: config.customAgents,
       skillDirectories: config.skillDirectories,
       disabledSkills: config.disabledSkills,
+      infiniteSessions: config.infiniteSessions,
       disableResume: config.disableResume
     });
     const { sessionId: resumedSessionId, workspacePath } = response;
@@ -472,16 +486,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
@@ -583,6 +615,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
    */
@@ -590,7 +693,7 @@ class CopilotClient {
     return new Promise((resolve, reject) => {
       const args = [
         ...this.options.cliArgs,
-        "--server",
+        "--headless",
         "--log-level",
         this.options.logLevel
       ];
@@ -735,6 +838,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)
@@ -768,6 +874,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");

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, SessionEventPayload, SessionEventType, SessionMetadata, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageReplaceConfig, Tool, ToolHandler, ToolInvocation, ToolResultObject, TypedSessionEventHandler, 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.js

@@ -96,10 +96,11 @@ class CopilotSession {
         rejectWithError(error);
       }
     });
+    let timeoutId;
     try {
       await this.send(options);
       const timeoutPromise = new Promise((_, reject) => {
-        setTimeout(
+        timeoutId = setTimeout(
           () => reject(
             new Error(
               `Timeout after ${effectiveTimeout}ms waiting for session.idle`
@@ -111,6 +112,9 @@ class CopilotSession {
       await Promise.race([idlePromise, timeoutPromise]);
       return lastAssistantMessage;
     } finally {
+      if (timeoutId !== void 0) {
+        clearTimeout(timeoutId);
+      }
       unsubscribe();
     }
   }

package/dist/types.d.ts

@@ -490,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
@@ -500,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.
@@ -577,7 +587,7 @@ export interface SessionConfig {
 /**
  * Configuration for resuming a session
  */
-export type ResumeSessionConfig = Pick<SessionConfig, "tools" | "provider" | "streaming" | "onPermissionRequest" | "onUserInputRequest" | "hooks" | "workingDirectory" | "mcpServers" | "customAgents" | "skillDirectories" | "disabledSkills"> & {
+export type ResumeSessionConfig = Pick<SessionConfig, "model" | "tools" | "systemMessage" | "availableTools" | "excludedTools" | "provider" | "streaming" | "reasoningEffort" | "onPermissionRequest" | "onUserInputRequest" | "hooks" | "workingDirectory" | "configDir" | "mcpServers" | "customAgents" | "skillDirectories" | "disabledSkills" | "infiniteSessions"> & {
     /**
      * When true, skips emitting the session.resume event.
      * Useful for reconnecting to a session without triggering resume-related side effects.
@@ -630,12 +640,31 @@ export interface MessageOptions {
      */
     prompt: string;
     /**
-     * File or directory attachments
+     * File, directory, or selection attachments
      */
     attachments?: Array<{
-        type: "file" | "directory";
+        type: "file";
+        path: string;
+        displayName?: string;
+    } | {
+        type: "directory";
         path: string;
         displayName?: string;
+    } | {
+        type: "selection";
+        filePath: string;
+        displayName: string;
+        selection?: {
+            start: {
+                line: number;
+                character: number;
+            };
+            end: {
+                line: number;
+                character: number;
+            };
+        };
+        text?: string;
     }>;
     /**
      * Message delivery mode
@@ -706,6 +735,8 @@ export interface GetAuthStatusResponse {
 export interface ModelCapabilities {
     supports: {
         vision: boolean;
+        /** Whether this model supports reasoning effort configuration */
+        reasoningEffort: boolean;
     };
     limits: {
         max_prompt_tokens?: number;
@@ -744,5 +775,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.20",
+  "version": "0.1.22",
   "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -40,26 +40,26 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
-    "@github/copilot": "^0.0.399",
+    "@github/copilot": "^0.0.403",
     "vscode-jsonrpc": "^8.2.1",
-    "zod": "^4.3.5"
+    "zod": "^4.3.6"
   },
   "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",
+    "glob": "^13.0.1",
     "json-schema": "^0.4.0",
     "json-schema-to-typescript": "^15.0.4",
-    "prettier": "^3.4.0",
+    "prettier": "^3.8.1",
     "quicktype-core": "^23.2.6",
     "rimraf": "^6.1.2",
     "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"