@github/copilot-sdk 1.0.15 → 1.0.16

package/dist/client.js

@@ -4,7 +4,7 @@ import { existsSync } from "node:fs";
 import { isIPv6, Socket } from "node:net";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import {
-  createMessageConnection,
+  createMessageConnection as createRpcMessageConnection,
   ErrorCodes,
   ResponseError,
   StreamMessageReader,
@@ -18,6 +18,7 @@ import {
 } from "./generated/rpc.js";
 import { getSdkProtocolVersion } from "./sdkProtocolVersion.js";
 import { CopilotSession } from "./session.js";
+import { AhpHost } from "./host.js";
 import { ensureRuntimeBundle } from "./runtimeArtifacts.js";
 import { COPILOT_CLI_VERSION } from "./cliVersion.js";
 import { createSessionFsAdapter } from "./sessionFsProvider.js";
@@ -31,6 +32,57 @@ import { ToolSet } from "./toolSet.js";
 import { defaultJoinSessionPermissionHandler } from "./types.js";
 const MIN_PROTOCOL_VERSION = 3;
 const RUNTIME_SHUTDOWN_TIMEOUT_MS = 1e4;
+function createMessageConnection(reader, writer) {
+  let dispatch;
+  let finishDrain;
+  let drained;
+  let disposed = false;
+  const barrier = { jsonrpc: "2.0", method: "$/sdkDrain" };
+  const connection = createRpcMessageConnection(
+    {
+      onError: reader.onError,
+      onClose: reader.onClose,
+      onPartialMessage: reader.onPartialMessage,
+      listen: (callback) => {
+        dispatch = callback;
+        return reader.listen(callback);
+      },
+      dispose: () => reader.dispose()
+    },
+    writer,
+    void 0,
+    {
+      messageStrategy: {
+        handleMessage: (message, next) => {
+          if (message === barrier) {
+            finishDrain?.();
+          } else {
+            next(message);
+          }
+        }
+      }
+    }
+  );
+  connection.onDispose(() => {
+    disposed = true;
+    finishDrain?.();
+  });
+  return Object.assign(connection, {
+    drain: () => {
+      if (!drained) {
+        drained = new Promise((resolve2) => {
+          finishDrain = resolve2;
+          if (disposed || !dispatch) {
+            resolve2();
+          } else {
+            dispatch(barrier);
+          }
+        });
+      }
+      return drained;
+    }
+  });
+}
 async function withTimeout(promise, timeoutMs, message) {
   let timeout;
   try {
@@ -217,6 +269,9 @@ class CopilotClient {
   /** Shared in-flight start; concurrent callers await it instead of spawning another CLI. */
   startPromise = null;
   sessions = /* @__PURE__ */ new Map();
+  hostExitCallbacks = /* @__PURE__ */ new Map();
+  hostSessionFactories = /* @__PURE__ */ new Map();
+  hostHandoffs = /* @__PURE__ */ new Map();
   stderrBuffer = "";
   // Captures CLI stderr for error messages
   /** Resolved connection mode chosen in the constructor. */
@@ -508,6 +563,11 @@ class CopilotClient {
   }
   setupClientGlobalHandlers() {
     const handlers = {};
+    handlers.host = {
+      exited: async (exit) => {
+        this.handleHostExit(exit);
+      }
+    };
     handlers.extensionLaunchProvider = this.extensionLaunchProvider;
     if (this.requestHandler) {
       this.requestAdapter = createCopilotRequestAdapter(this.requestHandler, () => {
@@ -661,7 +721,8 @@ class CopilotClient {
    * 1. Closes all active sessions (releases in-memory resources)
    * 2. Requests runtime shutdown for SDK-owned CLI processes
    * 3. Closes the JSON-RPC connection
-   * 4. Terminates the CLI server process (if spawned by this client)
+   * 4. Signals EOF to an owned stdio process and waits for host cleanup, then
+   *    terminates the process if it does not exit within the shutdown timeout
    *
    * Note: session data on disk is preserved, so sessions can be resumed later.
    * To permanently remove session data before stopping, call
@@ -779,7 +840,23 @@ class CopilotClient {
     }
     if (this.cliProcess && !this.isExternalServer) {
       const child = this.cliProcess;
-      this.cliProcess = null;
+      if (this.connectionConfig.kind === "stdio" && child.stdin && child.exitCode == null && child.signalCode == null) {
+        const gracefulExitStart = Date.now();
+        try {
+          child.stdin.end();
+          const exited = await waitForChildExit(child, RUNTIME_SHUTDOWN_TIMEOUT_MS);
+          this.logDebugTiming(
+            exited ? "CopilotClient.stop graceful stdio exit complete" : "CopilotClient.stop graceful stdio exit timed out; terminating child",
+            gracefulExitStart
+          );
+        } catch (error) {
+          errors.push(
+            new Error(
+              `Failed to close CLI stdin: ${error instanceof Error ? error.message : String(error)}`
+            )
+          );
+        }
+      }
       try {
         if (child.exitCode == null && child.signalCode == null) {
           child.kill();
@@ -797,6 +874,10 @@ class CopilotClient {
             `Failed to kill CLI process: ${error instanceof Error ? error.message : String(error)}`
           )
         );
+      } finally {
+        if (this.cliProcess === child) {
+          this.cliProcess = null;
+        }
       }
     }
     if (this.ffiHost) {
@@ -820,6 +901,7 @@ class CopilotClient {
     this.runtimePort = null;
     this.stderrBuffer = "";
     this.processExitPromise = null;
+    this.disconnectHosts();
     return errors;
   }
   /**
@@ -864,6 +946,7 @@ class CopilotClient {
    */
   async forceStop() {
     this.forceStopping = true;
+    this.disconnectHosts();
     for (const session of this.sessions.values()) {
       session._markDisconnected();
     }
@@ -1163,6 +1246,7 @@ class CopilotClient {
       const response = await this.connection.sendRequest("session.create", {
         ...await getTraceContext(this.onGetTraceContext),
         model: config.model,
+        allowedModels: config.allowedModels,
         sessionId: localSessionId,
         clientName: config.clientName,
         reasoningEffort: config.reasoningEffort,
@@ -1293,6 +1377,11 @@ class CopilotClient {
       }
       throw e;
     }
+    for (const entry of this.hostHandoffs.values()) {
+      if (entry.requestedSessionId === session.sessionId) {
+        entry.configs.set(session, config);
+      }
+    }
     return session;
   }
   /**
@@ -1399,6 +1488,7 @@ class CopilotClient {
     }
     try {
       const response = await this.connection.sendRequest("session.resume", {
+        allowedModels: config.allowedModels,
         ...await getTraceContext(this.onGetTraceContext),
         sessionId,
         clientName: config.clientName,
@@ -1527,8 +1617,205 @@ class CopilotClient {
       }
       throw e;
     }
+    for (const entry of this.hostHandoffs.values()) {
+      if (entry.requestedSessionId === session.sessionId) {
+        entry.configs.set(session, { ...config, sessionId });
+      }
+    }
     return session;
   }
+  /**
+   * Start a complete AHP listener hosted in-process by this runtime.
+   *
+   * This connection owns the host. Disposing it or disconnecting the client
+   * stops the listener without deleting sessions. The host uses a separate
+   * SDK connection to the same runtime, not another runtime process.
+   * Only one AHP host may own the catalog in an effective Copilot home
+   * at a time. Other SDK clients and sessions remain usable in that home.
+   * Select localServer, githubEnvironment, or both. An empty localServer
+   * selects 127.0.0.1 on an available port. `onExit` runs at most once; owner disconnection cannot
+   * acknowledge listener cleanup over the disconnected transport.
+   *
+   * @experimental
+   */
+  async startAhpHost(options) {
+    if (!options?.localServer && !options?.githubEnvironment) {
+      throw new Error("At least one of localServer or githubEnvironment is required");
+    }
+    if (this.state !== "connected") {
+      await this.start();
+    }
+    const rpc = this.rpc;
+    const hostId = randomUUID();
+    const {
+      localServer,
+      githubEnvironment,
+      onExit,
+      createSession,
+      resumeSession,
+      onSessionReleased
+    } = options;
+    if (createSession || resumeSession) {
+      this.hostSessionFactories.set(hostId, {
+        createSession,
+        resumeSession,
+        onSessionReleased
+      });
+    }
+    if (onExit) {
+      this.hostExitCallbacks.set(hostId, onExit);
+    }
+    try {
+      const info = await rpc.host.start({
+        hostId,
+        localServer,
+        githubEnvironment,
+        sessionFactory: createSession ? true : void 0,
+        resumeFactory: resumeSession ? true : void 0
+      });
+      return new AhpHost(
+        info,
+        async () => {
+          await rpc.host.dispose({ hostId });
+        },
+        (sessionId) => rpc.host.publishSession({ hostId, sessionId })
+      );
+    } catch (error) {
+      this.hostExitCallbacks.delete(hostId);
+      this.releaseHostSessions(hostId);
+      throw error;
+    }
+  }
+  handleHostExit(exit) {
+    this.releaseHostSessions(exit.hostId);
+    const onExit = this.hostExitCallbacks.get(exit.hostId);
+    if (onExit) {
+      this.hostExitCallbacks.delete(exit.hostId);
+      const reportError = (error) => {
+        console.error("AHP host exit callback failed", { hostId: exit.hostId, error });
+      };
+      try {
+        void Promise.resolve(onExit(exit)).catch(reportError);
+      } catch (error) {
+        reportError(error);
+      }
+    }
+  }
+  disconnectHosts() {
+    for (const hostId of /* @__PURE__ */ new Set([
+      ...this.hostExitCallbacks.keys(),
+      ...this.hostSessionFactories.keys()
+    ])) {
+      this.handleHostExit({
+        hostId,
+        reason: "ownerDisconnected",
+        error: "Owner connection closed; runtime cleanup cannot be acknowledged on this connection."
+      });
+    }
+  }
+  releaseHostSessions(hostId) {
+    this.hostSessionFactories.delete(hostId);
+    for (const [handoffId, entry] of this.hostHandoffs) {
+      if (entry.hostId === hostId) this.releaseHostSession(handoffId);
+    }
+  }
+  releaseHostSession(handoffId) {
+    const entry = this.hostHandoffs.get(handoffId);
+    if (!entry) return;
+    this.hostHandoffs.delete(handoffId);
+    entry.released = true;
+    entry.configs.clear();
+    entry.controller.abort();
+    if (entry.session) this.notifyHostSessionReleased(entry);
+  }
+  notifyHostSessionReleased(entry) {
+    const { session, onReleased } = entry;
+    entry.session = void 0;
+    if (session && onReleased) {
+      try {
+        void Promise.resolve(onReleased(session)).catch(() => {
+          console.error("AHP session release callback failed");
+        });
+      } catch {
+        console.error("AHP session release callback failed");
+      }
+    }
+  }
+  async createHostSession(params) {
+    const options = this.hostSessionFactories.get(params.hostId);
+    if (!(params.resume ? options?.resumeSession : options?.createSession) || this.hostHandoffs.has(params.handoffId)) {
+      throw new Error("AHP session factory is unavailable or handoff already exists");
+    }
+    const entry = {
+      hostId: params.hostId,
+      requestedSessionId: params.config.sessionId,
+      controller: new AbortController(),
+      configs: /* @__PURE__ */ new Map(),
+      released: false,
+      onReleased: options.onSessionReleased
+    };
+    this.hostHandoffs.set(params.handoffId, entry);
+    const { configDir, ...config } = params.config;
+    if (configDir !== void 0) config.configDirectory = configDir;
+    const expected = structuredClone(config);
+    const cancelled = new Promise((_resolve, reject) => {
+      entry.controller.signal.addEventListener(
+        "abort",
+        () => {
+          reject(new Error("AHP session handoff ended"));
+        },
+        { once: true }
+      );
+    });
+    const materialized = Promise.resolve().then(() => {
+      if (params.resume) {
+        const { sessionId, ...resumeConfig } = config;
+        if (!sessionId) throw new Error("AHP resume requires sessionId");
+        return options.resumeSession({
+          sessionId,
+          config: resumeConfig,
+          signal: entry.controller.signal
+        });
+      }
+      return options.createSession({
+        config,
+        signal: entry.controller.signal
+      });
+    }).then((session) => {
+      entry.session = session;
+      const actual = entry.configs.get(session);
+      entry.configs.clear();
+      if (entry.released) {
+        this.notifyHostSessionReleased(entry);
+        throw new Error("AHP session handoff ended");
+      }
+      if (this.sessions.get(session.sessionId) !== session || session.sessionId !== expected.sessionId) {
+        throw new Error(
+          "AHP callback must return the requested session from this client"
+        );
+      }
+      const contains = (value, required) => {
+        if (required && typeof required === "object" && !Array.isArray(required)) {
+          return !!value && typeof value === "object" && Object.entries(required).every(
+            ([key, child]) => contains(value[key], child)
+          );
+        }
+        return JSON.stringify(value) === JSON.stringify(required);
+      };
+      if ((!params.resume || actual !== void 0) && !contains(actual, expected)) {
+        throw new Error(
+          "AHP callback must preserve the supplied session configuration"
+        );
+      }
+      return { sessionId: session.sessionId };
+    });
+    try {
+      return await Promise.race([materialized, cancelled]);
+    } catch (error) {
+      this.releaseHostSession(params.handoffId);
+      throw error;
+    }
+  }
   /**
    * Sends a ping request to the server to verify connectivity.
    *
@@ -2068,8 +2355,13 @@ stderr: ${stderrOutput}`
       case "inprocess":
         return this.connectViaFfi();
       case "tcp":
-      case "uri":
         return this.connectViaTcp();
+      case "uri": {
+        const { host, port } = this.parseCliUrl(this.connectionConfig.url);
+        this.actualHost = host;
+        this.runtimePort = port;
+        return this.connectViaTcp();
+      }
     }
   }
   /** Starts the in-process FFI runtime with SDK-managed typed options. */
@@ -2277,6 +2569,18 @@ stderr: ${stderrOutput}` : ""}`
         (params, token) => confirmation.confirm(params, token)
       );
     }
+    this.connection.onRequest(
+      "host.materializeSession",
+      (params) => this.createHostSession(params)
+    );
+    this.connection.onNotification(
+      "host.sessionReleased",
+      (params) => {
+        if (this.hostHandoffs.get(params.handoffId)?.hostId === params.hostId) {
+          this.releaseHostSession(params.handoffId);
+        }
+      }
+    );
     this.connection.onRequest(
       "hooks.invoke",
       async (params) => {
@@ -2284,20 +2588,27 @@ stderr: ${stderrOutput}` : ""}`
       }
     );
     const connection = this.connection;
+    const messageWriter = this.messageWriter;
     const markDisconnected = () => {
       if (this.connection !== connection) {
+        connection.dispose();
         return;
       }
       this.connectionClosed = true;
       this.state = "disconnected";
+      this.disconnectHosts();
       for (const session of this.sessions.values()) {
         session._markDisconnected();
       }
       this.sessions.clear();
       this.githubTokenProviders.clear();
       this.requestAdapter?.cancelPending();
+      connection.dispose();
     };
-    this.connection.onClose(markDisconnected);
+    this.connection.onClose(() => {
+      if (messageWriter) messageWriter.suppressWriteErrors = true;
+      void connection.drain().then(markDisconnected);
+    });
     this.connection.onError(() => {
       if (this.connection === connection) {
         this.state = "disconnected";