@github/copilot-sdk 1.0.0 → 1.0.2-preview.0

package/README.md

@@ -2,6 +2,12 @@
 
 TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC.
 
+## Prerequisites
+
+To use the SDK, you'll need:
+
+- Node.js ^20.19.0 or >=22.12.0
+
 ## Installation
 
 ```bash
@@ -482,6 +488,21 @@ defineTool("safe_lookup", {
 });
 ```
 
+#### Deferring Tools
+
+Set `defer` to control whether a tool may be loaded lazily via tool search rather than always pre-loaded. Use `"auto"` to allow the tool to be deferred and surfaced through tool search, or `"never"` to force it to always be pre-loaded. Defaults to `"auto"`.
+
+```ts
+defineTool("lookup_issue", {
+    description: "Fetch issue details",
+    parameters: z.object({ id: z.string() }),
+    defer: "auto",
+    handler: async ({ id }) => {
+        /* your logic */
+    },
+});
+```
+
 ### Commands
 
 Register slash commands so that users of the CLI's TUI can invoke custom actions via `/commandName`. Each command has a `name`, optional `description`, and a `handler` called when the user executes it.
@@ -656,6 +677,28 @@ When enabled, sessions emit compaction events:
 - `session.compaction_start` - Background compaction started
 - `session.compaction_complete` - Compaction finished (includes token counts)
 
+### Memory
+
+Sessions can opt in to the memory feature, which lets the agent persist and recall
+information across turns. Provide a `memory` configuration on session create or resume;
+when omitted, the runtime default applies. In the default `"copilot-cli"` client mode the
+SDK leaves `memory` unset so the runtime applies its own default, while `"empty"` mode
+defaults `memory` to disabled unless you set it explicitly.
+
+```typescript
+// Enable memory for a session
+const session = await client.createSession({
+    model: "gpt-5",
+    memory: { enabled: true },
+});
+
+// Disable memory for a session
+const session = await client.createSession({
+    model: "gpt-5",
+    memory: { enabled: false },
+});
+```
+
 ### Multiple Sessions
 
 ```typescript
@@ -771,6 +814,7 @@ With just this configuration, the CLI emits spans for every session, message, an
 **TelemetryConfig options:**
 
 - `otlpEndpoint?: string` - OTLP HTTP endpoint URL
+- `otlpProtocol?: "http/json" | "http/protobuf"` - OTLP HTTP protocol for all signals
 - `filePath?: string` - File path for JSON-lines trace output
 - `exporterType?: string` - `"otlp-http"` or `"file"`
 - `sourceName?: string` - Instrumentation scope name
@@ -1033,11 +1077,6 @@ try {
 }
 ```
 
-## Requirements
-
-- Node.js >= 18.0.0
-- GitHub Copilot CLI installed and in PATH (or provide a custom `connection`)
-
 ## License
 
 MIT

package/dist/canvas.js

@@ -4,6 +4,7 @@ class CanvasError extends Error {
     this.code = code;
     this.name = "CanvasError";
   }
+  code;
   /** Default error when an action is declared but no `handler` is wired. */
   static noHandler() {
     return new CanvasError(

package/dist/cjs/canvas.js

@@ -29,6 +29,7 @@ class CanvasError extends Error {
     this.code = code;
     this.name = "CanvasError";
   }
+  code;
   /** Default error when an action is declared but no `handler` is wired. */
   static noHandler() {
     return new CanvasError(

package/dist/cjs/client.js

@@ -38,9 +38,54 @@ var import_toolSet = require("./toolSet.js");
 var import_types = require("./types.js");
 const import_meta = {};
 const MIN_PROTOCOL_VERSION = 3;
+const RUNTIME_SHUTDOWN_TIMEOUT_MS = 1e4;
 function isZodSchema(value) {
   return value != null && typeof value === "object" && "toJSONSchema" in value && typeof value.toJSONSchema === "function";
 }
+async function withTimeout(promise, timeoutMs, message) {
+  let timeout;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timeout = setTimeout(() => reject(new Error(message)), timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timeout !== void 0) {
+      clearTimeout(timeout);
+    }
+  }
+}
+async function waitForChildExit(child, timeoutMs) {
+  if (child.exitCode != null || child.signalCode != null) {
+    return true;
+  }
+  return new Promise((resolve) => {
+    let timeout;
+    let settled = false;
+    const onExit = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      resolve(true);
+    };
+    timeout = setTimeout(() => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      child.off("exit", onExit);
+      resolve(false);
+    }, timeoutMs);
+    child.once("exit", onExit);
+    if (child.exitCode != null || child.signalCode != null) {
+      onExit();
+    }
+  });
+}
 function toJsonSchema(parameters) {
   if (!parameters) return void 0;
   if (isZodSchema(parameters)) {
@@ -204,6 +249,13 @@ class CopilotClient {
     }
     return this._internalRpc;
   }
+  logDebugTiming(message, startMs) {
+    const level = this.options.logLevel?.toLowerCase();
+    if (level === "debug" || level === "all") {
+      process.stderr.write(`[copilot-sdk] ${message}. Elapsed=${Date.now() - startMs}ms
+`);
+    }
+  }
   /**
    * Creates a new CopilotClient instance.
    *
@@ -390,8 +442,9 @@ class CopilotClient {
    *
    * This method performs graceful cleanup:
    * 1. Closes all active sessions (releases in-memory resources)
-   * 2. Closes the JSON-RPC connection
-   * 3. Terminates the CLI server process (if spawned by this client)
+   * 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)
    *
    * Note: session data on disk is preserved, so sessions can be resumed later.
    * To permanently remove session data before stopping, call
@@ -435,6 +488,34 @@ class CopilotClient {
       }
     }
     this.sessions.clear();
+    let runtimeShutdownCompleted = false;
+    if (this.connection && this.cliProcess && !this.isExternalServer) {
+      const runtimeShutdownStart = Date.now();
+      const shutdownPromise = this.rpc.runtime.shutdown();
+      void shutdownPromise.catch(() => void 0);
+      try {
+        await withTimeout(
+          shutdownPromise,
+          RUNTIME_SHUTDOWN_TIMEOUT_MS,
+          `runtime.shutdown timed out after ${RUNTIME_SHUTDOWN_TIMEOUT_MS}ms`
+        );
+        runtimeShutdownCompleted = true;
+        this.logDebugTiming(
+          "CopilotClient.stop runtime shutdown complete",
+          runtimeShutdownStart
+        );
+      } catch (error) {
+        this.logDebugTiming(
+          "CopilotClient.stop runtime shutdown failed",
+          runtimeShutdownStart
+        );
+        errors.push(
+          new Error(
+            `Failed to gracefully shut down runtime: ${error instanceof Error ? error.message : String(error)}`
+          )
+        );
+      }
+    }
     if (this.connection) {
       try {
         this.connection.dispose();
@@ -447,6 +528,7 @@ class CopilotClient {
       }
       this.connection = null;
       this._rpc = null;
+      this._internalRpc = null;
     }
     this.modelsCache = null;
     if (this.socket) {
@@ -471,12 +553,18 @@ class CopilotClient {
       const child = this.cliProcess;
       this.cliProcess = null;
       try {
-        if (child.exitCode === null && child.signalCode === null) {
-          const exited = new Promise((resolve) => {
-            child.once("exit", () => resolve());
-          });
-          child.kill();
-          await exited;
+        if (child.exitCode == null && child.signalCode == null) {
+          const exitedGracefully = runtimeShutdownCompleted ? await waitForChildExit(child, RUNTIME_SHUTDOWN_TIMEOUT_MS) : false;
+          if (!exitedGracefully) {
+            child.kill();
+            if (!await waitForChildExit(child, RUNTIME_SHUTDOWN_TIMEOUT_MS)) {
+              errors.push(
+                new Error(
+                  `Timed out waiting for CLI process to exit after kill: ${RUNTIME_SHUTDOWN_TIMEOUT_MS}ms`
+                )
+              );
+            }
+          }
         }
       } catch (error) {
         errors.push(
@@ -546,6 +634,7 @@ class CopilotClient {
       }
       this.connection = null;
       this._rpc = null;
+      this._internalRpc = null;
     }
     this.modelsCache = null;
     if (this.socket) {
@@ -638,7 +727,8 @@ class CopilotClient {
         enableFileHooks: false,
         enableHostGitOperations: false,
         enableSessionStore: false,
-        enableSkills: false
+        enableSkills: false,
+        memory: { enabled: false }
       };
     }
     return {};
@@ -788,7 +878,8 @@ class CopilotClient {
           description: tool.description,
           parameters: toJsonSchema(tool.parameters),
           overridesBuiltInTool: tool.overridesBuiltInTool,
-          skipPermission: tool.skipPermission
+          skipPermission: tool.skipPermission,
+          defer: tool.defer
         })),
         canvases: config.canvases?.map((canvas) => canvas.declaration),
         requestCanvasRenderer: config.requestCanvasRenderer,
@@ -838,6 +929,7 @@ class CopilotClient {
         instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
         infiniteSessions: config.infiniteSessions,
+        memory: config.memory,
         gitHubToken: config.gitHubToken,
         remoteSession: config.remoteSession,
         cloud: config.cloud
@@ -956,7 +1048,8 @@ class CopilotClient {
           description: tool.description,
           parameters: toJsonSchema(tool.parameters),
           overridesBuiltInTool: tool.overridesBuiltInTool,
-          skipPermission: tool.skipPermission
+          skipPermission: tool.skipPermission,
+          defer: tool.defer
         })),
         canvases: config.canvases?.map((canvas) => canvas.declaration),
         requestCanvasRenderer: config.requestCanvasRenderer,
@@ -1001,6 +1094,7 @@ class CopilotClient {
         instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
         infiniteSessions: config.infiniteSessions,
+        memory: config.memory,
         disableResume: config.suppressResumeEvent,
         continuePendingWork: config.continuePendingWork,
         gitHubToken: config.gitHubToken,
@@ -1403,6 +1497,8 @@ class CopilotClient {
         envWithoutNodeDebug.COPILOT_OTEL_ENABLED = "true";
         if (t.otlpEndpoint !== void 0)
           envWithoutNodeDebug.OTEL_EXPORTER_OTLP_ENDPOINT = t.otlpEndpoint;
+        if (t.otlpProtocol !== void 0)
+          envWithoutNodeDebug.OTEL_EXPORTER_OTLP_PROTOCOL = t.otlpProtocol;
         if (t.filePath !== void 0)
           envWithoutNodeDebug.COPILOT_OTEL_FILE_EXPORTER_PATH = t.filePath;
         if (t.exporterType !== void 0)