@github/copilot-sdk 0.0.1 → 0.1.9

package/README.md

@@ -0,0 +1 @@
+Coming soon

package/dist/client.d.ts

@@ -0,0 +1,95 @@
+import { CopilotSession } from "./session.js";
+import type { ConnectionState, CopilotClientOptions, ResumeSessionConfig, SessionConfig, SessionMetadata } from "./types.js";
+export declare class CopilotClient {
+    private cliProcess;
+    private connection;
+    private socket;
+    private actualPort;
+    private actualHost;
+    private state;
+    private sessions;
+    private options;
+    private isExternalServer;
+    private forceStopping;
+    constructor(options?: CopilotClientOptions);
+    /**
+     * Parse CLI URL into host and port
+     * Supports formats: "host:port", "http://host:port", "https://host:port", or just "port"
+     */
+    private parseCliUrl;
+    /**
+     * Start the CLI server and establish connection
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the CLI server and close all sessions
+     * Returns array of errors encountered during cleanup (empty if all succeeded)
+     */
+    stop(): Promise<Error[]>;
+    /**
+     * Force stop the CLI server without graceful cleanup
+     * Use when normal stop() fails or takes too long
+     */
+    forceStop(): Promise<void>;
+    /**
+     * Create a new session
+     */
+    createSession(config?: SessionConfig): Promise<CopilotSession>;
+    /**
+     * Resume an existing session
+     */
+    resumeSession(sessionId: string, config?: ResumeSessionConfig): Promise<CopilotSession>;
+    /**
+     * Get connection state
+     */
+    getState(): ConnectionState;
+    /**
+     * Ping the server
+     */
+    ping(message?: string): Promise<{
+        message: string;
+        timestamp: number;
+    }>;
+    /**
+     * Get the ID of the most recently updated session
+     * @returns The session ID, or undefined if no sessions exist
+     */
+    getLastSessionId(): Promise<string | undefined>;
+    /**
+     * Delete a session and its data from disk
+     * @param sessionId The ID of the session to delete
+     */
+    deleteSession(sessionId: string): Promise<void>;
+    /**
+     * List all available sessions
+     * @returns Array of session metadata
+     */
+    listSessions(): Promise<SessionMetadata[]>;
+    /**
+     * Start the CLI server process
+     */
+    private startCLIServer;
+    /**
+     * Connect to the CLI server (via socket or stdio)
+     */
+    private connectToServer;
+    /**
+     * Connect via stdio pipes
+     */
+    private connectViaStdio;
+    /**
+     * Connect to the CLI server via TCP socket
+     */
+    private connectViaTcp;
+    private attachConnectionHandlers;
+    private handleSessionEventNotification;
+    private handleToolCallRequest;
+    private executeToolCall;
+    private normalizeToolResult;
+    private isToolResultObject;
+    private buildUnsupportedToolResult;
+    /**
+     * Attempt to reconnect to the server
+     */
+    private reconnect;
+}

package/dist/client.js

@@ -0,0 +1,549 @@
+import { spawn } from "node:child_process";
+import { Socket } from "node:net";
+import {
+  createMessageConnection,
+  StreamMessageReader,
+  StreamMessageWriter
+} from "vscode-jsonrpc/node.js";
+import { CopilotSession } from "./session.js";
+function isZodSchema(value) {
+  return value != null && typeof value === "object" && "toJSONSchema" in value && typeof value.toJSONSchema === "function";
+}
+function toJsonSchema(parameters) {
+  if (!parameters) return void 0;
+  if (isZodSchema(parameters)) {
+    return parameters.toJSONSchema();
+  }
+  return parameters;
+}
+class CopilotClient {
+  cliProcess = null;
+  connection = null;
+  socket = null;
+  actualPort = null;
+  actualHost = "localhost";
+  state = "disconnected";
+  sessions = /* @__PURE__ */ new Map();
+  options;
+  isExternalServer = false;
+  forceStopping = false;
+  constructor(options = {}) {
+    if (options.cliUrl && (options.useStdio === true || options.cliPath)) {
+      throw new Error("cliUrl is mutually exclusive with useStdio and cliPath");
+    }
+    if (options.cliUrl) {
+      const { host, port } = this.parseCliUrl(options.cliUrl);
+      this.actualHost = host;
+      this.actualPort = port;
+      this.isExternalServer = true;
+    }
+    this.options = {
+      cliPath: options.cliPath || "copilot",
+      cliArgs: options.cliArgs ?? [],
+      cwd: options.cwd ?? process.cwd(),
+      port: options.port || 0,
+      useStdio: options.cliUrl ? false : options.useStdio ?? true,
+      // Default to stdio unless cliUrl is provided
+      cliUrl: options.cliUrl,
+      logLevel: options.logLevel || "info",
+      autoStart: options.autoStart ?? true,
+      autoRestart: options.autoRestart ?? true,
+      env: options.env ?? process.env
+    };
+  }
+  /**
+   * Parse CLI URL into host and port
+   * Supports formats: "host:port", "http://host:port", "https://host:port", or just "port"
+   */
+  parseCliUrl(url) {
+    let cleanUrl = url.replace(/^https?:\/\//, "");
+    if (/^\d+$/.test(cleanUrl)) {
+      return { host: "localhost", port: parseInt(cleanUrl, 10) };
+    }
+    const parts = cleanUrl.split(":");
+    if (parts.length !== 2) {
+      throw new Error(
+        `Invalid cliUrl format: ${url}. Expected "host:port", "http://host:port", or "port"`
+      );
+    }
+    const host = parts[0] || "localhost";
+    const port = parseInt(parts[1], 10);
+    if (isNaN(port) || port <= 0 || port > 65535) {
+      throw new Error(`Invalid port in cliUrl: ${url}`);
+    }
+    return { host, port };
+  }
+  /**
+   * Start the CLI server and establish connection
+   */
+  async start() {
+    if (this.state === "connected") {
+      return;
+    }
+    this.state = "connecting";
+    try {
+      if (!this.isExternalServer) {
+        await this.startCLIServer();
+      }
+      await this.connectToServer();
+      this.state = "connected";
+    } catch (error) {
+      this.state = "error";
+      throw error;
+    }
+  }
+  /**
+   * Stop the CLI server and close all sessions
+   * Returns array of errors encountered during cleanup (empty if all succeeded)
+   */
+  async stop() {
+    const errors = [];
+    for (const session of this.sessions.values()) {
+      const sessionId = session.sessionId;
+      let lastError = null;
+      for (let attempt = 1; attempt <= 3; attempt++) {
+        try {
+          await session.destroy();
+          lastError = null;
+          break;
+        } catch (error) {
+          lastError = error instanceof Error ? error : new Error(String(error));
+          if (attempt < 3) {
+            const delay = 100 * Math.pow(2, attempt - 1);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+          }
+        }
+      }
+      if (lastError) {
+        errors.push(
+          new Error(
+            `Failed to destroy session ${sessionId} after 3 attempts: ${lastError.message}`
+          )
+        );
+      }
+    }
+    this.sessions.clear();
+    if (this.connection) {
+      try {
+        this.connection.dispose();
+      } catch (error) {
+        errors.push(
+          new Error(
+            `Failed to dispose connection: ${error instanceof Error ? error.message : String(error)}`
+          )
+        );
+      }
+      this.connection = null;
+    }
+    if (this.socket) {
+      try {
+        this.socket.end();
+      } catch (error) {
+        errors.push(
+          new Error(
+            `Failed to close socket: ${error instanceof Error ? error.message : String(error)}`
+          )
+        );
+      }
+      this.socket = null;
+    }
+    if (this.cliProcess && !this.isExternalServer) {
+      try {
+        this.cliProcess.kill();
+      } catch (error) {
+        errors.push(
+          new Error(
+            `Failed to kill CLI process: ${error instanceof Error ? error.message : String(error)}`
+          )
+        );
+      }
+      this.cliProcess = null;
+    }
+    this.state = "disconnected";
+    this.actualPort = null;
+    return errors;
+  }
+  /**
+   * Force stop the CLI server without graceful cleanup
+   * Use when normal stop() fails or takes too long
+   */
+  async forceStop() {
+    this.forceStopping = true;
+    this.sessions.clear();
+    if (this.connection) {
+      try {
+        this.connection.dispose();
+      } catch {
+      }
+      this.connection = null;
+    }
+    if (this.socket) {
+      try {
+        this.socket.destroy();
+      } catch {
+      }
+      this.socket = null;
+    }
+    if (this.cliProcess && !this.isExternalServer) {
+      try {
+        this.cliProcess.kill("SIGKILL");
+      } catch {
+      }
+      this.cliProcess = null;
+    }
+    this.state = "disconnected";
+    this.actualPort = null;
+  }
+  /**
+   * Create a new session
+   */
+  async createSession(config = {}) {
+    if (!this.connection) {
+      if (this.options.autoStart) {
+        await this.start();
+      } else {
+        throw new Error("Client not connected. Call start() first.");
+      }
+    }
+    const response = await this.connection.sendRequest("session.create", {
+      model: config.model,
+      sessionId: config.sessionId,
+      tools: config.tools?.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        parameters: toJsonSchema(tool.parameters)
+      })),
+      systemMessage: config.systemMessage,
+      availableTools: config.availableTools,
+      excludedTools: config.excludedTools,
+      provider: config.provider
+    });
+    const sessionId = response.sessionId;
+    const session = new CopilotSession(sessionId, this.connection);
+    session.registerTools(config.tools);
+    this.sessions.set(sessionId, session);
+    return session;
+  }
+  /**
+   * Resume an existing session
+   */
+  async resumeSession(sessionId, config = {}) {
+    if (!this.connection) {
+      if (this.options.autoStart) {
+        await this.start();
+      } else {
+        throw new Error("Client not connected. Call start() first.");
+      }
+    }
+    const response = await this.connection.sendRequest("session.resume", {
+      sessionId,
+      tools: config.tools?.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        parameters: toJsonSchema(tool.parameters)
+      })),
+      provider: config.provider
+    });
+    const resumedSessionId = response.sessionId;
+    const session = new CopilotSession(resumedSessionId, this.connection);
+    session.registerTools(config.tools);
+    this.sessions.set(resumedSessionId, session);
+    return session;
+  }
+  /**
+   * Get connection state
+   */
+  getState() {
+    return this.state;
+  }
+  /**
+   * Ping the server
+   */
+  async ping(message) {
+    if (!this.connection) {
+      throw new Error("Client not connected");
+    }
+    const result = await this.connection.sendRequest("ping", { message });
+    return result;
+  }
+  /**
+   * Get the ID of the most recently updated session
+   * @returns The session ID, or undefined if no sessions exist
+   */
+  async getLastSessionId() {
+    if (!this.connection) {
+      throw new Error("Client not connected");
+    }
+    const response = await this.connection.sendRequest("session.getLastId", {});
+    return response.sessionId;
+  }
+  /**
+   * Delete a session and its data from disk
+   * @param sessionId The ID of the session to delete
+   */
+  async deleteSession(sessionId) {
+    if (!this.connection) {
+      throw new Error("Client not connected");
+    }
+    const response = await this.connection.sendRequest("session.delete", {
+      sessionId
+    });
+    const { success, error } = response;
+    if (!success) {
+      throw new Error(`Failed to delete session ${sessionId}: ${error || "Unknown error"}`);
+    }
+    this.sessions.delete(sessionId);
+  }
+  /**
+   * List all available sessions
+   * @returns Array of session metadata
+   */
+  async listSessions() {
+    if (!this.connection) {
+      throw new Error("Client not connected");
+    }
+    const response = await this.connection.sendRequest("session.list", {});
+    const { sessions } = response;
+    return sessions.map((s) => ({
+      sessionId: s.sessionId,
+      startTime: new Date(s.startTime),
+      modifiedTime: new Date(s.modifiedTime),
+      summary: s.summary,
+      isRemote: s.isRemote
+    }));
+  }
+  /**
+   * Start the CLI server process
+   */
+  async startCLIServer() {
+    return new Promise((resolve, reject) => {
+      const args = [
+        ...this.options.cliArgs,
+        "--server",
+        "--log-level",
+        this.options.logLevel
+      ];
+      if (this.options.useStdio) {
+        args.push("--stdio");
+      } else if (this.options.port > 0) {
+        args.push("--port", this.options.port.toString());
+      }
+      const envWithoutNodeDebug = { ...this.options.env };
+      delete envWithoutNodeDebug.NODE_DEBUG;
+      const isJsFile = this.options.cliPath.endsWith(".js");
+      const command = isJsFile ? "node" : this.options.cliPath;
+      const spawnArgs = isJsFile ? [this.options.cliPath, ...args] : args;
+      this.cliProcess = spawn(command, spawnArgs, {
+        stdio: this.options.useStdio ? ["pipe", "pipe", "pipe"] : ["ignore", "pipe", "pipe"],
+        cwd: this.options.cwd,
+        env: envWithoutNodeDebug
+      });
+      let stdout = "";
+      let resolved = false;
+      if (this.options.useStdio) {
+        resolved = true;
+        resolve();
+      } else {
+        this.cliProcess.stdout?.on("data", (data) => {
+          stdout += data.toString();
+          const match = stdout.match(/listening on port (\d+)/i);
+          if (match && !resolved) {
+            this.actualPort = parseInt(match[1], 10);
+            resolved = true;
+            resolve();
+          }
+        });
+      }
+      this.cliProcess.stderr?.on("data", (data) => {
+        const lines = data.toString().split("\n");
+        for (const line of lines) {
+          if (line.trim()) {
+            process.stderr.write(`[CLI subprocess] ${line}
+`);
+          }
+        }
+      });
+      this.cliProcess.on("error", (error) => {
+        if (!resolved) {
+          resolved = true;
+          reject(new Error(`Failed to start CLI server: ${error.message}`));
+        }
+      });
+      this.cliProcess.on("exit", (code) => {
+        if (!resolved) {
+          resolved = true;
+          reject(new Error(`CLI server exited with code ${code}`));
+        } else if (this.options.autoRestart && this.state === "connected") {
+          void this.reconnect();
+        }
+      });
+      setTimeout(() => {
+        if (!resolved) {
+          resolved = true;
+          reject(new Error("Timeout waiting for CLI server to start"));
+        }
+      }, 1e4);
+    });
+  }
+  /**
+   * Connect to the CLI server (via socket or stdio)
+   */
+  async connectToServer() {
+    if (this.options.useStdio) {
+      return this.connectViaStdio();
+    } else {
+      return this.connectViaTcp();
+    }
+  }
+  /**
+   * Connect via stdio pipes
+   */
+  async connectViaStdio() {
+    if (!this.cliProcess) {
+      throw new Error("CLI process not started");
+    }
+    this.cliProcess.stdin?.on("error", (err) => {
+      if (!this.forceStopping) {
+        throw err;
+      }
+    });
+    this.connection = createMessageConnection(
+      new StreamMessageReader(this.cliProcess.stdout),
+      new StreamMessageWriter(this.cliProcess.stdin)
+    );
+    this.attachConnectionHandlers();
+    this.connection.listen();
+  }
+  /**
+   * Connect to the CLI server via TCP socket
+   */
+  async connectViaTcp() {
+    if (!this.actualPort) {
+      throw new Error("Server port not available");
+    }
+    return new Promise((resolve, reject) => {
+      this.socket = new Socket();
+      this.socket.connect(this.actualPort, this.actualHost, () => {
+        this.connection = createMessageConnection(
+          new StreamMessageReader(this.socket),
+          new StreamMessageWriter(this.socket)
+        );
+        this.attachConnectionHandlers();
+        this.connection.listen();
+        resolve();
+      });
+      this.socket.on("error", (error) => {
+        reject(new Error(`Failed to connect to CLI server: ${error.message}`));
+      });
+    });
+  }
+  attachConnectionHandlers() {
+    if (!this.connection) {
+      return;
+    }
+    this.connection.onNotification("session.event", (notification) => {
+      this.handleSessionEventNotification(notification);
+    });
+    this.connection.onRequest(
+      "tool.call",
+      async (params) => await this.handleToolCallRequest(params)
+    );
+    this.connection.onClose(() => {
+      if (this.state === "connected" && this.options.autoRestart) {
+        void this.reconnect();
+      }
+    });
+    this.connection.onError((_error) => {
+    });
+  }
+  handleSessionEventNotification(notification) {
+    if (typeof notification !== "object" || !notification || !("sessionId" in notification) || typeof notification.sessionId !== "string" || !("event" in notification)) {
+      return;
+    }
+    const session = this.sessions.get(notification.sessionId);
+    if (session) {
+      session._dispatchEvent(notification.event);
+    }
+  }
+  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: {}
+        }
+      };
+    }
+  }
+  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
+   */
+  async reconnect() {
+    this.state = "disconnected";
+    try {
+      await this.stop();
+      await this.start();
+    } catch (_error) {
+    }
+  }
+}
+export {
+  CopilotClient
+};