@github/copilot-sdk 1.0.15 → 1.0.16

package/README.md

@@ -37,6 +37,139 @@ verify all eight platforms.
 npm install @github/copilot-sdk
 ```
 
+## Runtime-supervised AHP host (experimental)
+
+`startAhpHost()` exposes copilotd's complete Agent Host Protocol server through the
+same runtime used by the SDK:
+
+```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+
+await using client = new CopilotClient();
+await client.start();
+const host = await client.startAhpHost({
+    localServer: {},
+    onExit: (exit) => {
+        if (exit.error) console.error(exit.error);
+    },
+});
+
+// Connect an AHP client using host.url and host.token.
+// Treat host.token as a secret; do not log it.
+
+// Existing SDK sessions and AHP sessions share this runtime.
+// Keep client alive while the listener is needed. Leaving this scope disposes
+// client, and the runtime stops its listener without a separate host.dispose().
+```
+
+The runtime hosts the complete AHP server in-process; the SDK does not launch a
+second runtime or relay the host's traffic. The host has its own SDK connection
+and belongs to the client connection that started it. Explicit disposal,
+connection loss, and runtime shutdown stop the listener and its hosting task
+without deleting underlying sessions. Reconnecting does not reclaim a host.
+The optional `onExit` callback reports exits at most once. If the owner connection
+is lost, it reports that loss rather than claiming that listener cleanup was
+acknowledged.
+
+`host.pid` is absent for in-process listeners. The optional field is retained
+for separate host process IDs returned by legacy runtimes, never the runtime PID.
+Use `dispose()` to stop the listener. `reason: "exited"` reports hosting-task
+failure, not runtime process death, and `exitCode` is absent. Hosting no longer
+provides process isolation from the runtime.
+
+Select at least one transport explicitly: `localServer: {}` enables the local
+listener, `githubEnvironment: { name: "My app", computeId: "stable-installation-id" }`
+registers a Mission Control environment and enables remote WPS connections, and
+both enables both transports. GitHub-only hosting opens no local listener;
+`host.url` and `host.token` are undefined, while `host.environmentId` identifies
+the environment. The application supplies a stable compute ID and configures
+transports only at startup. Dispose and recreate the host to change them.
+
+The runtime validates options inside `localServer` and applies their defaults:
+
+- `hostname` defaults to `127.0.0.1`. Set it explicitly to request a non-loopback
+  listener, such as `hostname: "0.0.0.0"`, and restrict network access appropriately.
+- `port` defaults to `0`, which selects an available port.
+- `requireConnectionToken` defaults to `true`. The runtime generates a random
+  token unless you supply a nonempty `token`.
+- Set `requireConnectionToken: false` to disable token authentication;
+  `host.token` is then undefined. A supplied `token` cannot be combined with
+  `requireConnectionToken: false`.
+
+The listener follows the owning client's lifetime. Call `await host.dispose()`
+only when you want to stop it earlier; `await using host` also supports a shorter
+scope. Each disposal call forwards to the runtime, which owns idempotent cleanup.
+The AHP transport remains owned by the host.
+
+### Application-owned sessions
+
+Supply `createSession` to materialize fresh AHP sessions in your application:
+
+```typescript
+import { approveAll, CopilotClient, defineTool } from "@github/copilot-sdk";
+
+await using client = new CopilotClient();
+await using host = await client.startAhpHost({
+    localServer: {},
+    createSession: ({ config, signal }) => {
+        signal.throwIfAborted();
+        return client.createSession({
+            ...config,
+            onPermissionRequest: approveAll,
+            systemMessage: { mode: "append", content: "Use the app's greeting tool." },
+            tools: [defineTool("greeting", {
+                description: "Get the application's greeting",
+                parameters: { type: "object", properties: {} },
+                handler: () => "Hello from the application!",
+            })],
+        });
+    },
+    onSessionReleased: async (originalSession) => {
+        // Optional: the app decides whether to disconnect, keep, or destroy it.
+        await originalSession.disconnect();
+    },
+});
+```
+
+Preserve the supplied `config`, including its fresh session identity, workspace,
+and selected host settings. Add your prompt and tools where the host has not
+explicitly selected those settings; conflicting settings fail rather than
+silently advertising configuration that was not applied. Return a normal session
+created by this same client. The creation factory does not adopt an arbitrary existing
+session or expose unrelated application sessions in the AHP catalog.
+
+Only the session ID returns through ordinary SDK RPC. The host attaches to **that same
+resident session**, adding its own callback/tool registrations without replacing
+the application's prompt, tool filters, hooks, or tools. Application tool functions
+continue running in the app while their results stream through the existing AHP
+projector. No second application connection or function serialization is involved.
+
+The SDK retains the original returned object until participation ends and invokes
+`onSessionReleased` at most once per handoff, including attach failure, hosting-task exit,
+and owner disconnection. The SDK never automatically disconnects or destroys the
+app object. The creation callback receives an abort signal; materialization
+is bounded to 30 seconds and cancellation also releases objects returned late.
+Graceful host disposal waits for AHP detach before reporting release. Omitting
+`createSession` preserves copilotd-owned creation.
+
+To restore durable application-owned sessions, also supply `resumeSession`.
+It receives `{ sessionId, config, signal }` (`AhpSessionResumeRequest`).
+Return the object from this client's `resumeSession(sessionId, { ...config,
+onPermissionRequest, ... })`, restoring your tools, hooks, and handlers.
+Alternatively, return a retained original session from this client when it
+still matches the requested identity and workspace.
+Only catalog entries marked as application-owned invoke this callback.
+If the callback is missing, restoring such an entry fails instead of falling
+back to host-owned creation.
+Published resident sessions attach directly, without invoking it or replacing
+their current registrations. Resumed sessions follow the same original-object
+retention, cancellation, late-result release, and `onSessionReleased` rules.
+
+The `copilotd-hosting` library runs inside the runtime provider.
+Development integrations require a
+source-built launcher and provider (`COPILOT_RUNTIME_PROVIDER_LIB`). Older
+runtimes without these RPC operations cannot start a host.
+
 ## Run the Sample
 
 Try the interactive chat sample (from the repo root):
@@ -188,6 +321,9 @@ Start the CLI server and establish connection.
 ##### `stop(): Promise<Error[]>`
 
 Stop the server and close all sessions. Returns a list of any errors encountered during cleanup.
+For an owned stdio runtime, closes stdin and waits up to 10 seconds for host cleanup
+(including telemetry export) and process exit before falling back to termination.
+This graceful-exit timeout is separate from the shutdown RPC and post-termination wait.
 
 ##### `forceStop(): Promise<void>`
 

package/dist/cjs/cliVersion.js

@@ -22,7 +22,7 @@ __export(cliVersion_exports, {
   COPILOT_CLI_VERSION: () => COPILOT_CLI_VERSION
 });
 module.exports = __toCommonJS(cliVersion_exports);
-const COPILOT_CLI_VERSION = "1.0.89";
+const COPILOT_CLI_VERSION = "1.0.90";
 const COPILOT_CLI_USE_NPM_PACKAGE = false;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/cjs/client.js

@@ -40,6 +40,7 @@ var import_node = require("vscode-jsonrpc/node.js");
 var import_rpc = require("./generated/rpc.js");
 var import_sdkProtocolVersion = require("./sdkProtocolVersion.js");
 var import_session = require("./session.js");
+var import_host = require("./host.js");
 var import_runtimeArtifacts = require("./runtimeArtifacts.js");
 var import_cliVersion = require("./cliVersion.js");
 var import_sessionFsProvider = require("./sessionFsProvider.js");
@@ -51,6 +52,57 @@ var import_toolSet = require("./toolSet.js");
 var import_types = require("./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 = (0, import_node.createMessageConnection)(
+    {
+      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 {
@@ -237,6 +289,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. */
@@ -528,6 +583,11 @@ class CopilotClient {
   }
   setupClientGlobalHandlers() {
     const handlers = {};
+    handlers.host = {
+      exited: async (exit) => {
+        this.handleHostExit(exit);
+      }
+    };
     handlers.extensionLaunchProvider = this.extensionLaunchProvider;
     if (this.requestHandler) {
       this.requestAdapter = (0, import_copilotRequestHandler.createCopilotRequestAdapter)(this.requestHandler, () => {
@@ -681,7 +741,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
@@ -799,7 +860,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();
@@ -817,6 +894,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) {
@@ -840,6 +921,7 @@ class CopilotClient {
     this.runtimePort = null;
     this.stderrBuffer = "";
     this.processExitPromise = null;
+    this.disconnectHosts();
     return errors;
   }
   /**
@@ -884,6 +966,7 @@ class CopilotClient {
    */
   async forceStop() {
     this.forceStopping = true;
+    this.disconnectHosts();
     for (const session of this.sessions.values()) {
       session._markDisconnected();
     }
@@ -1183,6 +1266,7 @@ class CopilotClient {
       const response = await this.connection.sendRequest("session.create", {
         ...await (0, import_telemetry.getTraceContext)(this.onGetTraceContext),
         model: config.model,
+        allowedModels: config.allowedModels,
         sessionId: localSessionId,
         clientName: config.clientName,
         reasoningEffort: config.reasoningEffort,
@@ -1313,6 +1397,11 @@ class CopilotClient {
       }
       throw e;
     }
+    for (const entry of this.hostHandoffs.values()) {
+      if (entry.requestedSessionId === session.sessionId) {
+        entry.configs.set(session, config);
+      }
+    }
     return session;
   }
   /**
@@ -1419,6 +1508,7 @@ class CopilotClient {
     }
     try {
       const response = await this.connection.sendRequest("session.resume", {
+        allowedModels: config.allowedModels,
         ...await (0, import_telemetry.getTraceContext)(this.onGetTraceContext),
         sessionId,
         clientName: config.clientName,
@@ -1547,8 +1637,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 = (0, import_node_crypto.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 import_host.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.
    *
@@ -2088,8 +2375,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. */
@@ -2148,7 +2440,7 @@ stderr: ${stderrOutput}`
       throw new Error("In-process FFI runtime host not started");
     }
     this.messageWriter = new TeardownResilientStreamMessageWriter(this.ffiHost.sendStream);
-    this.connection = (0, import_node.createMessageConnection)(
+    this.connection = createMessageConnection(
       new import_node.StreamMessageReader(this.ffiHost.receiveStream),
       this.messageWriter
     );
@@ -2202,7 +2494,7 @@ stderr: ${stderrOutput}` : ""}`
       }
     });
     this.messageWriter = new TeardownResilientStreamMessageWriter(this.cliProcess.stdin);
-    this.connection = (0, import_node.createMessageConnection)(
+    this.connection = createMessageConnection(
       new import_node.StreamMessageReader(this.cliProcess.stdout),
       this.messageWriter
     );
@@ -2217,7 +2509,7 @@ stderr: ${stderrOutput}` : ""}`
       throw new Error("CLI child process was unexpectedly started in parent process mode");
     }
     this.messageWriter = new TeardownResilientStreamMessageWriter(process.stdout);
-    this.connection = (0, import_node.createMessageConnection)(
+    this.connection = createMessageConnection(
       new import_node.StreamMessageReader(process.stdin),
       this.messageWriter
     );
@@ -2240,7 +2532,7 @@ stderr: ${stderrOutput}` : ""}`
       this.socket.connect(this.runtimePort, this.actualHost, () => {
         clearTimeout(connectionTimeout);
         this.messageWriter = new TeardownResilientStreamMessageWriter(this.socket);
-        this.connection = (0, import_node.createMessageConnection)(
+        this.connection = createMessageConnection(
           new import_node.StreamMessageReader(this.socket),
           this.messageWriter
         );
@@ -2297,6 +2589,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) => {
@@ -2304,20 +2608,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";