@github/copilot-sdk 1.0.0-beta.5 → 1.0.0-beta.7

package/dist/client.js

@@ -17,17 +17,15 @@ import {
   createInternalServerRpc,
   registerClientSessionApiHandlers
 } from "./generated/rpc.js";
+import {
+  dispatchCanvasProviderRequest
+} from "./canvas.js";
 import { getSdkProtocolVersion } from "./sdkProtocolVersion.js";
-import { CopilotSession, NO_RESULT_PERMISSION_V2_ERROR } from "./session.js";
+import { CopilotSession } 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;
+const MIN_PROTOCOL_VERSION = 3;
 function isZodSchema(value) {
   return value != null && typeof value === "object" && "toJSONSchema" in value && typeof value.toJSONSchema === "function";
 }
@@ -38,6 +36,36 @@ 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 isCanvasProviderRequestParams(params) {
+  if (!params || typeof params !== "object") {
+    return false;
+  }
+  const request = params;
+  return typeof request.sessionId === "string" && typeof request.extensionId === "string" && typeof request.canvasId === "string" && typeof request.instanceId === "string";
+}
+function isCanvasActionInvokeParams(params) {
+  return isCanvasProviderRequestParams(params) && typeof params.actionName === "string";
+}
 function extractTransformCallbacks(systemMessage) {
   if (!systemMessage || systemMessage.mode !== "customize" || !systemMessage.sections) {
     return { wirePayload: systemMessage, transformCallbacks: void 0 };
@@ -91,12 +119,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 +179,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"),
+   * });
    *
-   * // Custom CLI path with specific log level
+   * // Spawn the runtime over TCP on a chosen port
    * const client = new CopilotClient({
-   *   cliPath: "/usr/local/bin/copilot",
-   *   logLevel: "debug"
+   *   connection: RuntimeConnection.forTcp({ port: 9001 }),
+   * });
+   *
+   * // Use a custom runtime binary
+   * const client = new CopilotClient({
+   *   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)) {
-      throw new Error(
-        "isChildProcess must be used in conjunction with useStdio and not with cliUrl"
-      );
-    }
-    if (options.cliUrl && (options.gitHubToken || options.useLoggedInUser !== void 0)) {
+    const conn = options._internalConnection ?? options.connection ?? { kind: "stdio" };
+    if (conn.kind === "uri" && (options.gitHubToken !== void 0 || options.useLoggedInUser !== void 0)) {
       throw new Error(
-        "gitHubToken and useLoggedInUser cannot be used with cliUrl (external server manages its own auth)"
+        "gitHubToken and useLoggedInUser cannot be used with RuntimeConnection.forUri (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"
@@ -262,12 +289,12 @@ class CopilotClient {
     if (!this.sessionFsConfig) {
       return;
     }
-    if (!config.createSessionFsHandler) {
+    if (!config.createSessionFsProvider) {
       throw new Error(
-        "createSessionFsHandler is required in session config when sessionFs is enabled in client options."
+        "createSessionFsProvider is required in session config when sessionFs is enabled in client options."
       );
     }
-    const provider = config.createSessionFsHandler(session);
+    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."
@@ -281,14 +308,14 @@ class CopilotClient {
    * 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
    * ```
@@ -383,8 +410,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(
@@ -392,11 +426,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(
@@ -404,18 +445,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.
    *
@@ -472,7 +527,7 @@ class CopilotClient {
       this.cliStartTimeout = null;
     }
     this.state = "disconnected";
-    this.actualPort = null;
+    this.runtimePort = null;
     this.stderrBuffer = "";
     this.processExitPromise = null;
   }
@@ -480,12 +535,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
@@ -507,11 +561,7 @@ class CopilotClient {
    */
   async createSession(config) {
     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(
@@ -521,6 +571,7 @@ class CopilotClient {
       this.onGetTraceContext
     );
     session.registerTools(config.tools);
+    session.registerCanvases(config.canvases);
     session.registerCommands(config.commands);
     session.registerPermissionHandler(config.onPermissionRequest);
     if (config.onUserInputRequest) {
@@ -529,11 +580,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);
@@ -563,6 +614,10 @@ class CopilotClient {
           overridesBuiltInTool: tool.overridesBuiltInTool,
           skipPermission: tool.skipPermission
         })),
+        canvases: config.canvases?.map((canvas) => canvas.declaration),
+        requestCanvasRenderer: config.requestCanvasRenderer,
+        requestExtensions: config.requestExtensions,
+        extensionInfo: config.extensionInfo,
         commands: config.commands?.map((cmd) => ({
           name: cmd.name,
           description: cmd.description
@@ -570,21 +625,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,
+        requestPermission: !!config.onPermissionRequest,
         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,
@@ -632,11 +687,7 @@ class CopilotClient {
    */
   async resumeSession(sessionId, config) {
     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,
@@ -645,6 +696,7 @@ class CopilotClient {
       this.onGetTraceContext
     );
     session.registerTools(config.tools);
+    session.registerCanvases(config.canvases);
     session.registerCommands(config.commands);
     session.registerPermissionHandler(config.onPermissionRequest);
     if (config.onUserInputRequest) {
@@ -653,11 +705,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);
@@ -691,61 +743,52 @@ class CopilotClient {
           overridesBuiltInTool: tool.overridesBuiltInTool,
           skipPermission: tool.skipPermission
         })),
+        canvases: config.canvases?.map((canvas) => canvas.declaration),
+        requestCanvasRenderer: config.requestCanvasRenderer,
+        requestExtensions: config.requestExtensions,
+        extensionInfo: config.extensionInfo,
         commands: config.commands?.map((cmd) => ({
           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,
-        remoteSession: config.remoteSession
+        remoteSession: config.remoteSession,
+        openCanvases: config.openCanvases
       });
-      const { workspacePath, capabilities } = response;
+      const { workspacePath, capabilities, openCanvases } = response;
       session["_workspacePath"] = workspacePath;
       session.setCapabilities(capabilities);
+      session.setOpenCanvases(openCanvases ?? []);
     } catch (e) {
       this.sessions.delete(sessionId);
       throw e;
     }
     return session;
   }
-  /**
-   * Gets the current connection state of the client.
-   *
-   * @returns The current connection state: "disconnected", "connecting", "connected", or "error"
-   *
-   * @example
-   * ```typescript
-   * if (client.getState() === "connected") {
-   *   const session = await client.createSession({ onPermissionRequest: approveAll });
-   * }
-   * ```
-   */
-  getState() {
-    return this.state;
-  }
   /**
    * Sends a ping request to the server to verify connectivity.
    *
@@ -947,8 +990,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);
@@ -983,13 +1031,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
     };
   }
   /**
@@ -1042,7 +1096,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)) {
@@ -1069,17 +1123,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");
@@ -1093,10 +1147,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;
@@ -1104,12 +1158,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) {
@@ -1128,31 +1182,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 {
@@ -1160,7 +1214,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();
           }
@@ -1234,19 +1288,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();
     }
   }
   /**
@@ -1286,7 +1342,7 @@ 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) => {
@@ -1295,7 +1351,7 @@ stderr: ${stderrOutput}`
         this.socket?.destroy();
         reject(new Error("Timeout connecting to CLI server"));
       }, 1e4);
-      this.socket.connect(this.actualPort, this.actualHost, () => {
+      this.socket.connect(this.runtimePort, this.actualHost, () => {
         clearTimeout(connectionTimeout);
         this.connection = createMessageConnection(
           new StreamMessageReader(this.socket),
@@ -1321,14 +1377,6 @@ stderr: ${stderrOutput}`
     this.connection.onNotification("session.lifecycle", (notification) => {
       this.handleSessionLifecycleNotification(notification);
     });
-    this.connection.onRequest(
-      "tool.call",
-      async (params) => await this.handleToolCallRequestV2(params)
-    );
-    this.connection.onRequest(
-      "permission.request",
-      async (params) => await this.handlePermissionRequestV2(params)
-    );
     this.connection.onRequest(
       "userInput.request",
       async (params) => await this.handleUserInputRequest(params)
@@ -1349,6 +1397,18 @@ stderr: ${stderrOutput}`
       "systemMessage.transform",
       async (params) => await this.handleSystemMessageTransform(params)
     );
+    this.connection.onRequest(
+      "canvas.open",
+      async (params) => this.handleCanvasProviderRequest("canvas.open", params)
+    );
+    this.connection.onRequest(
+      "canvas.close",
+      async (params) => this.handleCanvasProviderRequest("canvas.close", params)
+    );
+    this.connection.onRequest(
+      "canvas.action.invoke",
+      async (params) => this.handleCanvasActionInvokeRequest(params)
+    );
     const sessions = this.sessions;
     registerClientSessionApiHandlers(this.connection, (sessionId) => {
       const session = sessions.get(sessionId);
@@ -1375,7 +1435,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) {
@@ -1457,104 +1530,25 @@ stderr: ${stderrOutput}`
     }
     return await session._handleSystemMessageTransform(params.sections);
   }
-  // ========================================================================
-  // Protocol v2 backward-compatibility adapters
-  // ========================================================================
-  /**
-   * Handles a v2-style tool.call RPC request from the server.
-   * Looks up the session and tool handler, executes it, and returns the result
-   * in the v2 response format.
-   */
-  async handleToolCallRequestV2(params) {
-    if (!params || typeof params.sessionId !== "string" || typeof params.toolCallId !== "string" || typeof params.toolName !== "string") {
-      throw new Error("Invalid tool call payload");
-    }
-    const session = this.sessions.get(params.sessionId);
-    if (!session) {
-      throw new Error(`Unknown session ${params.sessionId}`);
-    }
-    const handler = session.getToolHandler(params.toolName);
-    if (!handler) {
-      return {
-        result: {
-          textResultForLlm: `Tool '${params.toolName}' is not supported by this client instance.`,
-          resultType: "failure",
-          error: `tool '${params.toolName}' not supported`,
-          toolTelemetry: {}
-        }
-      };
-    }
-    try {
-      const traceparent = params.traceparent;
-      const tracestate = params.tracestate;
-      const invocation = {
-        sessionId: params.sessionId,
-        toolCallId: params.toolCallId,
-        toolName: params.toolName,
-        arguments: params.arguments,
-        traceparent,
-        tracestate
-      };
-      const result = await handler(params.arguments, invocation);
-      return { result: this.normalizeToolResultV2(result) };
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      return {
-        result: {
-          textResultForLlm: "Invoking this tool produced an error. Detailed information is not available.",
-          resultType: "failure",
-          error: message,
-          toolTelemetry: {}
-        }
-      };
-    }
-  }
-  /**
-   * Handles a v2-style permission.request RPC request from the server.
-   */
-  async handlePermissionRequestV2(params) {
-    if (!params || typeof params.sessionId !== "string" || !params.permissionRequest) {
-      throw new Error("Invalid permission request payload");
+  async handleCanvasProviderRequest(actionName, params) {
+    if (!isCanvasProviderRequestParams(params)) {
+      throw new Error("Invalid canvas provider request payload");
     }
     const session = this.sessions.get(params.sessionId);
     if (!session) {
       throw new Error(`Session not found: ${params.sessionId}`);
     }
-    try {
-      const result = await session._handlePermissionRequestV2(params.permissionRequest);
-      return { result };
-    } catch (error) {
-      if (error instanceof Error && error.message === NO_RESULT_PERMISSION_V2_ERROR) {
-        throw error;
-      }
-      return {
-        result: {
-          kind: "user-not-available"
-        }
-      };
+    const canvas = session.getCanvas(params.canvasId);
+    if (!canvas) {
+      throw new Error(`No canvas registered with id "${params.canvasId}"`);
     }
+    return dispatchCanvasProviderRequest(canvas, actionName, params);
   }
-  normalizeToolResultV2(result) {
-    if (result === void 0 || result === null) {
-      return {
-        textResultForLlm: "Tool returned no result",
-        resultType: "failure",
-        error: "tool returned no result",
-        toolTelemetry: {}
-      };
-    }
-    if (this.isToolResultObject(result)) {
-      return result;
+  async handleCanvasActionInvokeRequest(params) {
+    if (!isCanvasActionInvokeParams(params)) {
+      throw new Error("Invalid canvas provider request payload");
     }
-    const textResult = typeof result === "string" ? result : JSON.stringify(result);
-    return {
-      textResultForLlm: textResult,
-      resultType: "success",
-      toolTelemetry: {}
-    };
-  }
-  isToolResultObject(value) {
-    return typeof value === "object" && value !== null && "textResultForLlm" in value && typeof value.textResultForLlm === "string" && "resultType" in value;
+    return this.handleCanvasProviderRequest(params.actionName, params);
   }
 }
 export {