Add VS Code launch config for debugging SDK/runtime (#925)

* Add VS Code launch config for debugging sdk/runtime

* Cleanup

* Make all SDKs consistent in support for COPILOT_CLI_PATH

* Respect uv lockfile to avoid getting new ty versions randomly

* Clean up Node readme

* Update python-sdk-tests.yml

* Different fix for random ty versioning

Author: SteveSandersonMS

.vscode/launch.json

@@ -0,0 +1,23 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug Node.js SDK (chat sample)",
+      "type": "node",
+      "request": "launch",
+      "runtimeArgs": ["--enable-source-maps", "--import", "tsx"],
+      "program": "samples/chat.ts",
+      "cwd": "${workspaceFolder}/nodejs",
+      "env": {
+        "COPILOT_CLI_PATH": "${workspaceFolder}/../copilot-agent-runtime/dist-cli/index.js"
+      },
+      "console": "integratedTerminal",
+      "autoAttachChildProcesses": true,
+      "sourceMaps": true,
+      "resolveSourceMapLocations": [
+        "${workspaceFolder}/**",
+        "${workspaceFolder}/../copilot-agent-runtime/**"
+      ]
+    }
+  ]
+}

dotnet/README.md

@@ -67,7 +67,7 @@ new CopilotClient(CopilotClientOptions? options = null)
 
 **Options:**
 
-- `CliPath` - Path to CLI executable (default: "copilot" from PATH)
+- `CliPath` - Path to CLI executable (default: `COPILOT_CLI_PATH` env var, or bundled CLI)
 - `CliArgs` - Extra arguments prepended before SDK-managed flags
 - `CliUrl` - URL of existing CLI server to connect to (e.g., `"localhost:8080"`). When provided, the client will not spawn a CLI process.
 - `Port` - Server port (default: 0 for random)

dotnet/src/Client.cs

@@ -1064,8 +1064,12 @@ private async Task VerifyProtocolVersionAsync(Connection connection, Cancellatio
 
     private static async Task<(Process Process, int? DetectedLocalhostTcpPort, StringBuilder StderrBuffer)> StartCliServerAsync(CopilotClientOptions options, ILogger logger, CancellationToken cancellationToken)
     {
-        // Use explicit path or bundled CLI - no PATH fallback
-        var cliPath = options.CliPath ?? GetBundledCliPath(out var searchedPath)
+        // Use explicit path, COPILOT_CLI_PATH env var (from options.Environment or process env), or bundled CLI - no PATH fallback
+        var envCliPath = options.Environment is not null && options.Environment.TryGetValue("COPILOT_CLI_PATH", out var envValue) ? envValue
+            : System.Environment.GetEnvironmentVariable("COPILOT_CLI_PATH");
+        var cliPath = options.CliPath
+            ?? envCliPath
+            ?? GetBundledCliPath(out var searchedPath)
             ?? throw new InvalidOperationException($"Copilot CLI not found at '{searchedPath}'. Ensure the SDK NuGet package was restored correctly or provide an explicit CliPath.");
         var args = new List<string>();
 

go/client.go

@@ -199,15 +199,29 @@ func NewClient(options *ClientOptions) *Client {
 		opts.Env = os.Environ()
 	}
 
-	// Check environment variable for CLI path
-	if cliPath := os.Getenv("COPILOT_CLI_PATH"); cliPath != "" {
-		opts.CLIPath = cliPath
+	// Check effective environment for CLI path (only if not explicitly set via options)
+	if opts.CLIPath == "" {
+		if cliPath := getEnvValue(opts.Env, "COPILOT_CLI_PATH"); cliPath != "" {
+			opts.CLIPath = cliPath
+		}
 	}
 
 	client.options = opts
 	return client
 }
 
+// getEnvValue looks up a key in an environment slice ([]string of "KEY=VALUE").
+// Returns the value if found, or empty string otherwise.
+func getEnvValue(env []string, key string) string {
+	prefix := key + "="
+	for i := len(env) - 1; i >= 0; i-- {
+		if strings.HasPrefix(env[i], prefix) {
+			return env[i][len(prefix):]
+		}
+	}
+	return ""
+}
+
 // parseCliUrl parses a CLI URL into host and port components.
 //
 // Supports formats: "host:port", "http://host:port", "https://host:port", or just "port".

nodejs/README.md

@@ -60,7 +60,10 @@ await client.stop();
 Sessions also support `Symbol.asyncDispose` for use with [`await using`](https://github.com/tc39/proposal-explicit-resource-management) (TypeScript 5.2+/Node.js 18.0+):
 
 ```typescript
-await using session = await client.createSession({ model: "gpt-5", onPermissionRequest: approveAll });
+await using session = await client.createSession({
+    model: "gpt-5",
+    onPermissionRequest: approveAll,
+});
 // session is automatically disconnected when leaving scope
 ```
 
@@ -76,7 +79,7 @@ new CopilotClient(options?: CopilotClientOptions)
 
 **Options:**
 
-- `cliPath?: string` - Path to CLI executable (default: "copilot" from PATH)
+- `cliPath?: string` - Path to CLI executable (default: uses COPILOT_CLI_PATH env var or bundled instance)
 - `cliArgs?: string[]` - Extra arguments prepended before SDK-managed flags (e.g. `["./dist-cli/index.js"]` when using `node`)
 - `cliUrl?: string` - URL of existing CLI server to connect to (e.g., `"localhost:8080"`, `"http://127.0.0.1:9000"`, or just `"8080"`). When provided, the client will not spawn a CLI process.
 - `port?: number` - Server port (default: 0 for random)
@@ -184,6 +187,7 @@ const unsubscribe = client.on((event) => {
 ```
 
 **Lifecycle Event Types:**
+
 - `session.created` - A new session was created
 - `session.deleted` - A session was deleted
 - `session.updated` - A session was updated (e.g., new messages)
@@ -293,7 +297,7 @@ if (session.capabilities.ui?.elicitation) {
 
 Interactive UI methods for showing dialogs to the user. Only available when the CLI host supports elicitation (`session.capabilities.ui?.elicitation === true`). See [UI Elicitation](#ui-elicitation) for full details.
 
-##### `destroy(): Promise<void>` *(deprecated)*
+##### `destroy(): Promise<void>` _(deprecated)_
 
 Deprecated — use `disconnect()` instead.
 
@@ -454,8 +458,10 @@ 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 */ },
-})
+    handler: async ({ path, content }) => {
+        /* your logic */
+    },
+});
 ```
 
 #### Skipping Permission Prompts
@@ -467,8 +473,10 @@ defineTool("safe_lookup", {
     description: "A read-only lookup that needs no confirmation",
     parameters: z.object({ id: z.string() }),
     skipPermission: true,
-    handler: async ({ id }) => { /* your logic */ },
-})
+    handler: async ({ id }) => {
+        /* your logic */
+    },
+});
 ```
 
 ### Commands
@@ -571,7 +579,10 @@ const session = await client.createSession({
         mode: "customize",
         sections: {
             // Replace the tone/style section
-            tone: { action: "replace", content: "Respond in a warm, professional tone. Be thorough in explanations." },
+            tone: {
+                action: "replace",
+                content: "Respond in a warm, professional tone. Be thorough in explanations.",
+            },
             // Remove coding-specific rules
             code_change_rules: { action: "remove" },
             // Append to existing guidelines
@@ -586,6 +597,7 @@ const session = await client.createSession({
 Available section IDs: `identity`, `tone`, `tool_efficiency`, `environment_context`, `code_change_rules`, `guidelines`, `safety`, `tool_instructions`, `custom_instructions`, `last_instructions`. Use the `SYSTEM_PROMPT_SECTIONS` constant for descriptions of each section.
 
 Each section override supports four actions:
+
 - **`replace`** — Replace the section content entirely
 - **`remove`** — Remove the section from the prompt
 - **`append`** — Add content after the existing section
@@ -624,7 +636,7 @@ const session = await client.createSession({
     model: "gpt-5",
     infiniteSessions: {
         enabled: true,
-        backgroundCompactionThreshold: 0.80, // Start compacting at 80% context usage
+        backgroundCompactionThreshold: 0.8, // Start compacting at 80% context usage
         bufferExhaustionThreshold: 0.95, // Block at 95% until compaction completes
     },
 });
@@ -723,8 +735,8 @@ const session = await client.createSession({
 const session = await client.createSession({
     model: "gpt-4",
     provider: {
-        type: "azure",  // Must be "azure" for Azure endpoints, NOT "openai"
-        baseUrl: "https://my-resource.openai.azure.com",  // Just the host, no path
+        type: "azure", // Must be "azure" for Azure endpoints, NOT "openai"
+        baseUrl: "https://my-resource.openai.azure.com", // Just the host, no path
         apiKey: process.env.AZURE_OPENAI_KEY,
         azure: {
             apiVersion: "2024-10-21",
@@ -734,6 +746,7 @@ const session = await client.createSession({
 ```
 
 > **Important notes:**
+>
 > - When using a custom provider, the `model` parameter is **required**. The SDK will throw an error if no model is specified.
 > - For Azure OpenAI endpoints (`*.openai.azure.com`), you **must** use `type: "azure"`, not `type: "openai"`.
 > - The `baseUrl` should be just the host (e.g., `https://my-resource.openai.azure.com`). Do **not** include `/openai/v1` in the URL - the SDK handles path construction automatically.
@@ -744,9 +757,9 @@ The SDK supports OpenTelemetry for distributed tracing. Provide a `telemetry` co
 
 ```typescript
 const client = new CopilotClient({
-  telemetry: {
-    otlpEndpoint: "http://localhost:4318",
-  },
+    telemetry: {
+        otlpEndpoint: "http://localhost:4318",
+    },
 });
 ```
 
@@ -772,12 +785,12 @@ If you're already using `@opentelemetry/api` in your app and want this linkage,
 import { propagation, context } from "@opentelemetry/api";
 
 const client = new CopilotClient({
-  telemetry: { otlpEndpoint: "http://localhost:4318" },
-  onGetTraceContext: () => {
-    const carrier: Record<string, string> = {};
-    propagation.inject(context.active(), carrier);
-    return carrier;
-  },
+    telemetry: { otlpEndpoint: "http://localhost:4318" },
+    onGetTraceContext: () => {
+        const carrier: Record<string, string> = {};
+        propagation.inject(context.active(), carrier);
+        return carrier;
+    },
 });
 ```
 
@@ -837,14 +850,15 @@ const session = await client.createSession({
 
 ### Permission Result Kinds
 
-| Kind | Meaning |
-|------|---------|
-| `"approved"` | Allow the tool to run |
-| `"denied-interactively-by-user"` | User explicitly denied the request |
-| `"denied-no-approval-rule-and-could-not-request-from-user"` | No approval rule matched and user could not be asked |
-| `"denied-by-rules"` | Denied by a policy rule |
-| `"denied-by-content-exclusion-policy"` | Denied due to a content exclusion policy |
-| `"no-result"` | Leave the request unanswered (only valid with protocol v1; rejected by protocol v2 servers) |
+| Kind                                                        | Meaning                                                                                     |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `"approved"`                                                | Allow the tool to run                                                                       |
+| `"denied-interactively-by-user"`                            | User explicitly denied the request                                                          |
+| `"denied-no-approval-rule-and-could-not-request-from-user"` | No approval rule matched and user could not be asked                                        |
+| `"denied-by-rules"`                                         | Denied by a policy rule                                                                     |
+| `"denied-by-content-exclusion-policy"`                      | Denied due to a content exclusion policy                                                    |
+| `"no-result"`                                               | Leave the request unanswered (only valid with protocol v1; rejected by protocol v2 servers) |
+
 ### Resuming Sessions
 
 Pass `onPermissionRequest` when resuming a session too — it is required:

nodejs/samples/chat.ts

@@ -1,5 +1,5 @@
-import * as readline from "node:readline";
 import { CopilotClient, approveAll, type SessionEvent } from "@github/copilot-sdk";
+import * as readline from "node:readline";
 
 async function main() {
     const client = new CopilotClient();

nodejs/src/client.ts

@@ -308,8 +308,11 @@ export class CopilotClient {
         this.onListModels = options.onListModels;
         this.onGetTraceContext = options.onGetTraceContext;
 
+        const effectiveEnv = options.env ?? process.env;
         this.options = {
-            cliPath: options.cliUrl ? undefined : options.cliPath || getBundledCliPath(),
+            cliPath: options.cliUrl
+                ? undefined
+                : options.cliPath || effectiveEnv.COPILOT_CLI_PATH || getBundledCliPath(),
             cliArgs: options.cliArgs ?? [],
             cwd: options.cwd ?? process.cwd(),
             port: options.port || 0,
@@ -320,7 +323,7 @@ export class CopilotClient {
             autoStart: options.autoStart ?? true,
             autoRestart: false,
 
-            env: options.env ?? process.env,
+            env: effectiveEnv,
             githubToken: options.githubToken,
             // Default useLoggedInUser to false when githubToken is provided, otherwise true
             useLoggedInUser: options.useLoggedInUser ?? (options.githubToken ? false : true),

python/README.md

@@ -125,7 +125,7 @@ CopilotClient(
 
 **SubprocessConfig** — spawn a local CLI process:
 
-- `cli_path` (str | None): Path to CLI executable (default: bundled binary)
+- `cli_path` (str | None): Path to CLI executable (default: `COPILOT_CLI_PATH` env var, or bundled binary)
 - `cli_args` (list[str]): Extra arguments for the CLI executable
 - `cwd` (str | None): Working directory for CLI process (default: current dir)
 - `use_stdio` (bool): Use stdio transport instead of TCP (default: True)

python/copilot/client.py

@@ -794,16 +794,21 @@ def __init__(
         else:
             self._actual_port = None
 
-            # Resolve CLI path: explicit > bundled binary
+            # Resolve CLI path: explicit > COPILOT_CLI_PATH env var > bundled binary
+            effective_env = config.env if config.env is not None else os.environ
             if config.cli_path is None:
-                bundled_path = _get_bundled_cli_path()
-                if bundled_path:
-                    config.cli_path = bundled_path
+                env_cli_path = effective_env.get("COPILOT_CLI_PATH")
+                if env_cli_path:
+                    config.cli_path = env_cli_path
                 else:
-                    raise RuntimeError(
-                        "Copilot CLI not found. The bundled CLI binary is not available. "
-                        "Ensure you installed a platform-specific wheel, or provide cli_path."
-                    )
+                    bundled_path = _get_bundled_cli_path()
+                    if bundled_path:
+                        config.cli_path = bundled_path
+                    else:
+                        raise RuntimeError(
+                            "Copilot CLI not found. The bundled CLI binary is not available. "
+                            "Ensure you installed a platform-specific wheel, or provide cli_path."
+                        )
 
             # Resolve use_logged_in_user default
             if config.use_logged_in_user is None:

python/pyproject.toml

@@ -34,7 +34,7 @@ Repository = "https://github.com/github/copilot-sdk"
 [project.optional-dependencies]
 dev = [
     "ruff>=0.1.0",
-    "ty>=0.0.2",
+    "ty>=0.0.2,<0.0.25",
     "pytest>=7.0.0",
     "pytest-asyncio>=0.21.0",
     "pytest-timeout>=2.0.0",