@github/copilot-sdk 1.0.0-beta.4 → 1.0.0-beta.6

package/dist/cjs/index.js

@@ -20,20 +20,23 @@ var index_exports = {};
 __export(index_exports, {
   CopilotClient: () => import_client.CopilotClient,
   CopilotSession: () => import_session.CopilotSession,
-  SYSTEM_PROMPT_SECTIONS: () => import_types.SYSTEM_PROMPT_SECTIONS,
-  approveAll: () => import_types.approveAll,
-  convertMcpCallToolResult: () => import_types.convertMcpCallToolResult,
-  createSessionFsAdapter: () => import_types.createSessionFsAdapter,
-  defineTool: () => import_types.defineTool
+  RuntimeConnection: () => import_types.RuntimeConnection,
+  SYSTEM_PROMPT_SECTIONS: () => import_types2.SYSTEM_PROMPT_SECTIONS,
+  approveAll: () => import_types2.approveAll,
+  convertMcpCallToolResult: () => import_types2.convertMcpCallToolResult,
+  createSessionFsAdapter: () => import_types2.createSessionFsAdapter,
+  defineTool: () => import_types2.defineTool
 });
 module.exports = __toCommonJS(index_exports);
 var import_client = require("./client.js");
-var import_session = require("./session.js");
 var import_types = require("./types.js");
+var import_session = require("./session.js");
+var import_types2 = require("./types.js");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CopilotClient,
   CopilotSession,
+  RuntimeConnection,
   SYSTEM_PROMPT_SECTIONS,
   approveAll,
   convertMcpCallToolResult,

package/dist/cjs/session.js

@@ -26,6 +26,14 @@ var import_node = require("vscode-jsonrpc/node.js");
 var import_rpc = require("./generated/rpc.js");
 var import_telemetry = require("./telemetry.js");
 const NO_RESULT_PERMISSION_V2_ERROR = "Permission handlers cannot return 'no-result' when connected to a protocol v2 server.";
+function deserializeHookInput(raw) {
+  if (!raw || typeof raw !== "object" || typeof raw.timestamp !== "number") {
+    return raw;
+  }
+  const obj = raw;
+  const { cwd, ...rest } = obj;
+  return { ...rest, timestamp: new Date(obj.timestamp), workingDirectory: cwd };
+}
 class CopilotSession {
   /**
    * Creates a new CopilotSession instance.
@@ -102,25 +110,8 @@ class CopilotSession {
       input: (message, options) => this._input(message, options)
     };
   }
-  /**
-   * Sends a message to this session and waits for the response.
-   *
-   * The message is processed asynchronously. Subscribe to events via {@link on}
-   * to receive streaming responses and other session events.
-   *
-   * @param options - The message options including the prompt and optional attachments
-   * @returns A promise that resolves with the message ID of the response
-   * @throws Error if the session has been disconnected or the connection fails
-   *
-   * @example
-   * ```typescript
-   * const messageId = await session.send({
-   *   prompt: "Explain this code",
-   *   attachments: [{ type: "file", path: "./src/index.ts" }]
-   * });
-   * ```
-   */
-  async send(options) {
+  async send(optionsOrPrompt) {
+    const options = typeof optionsOrPrompt === "string" ? { prompt: optionsOrPrompt } : optionsOrPrompt;
     const response = await this.connection.sendRequest("session.send", {
       ...await (0, import_telemetry.getTraceContext)(this.traceContextProvider),
       sessionId: this.sessionId,
@@ -131,30 +122,8 @@ class CopilotSession {
     });
     return response.messageId;
   }
-  /**
-   * Sends a message to this session and waits until the session becomes idle.
-   *
-   * This is a convenience method that combines {@link send} with waiting for
-   * the `session.idle` event. Use this when you want to block until the
-   * assistant has finished processing the message.
-   *
-   * Events are still delivered to handlers registered via {@link on} while waiting.
-   *
-   * @param options - The message options including the prompt and optional attachments
-   * @param timeout - Timeout in milliseconds (default: 60000). Controls how long to wait; does not abort in-flight agent work.
-   * @returns A promise that resolves with the final assistant message when the session becomes idle,
-   *          or undefined if no assistant message was received
-   * @throws Error if the timeout is reached before the session becomes idle
-   * @throws Error if the session has been disconnected or the connection fails
-   *
-   * @example
-   * ```typescript
-   * // Send and wait for completion with default 60s timeout
-   * const response = await session.sendAndWait({ prompt: "What is 2+2?" });
-   * console.log(response?.data.content); // "4"
-   * ```
-   */
-  async sendAndWait(options, timeout) {
+  async sendAndWait(optionsOrPrompt, timeout) {
+    const options = typeof optionsOrPrompt === "string" ? { prompt: optionsOrPrompt } : optionsOrPrompt;
     const effectiveTimeout = timeout ?? 6e4;
     let resolveIdle;
     let rejectWithError;
@@ -397,8 +366,8 @@ class CopilotSession {
   /**
    * Registers custom tool handlers for this session.
    *
-   * Tools allow the assistant to execute custom functions. When the assistant
-   * invokes a tool, the corresponding handler is called with the tool arguments.
+   * Tools with handlers allow the assistant to execute custom functions automatically.
+   * Declaration-only tools are surfaced as events and left pending for the consumer.
    *
    * @param tools - An array of tool definitions with their handlers, or undefined to clear all tools
    * @internal This method is typically called internally when creating a session with tools.
@@ -409,7 +378,9 @@ class CopilotSession {
       return;
     }
     for (const tool of tools) {
-      this.toolHandlers.set(tool.name, tool.handler);
+      if (tool.handler) {
+        this.toolHandlers.set(tool.name, tool.handler);
+      }
     }
   }
   /**
@@ -716,8 +687,10 @@ class CopilotSession {
     if (!this.hooks) {
       return void 0;
     }
+    const normalized = deserializeHookInput(input);
     const handlerMap = {
       preToolUse: this.hooks.onPreToolUse,
+      preMcpToolCall: this.hooks.onPreMcpToolCall,
       postToolUse: this.hooks.onPostToolUse,
       userPromptSubmitted: this.hooks.onUserPromptSubmitted,
       sessionStart: this.hooks.onSessionStart,
@@ -729,7 +702,7 @@ class CopilotSession {
       return void 0;
     }
     try {
-      const result = await handler(input, { sessionId: this.sessionId });
+      const result = await handler(normalized, { sessionId: this.sessionId });
       return result;
     } catch (_error) {
       return void 0;
@@ -746,7 +719,7 @@ class CopilotSession {
    *
    * @example
    * ```typescript
-   * const events = await session.getMessages();
+   * const events = await session.getEvents();
    * for (const event of events) {
    *   if (event.type === "assistant.message") {
    *     console.log("Assistant:", event.data.content);
@@ -754,7 +727,7 @@ class CopilotSession {
    * }
    * ```
    */
-  async getMessages() {
+  async getEvents() {
     const response = await this.connection.sendRequest("session.getMessages", {
       sessionId: this.sessionId
     });
@@ -794,18 +767,6 @@ class CopilotSession {
     this.exitPlanModeHandler = void 0;
     this.autoModeSwitchHandler = void 0;
   }
-  /**
-   * @deprecated Use {@link disconnect} instead. This method will be removed in a future release.
-   *
-   * Disconnects this session and releases all in-memory resources.
-   * Session data on disk is preserved for later resumption.
-   *
-   * @returns A promise that resolves when the session is disconnected
-   * @throws Error if the connection fails
-   */
-  async destroy() {
-    return this.disconnect();
-  }
   /** Enables `await using session = ...` syntax for automatic cleanup. */
   async [Symbol.asyncDispose]() {
     return this.disconnect();

package/dist/cjs/sessionFsProvider.js

@@ -21,6 +21,18 @@ __export(sessionFsProvider_exports, {
   createSessionFsAdapter: () => createSessionFsAdapter
 });
 module.exports = __toCommonJS(sessionFsProvider_exports);
+function normalizeSqliteParams(params) {
+  if (!params) {
+    return void 0;
+  }
+  const normalized = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== void 0) {
+      normalized[key] = value;
+    }
+  }
+  return normalized;
+}
 function createSessionFsAdapter(provider) {
   return {
     readFile: async ({ path }) => {
@@ -107,6 +119,28 @@ function createSessionFsAdapter(provider) {
       } catch (err) {
         return toSessionFsError(err);
       }
+    },
+    // Unlike the FS methods above, SQLite methods let errors propagate to the JSON-RPC layer
+    // rather than catching and mapping via toSessionFsError. The FS error mapping is specifically
+    // for translating Node.js errno codes (e.g., ENOENT) into SessionFsError, which isn't
+    // meaningful for SQL errors. Letting exceptions propagate preserves the original error
+    // message in the JSON-RPC error response.
+    sqliteQuery: async ({ queryType, query, params: bindParams }) => {
+      if (!provider.sqlite) {
+        throw new Error("SQLite is not supported by this provider");
+      }
+      const result = await provider.sqlite.query(
+        queryType,
+        query,
+        normalizeSqliteParams(bindParams)
+      );
+      return result ?? { rows: [], columns: [], rowsAffected: 0 };
+    },
+    sqliteExists: async () => {
+      if (!provider.sqlite) {
+        throw new Error("SQLite is not supported by this provider");
+      }
+      return { exists: await provider.sqlite.exists() };
     }
   };
 }

package/dist/cjs/types.js

@@ -18,6 +18,7 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var types_exports = {};
 __export(types_exports, {
+  RuntimeConnection: () => RuntimeConnection,
   SYSTEM_PROMPT_SECTIONS: () => SYSTEM_PROMPT_SECTIONS,
   approveAll: () => approveAll,
   convertMcpCallToolResult: () => convertMcpCallToolResult,
@@ -27,6 +28,34 @@ __export(types_exports, {
 });
 module.exports = __toCommonJS(types_exports);
 var import_sessionFsProvider = require("./sessionFsProvider.js");
+const RuntimeConnection = {
+  /**
+   * Spawn a runtime child process and communicate over its stdin/stdout.
+   * This is the default if no {@link CopilotClientOptions.connection} is set.
+   */
+  forStdio(opts = {}) {
+    return { kind: "stdio", path: opts.path, args: opts.args };
+  },
+  /**
+   * Spawn a runtime child process that listens on a TCP socket and connect to it.
+   */
+  forTcp(opts = {}) {
+    return {
+      kind: "tcp",
+      port: opts.port,
+      connectionToken: opts.connectionToken,
+      path: opts.path,
+      args: opts.args
+    };
+  },
+  /**
+   * Connect to an already-running runtime at the given URL. The SDK does not
+   * spawn a process in this mode.
+   */
+  forUri(url, opts = {}) {
+    return { kind: "uri", url, connectionToken: opts.connectionToken };
+  }
+};
 function convertMcpCallToolResult(callResult) {
   const textParts = [];
   const binaryResults = [];
@@ -92,6 +121,7 @@ const defaultJoinSessionPermissionHandler = () => ({
 });
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  RuntimeConnection,
   SYSTEM_PROMPT_SECTIONS,
   approveAll,
   convertMcpCallToolResult,

package/dist/client.d.ts

@@ -16,7 +16,7 @@ import type { ConnectionState, CopilotClientOptions, GetAuthStatusResponse, GetS
  * const client = new CopilotClient();
  *
  * // Or connect to an existing server
- * const client = new CopilotClient({ cliUrl: "localhost:3000" });
+ * const client = new CopilotClient({ connection: RuntimeConnection.forUri("localhost:3000") });
  *
  * // Create a session
  * const session = await client.createSession({ onPermissionRequest: approveAll, model: "gpt-4" });
@@ -39,11 +39,17 @@ export declare class CopilotClient {
     private cliProcess;
     private connection;
     private socket;
-    private actualPort;
+    private runtimePort;
     private actualHost;
     private state;
     private sessions;
     private stderrBuffer;
+    /** Resolved connection mode chosen in the constructor. */
+    private connectionConfig;
+    /** Resolved path to the runtime executable (only used for child-process kinds). */
+    private resolvedCliPath;
+    /** Resolved environment passed to the spawned runtime. */
+    private resolvedEnv;
     private options;
     private isExternalServer;
     private forceStopping;
@@ -66,53 +72,56 @@ export declare class CopilotClient {
      * @throws Error if the client is not connected
      */
     get rpc(): ReturnType<typeof createServerRpc>;
-    /**
-     * Internal RPC surface (e.g. handshake helpers). Not part of the public API.
-     * @internal
-     */
-    private get internalRpc();
     /**
      * Creates a new CopilotClient instance.
      *
      * @param options - Configuration options for the client
-     * @throws Error if mutually exclusive options are provided (e.g., cliUrl with useStdio or cliPath)
      *
      * @example
      * ```typescript
-     * // Default options - spawns CLI server using stdio
+     * // Default: spawns the bundled runtime over stdio
      * const client = new CopilotClient();
      *
-     * // Connect to an existing server
-     * const client = new CopilotClient({ cliUrl: "localhost:3000" });
+     * // Connect to an existing runtime
+     * const client = new CopilotClient({
+     *   connection: RuntimeConnection.forUri("localhost:3000"),
+     * });
+     *
+     * // Spawn the runtime over TCP on a chosen port
+     * const client = new CopilotClient({
+     *   connection: RuntimeConnection.forTcp({ port: 9001 }),
+     * });
      *
-     * // Custom CLI path with specific log level
+     * // Use a custom runtime binary
      * const client = new CopilotClient({
-     *   cliPath: "/usr/local/bin/copilot",
-     *   logLevel: "debug"
+     *   connection: RuntimeConnection.forStdio({ path: "/usr/local/bin/copilot" }),
+     *   logLevel: "debug",
      * });
      * ```
      */
     constructor(options?: CopilotClientOptions);
+    private connectionExtraArgs;
     /**
      * Parse CLI URL into host and port
      * Supports formats: "host:port", "http://host:port", "https://host:port", or just "port"
      */
     private parseCliUrl;
     private validateSessionFsConfig;
+    private setupSessionFs;
     /**
      * Starts the CLI server and establishes a connection.
      *
      * If connecting to an external server (via cliUrl), only establishes the connection.
      * Otherwise, spawns the CLI server process and then connects.
      *
-     * This method is called automatically when creating a session if `autoStart` is true (default).
+     * This method is called automatically the first time you create or resume a session.
      *
      * @returns A promise that resolves when the connection is established
      * @throws Error if the server fails to start or the connection fails
      *
      * @example
      * ```typescript
-     * const client = new CopilotClient({ autoStart: false });
+     * const client = new CopilotClient();
      * await client.start();
      * // Now ready to create sessions
      * ```
@@ -142,6 +151,19 @@ export declare class CopilotClient {
      * ```
      */
     stop(): Promise<Error[]>;
+    /**
+     * Alias for {@link stop} that lets `CopilotClient` participate in `await using`
+     * blocks for automatic cleanup.
+     *
+     * @example
+     * ```typescript
+     * await using client = new CopilotClient();
+     * const session = await client.createSession({ onPermissionRequest: approveAll });
+     * await session.sendAndWait("Hello");
+     * // client.stop() is called automatically when the block exits.
+     * ```
+     */
+    [Symbol.asyncDispose](): Promise<void>;
     /**
      * Forcefully stops the CLI server without graceful cleanup.
      *
@@ -172,12 +194,11 @@ export declare class CopilotClient {
      * Creates a new conversation session with the Copilot CLI.
      *
      * Sessions maintain conversation state, handle events, and manage tool execution.
-     * If the client is not connected and `autoStart` is enabled, this will automatically
-     * start the connection.
+     * If the client is not connected, this method automatically starts the connection.
      *
      * @param config - Optional configuration for the session
      * @returns A promise that resolves with the created session
-     * @throws Error if the client is not connected and autoStart is disabled
+     * @throws Error if the client fails to start
      *
      * @example
      * ```typescript
@@ -251,7 +272,7 @@ export declare class CopilotClient {
      */
     ping(message?: string): Promise<{
         message: string;
-        timestamp: number;
+        timestamp: string;
         protocolVersion?: number;
     }>;
     /**
@@ -398,7 +419,7 @@ export declare class CopilotClient {
      * @example
      * ```typescript
      * // Listen for when a session becomes foreground in TUI
-     * const unsubscribe = client.on("session.foreground", (event) => {
+     * const unsubscribe = client.onLifecycle("session.foreground", (event) => {
      *   console.log(`Session ${event.sessionId} is now displayed in TUI`);
      * });
      *
@@ -406,7 +427,7 @@ export declare class CopilotClient {
      * unsubscribe();
      * ```
      */
-    on<K extends SessionLifecycleEventType>(eventType: K, handler: TypedSessionLifecycleHandler<K>): () => void;
+    onLifecycle<K extends SessionLifecycleEventType>(eventType: K, handler: TypedSessionLifecycleHandler<K>): () => void;
     /**
      * Subscribes to all session lifecycle events.
      *
@@ -415,7 +436,7 @@ export declare class CopilotClient {
      *
      * @example
      * ```typescript
-     * const unsubscribe = client.on((event) => {
+     * const unsubscribe = client.onLifecycle((event) => {
      *   switch (event.type) {
      *     case "session.foreground":
      *       console.log(`Session ${event.sessionId} is now in foreground`);
@@ -430,7 +451,7 @@ export declare class CopilotClient {
      * unsubscribe();
      * ```
      */
-    on(handler: SessionLifecycleHandler): () => void;
+    onLifecycle(handler: SessionLifecycleHandler): () => void;
     /**
      * Start the CLI server process
      */