@github/copilot-sdk 1.0.0-beta.4 → 1.0.0-beta.6

package/dist/client.js

@@ -22,11 +22,6 @@ import { CopilotSession, NO_RESULT_PERMISSION_V2_ERROR } from "./session.js";
 import { createSessionFsAdapter } from "./sessionFsProvider.js";
 import { getTraceContext } from "./telemetry.js";
 import { defaultJoinSessionPermissionHandler } from "./types.js";
-function toWireProviderConfig(provider) {
-  const { maxInputTokens, ...rest } = provider;
-  if (maxInputTokens === void 0) return rest;
-  return { ...rest, maxPromptTokens: maxInputTokens };
-}
 const MIN_PROTOCOL_VERSION = 2;
 function isZodSchema(value) {
   return value != null && typeof value === "object" && "toJSONSchema" in value && typeof value.toJSONSchema === "function";
@@ -38,6 +33,26 @@ function toJsonSchema(parameters) {
   }
   return parameters;
 }
+function toWireMcpServers(mcpServers) {
+  if (!mcpServers) return void 0;
+  return Object.fromEntries(
+    Object.entries(mcpServers).map(([name, server]) => {
+      if ("workingDirectory" in server) {
+        const { workingDirectory, ...rest } = server;
+        return [name, { ...rest, cwd: workingDirectory }];
+      }
+      return [name, server];
+    })
+  );
+}
+function toWireCustomAgents(agents) {
+  if (!agents) return void 0;
+  return agents.map((agent) => {
+    if (!agent.mcpServers) return agent;
+    const { mcpServers, ...rest } = agent;
+    return { ...rest, mcpServers: toWireMcpServers(mcpServers) };
+  });
+}
 function extractTransformCallbacks(systemMessage) {
   if (!systemMessage || systemMessage.mode !== "customize" || !systemMessage.sections) {
     return { wirePayload: systemMessage, transformCallbacks: void 0 };
@@ -91,12 +106,18 @@ class CopilotClient {
   cliProcess = null;
   connection = null;
   socket = null;
-  actualPort = null;
+  runtimePort = null;
   actualHost = "localhost";
   state = "disconnected";
   sessions = /* @__PURE__ */ new Map();
   stderrBuffer = "";
   // Captures CLI stderr for error messages
+  /** Resolved connection mode chosen in the constructor. */
+  connectionConfig;
+  /** Resolved path to the runtime executable (only used for child-process kinds). */
+  resolvedCliPath;
+  /** Resolved environment passed to the spawned runtime. */
+  resolvedEnv;
   options;
   isExternalServer = false;
   forceStopping = false;
@@ -145,86 +166,79 @@ class CopilotClient {
    * Creates a new CopilotClient instance.
    *
    * @param options - Configuration options for the client
-   * @throws Error if mutually exclusive options are provided (e.g., cliUrl with useStdio or cliPath)
    *
    * @example
    * ```typescript
-   * // Default options - spawns CLI server using stdio
+   * // Default: spawns the bundled runtime over stdio
    * const client = new CopilotClient();
    *
-   * // Connect to an existing server
-   * const client = new CopilotClient({ cliUrl: "localhost:3000" });
+   * // Connect to an existing runtime
+   * const client = new CopilotClient({
+   *   connection: RuntimeConnection.forUri("localhost:3000"),
+   * });
+   *
+   * // Spawn the runtime over TCP on a chosen port
+   * const client = new CopilotClient({
+   *   connection: RuntimeConnection.forTcp({ port: 9001 }),
+   * });
    *
-   * // Custom CLI path with specific log level
+   * // Use a custom runtime binary
    * const client = new CopilotClient({
-   *   cliPath: "/usr/local/bin/copilot",
-   *   logLevel: "debug"
+   *   connection: RuntimeConnection.forStdio({ path: "/usr/local/bin/copilot" }),
+   *   logLevel: "debug",
    * });
    * ```
    */
   constructor(options = {}) {
-    if (options.cliUrl && (options.useStdio === true || options.cliPath)) {
-      throw new Error("cliUrl is mutually exclusive with useStdio and cliPath");
-    }
-    if (options.isChildProcess && (options.cliUrl || options.useStdio === false)) {
+    const conn = options._internalConnection ?? options.connection ?? { kind: "stdio" };
+    if (conn.kind === "uri" && (options.gitHubToken !== void 0 || options.useLoggedInUser !== void 0)) {
       throw new Error(
-        "isChildProcess must be used in conjunction with useStdio and not with cliUrl"
+        "gitHubToken and useLoggedInUser cannot be used with RuntimeConnection.forUri (external server manages its own auth)"
       );
     }
-    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.tcpConnectionToken !== void 0) {
-      if (typeof options.tcpConnectionToken !== "string" || options.tcpConnectionToken.length === 0) {
-        throw new Error("tcpConnectionToken must be a non-empty string");
-      }
-      if (options.useStdio === true) {
-        throw new Error("tcpConnectionToken cannot be used with useStdio: true");
+    if (conn.kind === "tcp" && conn.connectionToken !== void 0) {
+      if (typeof conn.connectionToken !== "string" || conn.connectionToken.length === 0) {
+        throw new Error("connectionToken must be a non-empty string");
       }
     }
-    const willUseStdio = options.cliUrl ? false : options.useStdio ?? true;
-    const sdkSpawnsCli = !willUseStdio && !options.cliUrl && !options.isChildProcess;
-    this.effectiveConnectionToken = options.tcpConnectionToken ?? (sdkSpawnsCli ? randomUUID() : void 0);
+    this.connectionConfig = conn;
     if (options.sessionFs) {
       this.validateSessionFsConfig(options.sessionFs);
     }
-    if (options.cliUrl) {
-      const { host, port } = this.parseCliUrl(options.cliUrl);
+    if (conn.kind === "uri") {
+      const { host, port } = this.parseCliUrl(conn.url);
       this.actualHost = host;
-      this.actualPort = port;
+      this.runtimePort = port;
       this.isExternalServer = true;
-    }
-    if (options.isChildProcess) {
+    } else if (conn.kind === "parent-process") {
       this.isExternalServer = true;
     }
+    if (conn.kind === "tcp") {
+      this.effectiveConnectionToken = conn.connectionToken ?? randomUUID();
+    } else if (conn.kind === "uri") {
+      this.effectiveConnectionToken = conn.connectionToken;
+    }
     this.onListModels = options.onListModels;
     this.onGetTraceContext = options.onGetTraceContext;
     this.sessionFsConfig = options.sessionFs ?? null;
     const effectiveEnv = options.env ?? process.env;
+    this.resolvedEnv = effectiveEnv;
+    this.resolvedCliPath = conn.kind === "stdio" || conn.kind === "tcp" ? conn.path ?? effectiveEnv.COPILOT_CLI_PATH ?? getBundledCliPath() : void 0;
+    const connArgs = conn.kind === "stdio" || conn.kind === "tcp" ? conn.args ?? [] : [];
+    this.connectionExtraArgs = [...connArgs];
     this.options = {
-      cliPath: options.cliUrl ? void 0 : options.cliPath || effectiveEnv.COPILOT_CLI_PATH || getBundledCliPath(),
-      cliArgs: options.cliArgs ?? [],
-      cwd: options.cwd ?? process.cwd(),
-      port: options.port || 0,
-      useStdio: options.cliUrl ? false : options.useStdio ?? true,
-      // Default to stdio unless cliUrl is provided
-      isChildProcess: options.isChildProcess ?? false,
-      cliUrl: options.cliUrl,
-      logLevel: options.logLevel || "debug",
-      autoStart: options.autoStart ?? true,
-      autoRestart: false,
-      env: effectiveEnv,
+      workingDirectory: options.workingDirectory ?? process.cwd(),
+      logLevel: options.logLevel,
       gitHubToken: options.gitHubToken,
-      // Default useLoggedInUser to false when gitHubToken is provided, otherwise true
+      // Default useLoggedInUser to false when gitHubToken is provided, otherwise true.
       useLoggedInUser: options.useLoggedInUser ?? (options.gitHubToken ? false : true),
       telemetry: options.telemetry,
-      copilotHome: options.copilotHome,
+      baseDirectory: options.baseDirectory,
       sessionIdleTimeoutSeconds: options.sessionIdleTimeoutSeconds ?? 0,
-      remote: options.remote ?? false
+      enableRemoteSessions: options.enableRemoteSessions ?? false
     };
   }
+  connectionExtraArgs = [];
   /**
    * Parse CLI URL into host and port
    * Supports formats: "host:port", "http://host:port", "https://host:port", or just "port"
@@ -258,20 +272,37 @@ class CopilotClient {
       throw new Error("sessionFs.conventions must be either 'windows' or 'posix'");
     }
   }
+  setupSessionFs(session, config) {
+    if (!this.sessionFsConfig) {
+      return;
+    }
+    if (!config.createSessionFsProvider) {
+      throw new Error(
+        "createSessionFsProvider is required in session config when sessionFs is enabled in client options."
+      );
+    }
+    const provider = config.createSessionFsProvider(session);
+    if (this.sessionFsConfig.capabilities?.sqlite && !provider.sqlite) {
+      throw new Error(
+        "SessionFsConfig declares capabilities.sqlite but the provider does not implement sqlite."
+      );
+    }
+    session.clientSessionApis.sessionFs = createSessionFsAdapter(provider);
+  }
   /**
    * Starts the CLI server and establishes a connection.
    *
    * If connecting to an external server (via cliUrl), only establishes the connection.
    * Otherwise, spawns the CLI server process and then connects.
    *
-   * This method is called automatically when creating a session if `autoStart` is true (default).
+   * This method is called automatically the first time you create or resume a session.
    *
    * @returns A promise that resolves when the connection is established
    * @throws Error if the server fails to start or the connection fails
    *
    * @example
    * ```typescript
-   * const client = new CopilotClient({ autoStart: false });
+   * const client = new CopilotClient();
    * await client.start();
    * // Now ready to create sessions
    * ```
@@ -291,7 +322,8 @@ class CopilotClient {
         await this.connection.sendRequest("sessionFs.setProvider", {
           initialCwd: this.sessionFsConfig.initialCwd,
           sessionStatePath: this.sessionFsConfig.sessionStatePath,
-          conventions: this.sessionFsConfig.conventions
+          conventions: this.sessionFsConfig.conventions,
+          capabilities: this.sessionFsConfig.capabilities
         });
       }
       this.state = "connected";
@@ -365,8 +397,15 @@ class CopilotClient {
     }
     this.modelsCache = null;
     if (this.socket) {
+      const socket = this.socket;
+      this.socket = null;
       try {
-        this.socket.end();
+        if (!socket.destroyed) {
+          await new Promise((resolve) => {
+            socket.once("close", () => resolve());
+            socket.end();
+          });
+        }
       } catch (error) {
         errors.push(
           new Error(
@@ -374,11 +413,18 @@ class CopilotClient {
           )
         );
       }
-      this.socket = null;
     }
     if (this.cliProcess && !this.isExternalServer) {
+      const child = this.cliProcess;
+      this.cliProcess = null;
       try {
-        this.cliProcess.kill();
+        if (child.exitCode === null && child.signalCode === null) {
+          const exited = new Promise((resolve) => {
+            child.once("exit", () => resolve());
+          });
+          child.kill();
+          await exited;
+        }
       } catch (error) {
         errors.push(
           new Error(
@@ -386,18 +432,32 @@ class CopilotClient {
           )
         );
       }
-      this.cliProcess = null;
     }
     if (this.cliStartTimeout) {
       clearTimeout(this.cliStartTimeout);
       this.cliStartTimeout = null;
     }
     this.state = "disconnected";
-    this.actualPort = null;
+    this.runtimePort = null;
     this.stderrBuffer = "";
     this.processExitPromise = null;
     return errors;
   }
+  /**
+   * Alias for {@link stop} that lets `CopilotClient` participate in `await using`
+   * blocks for automatic cleanup.
+   *
+   * @example
+   * ```typescript
+   * await using client = new CopilotClient();
+   * const session = await client.createSession({ onPermissionRequest: approveAll });
+   * await session.sendAndWait("Hello");
+   * // client.stop() is called automatically when the block exits.
+   * ```
+   */
+  async [Symbol.asyncDispose]() {
+    await this.stop();
+  }
   /**
    * Forcefully stops the CLI server without graceful cleanup.
    *
@@ -454,7 +514,7 @@ class CopilotClient {
       this.cliStartTimeout = null;
     }
     this.state = "disconnected";
-    this.actualPort = null;
+    this.runtimePort = null;
     this.stderrBuffer = "";
     this.processExitPromise = null;
   }
@@ -462,12 +522,11 @@ class CopilotClient {
    * Creates a new conversation session with the Copilot CLI.
    *
    * Sessions maintain conversation state, handle events, and manage tool execution.
-   * If the client is not connected and `autoStart` is enabled, this will automatically
-   * start the connection.
+   * If the client is not connected, this method automatically starts the connection.
    *
    * @param config - Optional configuration for the session
    * @returns A promise that resolves with the created session
-   * @throws Error if the client is not connected and autoStart is disabled
+   * @throws Error if the client fails to start
    *
    * @example
    * ```typescript
@@ -488,17 +547,8 @@ class CopilotClient {
    * ```
    */
   async createSession(config) {
-    if (!config?.onPermissionRequest) {
-      throw new Error(
-        "An onPermissionRequest handler is required when creating a session. For example, to allow all permissions, use { onPermissionRequest: approveAll }."
-      );
-    }
     if (!this.connection) {
-      if (this.options.autoStart) {
-        await this.start();
-      } else {
-        throw new Error("Client not connected. Call start() first.");
-      }
+      await this.start();
     }
     const sessionId = config.sessionId ?? randomUUID();
     const session = new CopilotSession(
@@ -516,11 +566,11 @@ class CopilotClient {
     if (config.onElicitationRequest) {
       session.registerElicitationHandler(config.onElicitationRequest);
     }
-    if (config.onExitPlanMode) {
-      session.registerExitPlanModeHandler(config.onExitPlanMode);
+    if (config.onExitPlanModeRequest) {
+      session.registerExitPlanModeHandler(config.onExitPlanModeRequest);
     }
-    if (config.onAutoModeSwitch) {
-      session.registerAutoModeSwitchHandler(config.onAutoModeSwitch);
+    if (config.onAutoModeSwitchRequest) {
+      session.registerAutoModeSwitchHandler(config.onAutoModeSwitchRequest);
     }
     if (config.hooks) {
       session.registerHooks(config.hooks);
@@ -535,17 +585,7 @@ class CopilotClient {
       session.on(config.onEvent);
     }
     this.sessions.set(sessionId, session);
-    if (this.sessionFsConfig) {
-      if (config.createSessionFsHandler) {
-        session.clientSessionApis.sessionFs = createSessionFsAdapter(
-          config.createSessionFsHandler(session)
-        );
-      } else {
-        throw new Error(
-          "createSessionFsHandler is required in session config when sessionFs is enabled in client options."
-        );
-      }
-    }
+    this.setupSessionFs(session, config);
     try {
       const response = await this.connection.sendRequest("session.create", {
         ...await getTraceContext(this.onGetTraceContext),
@@ -567,21 +607,21 @@ class CopilotClient {
         systemMessage: wireSystemMessage,
         availableTools: config.availableTools,
         excludedTools: config.excludedTools,
-        provider: config.provider ? toWireProviderConfig(config.provider) : void 0,
+        provider: config.provider,
         enableSessionTelemetry: config.enableSessionTelemetry,
         modelCapabilities: config.modelCapabilities,
         requestPermission: true,
         requestUserInput: !!config.onUserInputRequest,
         requestElicitation: !!config.onElicitationRequest,
-        requestExitPlanMode: !!config.onExitPlanMode,
-        requestAutoModeSwitch: !!config.onAutoModeSwitch,
+        requestExitPlanMode: !!config.onExitPlanModeRequest,
+        requestAutoModeSwitch: !!config.onAutoModeSwitchRequest,
         hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
         workingDirectory: config.workingDirectory,
         streaming: config.streaming,
         includeSubAgentStreamingEvents: config.includeSubAgentStreamingEvents ?? true,
-        mcpServers: config.mcpServers,
+        mcpServers: toWireMcpServers(config.mcpServers),
         envValueMode: "direct",
-        customAgents: config.customAgents,
+        customAgents: toWireCustomAgents(config.customAgents),
         defaultAgent: config.defaultAgent,
         agent: config.agent,
         configDir: config.configDir,
@@ -590,7 +630,9 @@ class CopilotClient {
         instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
         infiniteSessions: config.infiniteSessions,
-        gitHubToken: config.gitHubToken
+        gitHubToken: config.gitHubToken,
+        remoteSession: config.remoteSession,
+        cloud: config.cloud
       });
       const { workspacePath, capabilities } = response;
       session["_workspacePath"] = workspacePath;
@@ -626,17 +668,8 @@ class CopilotClient {
    * ```
    */
   async resumeSession(sessionId, config) {
-    if (!config?.onPermissionRequest) {
-      throw new Error(
-        "An onPermissionRequest handler is required when resuming a session. For example, to allow all permissions, use { onPermissionRequest: approveAll }."
-      );
-    }
     if (!this.connection) {
-      if (this.options.autoStart) {
-        await this.start();
-      } else {
-        throw new Error("Client not connected. Call start() first.");
-      }
+      await this.start();
     }
     const session = new CopilotSession(
       sessionId,
@@ -653,11 +686,11 @@ class CopilotClient {
     if (config.onElicitationRequest) {
       session.registerElicitationHandler(config.onElicitationRequest);
     }
-    if (config.onExitPlanMode) {
-      session.registerExitPlanModeHandler(config.onExitPlanMode);
+    if (config.onExitPlanModeRequest) {
+      session.registerExitPlanModeHandler(config.onExitPlanModeRequest);
     }
-    if (config.onAutoModeSwitch) {
-      session.registerAutoModeSwitchHandler(config.onAutoModeSwitch);
+    if (config.onAutoModeSwitchRequest) {
+      session.registerAutoModeSwitchHandler(config.onAutoModeSwitchRequest);
     }
     if (config.hooks) {
       session.registerHooks(config.hooks);
@@ -672,17 +705,7 @@ class CopilotClient {
       session.on(config.onEvent);
     }
     this.sessions.set(sessionId, session);
-    if (this.sessionFsConfig) {
-      if (config.createSessionFsHandler) {
-        session.clientSessionApis.sessionFs = createSessionFsAdapter(
-          config.createSessionFsHandler(session)
-        );
-      } else {
-        throw new Error(
-          "createSessionFsHandler is required in session config when sessionFs is enabled in client options."
-        );
-      }
-    }
+    this.setupSessionFs(session, config);
     try {
       const response = await this.connection.sendRequest("session.resume", {
         ...await getTraceContext(this.onGetTraceContext),
@@ -705,31 +728,32 @@ class CopilotClient {
           name: cmd.name,
           description: cmd.description
         })),
-        provider: config.provider ? toWireProviderConfig(config.provider) : void 0,
+        provider: config.provider,
         modelCapabilities: config.modelCapabilities,
         requestPermission: config.onPermissionRequest !== defaultJoinSessionPermissionHandler,
         requestUserInput: !!config.onUserInputRequest,
         requestElicitation: !!config.onElicitationRequest,
-        requestExitPlanMode: !!config.onExitPlanMode,
-        requestAutoModeSwitch: !!config.onAutoModeSwitch,
+        requestExitPlanMode: !!config.onExitPlanModeRequest,
+        requestAutoModeSwitch: !!config.onAutoModeSwitchRequest,
         hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
         workingDirectory: config.workingDirectory,
         configDir: config.configDir,
         enableConfigDiscovery: config.enableConfigDiscovery,
         streaming: config.streaming,
         includeSubAgentStreamingEvents: config.includeSubAgentStreamingEvents ?? true,
-        mcpServers: config.mcpServers,
+        mcpServers: toWireMcpServers(config.mcpServers),
         envValueMode: "direct",
-        customAgents: config.customAgents,
+        customAgents: toWireCustomAgents(config.customAgents),
         defaultAgent: config.defaultAgent,
         agent: config.agent,
         skillDirectories: config.skillDirectories,
         instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
         infiniteSessions: config.infiniteSessions,
-        disableResume: config.disableResume,
+        suppressResumeEvent: config.suppressResumeEvent,
         continuePendingWork: config.continuePendingWork,
-        gitHubToken: config.gitHubToken
+        gitHubToken: config.gitHubToken,
+        remoteSession: config.remoteSession
       });
       const { workspacePath, capabilities } = response;
       session["_workspacePath"] = workspacePath;
@@ -956,8 +980,13 @@ class CopilotClient {
     if (!this.connection) {
       throw new Error("Client not connected");
     }
+    let wireFilter;
+    if (filter) {
+      const { workingDirectory, ...rest } = filter;
+      wireFilter = { ...rest, cwd: workingDirectory };
+    }
     const response = await this.connection.sendRequest("session.list", {
-      filter
+      filter: wireFilter
     });
     const { sessions } = response;
     return sessions.map(CopilotClient.toSessionMetadata);
@@ -992,13 +1021,19 @@ class CopilotClient {
     return CopilotClient.toSessionMetadata(session);
   }
   static toSessionMetadata(raw) {
+    const { context } = raw;
     return {
       sessionId: raw.sessionId,
       startTime: new Date(raw.startTime),
       modifiedTime: new Date(raw.modifiedTime),
       summary: raw.summary,
       isRemote: raw.isRemote,
-      context: raw.context
+      context: context ? {
+        workingDirectory: context.cwd,
+        gitRoot: context.gitRoot,
+        repository: context.repository,
+        branch: context.branch
+      } : void 0
     };
   }
   /**
@@ -1051,7 +1086,7 @@ class CopilotClient {
       throw new Error(result.error || "Failed to set foreground session");
     }
   }
-  on(eventTypeOrHandler, handler) {
+  onLifecycle(eventTypeOrHandler, handler) {
     if (typeof eventTypeOrHandler === "string" && handler) {
       const eventType = eventTypeOrHandler;
       if (!this.typedLifecycleHandlers.has(eventType)) {
@@ -1078,17 +1113,17 @@ class CopilotClient {
   async startCLIServer() {
     return new Promise((resolve, reject) => {
       this.stderrBuffer = "";
-      const args = [
-        ...this.options.cliArgs,
-        "--headless",
-        "--no-auto-update",
-        "--log-level",
-        this.options.logLevel
-      ];
-      if (this.options.useStdio) {
+      const args = [...this.connectionExtraArgs, "--headless", "--no-auto-update"];
+      if (this.options.logLevel) {
+        args.push("--log-level", this.options.logLevel);
+      }
+      if (this.connectionConfig.kind === "stdio") {
         args.push("--stdio");
-      } else if (this.options.port > 0) {
-        args.push("--port", this.options.port.toString());
+      } else if (this.connectionConfig.kind === "tcp") {
+        const requestedPort = this.connectionConfig.port ?? 0;
+        if (requestedPort > 0) {
+          args.push("--port", requestedPort.toString());
+        }
       }
       if (this.options.gitHubToken) {
         args.push("--auth-token-env", "COPILOT_SDK_AUTH_TOKEN");
@@ -1102,10 +1137,10 @@ class CopilotClient {
           this.options.sessionIdleTimeoutSeconds.toString()
         );
       }
-      if (this.options.remote) {
+      if (this.options.enableRemoteSessions) {
         args.push("--remote");
       }
-      const envWithoutNodeDebug = { ...this.options.env };
+      const envWithoutNodeDebug = { ...this.resolvedEnv };
       delete envWithoutNodeDebug.NODE_DEBUG;
       if (this.options.gitHubToken) {
         envWithoutNodeDebug.COPILOT_SDK_AUTH_TOKEN = this.options.gitHubToken;
@@ -1113,12 +1148,12 @@ class CopilotClient {
       if (this.effectiveConnectionToken) {
         envWithoutNodeDebug.COPILOT_CONNECTION_TOKEN = this.effectiveConnectionToken;
       }
-      if (this.options.copilotHome) {
-        envWithoutNodeDebug.COPILOT_HOME = this.options.copilotHome;
+      if (this.options.baseDirectory) {
+        envWithoutNodeDebug.COPILOT_HOME = this.options.baseDirectory;
       }
-      if (!this.options.cliPath) {
+      if (!this.resolvedCliPath) {
         throw new Error(
-          "Path to Copilot CLI is required. Please provide it via the cliPath option, or use cliUrl to rely on a remote CLI."
+          "Path to Copilot CLI is required. Please supply it via `RuntimeConnection.forStdio({ path })` or `RuntimeConnection.forTcp({ path })`, set the COPILOT_CLI_PATH environment variable, or use `RuntimeConnection.forUri(...)` to connect to an already-running runtime."
         );
       }
       if (this.options.telemetry) {
@@ -1137,31 +1172,31 @@ class CopilotClient {
             t.captureContent
           );
       }
-      if (!existsSync(this.options.cliPath)) {
+      if (!existsSync(this.resolvedCliPath)) {
         throw new Error(
-          `Copilot CLI not found at ${this.options.cliPath}. Ensure @github/copilot is installed.`
+          `Copilot CLI not found at ${this.resolvedCliPath}. Ensure @github/copilot is installed.`
         );
       }
-      const stdioConfig = this.options.useStdio ? ["pipe", "pipe", "pipe"] : ["ignore", "pipe", "pipe"];
-      const isJsFile = this.options.cliPath.endsWith(".js");
+      const stdioConfig = this.connectionConfig.kind === "stdio" ? ["pipe", "pipe", "pipe"] : ["ignore", "pipe", "pipe"];
+      const isJsFile = this.resolvedCliPath.endsWith(".js");
       if (isJsFile) {
-        this.cliProcess = spawn(getNodeExecPath(), [this.options.cliPath, ...args], {
+        this.cliProcess = spawn(getNodeExecPath(), [this.resolvedCliPath, ...args], {
           stdio: stdioConfig,
-          cwd: this.options.cwd,
+          cwd: this.options.workingDirectory,
           env: envWithoutNodeDebug,
           windowsHide: true
         });
       } else {
-        this.cliProcess = spawn(this.options.cliPath, args, {
+        this.cliProcess = spawn(this.resolvedCliPath, args, {
           stdio: stdioConfig,
-          cwd: this.options.cwd,
+          cwd: this.options.workingDirectory,
           env: envWithoutNodeDebug,
           windowsHide: true
         });
       }
       let stdout = "";
       let resolved = false;
-      if (this.options.useStdio) {
+      if (this.connectionConfig.kind === "stdio") {
         resolved = true;
         resolve();
       } else {
@@ -1169,7 +1204,7 @@ class CopilotClient {
           stdout += data.toString();
           const match = stdout.match(/listening on port (\d+)/i);
           if (match && !resolved) {
-            this.actualPort = parseInt(match[1], 10);
+            this.runtimePort = parseInt(match[1], 10);
             resolved = true;
             resolve();
           }
@@ -1243,19 +1278,21 @@ stderr: ${stderrOutput}`
           resolved = true;
           reject(new Error("Timeout waiting for CLI server to start"));
         }
-      }, 1e4);
+      }, 3e4);
     });
   }
   /**
    * Connect to the CLI server (via socket or stdio)
    */
   async connectToServer() {
-    if (this.options.isChildProcess) {
-      return this.connectToParentProcessViaStdio();
-    } else if (this.options.useStdio) {
-      return this.connectToChildProcessViaStdio();
-    } else {
-      return this.connectViaTcp();
+    switch (this.connectionConfig.kind) {
+      case "parent-process":
+        return this.connectToParentProcessViaStdio();
+      case "stdio":
+        return this.connectToChildProcessViaStdio();
+      case "tcp":
+      case "uri":
+        return this.connectViaTcp();
     }
   }
   /**
@@ -1295,12 +1332,17 @@ stderr: ${stderrOutput}`
    * Connect to the CLI server via TCP socket
    */
   async connectViaTcp() {
-    if (!this.actualPort) {
+    if (!this.runtimePort) {
       throw new Error("Server port not available");
     }
     return new Promise((resolve, reject) => {
       this.socket = new Socket();
-      this.socket.connect(this.actualPort, this.actualHost, () => {
+      const connectionTimeout = setTimeout(() => {
+        this.socket?.destroy();
+        reject(new Error("Timeout connecting to CLI server"));
+      }, 1e4);
+      this.socket.connect(this.runtimePort, this.actualHost, () => {
+        clearTimeout(connectionTimeout);
         this.connection = createMessageConnection(
           new StreamMessageReader(this.socket),
           new StreamMessageWriter(this.socket)
@@ -1310,6 +1352,7 @@ stderr: ${stderrOutput}`
         resolve();
       });
       this.socket.on("error", (error) => {
+        clearTimeout(connectionTimeout);
         reject(new Error(`Failed to connect to CLI server: ${error.message}`));
       });
     });
@@ -1378,7 +1421,20 @@ stderr: ${stderrOutput}`
     if (typeof notification !== "object" || !notification || !("type" in notification) || typeof notification.type !== "string" || !("sessionId" in notification) || typeof notification.sessionId !== "string") {
       return;
     }
-    const event = notification;
+    const raw = notification;
+    let metadata;
+    if (raw.metadata && raw.metadata.startTime && raw.metadata.modifiedTime) {
+      metadata = {
+        startTime: new Date(raw.metadata.startTime),
+        modifiedTime: new Date(raw.metadata.modifiedTime),
+        summary: raw.metadata.summary
+      };
+    }
+    const event = {
+      type: raw.type,
+      sessionId: raw.sessionId,
+      metadata
+    };
     const typedHandlers = this.typedLifecycleHandlers.get(event.type);
     if (typedHandlers) {
       for (const handler of typedHandlers) {