@github/copilot-sdk 0.1.29 → 0.1.31-unstable.0

package/README.md

@@ -402,6 +402,19 @@ const session = await client.createSession({
 
 When Copilot invokes `lookup_issue`, the client automatically runs your handler and responds to the CLI. Handlers can return any JSON-serializable value (automatically wrapped), a simple string, or a `ToolResultObject` for full control over result metadata. Raw JSON schemas are also supported if Zod isn't desired.
 
+#### Overriding Built-in Tools
+
+If you register a tool with the same name as a built-in CLI tool (e.g. `edit_file`, `read_file`), the SDK will throw an error unless you explicitly opt in by setting `overridesBuiltInTool: true`. This flag signals that you intend to replace the built-in tool with your custom implementation.
+
+```ts
+defineTool("edit_file", {
+    description: "Custom file editor with project-specific validation",
+    parameters: z.object({ path: z.string(), content: z.string() }),
+    overridesBuiltInTool: true,
+    handler: async ({ path, content }) => { /* your logic */ },
+})
+```
+
 ### System Message Customization
 
 Control the system prompt using `systemMessage` in session config:

package/dist/client.d.ts

@@ -361,9 +361,13 @@ export declare class CopilotClient {
      */
     private connectToServer;
     /**
-     * Connect via stdio pipes
+     * Connect to child via stdio pipes
      */
-    private connectViaStdio;
+    private connectToChildProcessViaStdio;
+    /**
+     * Connect to parent via stdio pipes
+     */
+    private connectToParentProcessViaStdio;
     /**
      * Connect to the CLI server via TCP socket
      */
@@ -371,14 +375,8 @@ export declare class CopilotClient {
     private attachConnectionHandlers;
     private handleSessionEventNotification;
     private handleSessionLifecycleNotification;
-    private handleToolCallRequest;
-    private executeToolCall;
-    private handlePermissionRequest;
     private handleUserInputRequest;
     private handleHooksInvoke;
-    private normalizeToolResult;
-    private isToolResultObject;
-    private buildUnsupportedToolResult;
     /**
      * Attempt to reconnect to the server
      */

package/dist/client.js

@@ -90,6 +90,11 @@ class CopilotClient {
     if (options.cliUrl && (options.useStdio === true || options.cliPath)) {
       throw new Error("cliUrl is mutually exclusive with useStdio and cliPath");
     }
+    if (options.isChildProcess && (options.cliUrl || options.useStdio === false)) {
+      throw new Error(
+        "isChildProcess must be used in conjunction with useStdio and not with cliUrl"
+      );
+    }
     if (options.cliUrl && (options.githubToken || options.useLoggedInUser !== void 0)) {
       throw new Error(
         "githubToken and useLoggedInUser cannot be used with cliUrl (external server manages its own auth)"
@@ -101,6 +106,9 @@ class CopilotClient {
       this.actualPort = port;
       this.isExternalServer = true;
     }
+    if (options.isChildProcess) {
+      this.isExternalServer = true;
+    }
     this.options = {
       cliPath: options.cliPath || getBundledCliPath(),
       cliArgs: options.cliArgs ?? [],
@@ -108,6 +116,7 @@ class CopilotClient {
       port: options.port || 0,
       useStdio: options.cliUrl ? false : options.useStdio ?? true,
       // Default to stdio unless cliUrl is provided
+      isChildProcess: options.isChildProcess ?? false,
       cliUrl: options.cliUrl,
       logLevel: options.logLevel || "debug",
       autoStart: options.autoStart ?? true,
@@ -371,7 +380,8 @@ class CopilotClient {
       tools: config.tools?.map((tool) => ({
         name: tool.name,
         description: tool.description,
-        parameters: toJsonSchema(tool.parameters)
+        parameters: toJsonSchema(tool.parameters),
+        overridesBuiltInTool: tool.overridesBuiltInTool
       })),
       systemMessage: config.systemMessage,
       availableTools: config.availableTools,
@@ -451,7 +461,8 @@ class CopilotClient {
       tools: config.tools?.map((tool) => ({
         name: tool.name,
         description: tool.description,
-        parameters: toJsonSchema(tool.parameters)
+        parameters: toJsonSchema(tool.parameters),
+        overridesBuiltInTool: tool.overridesBuiltInTool
       })),
       provider: config.provider,
       requestPermission: true,
@@ -884,16 +895,18 @@ stderr: ${stderrOutput}`
    * Connect to the CLI server (via socket or stdio)
    */
   async connectToServer() {
-    if (this.options.useStdio) {
-      return this.connectViaStdio();
+    if (this.options.isChildProcess) {
+      return this.connectToParentProcessViaStdio();
+    } else if (this.options.useStdio) {
+      return this.connectToChildProcessViaStdio();
     } else {
       return this.connectViaTcp();
     }
   }
   /**
-   * Connect via stdio pipes
+   * Connect to child via stdio pipes
    */
-  async connectViaStdio() {
+  async connectToChildProcessViaStdio() {
     if (!this.cliProcess) {
       throw new Error("CLI process not started");
     }
@@ -909,6 +922,20 @@ stderr: ${stderrOutput}`
     this.attachConnectionHandlers();
     this.connection.listen();
   }
+  /**
+   * Connect to parent via stdio pipes
+   */
+  async connectToParentProcessViaStdio() {
+    if (this.cliProcess) {
+      throw new Error("CLI child process was unexpectedly started in parent process mode");
+    }
+    this.connection = createMessageConnection(
+      new StreamMessageReader(process.stdin),
+      new StreamMessageWriter(process.stdout)
+    );
+    this.attachConnectionHandlers();
+    this.connection.listen();
+  }
   /**
    * Connect to the CLI server via TCP socket
    */
@@ -942,14 +969,6 @@ stderr: ${stderrOutput}`
     this.connection.onNotification("session.lifecycle", (notification) => {
       this.handleSessionLifecycleNotification(notification);
     });
-    this.connection.onRequest(
-      "tool.call",
-      async (params) => await this.handleToolCallRequest(params)
-    );
-    this.connection.onRequest(
-      "permission.request",
-      async (params) => await this.handlePermissionRequest(params)
-    );
     this.connection.onRequest(
       "userInput.request",
       async (params) => await this.handleUserInputRequest(params)
@@ -996,62 +1015,6 @@ stderr: ${stderrOutput}`
       }
     }
   }
-  async handleToolCallRequest(params) {
-    if (!params || typeof params.sessionId !== "string" || typeof params.toolCallId !== "string" || typeof params.toolName !== "string") {
-      throw new Error("Invalid tool call payload");
-    }
-    const session = this.sessions.get(params.sessionId);
-    if (!session) {
-      throw new Error(`Unknown session ${params.sessionId}`);
-    }
-    const handler = session.getToolHandler(params.toolName);
-    if (!handler) {
-      return { result: this.buildUnsupportedToolResult(params.toolName) };
-    }
-    return await this.executeToolCall(handler, params);
-  }
-  async executeToolCall(handler, request) {
-    try {
-      const invocation = {
-        sessionId: request.sessionId,
-        toolCallId: request.toolCallId,
-        toolName: request.toolName,
-        arguments: request.arguments
-      };
-      const result = await handler(request.arguments, invocation);
-      return { result: this.normalizeToolResult(result) };
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      return {
-        result: {
-          // Don't expose detailed error information to the LLM for security reasons
-          textResultForLlm: "Invoking this tool produced an error. Detailed information is not available.",
-          resultType: "failure",
-          error: message,
-          toolTelemetry: {}
-        }
-      };
-    }
-  }
-  async handlePermissionRequest(params) {
-    if (!params || typeof params.sessionId !== "string" || !params.permissionRequest) {
-      throw new Error("Invalid permission request payload");
-    }
-    const session = this.sessions.get(params.sessionId);
-    if (!session) {
-      throw new Error(`Session not found: ${params.sessionId}`);
-    }
-    try {
-      const result = await session._handlePermissionRequest(params.permissionRequest);
-      return { result };
-    } catch (_error) {
-      return {
-        result: {
-          kind: "denied-no-approval-rule-and-could-not-request-from-user"
-        }
-      };
-    }
-  }
   async handleUserInputRequest(params) {
     if (!params || typeof params.sessionId !== "string" || typeof params.question !== "string") {
       throw new Error("Invalid user input request payload");
@@ -1078,36 +1041,6 @@ stderr: ${stderrOutput}`
     const output = await session._handleHooksInvoke(params.hookType, params.input);
     return { output };
   }
-  normalizeToolResult(result) {
-    if (result === void 0 || result === null) {
-      return {
-        textResultForLlm: "Tool returned no result",
-        resultType: "failure",
-        error: "tool returned no result",
-        toolTelemetry: {}
-      };
-    }
-    if (this.isToolResultObject(result)) {
-      return result;
-    }
-    const textResult = typeof result === "string" ? result : JSON.stringify(result);
-    return {
-      textResultForLlm: textResult,
-      resultType: "success",
-      toolTelemetry: {}
-    };
-  }
-  isToolResultObject(value) {
-    return typeof value === "object" && value !== null && "textResultForLlm" in value && typeof value.textResultForLlm === "string" && "resultType" in value;
-  }
-  buildUnsupportedToolResult(toolName) {
-    return {
-      textResultForLlm: `Tool '${toolName}' is not supported by this client instance.`,
-      resultType: "failure",
-      error: `tool '${toolName}' not supported`,
-      toolTelemetry: {}
-    };
-  }
   /**
    * Attempt to reconnect to the server
    */

package/dist/extension.d.ts

@@ -0,0 +1,2 @@
+import { CopilotClient } from "./client.js";
+export declare const extension: CopilotClient;

package/dist/extension.js

@@ -0,0 +1,5 @@
+import { CopilotClient } from "./client.js";
+const extension = new CopilotClient({ isChildProcess: true });
+export {
+  extension
+};

package/dist/generated/rpc.d.ts

@@ -193,13 +193,17 @@ export interface SessionModeSetParams {
 }
 export interface SessionPlanReadResult {
     /**
-     * Whether plan.md exists in the workspace
+     * Whether the plan file exists in the workspace
      */
     exists: boolean;
     /**
-     * The content of plan.md, or null if it does not exist
+     * The content of the plan file, or null if it does not exist
      */
     content: string | null;
+    /**
+     * Absolute file path of the plan file, or null if workspace is not enabled
+     */
+    path: string | null;
 }
 export interface SessionPlanReadParams {
     /**
@@ -215,7 +219,7 @@ export interface SessionPlanUpdateParams {
      */
     sessionId: string;
     /**
-     * The new content for plan.md
+     * The new content for the plan file
      */
     content: string;
 }
@@ -394,6 +398,32 @@ export interface SessionCompactionCompactParams {
      */
     sessionId: string;
 }
+export interface SessionToolsHandlePendingToolCallResult {
+    success: boolean;
+}
+export interface SessionToolsHandlePendingToolCallParams {
+    /**
+     * Target session identifier
+     */
+    sessionId: string;
+    requestId: string;
+    result?: string;
+    error?: string;
+}
+export interface SessionPermissionsHandlePendingPermissionRequestResult {
+    success: boolean;
+}
+export interface SessionPermissionsHandlePendingPermissionRequestParams {
+    /**
+     * Target session identifier
+     */
+    sessionId: string;
+    requestId: string;
+    result: {
+        kind: "approved" | "denied-by-rules" | "denied-no-approval-rule-and-could-not-request-from-user" | "denied-interactively-by-user";
+        rules?: unknown[];
+    };
+}
 /** Create typed server-scoped RPC methods (no session required). */
 export declare function createServerRpc(connection: MessageConnection): {
     ping: (params: PingParams) => Promise<PingResult>;
@@ -439,4 +469,10 @@ export declare function createSessionRpc(connection: MessageConnection, sessionI
     compaction: {
         compact: () => Promise<SessionCompactionCompactResult>;
     };
+    tools: {
+        handlePendingToolCall: (params: Omit<SessionToolsHandlePendingToolCallParams, "sessionId">) => Promise<SessionToolsHandlePendingToolCallResult>;
+    };
+    permissions: {
+        handlePendingPermissionRequest: (params: Omit<SessionPermissionsHandlePendingPermissionRequestParams, "sessionId">) => Promise<SessionPermissionsHandlePendingPermissionRequestResult>;
+    };
 };

package/dist/generated/rpc.js

@@ -43,6 +43,12 @@ function createSessionRpc(connection, sessionId) {
     },
     compaction: {
       compact: async () => connection.sendRequest("session.compaction.compact", { sessionId })
+    },
+    tools: {
+      handlePendingToolCall: async (params) => connection.sendRequest("session.tools.handlePendingToolCall", { sessionId, ...params })
+    },
+    permissions: {
+      handlePendingPermissionRequest: async (params) => connection.sendRequest("session.permissions.handlePendingPermissionRequest", { sessionId, ...params })
     }
   };
 }