@github/copilot-sdk 1.0.13 → 1.0.14-preview.1

package/dist/client.js

@@ -219,6 +219,8 @@ class CopilotClient {
   runtimePort = null;
   actualHost = "localhost";
   state = "disconnected";
+  /** Shared in-flight start; concurrent callers await it instead of spawning another CLI. */
+  startPromise = null;
   sessions = /* @__PURE__ */ new Map();
   stderrBuffer = "";
   // Captures CLI stderr for error messages
@@ -596,6 +598,17 @@ class CopilotClient {
     if (this.state === "connected") {
       return;
     }
+    if (this.startPromise) {
+      return this.startPromise;
+    }
+    this.startPromise = this.doStart();
+    try {
+      await this.startPromise;
+    } finally {
+      this.startPromise = null;
+    }
+  }
+  async doStart() {
     this.forceStopping = false;
     this.connectionClosed = false;
     this.processTransportError = null;
@@ -785,7 +798,7 @@ class CopilotClient {
       const host = this.ffiHost;
       this.ffiHost = null;
       try {
-        host.dispose();
+        await host.dispose();
       } catch (error) {
         errors.push(
           new Error(
@@ -880,11 +893,12 @@ class CopilotClient {
       this.cliProcess = null;
     }
     if (this.ffiHost) {
+      const host = this.ffiHost;
+      this.ffiHost = null;
       try {
-        this.ffiHost.dispose();
+        await host.dispose();
       } catch {
       }
-      this.ffiHost = null;
     }
     if (this.cliStartTimeout) {
       clearTimeout(this.cliStartTimeout);
@@ -1201,6 +1215,7 @@ class CopilotClient {
         ...this.onGitHubTelemetry != null ? { enableGitHubTelemetryForwarding: true } : {},
         mcpServers: toWireMcpServers(config.mcpServers),
         mcpOAuthTokenStorage: config.mcpOAuthTokenStorage,
+        authClientIdMetadataUrl: config.authClientIdMetadataUrl,
         envValueMode: "direct",
         customAgents: toWireCustomAgents(config.customAgents),
         customAgentsLocalOnly: config.customAgentsLocalOnly,
@@ -1446,6 +1461,7 @@ class CopilotClient {
         ...this.onGitHubTelemetry != null ? { enableGitHubTelemetryForwarding: true } : {},
         mcpServers: toWireMcpServers(config.mcpServers),
         mcpOAuthTokenStorage: config.mcpOAuthTokenStorage,
+        authClientIdMetadataUrl: config.authClientIdMetadataUrl,
         envValueMode: "direct",
         customAgents: toWireCustomAgents(config.customAgents),
         customAgentsLocalOnly: config.customAgentsLocalOnly,

package/dist/factory.d.ts

@@ -1,7 +1,7 @@
 import type { FactoryGetRunProgressRequest, FactoryListRunsRequest, FactoryListRunsResult, FactoryProgressPage, FactoryRunDetail, FactoryRunResult, FactoryRunStatus, FactoryRunSummary } from "./generated/rpc.js";
 import type { ContextTier } from "./generated/session-events.js";
 import type { CopilotSession } from "./session.js";
-import type { FactoryLimits, FactoryMeta } from "./types.js";
+import type { FactoryMeta } from "./types.js";
 export type { FactoryRunResult };
 export type { FactoryAgentSummary, FactoryPhaseStatus, FactoryPhaseObservation, FactoryProgressLine, FactoryProgressPage, FactoryRunDetail, FactoryRunStatus, FactoryRunSummary, } from "./generated/rpc.js";
 /**
@@ -81,6 +81,21 @@ export interface FactoryStepOptions {
     /** Skip the journal and always invoke the producer. */
     volatile?: boolean;
 }
+/**
+ * Per-invocation factory resource ceiling overrides.
+ *
+ * An omitted field preserves the existing/default ceiling, a number replaces
+ * it, and `null` explicitly makes that dimension unlimited.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface FactoryLimitOverrides {
+    maxConcurrentSubagents?: number | null;
+    maxTotalSubagents?: number | null;
+    maxAiCredits?: number | null;
+    timeoutSeconds?: number | null;
+}
 /**
  * One stage in a per-item factory pipeline.
  *
@@ -101,6 +116,13 @@ export interface FactoryContext<TArgs extends JsonValue = JsonValue> {
     agent(prompt: string, options?: FactoryAgentOptions): Promise<unknown>;
     /** Memoize an arbitrary producer under a stable author-supplied key. */
     step(key: string, producer: () => Promise<JsonValue> | JsonValue, options?: FactoryStepOptions): Promise<JsonValue>;
+    /**
+     * Pause this run at a durable, one-shot checkpoint.
+     *
+     * The first attempt to reach a key pauses and aborts cooperatively. A
+     * resumed attempt returns from the same key and continues.
+     */
+    pause(key: string): Promise<void>;
     /**
      * Run thunks concurrently and await all of them.
      *
@@ -129,7 +151,7 @@ export interface FactoryContext<TArgs extends JsonValue = JsonValue> {
     args: TArgs;
     /**
      * The session instance returned by `joinSession`. It refuses calls that
-     * start or resume a factory run.
+     * start, resume, or pause a factory run.
      */
     session: CopilotSession;
     /** Cooperative cancellation signal for the current factory run. */
@@ -178,7 +200,7 @@ export interface RunOptions<TArgs extends JsonValue = JsonValue> {
     /** Input surfaced as `context.args`. */
     args?: TArgs;
     /** Optional per-invocation resource ceiling overrides. */
-    limits?: FactoryLimits;
+    limits?: FactoryLimitOverrides;
     /** Whether to notify the originating session when the factory completes. */
     notifyOnComplete?: boolean;
     /** Whether to emit factory phase names to the session transcript. */
@@ -198,7 +220,7 @@ export interface RunOptions<TArgs extends JsonValue = JsonValue> {
  */
 export interface ResumeOptions {
     /** Optional per-invocation resource ceiling overrides. */
-    limits?: FactoryLimits;
+    limits?: FactoryLimitOverrides;
     /** Whether to notify the originating session when the factory completes. */
     notifyOnComplete?: boolean;
     /** Whether to emit factory phase names to the session transcript. */
@@ -222,13 +244,14 @@ export interface SessionFactoryApi {
      * Run a registered factory and resolve with its run envelope.
      *
      * The envelope is returned for every outcome, including `error`, `halted`,
-     * and `cancelled` — inspect `status` and read `result` only when the run
-     * completed. SDK-initiated runs do not request permission, so they have no
-     * declined outcome. The model's `run_factory` tool requests permission
-     * before a durable row exists; declining it creates no run row. Failures
-     * that occur before a run exists (such as an unknown factory or attempting
-     * to start a run while the session is at its active top-level run limit)
-     * still reject.
+     * `paused`, and `cancelled` — inspect `status` and read `result` only when
+     * the run completed. `paused` settles the current attempt, but the same
+     * durable run can later resume under its existing run ID. SDK-initiated
+     * runs do not request permission, so they have no declined outcome. The
+     * model's `run_factory` tool requests permission before a durable row
+     * exists; declining it creates no run row. Failures that occur before a run
+     * exists (such as an unknown factory or attempting to start a run while the
+     * session is at its active top-level run limit) still reject.
      */
     run(name: string, options?: RunOptions): Promise<FactoryRunResult>;
     run<TArgs extends JsonValue>(factory: FactoryHandle<TArgs, JsonValue | void>, options?: RunOptions<TArgs>): Promise<FactoryRunResult>;
@@ -243,12 +266,13 @@ export interface SessionFactoryApi {
     /** Read the latest durable envelope for a factory run. */
     getRun(runId: string): Promise<FactoryRunResult>;
     /**
-     * Wait for a run to settle and resolve with its terminal envelope.
+     * Wait for the current attempt to settle and resolve with its envelope.
      *
-     * Resolves as soon as the run reaches `completed`, `error`, `halted`, or
-     * `cancelled`, and resolves immediately when it has already settled. A
-     * terminal envelope is final, so the resolved value never changes
-     * afterwards.
+     * Resolves as soon as the run reaches `completed`, `error`, `halted`,
+     * `paused`, or `cancelled`, and resolves immediately when the current
+     * attempt has already settled. A `paused` envelope is an attempt-level
+     * snapshot: resuming the same durable run can later change the envelope
+     * returned by {@link SessionFactoryApi.getRun}.
      *
      * This watches the run's `factory.run_updated` invalidation events and
      * periodically re-reads the durable envelope so a missed event cannot
@@ -279,6 +303,8 @@ export interface SessionFactoryApi {
     getRunDetail(runId: string): Promise<FactoryRunDetail>;
     /** Page durable progress forward, backward, or from the latest tail. */
     getRunProgress(runId: string, options?: Omit<FactoryGetRunProgressRequest, "runId">): Promise<FactoryProgressPage>;
+    /** Pause a running factory attempt and return its `paused` envelope. */
+    pause(runId: string): Promise<FactoryRunResult>;
     /** Cancel a factory run and return its terminal envelope. */
     cancel(runId: string): Promise<FactoryRunResult>;
 }

package/dist/factory.js

@@ -1,6 +1,7 @@
 const FACTORY_TERMINAL_STATUSES = /* @__PURE__ */ new Set([
   "completed",
   "halted",
+  "paused",
   "cancelled",
   "error"
 ]);

package/dist/ffiRuntimeHost.d.ts

@@ -4,12 +4,16 @@ export declare class FfiRuntimeHost {
     private readonly cliEntrypoint;
     private readonly environment;
     private readonly args;
+    private static readonly quarantinedHosts;
     private readonly lib;
     private serverId;
     private connectionId;
     private disposed;
+    private starting;
     private outboundCallback;
     private keepAliveTimer;
+    private cleanupRetryTimer;
+    private cleanupInProgress;
     /** The stream JSON-RPC reads server→client frames from. */
     readonly receiveStream: PassThrough;
     /** The stream JSON-RPC writes client→server frames to. */
@@ -30,6 +34,8 @@ export declare class FfiRuntimeHost {
      */
     private feedInbound;
     private unregisterCallback;
-    /** Closes the FFI connection, shuts down the native host, and releases resources. */
-    dispose(): void;
+    private scheduleCleanupRetry;
+    private tryFinalizeCleanup;
+    /** Awaits the initial cleanup attempt; a non-quiescent close is retried in the background. */
+    dispose(): Promise<void>;
 }

package/dist/ffiRuntimeHost.js

@@ -4,6 +4,7 @@ import { resolve } from "node:path";
 import { PassThrough, Writable } from "node:stream";
 const SYMBOL_PREFIX = "copilot_runtime_";
 const KEEP_ALIVE_INTERVAL_MS = 1 << 30;
+const CLEANUP_RETRY_INTERVAL_MS = 100;
 let loadedLibraryPath;
 let loadedLibrary;
 function loadLibrary(libraryPath) {
@@ -96,12 +97,16 @@ class FfiRuntimeHost {
   cliEntrypoint;
   environment;
   args;
+  static quarantinedHosts = /* @__PURE__ */ new Set();
   lib;
   serverId = 0;
   connectionId = 0;
   disposed = false;
+  starting = false;
   outboundCallback;
   keepAliveTimer;
+  cleanupRetryTimer;
+  cleanupInProgress = false;
   /** The stream JSON-RPC reads server→client frames from. */
   receiveStream;
   /** The stream JSON-RPC writes client→server frames to. */
@@ -123,49 +128,65 @@ class FfiRuntimeHost {
   }
   /** Starts the in-process Rust runtime and opens the FFI JSON-RPC connection. */
   async start() {
+    if (this.disposed) {
+      throw new Error("The in-process runtime host is disposed.");
+    }
+    this.starting = true;
     const argvJson = buildArgvJson(this.cliEntrypoint, this.args);
     const envJson = buildEnvJson(this.environment);
-    this.serverId = await new Promise((resolvePromise, rejectPromise) => {
-      this.lib.hostStart.async(
-        argvJson,
-        argvJson.length,
-        envJson,
-        envJson ? envJson.length : 0,
-        (error, result) => {
-          if (error) {
-            rejectPromise(error);
-          } else {
-            resolvePromise(result);
+    try {
+      this.serverId = await new Promise((resolvePromise, rejectPromise) => {
+        this.lib.hostStart.async(
+          argvJson,
+          argvJson.length,
+          envJson,
+          envJson ? envJson.length : 0,
+          (error, result) => {
+            if (error) {
+              rejectPromise(error);
+            } else {
+              resolvePromise(result);
+            }
           }
-        }
+        );
+      });
+      if (!this.serverId) {
+        throw new Error(
+          `copilot_runtime_host_start failed (library '${this.libraryPath}').`
+        );
+      }
+      if (this.disposed) {
+        throw new Error("The in-process runtime host was disposed during startup.");
+      }
+      this.outboundCallback = koffi.register(
+        (_userData, bytesPtr, bytesLen) => this.feedInbound(bytesPtr, bytesLen),
+        this.lib.outboundCallbackType
       );
-    });
-    if (!this.serverId) {
-      throw new Error(`copilot_runtime_host_start failed (library '${this.libraryPath}').`);
-    }
-    this.outboundCallback = koffi.register(
-      (_userData, bytesPtr, bytesLen) => this.feedInbound(bytesPtr, bytesLen),
-      this.lib.outboundCallbackType
-    );
-    this.connectionId = this.lib.connectionOpen(
-      this.serverId,
-      this.outboundCallback,
-      null,
-      null,
-      0,
-      null,
-      0,
-      null,
-      0
-    );
-    if (!this.connectionId) {
-      this.unregisterCallback();
-      this.lib.hostShutdown(this.serverId);
-      this.serverId = 0;
-      throw new Error("copilot_runtime_connection_open failed.");
+      this.connectionId = this.lib.connectionOpen(
+        this.serverId,
+        this.outboundCallback,
+        null,
+        null,
+        0,
+        null,
+        0,
+        null,
+        0
+      );
+      if (!this.connectionId) {
+        this.unregisterCallback();
+        this.lib.hostShutdown(this.serverId);
+        this.serverId = 0;
+        throw new Error("copilot_runtime_connection_open failed.");
+      }
+      this.keepAliveTimer = setInterval(() => {
+      }, KEEP_ALIVE_INTERVAL_MS);
+    } finally {
+      this.starting = false;
+      if (this.disposed) {
+        void this.tryFinalizeCleanup();
+      }
     }
-    this.keepAliveTimer = setInterval(() => {
-    }, KEEP_ALIVE_INTERVAL_MS);
   }
   writeFrame(frame) {
     if (this.disposed || !this.connectionId) {
@@ -204,41 +225,105 @@ class FfiRuntimeHost {
   }
   unregisterCallback() {
     if (this.outboundCallback === void 0) {
-      return;
+      return true;
     }
     const callback = this.outboundCallback;
-    this.outboundCallback = void 0;
     try {
       koffi.unregister(callback);
-    } catch {
+      this.outboundCallback = void 0;
+      return true;
+    } catch (error) {
+      console.error(
+        `Failed to unregister in-process FFI callback: ${error instanceof Error ? error.stack ?? error.message : String(error)}`
+      );
+      FfiRuntimeHost.quarantinedHosts.add(this);
+      return false;
     }
   }
-  /** Closes the FFI connection, shuts down the native host, and releases resources. */
-  dispose() {
-    if (this.disposed) {
+  scheduleCleanupRetry() {
+    if (this.cleanupRetryTimer !== void 0) {
       return;
     }
-    this.disposed = true;
-    if (this.keepAliveTimer !== void 0) {
-      clearInterval(this.keepAliveTimer);
-      this.keepAliveTimer = void 0;
+    this.cleanupRetryTimer = setTimeout(() => {
+      this.cleanupRetryTimer = void 0;
+      void this.tryFinalizeCleanup();
+    }, CLEANUP_RETRY_INTERVAL_MS);
+  }
+  async tryFinalizeCleanup() {
+    if (this.cleanupInProgress) {
+      this.scheduleCleanupRetry();
+      return;
     }
+    this.cleanupInProgress = true;
     try {
       if (this.connectionId) {
-        this.lib.connectionClose(this.connectionId);
+        let closed = false;
+        try {
+          closed = await new Promise((resolvePromise, rejectPromise) => {
+            this.lib.connectionClose.async(
+              this.connectionId,
+              (error, result) => {
+                if (error) {
+                  rejectPromise(error);
+                } else {
+                  resolvePromise(result);
+                }
+              }
+            );
+          });
+        } catch (error) {
+          console.error(
+            `Failed to close in-process FFI connection: ${error instanceof Error ? error.stack ?? error.message : String(error)}`
+          );
+          FfiRuntimeHost.quarantinedHosts.add(this);
+          if (this.keepAliveTimer !== void 0) {
+            clearInterval(this.keepAliveTimer);
+            this.keepAliveTimer = void 0;
+          }
+          return;
+        }
+        if (!closed) {
+          this.scheduleCleanupRetry();
+          return;
+        }
         this.connectionId = 0;
       }
-    } catch {
-    }
-    try {
+      const callbackUnregistered = this.unregisterCallback();
+      if (this.keepAliveTimer !== void 0) {
+        clearInterval(this.keepAliveTimer);
+        this.keepAliveTimer = void 0;
+      }
       if (this.serverId) {
-        this.lib.hostShutdown(this.serverId);
+        try {
+          if (!this.lib.hostShutdown(this.serverId)) {
+            console.error(
+              `In-process FFI host shutdown did not recognize server ${this.serverId}.`
+            );
+          }
+        } catch (error) {
+          console.error(
+            `Failed to shut down in-process FFI host: ${error instanceof Error ? error.stack ?? error.message : String(error)}`
+          );
+        }
         this.serverId = 0;
       }
-    } catch {
+      if (callbackUnregistered) {
+        FfiRuntimeHost.quarantinedHosts.delete(this);
+      }
+    } finally {
+      this.cleanupInProgress = false;
+    }
+  }
+  /** Awaits the initial cleanup attempt; a non-quiescent close is retried in the background. */
+  async dispose() {
+    if (this.disposed) {
+      return;
     }
+    this.disposed = true;
     this.receiveStream.end();
-    this.unregisterCallback();
+    if (!this.starting) {
+      await this.tryFinalizeCleanup();
+    }
   }
 }
 export {