@github/copilot-sdk 0.3.0 → 1.0.0-beta.10

package/dist/cjs/types.js

@@ -18,7 +18,8 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var types_exports = {};
 __export(types_exports, {
-  SYSTEM_PROMPT_SECTIONS: () => SYSTEM_PROMPT_SECTIONS,
+  RuntimeConnection: () => RuntimeConnection,
+  SYSTEM_MESSAGE_SECTIONS: () => SYSTEM_MESSAGE_SECTIONS,
   approveAll: () => approveAll,
   convertMcpCallToolResult: () => convertMcpCallToolResult,
   createSessionFsAdapter: () => import_sessionFsProvider.createSessionFsAdapter,
@@ -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 = [];
@@ -51,9 +80,10 @@ function convertMcpCallToolResult(callResult) {
           textParts.push(block.resource.text);
         }
         if (block.resource?.blob) {
+          const mimeType = block.resource.mimeType;
           binaryResults.push({
             data: block.resource.blob,
-            mimeType: block.resource.mimeType ?? "application/octet-stream",
+            mimeType: typeof mimeType === "string" && mimeType ? mimeType : "application/octet-stream",
             type: "resource",
             description: block.resource.uri
           });
@@ -71,7 +101,7 @@ function convertMcpCallToolResult(callResult) {
 function defineTool(name, config) {
   return { name, ...config };
 }
-const SYSTEM_PROMPT_SECTIONS = {
+const SYSTEM_MESSAGE_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" },
@@ -81,6 +111,9 @@ const SYSTEM_PROMPT_SECTIONS = {
   safety: { description: "Environment limitations, prohibited actions, security policies" },
   tool_instructions: { description: "Per-tool usage instructions" },
   custom_instructions: { description: "Repository and organization custom instructions" },
+  runtime_instructions: {
+    description: "Runtime-provided context and instructions (e.g. system notifications, memories, workspace context, mode-specific instructions, content-exclusion policy)"
+  },
   last_instructions: {
     description: "End-of-prompt instructions: parallel tool calling, persistence, task completion"
   }
@@ -91,7 +124,8 @@ const defaultJoinSessionPermissionHandler = () => ({
 });
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  SYSTEM_PROMPT_SECTIONS,
+  RuntimeConnection,
+  SYSTEM_MESSAGE_SECTIONS,
   approveAll,
   convertMcpCallToolResult,
   createSessionFsAdapter,

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import { createServerRpc } from "./generated/rpc.js";
 import { CopilotSession } from "./session.js";
-import type { ConnectionState, CopilotClientOptions, GetAuthStatusResponse, GetStatusResponse, ModelInfo, ResumeSessionConfig, SessionConfig, SessionLifecycleEventType, SessionLifecycleHandler, SessionListFilter, SessionMetadata, TypedSessionLifecycleHandler } from "./types.js";
+import type { CopilotClientOptions, GetAuthStatusResponse, GetStatusResponse, ModelInfo, ResumeSessionConfig, SessionConfig, SessionLifecycleEventType, SessionLifecycleHandler, SessionListFilter, SessionMetadata, TypedSessionLifecycleHandler } from "./types.js";
 /**
  * Main client for interacting with the Copilot CLI.
  *
@@ -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,14 +39,22 @@ 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;
+    /** Token sent in `connect`; auto-generated when the SDK spawns its own CLI in TCP mode. */
+    private effectiveConnectionToken?;
     private onListModels?;
     private onGetTraceContext?;
     private modelsCache;
@@ -54,6 +62,7 @@ export declare class CopilotClient {
     private sessionLifecycleHandlers;
     private typedLifecycleHandlers;
     private _rpc;
+    private _internalRpc;
     private processExitPromise;
     private negotiatedProtocolVersion;
     /** Connection-level session filesystem config, set via constructor option. */
@@ -67,44 +76,52 @@ export declare class CopilotClient {
      * 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
      * ```
@@ -134,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.
      *
@@ -160,35 +190,26 @@ export declare class CopilotClient {
      * ```
      */
     forceStop(): Promise<void>;
+    /** Mode-specific defaults spread under the caller's config (app values win). */
+    private configDefaultsForMode;
     /**
-     * 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.
-     *
-     * @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
-     *
-     * @example
-     * ```typescript
-     * // Basic session
-     * const session = await client.createSession({ onPermissionRequest: approveAll });
+     * Returns the systemMessage config to use, adjusted for the current mode.
+     * In empty mode we ensure the environment_context section is removed
+     * unless the app has already taken control of it. `append` (and
+     * unspecified) mode is promoted to `customize` so we can also strip
+     * environment_context; the caller's `content` is preserved verbatim
+     * because the runtime appends it as additional instructions in both
+     * customize and append modes.
+     */
+    private getSystemMessageConfigForMode;
+    /**
+     * Mode-specific options applied via session.options.update after create/resume.
      *
-     * // Session with model and tools
-     * const session = await client.createSession({
-     *   onPermissionRequest: approveAll,
-     *   model: "gpt-4",
-     *   tools: [{
-     *     name: "get_weather",
-     *     description: "Get weather for a location",
-     *     parameters: { type: "object", properties: { location: { type: "string" } } },
-     *     handler: async (args) => ({ temperature: 72 })
-     *   }]
-     * });
-     * ```
+     * In empty mode, defaults the four overridable feature flags to safe values
+     * (caller values from `config` win). `installedPlugins=[]` is unconditional
+     * in empty mode — apps that need custom plugins should switch modes.
      */
+    private updateSessionOptionsForMode;
     createSession(config: SessionConfig): Promise<CopilotSession>;
     /**
      * Resumes an existing conversation session by its ID.
@@ -215,19 +236,6 @@ export declare class CopilotClient {
      * ```
      */
     resumeSession(sessionId: string, config: ResumeSessionConfig): Promise<CopilotSession>;
-    /**
-     * Gets the current connection state of the client.
-     *
-     * @returns The current connection state: "disconnected", "connecting", "connected", or "error"
-     *
-     * @example
-     * ```typescript
-     * if (client.getState() === "connected") {
-     *   const session = await client.createSession({ onPermissionRequest: approveAll });
-     * }
-     * ```
-     */
-    getState(): ConnectionState;
     /**
      * Sends a ping request to the server to verify connectivity.
      *
@@ -243,7 +251,7 @@ export declare class CopilotClient {
      */
     ping(message?: string): Promise<{
         message: string;
-        timestamp: number;
+        timestamp: string;
         protocolVersion?: number;
     }>;
     /**
@@ -267,8 +275,9 @@ export declare class CopilotClient {
      */
     listModels(): Promise<ModelInfo[]>;
     /**
-     * Verify that the server's protocol version is within the supported range
-     * and store the negotiated version.
+     * Send the `connect` handshake (carrying the optional token) and verify the
+     * server's protocol version. Falls back to `ping` against legacy servers
+     * that don't implement `connect`.
      */
     private verifyProtocolVersion;
     /**
@@ -389,7 +398,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`);
      * });
      *
@@ -397,7 +406,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.
      *
@@ -406,7 +415,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`);
@@ -421,7 +430,7 @@ export declare class CopilotClient {
      * unsubscribe();
      * ```
      */
-    on(handler: SessionLifecycleHandler): () => void;
+    onLifecycle(handler: SessionLifecycleHandler): () => void;
     /**
      * Start the CLI server process
      */
@@ -446,18 +455,8 @@ export declare class CopilotClient {
     private handleSessionEventNotification;
     private handleSessionLifecycleNotification;
     private handleUserInputRequest;
+    private handleExitPlanModeRequest;
+    private handleAutoModeSwitchRequest;
     private handleHooksInvoke;
     private handleSystemMessageTransform;
-    /**
-     * Handles a v2-style tool.call RPC request from the server.
-     * Looks up the session and tool handler, executes it, and returns the result
-     * in the v2 response format.
-     */
-    private handleToolCallRequestV2;
-    /**
-     * Handles a v2-style permission.request RPC request from the server.
-     */
-    private handlePermissionRequestV2;
-    private normalizeToolResultV2;
-    private isToolResultObject;
 }