@github/copilot-sdk 0.1.33-unstable.1 → 0.2.0

package/dist/cjs/session.js

@@ -0,0 +1,616 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var session_exports = {};
+__export(session_exports, {
+  CopilotSession: () => CopilotSession,
+  NO_RESULT_PERMISSION_V2_ERROR: () => NO_RESULT_PERMISSION_V2_ERROR
+});
+module.exports = __toCommonJS(session_exports);
+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.";
+class CopilotSession {
+  /**
+   * Creates a new CopilotSession instance.
+   *
+   * @param sessionId - The unique identifier for this session
+   * @param connection - The JSON-RPC message connection to the Copilot CLI
+   * @param workspacePath - Path to the session workspace directory (when infinite sessions enabled)
+   * @param traceContextProvider - Optional callback to get W3C Trace Context for outbound RPCs
+   * @internal This constructor is internal. Use {@link CopilotClient.createSession} to create sessions.
+   */
+  constructor(sessionId, connection, _workspacePath, traceContextProvider) {
+    this.sessionId = sessionId;
+    this.connection = connection;
+    this._workspacePath = _workspacePath;
+    this.traceContextProvider = traceContextProvider;
+  }
+  eventHandlers = /* @__PURE__ */ new Set();
+  typedEventHandlers = /* @__PURE__ */ new Map();
+  toolHandlers = /* @__PURE__ */ new Map();
+  permissionHandler;
+  userInputHandler;
+  hooks;
+  transformCallbacks;
+  _rpc = null;
+  traceContextProvider;
+  /**
+   * Typed session-scoped RPC methods.
+   */
+  get rpc() {
+    if (!this._rpc) {
+      this._rpc = (0, import_rpc.createSessionRpc)(this.connection, this.sessionId);
+    }
+    return this._rpc;
+  }
+  /**
+   * Path to the session workspace directory when infinite sessions are enabled.
+   * Contains checkpoints/, plan.md, and files/ subdirectories.
+   * Undefined if infinite sessions are disabled.
+   */
+  get workspacePath() {
+    return this._workspacePath;
+  }
+  /**
+   * 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) {
+    const response = await this.connection.sendRequest("session.send", {
+      ...await (0, import_telemetry.getTraceContext)(this.traceContextProvider),
+      sessionId: this.sessionId,
+      prompt: options.prompt,
+      attachments: options.attachments,
+      mode: options.mode
+    });
+    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) {
+    const effectiveTimeout = timeout ?? 6e4;
+    let resolveIdle;
+    let rejectWithError;
+    const idlePromise = new Promise((resolve, reject) => {
+      resolveIdle = resolve;
+      rejectWithError = reject;
+    });
+    let lastAssistantMessage;
+    const unsubscribe = this.on((event) => {
+      if (event.type === "assistant.message") {
+        lastAssistantMessage = event;
+      } else if (event.type === "session.idle") {
+        resolveIdle();
+      } else if (event.type === "session.error") {
+        const error = new Error(event.data.message);
+        error.stack = event.data.stack;
+        rejectWithError(error);
+      }
+    });
+    let timeoutId;
+    try {
+      await this.send(options);
+      const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(
+          () => reject(
+            new Error(
+              `Timeout after ${effectiveTimeout}ms waiting for session.idle`
+            )
+          ),
+          effectiveTimeout
+        );
+      });
+      await Promise.race([idlePromise, timeoutPromise]);
+      return lastAssistantMessage;
+    } finally {
+      if (timeoutId !== void 0) {
+        clearTimeout(timeoutId);
+      }
+      unsubscribe();
+    }
+  }
+  on(eventTypeOrHandler, handler) {
+    if (typeof eventTypeOrHandler === "string" && handler) {
+      const eventType = eventTypeOrHandler;
+      if (!this.typedEventHandlers.has(eventType)) {
+        this.typedEventHandlers.set(eventType, /* @__PURE__ */ new Set());
+      }
+      const storedHandler = handler;
+      this.typedEventHandlers.get(eventType).add(storedHandler);
+      return () => {
+        const handlers = this.typedEventHandlers.get(eventType);
+        if (handlers) {
+          handlers.delete(storedHandler);
+        }
+      };
+    }
+    const wildcardHandler = eventTypeOrHandler;
+    this.eventHandlers.add(wildcardHandler);
+    return () => {
+      this.eventHandlers.delete(wildcardHandler);
+    };
+  }
+  /**
+   * Dispatches an event to all registered handlers.
+   * Also handles broadcast request events internally (external tool calls, permissions).
+   *
+   * @param event - The session event to dispatch
+   * @internal This method is for internal use by the SDK.
+   */
+  _dispatchEvent(event) {
+    this._handleBroadcastEvent(event);
+    const typedHandlers = this.typedEventHandlers.get(event.type);
+    if (typedHandlers) {
+      for (const handler of typedHandlers) {
+        try {
+          handler(event);
+        } catch (_error) {
+        }
+      }
+    }
+    for (const handler of this.eventHandlers) {
+      try {
+        handler(event);
+      } catch (_error) {
+      }
+    }
+  }
+  /**
+   * Handles broadcast request events by executing local handlers and responding via RPC.
+   * Handlers are dispatched as fire-and-forget — rejections propagate as unhandled promise
+   * rejections, consistent with standard EventEmitter / event handler semantics.
+   * @internal
+   */
+  _handleBroadcastEvent(event) {
+    if (event.type === "external_tool.requested") {
+      const { requestId, toolName } = event.data;
+      const args = event.data.arguments;
+      const toolCallId = event.data.toolCallId;
+      const traceparent = event.data.traceparent;
+      const tracestate = event.data.tracestate;
+      const handler = this.toolHandlers.get(toolName);
+      if (handler) {
+        void this._executeToolAndRespond(
+          requestId,
+          toolName,
+          toolCallId,
+          args,
+          handler,
+          traceparent,
+          tracestate
+        );
+      }
+    } else if (event.type === "permission.requested") {
+      const { requestId, permissionRequest } = event.data;
+      if (this.permissionHandler) {
+        void this._executePermissionAndRespond(requestId, permissionRequest);
+      }
+    }
+  }
+  /**
+   * Executes a tool handler and sends the result back via RPC.
+   * @internal
+   */
+  async _executeToolAndRespond(requestId, toolName, toolCallId, args, handler, traceparent, tracestate) {
+    try {
+      const rawResult = await handler(args, {
+        sessionId: this.sessionId,
+        toolCallId,
+        toolName,
+        arguments: args,
+        traceparent,
+        tracestate
+      });
+      let result;
+      if (rawResult == null) {
+        result = "";
+      } else if (typeof rawResult === "string") {
+        result = rawResult;
+      } else {
+        result = JSON.stringify(rawResult);
+      }
+      await this.rpc.tools.handlePendingToolCall({ requestId, result });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      try {
+        await this.rpc.tools.handlePendingToolCall({ requestId, error: message });
+      } catch (rpcError) {
+        if (!(rpcError instanceof import_node.ConnectionError || rpcError instanceof import_node.ResponseError)) {
+          throw rpcError;
+        }
+      }
+    }
+  }
+  /**
+   * Executes a permission handler and sends the result back via RPC.
+   * @internal
+   */
+  async _executePermissionAndRespond(requestId, permissionRequest) {
+    try {
+      const result = await this.permissionHandler(permissionRequest, {
+        sessionId: this.sessionId
+      });
+      if (result.kind === "no-result") {
+        return;
+      }
+      await this.rpc.permissions.handlePendingPermissionRequest({ requestId, result });
+    } catch (_error) {
+      try {
+        await this.rpc.permissions.handlePendingPermissionRequest({
+          requestId,
+          result: {
+            kind: "denied-no-approval-rule-and-could-not-request-from-user"
+          }
+        });
+      } catch (rpcError) {
+        if (!(rpcError instanceof import_node.ConnectionError || rpcError instanceof import_node.ResponseError)) {
+          throw rpcError;
+        }
+      }
+    }
+  }
+  /**
+   * 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.
+   *
+   * @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.
+   */
+  registerTools(tools) {
+    this.toolHandlers.clear();
+    if (!tools) {
+      return;
+    }
+    for (const tool of tools) {
+      this.toolHandlers.set(tool.name, tool.handler);
+    }
+  }
+  /**
+   * Retrieves a registered tool handler by name.
+   *
+   * @param name - The name of the tool to retrieve
+   * @returns The tool handler if found, or undefined
+   * @internal This method is for internal use by the SDK.
+   */
+  getToolHandler(name) {
+    return this.toolHandlers.get(name);
+  }
+  /**
+   * Registers a handler for permission requests.
+   *
+   * When the assistant needs permission to perform certain actions (e.g., file operations),
+   * this handler is called to approve or deny the request.
+   *
+   * @param handler - The permission handler function, or undefined to remove the handler
+   * @internal This method is typically called internally when creating a session.
+   */
+  registerPermissionHandler(handler) {
+    this.permissionHandler = handler;
+  }
+  /**
+   * Registers a user input handler for ask_user requests.
+   *
+   * When the agent needs input from the user (via ask_user tool),
+   * this handler is called to provide the response.
+   *
+   * @param handler - The user input handler function, or undefined to remove the handler
+   * @internal This method is typically called internally when creating a session.
+   */
+  registerUserInputHandler(handler) {
+    this.userInputHandler = handler;
+  }
+  /**
+   * Registers hook handlers for session lifecycle events.
+   *
+   * Hooks allow custom logic to be executed at various points during
+   * the session lifecycle (before/after tool use, session start/end, etc.).
+   *
+   * @param hooks - The hook handlers object, or undefined to remove all hooks
+   * @internal This method is typically called internally when creating a session.
+   */
+  registerHooks(hooks) {
+    this.hooks = hooks;
+  }
+  /**
+   * Registers transform callbacks for system message sections.
+   *
+   * @param callbacks - Map of section ID to transform callback, or undefined to clear
+   * @internal This method is typically called internally when creating a session.
+   */
+  registerTransformCallbacks(callbacks) {
+    this.transformCallbacks = callbacks;
+  }
+  /**
+   * Handles a systemMessage.transform request from the runtime.
+   * Dispatches each section to its registered transform callback.
+   *
+   * @param sections - Map of section IDs to their current rendered content
+   * @returns A promise that resolves with the transformed sections
+   * @internal This method is for internal use by the SDK.
+   */
+  async _handleSystemMessageTransform(sections) {
+    const result = {};
+    for (const [sectionId, { content }] of Object.entries(sections)) {
+      const callback = this.transformCallbacks?.get(sectionId);
+      if (callback) {
+        try {
+          const transformed = await callback(content);
+          result[sectionId] = { content: transformed };
+        } catch (_error) {
+          result[sectionId] = { content };
+        }
+      } else {
+        result[sectionId] = { content };
+      }
+    }
+    return { sections: result };
+  }
+  /**
+   * Handles a permission request in the v2 protocol format (synchronous RPC).
+   * Used as a back-compat adapter when connected to a v2 server.
+   *
+   * @param request - The permission request data from the CLI
+   * @returns A promise that resolves with the permission decision
+   * @internal This method is for internal use by the SDK.
+   */
+  async _handlePermissionRequestV2(request) {
+    if (!this.permissionHandler) {
+      return { kind: "denied-no-approval-rule-and-could-not-request-from-user" };
+    }
+    try {
+      const result = await this.permissionHandler(request, {
+        sessionId: this.sessionId
+      });
+      if (result.kind === "no-result") {
+        throw new Error(NO_RESULT_PERMISSION_V2_ERROR);
+      }
+      return result;
+    } catch (error) {
+      if (error instanceof Error && error.message === NO_RESULT_PERMISSION_V2_ERROR) {
+        throw error;
+      }
+      return { kind: "denied-no-approval-rule-and-could-not-request-from-user" };
+    }
+  }
+  /**
+   * Handles a user input request from the Copilot CLI.
+   *
+   * @param request - The user input request data from the CLI
+   * @returns A promise that resolves with the user's response
+   * @internal This method is for internal use by the SDK.
+   */
+  async _handleUserInputRequest(request) {
+    if (!this.userInputHandler) {
+      throw new Error("User input requested but no handler registered");
+    }
+    try {
+      const result = await this.userInputHandler(request, {
+        sessionId: this.sessionId
+      });
+      return result;
+    } catch (error) {
+      throw error;
+    }
+  }
+  /**
+   * Handles a hooks invocation from the Copilot CLI.
+   *
+   * @param hookType - The type of hook being invoked
+   * @param input - The input data for the hook
+   * @returns A promise that resolves with the hook output, or undefined
+   * @internal This method is for internal use by the SDK.
+   */
+  async _handleHooksInvoke(hookType, input) {
+    if (!this.hooks) {
+      return void 0;
+    }
+    const handlerMap = {
+      preToolUse: this.hooks.onPreToolUse,
+      postToolUse: this.hooks.onPostToolUse,
+      userPromptSubmitted: this.hooks.onUserPromptSubmitted,
+      sessionStart: this.hooks.onSessionStart,
+      sessionEnd: this.hooks.onSessionEnd,
+      errorOccurred: this.hooks.onErrorOccurred
+    };
+    const handler = handlerMap[hookType];
+    if (!handler) {
+      return void 0;
+    }
+    try {
+      const result = await handler(input, { sessionId: this.sessionId });
+      return result;
+    } catch (_error) {
+      return void 0;
+    }
+  }
+  /**
+   * Retrieves all events and messages from this session's history.
+   *
+   * This returns the complete conversation history including user messages,
+   * assistant responses, tool executions, and other session events.
+   *
+   * @returns A promise that resolves with an array of all session events
+   * @throws Error if the session has been disconnected or the connection fails
+   *
+   * @example
+   * ```typescript
+   * const events = await session.getMessages();
+   * for (const event of events) {
+   *   if (event.type === "assistant.message") {
+   *     console.log("Assistant:", event.data.content);
+   *   }
+   * }
+   * ```
+   */
+  async getMessages() {
+    const response = await this.connection.sendRequest("session.getMessages", {
+      sessionId: this.sessionId
+    });
+    return response.events;
+  }
+  /**
+   * Disconnects this session and releases all in-memory resources (event handlers,
+   * tool handlers, permission handlers).
+   *
+   * Session state on disk (conversation history, planning state, artifacts) is
+   * preserved, so the conversation can be resumed later by calling
+   * {@link CopilotClient.resumeSession} with the session ID. To permanently
+   * remove all session data including files on disk, use
+   * {@link CopilotClient.deleteSession} instead.
+   *
+   * After calling this method, the session object can no longer be used.
+   *
+   * @returns A promise that resolves when the session is disconnected
+   * @throws Error if the connection fails
+   *
+   * @example
+   * ```typescript
+   * // Clean up when done — session can still be resumed later
+   * await session.disconnect();
+   * ```
+   */
+  async disconnect() {
+    await this.connection.sendRequest("session.destroy", {
+      sessionId: this.sessionId
+    });
+    this.eventHandlers.clear();
+    this.typedEventHandlers.clear();
+    this.toolHandlers.clear();
+    this.permissionHandler = 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();
+  }
+  /**
+   * Aborts the currently processing message in this session.
+   *
+   * Use this to cancel a long-running request. The session remains valid
+   * and can continue to be used for new messages.
+   *
+   * @returns A promise that resolves when the abort request is acknowledged
+   * @throws Error if the session has been disconnected or the connection fails
+   *
+   * @example
+   * ```typescript
+   * // Start a long-running request
+   * const messagePromise = session.send({ prompt: "Write a very long story..." });
+   *
+   * // Abort after 5 seconds
+   * setTimeout(async () => {
+   *   await session.abort();
+   * }, 5000);
+   * ```
+   */
+  async abort() {
+    await this.connection.sendRequest("session.abort", {
+      sessionId: this.sessionId
+    });
+  }
+  /**
+   * Change the model for this session.
+   * The new model takes effect for the next message. Conversation history is preserved.
+   *
+   * @param model - Model ID to switch to
+   * @param options - Optional settings for the new model
+   *
+   * @example
+   * ```typescript
+   * await session.setModel("gpt-4.1");
+   * await session.setModel("claude-sonnet-4.6", { reasoningEffort: "high" });
+   * ```
+   */
+  async setModel(model, options) {
+    await this.rpc.model.switchTo({ modelId: model, ...options });
+  }
+  /**
+   * Log a message to the session timeline.
+   * The message appears in the session event stream and is visible to SDK consumers
+   * and (for non-ephemeral messages) persisted to the session event log on disk.
+   *
+   * @param message - Human-readable message text
+   * @param options - Optional log level and ephemeral flag
+   *
+   * @example
+   * ```typescript
+   * await session.log("Processing started");
+   * await session.log("Disk usage high", { level: "warning" });
+   * await session.log("Connection failed", { level: "error" });
+   * await session.log("Debug info", { ephemeral: true });
+   * ```
+   */
+  async log(message, options) {
+    await this.rpc.log({ message, ...options });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CopilotSession,
+  NO_RESULT_PERMISSION_V2_ERROR
+});

package/dist/cjs/telemetry.js

@@ -0,0 +1,35 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var telemetry_exports = {};
+__export(telemetry_exports, {
+  getTraceContext: () => getTraceContext
+});
+module.exports = __toCommonJS(telemetry_exports);
+async function getTraceContext(provider) {
+  if (!provider) return {};
+  try {
+    return await provider() ?? {};
+  } catch {
+    return {};
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getTraceContext
+});

package/dist/cjs/types.js

@@ -0,0 +1,49 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var types_exports = {};
+__export(types_exports, {
+  SYSTEM_PROMPT_SECTIONS: () => SYSTEM_PROMPT_SECTIONS,
+  approveAll: () => approveAll,
+  defineTool: () => defineTool
+});
+module.exports = __toCommonJS(types_exports);
+function defineTool(name, config) {
+  return { name, ...config };
+}
+const SYSTEM_PROMPT_SECTIONS = {
+  identity: { description: "Agent identity preamble and mode statement" },
+  tone: { description: "Response style, conciseness rules, output formatting preferences" },
+  tool_efficiency: { description: "Tool usage patterns, parallel calling, batching guidelines" },
+  environment_context: { description: "CWD, OS, git root, directory listing, available tools" },
+  code_change_rules: { description: "Coding rules, linting/testing, ecosystem tools, style" },
+  guidelines: { description: "Tips, behavioral best practices, behavioral guidelines" },
+  safety: { description: "Environment limitations, prohibited actions, security policies" },
+  tool_instructions: { description: "Per-tool usage instructions" },
+  custom_instructions: { description: "Repository and organization custom instructions" },
+  last_instructions: {
+    description: "End-of-prompt instructions: parallel tool calling, persistence, task completion"
+  }
+};
+const approveAll = () => ({ kind: "approved" });
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SYSTEM_PROMPT_SECTIONS,
+  approveAll,
+  defineTool
+});