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

package/README.md

@@ -32,7 +32,7 @@ import { CopilotClient, approveAll } from "@github/copilot-sdk";
 const client = new CopilotClient();
 await client.start();
 
-// Create a session (onPermissionRequest is required)
+// Create a session (onPermissionRequest is optional; approveAll allows every tool)
 const session = await client.createSession({
     model: "gpt-5",
     onPermissionRequest: approveAll,
@@ -115,11 +115,11 @@ Create a new conversation session.
 - `sessionId?: string` - Custom session ID.
 - `model?: string` - Model to use ("gpt-5", "claude-sonnet-4.5", etc.). **Required when using custom provider.**
 - `reasoningEffort?: "low" | "medium" | "high" | "xhigh"` - Reasoning effort level for models that support it. Use `listModels()` to check which models support this option.
-- `tools?: Tool[]` - Custom tools exposed to the CLI
+- `tools?: Tool[]` - Custom tools exposed to the CLI. Tools without `handler` are declaration-only and must be resolved via pending tool-call RPCs.
 - `systemMessage?: SystemMessageConfig` - System message customization (see below)
 - `infiniteSessions?: InfiniteSessionConfig` - Configure automatic context compaction (see below)
 - `provider?: ProviderConfig` - Custom API provider configuration (BYOK - Bring Your Own Key). See [Custom Providers](#custom-providers) section.
-- `onPermissionRequest: PermissionHandler` - **Required.** Handler called before each tool execution to approve or deny it. Use `approveAll` to allow everything, or provide a custom function for fine-grained control. See [Permission Handling](#permission-handling) section.
+- `onPermissionRequest?: PermissionHandler` - Optional handler called before each tool execution to approve or deny it. When omitted, permission requests are emitted as events and left pending for manual resolution. Use `approveAll` to allow everything, or provide a custom function for fine-grained control. See [Permission Handling](#permission-handling) section.
 - `onUserInputRequest?: UserInputHandler` - Handler for user input requests from the agent. Enables the `ask_user` tool. See [User Input Requests](#user-input-requests) section.
 - `onElicitationRequest?: ElicitationHandler` - Handler for elicitation requests dispatched by the server. Enables this client to present form-based UI dialogs on behalf of the agent or other session participants. See [Elicitation Requests](#elicitation-requests) section.
 - `hooks?: SessionHooks` - Hook handlers for session lifecycle events. See [Session Hooks](#session-hooks) section.
@@ -128,7 +128,7 @@ Create a new conversation session.
 
 Resume an existing session. Returns the session with `workspacePath` populated if infinite sessions were enabled.
 
-##### `ping(message?: string): Promise<{ message: string; timestamp: number }>`
+##### `ping(message?: string): Promise<{ message: string; timestamp: string }>`
 
 Ping the server to check connectivity.
 
@@ -802,7 +802,7 @@ Inbound trace context from the CLI is available on the `ToolInvocation` object p
 
 ## Permission Handling
 
-An `onPermissionRequest` handler is **required** whenever you create or resume a session. The handler is called before the agent executes each tool (file writes, shell commands, custom tools, etc.) and must return a decision.
+An `onPermissionRequest` handler is optional when you create or resume a session. When provided, it is called before the agent executes each tool (file writes, shell commands, custom tools, etc.) and returns a decision. When omitted, permission requests are emitted as events and left pending for the consumer to resolve with the pending permission RPC.
 
 ### Approve All (simplest)
 
@@ -843,29 +843,32 @@ const session = await client.createSession({
         // request.fullCommandText — full shell command (for shell)
 
         if (request.kind === "shell") {
-            // Deny shell commands
-            return { kind: "denied-interactively-by-user" };
+            // Deny shell commands, optionally telling the model why
+            return { kind: "reject", feedback: "Shell commands are not allowed." };
         }
 
-        return { kind: "approved" };
+        return { kind: "approve-once" };
     },
 });
 ```
 
 ### Permission Result Kinds
 
-| Kind                                                        | Meaning                                                                                     |
-| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `"approved"`                                                | Allow the tool to run                                                                       |
-| `"denied-interactively-by-user"`                            | User explicitly denied the request                                                          |
-| `"denied-no-approval-rule-and-could-not-request-from-user"` | No approval rule matched and user could not be asked                                        |
-| `"denied-by-rules"`                                         | Denied by a policy rule                                                                     |
-| `"denied-by-content-exclusion-policy"`                      | Denied due to a content exclusion policy                                                    |
-| `"no-result"`                                               | Leave the request unanswered (only valid with protocol v1; rejected by protocol v2 servers) |
+The handler must return one of the `PermissionDecision` shapes (or `{ kind: "no-result" }`). Approval scopes are present-tense — they describe the decision to apply, not the outcome reported back on session events:
+
+| Kind                     | Meaning                                                                                       | Extra fields                                                            |
+| ------------------------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `"approve-once"`         | Allow this single request                                                                     | —                                                                       |
+| `"approve-for-session"`  | Allow this request and remember the approval for the rest of the session                      | `approval?` (rule to remember), `domain?` (for URL approvals)           |
+| `"approve-for-location"` | Allow this request and persist the approval for this project location (git root or cwd)      | `approval` (rule to persist), `locationKey` (location to persist under) |
+| `"approve-permanently"`  | Allow this request and persist the approval across sessions (currently used for URL domains) | `domain` (URL domain to approve)                                        |
+| `"reject"`               | Deny the request                                                                              | `feedback?` (optional string surfaced to the agent)                     |
+| `"user-not-available"`   | Deny the request because no user is available to confirm it                                   | —                                                                       |
+| `"no-result"`            | Leave the request unanswered (only valid with protocol v1; rejected by protocol v2 servers)   | —                                                                       |
 
 ### Resuming Sessions
 
-Pass `onPermissionRequest` when resuming a session too — it is required:
+You may pass `onPermissionRequest` when resuming a session too:
 
 ```typescript
 const session = await client.resumeSession("session-id", {

package/dist/cjs/client.js

@@ -272,6 +272,23 @@ class CopilotClient {
       throw new Error("sessionFs.conventions must be either 'windows' or 'posix'");
     }
   }
+  setupSessionFs(session, config) {
+    if (!this.sessionFsConfig) {
+      return;
+    }
+    if (!config.createSessionFsHandler) {
+      throw new Error(
+        "createSessionFsHandler is required in session config when sessionFs is enabled in client options."
+      );
+    }
+    const provider = config.createSessionFsHandler(session);
+    if (this.sessionFsConfig.capabilities?.sqlite && !provider.sqlite) {
+      throw new Error(
+        "SessionFsConfig declares capabilities.sqlite but the provider does not implement sqlite."
+      );
+    }
+    session.clientSessionApis.sessionFs = (0, import_sessionFsProvider.createSessionFsAdapter)(provider);
+  }
   /**
    * Starts the CLI server and establishes a connection.
    *
@@ -305,7 +322,8 @@ class CopilotClient {
         await this.connection.sendRequest("sessionFs.setProvider", {
           initialCwd: this.sessionFsConfig.initialCwd,
           sessionStatePath: this.sessionFsConfig.sessionStatePath,
-          conventions: this.sessionFsConfig.conventions
+          conventions: this.sessionFsConfig.conventions,
+          capabilities: this.sessionFsConfig.capabilities
         });
       }
       this.state = "connected";
@@ -502,11 +520,6 @@ class CopilotClient {
    * ```
    */
   async createSession(config) {
-    if (!config?.onPermissionRequest) {
-      throw new Error(
-        "An onPermissionRequest handler is required when creating a session. For example, to allow all permissions, use { onPermissionRequest: approveAll }."
-      );
-    }
     if (!this.connection) {
       if (this.options.autoStart) {
         await this.start();
@@ -549,17 +562,7 @@ class CopilotClient {
       session.on(config.onEvent);
     }
     this.sessions.set(sessionId, session);
-    if (this.sessionFsConfig) {
-      if (config.createSessionFsHandler) {
-        session.clientSessionApis.sessionFs = (0, import_sessionFsProvider.createSessionFsAdapter)(
-          config.createSessionFsHandler(session)
-        );
-      } else {
-        throw new Error(
-          "createSessionFsHandler is required in session config when sessionFs is enabled in client options."
-        );
-      }
-    }
+    this.setupSessionFs(session, config);
     try {
       const response = await this.connection.sendRequest("session.create", {
         ...await (0, import_telemetry.getTraceContext)(this.onGetTraceContext),
@@ -604,7 +607,9 @@ class CopilotClient {
         instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
         infiniteSessions: config.infiniteSessions,
-        gitHubToken: config.gitHubToken
+        gitHubToken: config.gitHubToken,
+        remoteSession: config.remoteSession,
+        cloud: config.cloud
       });
       const { workspacePath, capabilities } = response;
       session["_workspacePath"] = workspacePath;
@@ -640,11 +645,6 @@ class CopilotClient {
    * ```
    */
   async resumeSession(sessionId, config) {
-    if (!config?.onPermissionRequest) {
-      throw new Error(
-        "An onPermissionRequest handler is required when resuming a session. For example, to allow all permissions, use { onPermissionRequest: approveAll }."
-      );
-    }
     if (!this.connection) {
       if (this.options.autoStart) {
         await this.start();
@@ -686,17 +686,7 @@ class CopilotClient {
       session.on(config.onEvent);
     }
     this.sessions.set(sessionId, session);
-    if (this.sessionFsConfig) {
-      if (config.createSessionFsHandler) {
-        session.clientSessionApis.sessionFs = (0, import_sessionFsProvider.createSessionFsAdapter)(
-          config.createSessionFsHandler(session)
-        );
-      } else {
-        throw new Error(
-          "createSessionFsHandler is required in session config when sessionFs is enabled in client options."
-        );
-      }
-    }
+    this.setupSessionFs(session, config);
     try {
       const response = await this.connection.sendRequest("session.resume", {
         ...await (0, import_telemetry.getTraceContext)(this.onGetTraceContext),
@@ -743,7 +733,8 @@ class CopilotClient {
         infiniteSessions: config.infiniteSessions,
         disableResume: config.disableResume,
         continuePendingWork: config.continuePendingWork,
-        gitHubToken: config.gitHubToken
+        gitHubToken: config.gitHubToken,
+        remoteSession: config.remoteSession
       });
       const { workspacePath, capabilities } = response;
       session["_workspacePath"] = workspacePath;
@@ -1314,7 +1305,12 @@ stderr: ${stderrOutput}`
     }
     return new Promise((resolve, reject) => {
       this.socket = new import_node_net.Socket();
+      const connectionTimeout = setTimeout(() => {
+        this.socket?.destroy();
+        reject(new Error("Timeout connecting to CLI server"));
+      }, 1e4);
       this.socket.connect(this.actualPort, this.actualHost, () => {
+        clearTimeout(connectionTimeout);
         this.connection = (0, import_node.createMessageConnection)(
           new import_node.StreamMessageReader(this.socket),
           new import_node.StreamMessageWriter(this.socket)
@@ -1324,6 +1320,7 @@ stderr: ${stderrOutput}`
         resolve();
       });
       this.socket.on("error", (error) => {
+        clearTimeout(connectionTimeout);
         reject(new Error(`Failed to connect to CLI server: ${error.message}`));
       });
     });