Merge remote-tracking branch 'origin/main' into tclem/rust-sdk-release-prep

Author: tclem

docs/setup/backend-services.md

@@ -73,14 +73,40 @@ By default the headless server only accepts connections from loopback (`127.0.0.
 copilot --headless --host 0.0.0.0 --port 4321
 ```
 
-For production, run it as a system service or in a container:
+For production, run it as a system service or in a container.
+
+> **Note:** There is no official pre-built Docker image for the Copilot CLI. You can build your own from the [GitHub releases](https://github.com/github/copilot-cli/releases):
+
+```dockerfile
+FROM debian:bookworm-slim
+ARG COPILOT_VERSION=1.0.7
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates wget \
+    && ARCH=$(dpkg --print-architecture) \
+    && case "${ARCH}" in amd64) COPILOT_ARCH="x64" ;; arm64) COPILOT_ARCH="arm64" ;; *) echo "Unsupported: ${ARCH}" && exit 1 ;; esac \
+    && wget -q "https://github.com/github/copilot-cli/releases/download/v${COPILOT_VERSION}/copilot-linux-${COPILOT_ARCH}.tar.gz" \
+    && tar -xzf "copilot-linux-${COPILOT_ARCH}.tar.gz" \
+    && mv copilot /usr/local/bin/ \
+    && rm "copilot-linux-${COPILOT_ARCH}.tar.gz" \
+    && apt-get purge -y wget && apt-get autoremove -y && rm -rf /var/lib/apt/lists/*
+ENTRYPOINT ["copilot"]
+```
+
+```bash
+# Build the image
+docker build --build-arg COPILOT_VERSION=1.0.7 -t copilot-cli:latest .
+
+# For remote deployments (Kubernetes, ACI, etc.), push to your registry
+docker tag copilot-cli:latest your-registry/copilot-cli:latest
+docker push your-registry/copilot-cli:latest
+```
 
 ```bash
 # Docker — must bind to 0.0.0.0 so the container's published port is reachable
 docker run -d --name copilot-cli \
     -p 4321:4321 \
     -e COPILOT_GITHUB_TOKEN="$TOKEN" \
-    ghcr.io/github/copilot-cli:latest \
+    copilot-cli:latest \
     --headless --host 0.0.0.0 --port 4321
 
 # systemd
@@ -420,7 +446,7 @@ version: "3.8"
 
 services:
   copilot-cli:
-    image: ghcr.io/github/copilot-cli:latest
+    image: copilot-cli:latest  # See "Step 1" above for how to build this image
     command: ["--headless", "--host", "0.0.0.0", "--port", "4321"]
     environment:
       - COPILOT_GITHUB_TOKEN=${COPILOT_GITHUB_TOKEN}

docs/setup/scaling.md

@@ -519,7 +519,7 @@ spec:
     spec:
       containers:
         - name: copilot-cli
-          image: ghcr.io/github/copilot-cli:latest
+          image: your-registry/copilot-cli:latest  # See backend-services.md for how to build and push this image
           args: ["--headless", "--host", "0.0.0.0", "--port", "4321"]
           env:
             - name: COPILOT_GITHUB_TOKEN
@@ -576,7 +576,7 @@ flowchart TB
 ```yaml
 containers:
   - name: copilot-cli
-    image: ghcr.io/github/copilot-cli:latest
+    image: your-registry/copilot-cli:latest  # See backend-services.md for how to build and push this image
     command: ["copilot", "--headless", "--host", "0.0.0.0", "--port", "4321"]
     volumeMounts:
       - name: session-storage

dotnet/README.md

@@ -75,6 +75,7 @@ new CopilotClient(CopilotClientOptions? options = null)
 - `LogLevel` - Log level (default: "info")
 - `AutoStart` - Auto-start server (default: true)
 - `Cwd` - Working directory for the CLI process
+- `CopilotHome` - Base directory for Copilot data (session state, config, etc.). Sets `COPILOT_HOME` on the spawned CLI process. When not set, the CLI defaults to `~/.copilot`. Useful in restricted environments where only specific directories are writable. Ignored when using `CliUrl`.
 - `Environment` - Environment variables to pass to the CLI process
 - `Logger` - `ILogger` instance for SDK logging
 - `GitHubToken` - GitHub token for authentication. When provided, takes priority over other auth methods.

dotnet/src/Client.cs

@@ -70,6 +70,7 @@ public sealed partial class CopilotClient : IDisposable, IAsyncDisposable
     private bool _disposed;
     private readonly int? _optionsPort;
     private readonly string? _optionsHost;
+    private readonly string? _effectiveConnectionToken;
     private int? _actualPort;
     private int? _negotiatedProtocolVersion;
     private List<ModelInfo>? _modelsCache;
@@ -123,23 +124,43 @@ public CopilotClient(CopilotClientOptions? options = null)
         _options = options ?? new();
 
         // Validate mutually exclusive options
-        if (!string.IsNullOrEmpty(_options.CliUrl) && _options.CliPath != null)
+        if (!string.IsNullOrEmpty(_options.CliUrl) && (_options.UseStdio == true || _options.CliPath != null))
         {
-            throw new ArgumentException("CliUrl is mutually exclusive with CliPath");
+            throw new ArgumentException("CliUrl is mutually exclusive with UseStdio and CliPath");
         }
 
-        // When CliUrl is provided, disable UseStdio (we connect to an external server, not spawn one)
+        // When CliUrl is provided, force TCP mode (we connect to an external server, not spawn one)
         if (!string.IsNullOrEmpty(_options.CliUrl))
         {
             _options.UseStdio = false;
         }
+        else
+        {
+            _options.UseStdio ??= true;
+        }
 
         // Validate auth options with external server
         if (!string.IsNullOrEmpty(_options.CliUrl) && (!string.IsNullOrEmpty(_options.GitHubToken) || _options.UseLoggedInUser != null))
         {
             throw new ArgumentException("GitHubToken and UseLoggedInUser cannot be used with CliUrl (external server manages its own auth)");
         }
 
+        if (_options.TcpConnectionToken is not null)
+        {
+            if (_options.TcpConnectionToken.Length == 0)
+            {
+                throw new ArgumentException("TcpConnectionToken must be a non-empty string");
+            }
+            if (_options.UseStdio == true)
+            {
+                throw new ArgumentException("TcpConnectionToken cannot be used with UseStdio = true");
+            }
+        }
+
+        var sdkSpawnsCli = _options.UseStdio == false && string.IsNullOrEmpty(_options.CliUrl);
+        _effectiveConnectionToken = _options.TcpConnectionToken
+            ?? (sdkSpawnsCli ? Guid.NewGuid().ToString() : null);
+
         _logger = _options.Logger ?? NullLogger.Instance;
         _onListModels = _options.OnListModels;
 
@@ -216,7 +237,7 @@ async Task<Connection> StartCoreAsync(CancellationToken ct)
             else
             {
                 // Child process (stdio or TCP)
-                var (cliProcess, portOrNull, stderrBuffer) = await StartCliServerAsync(_options, _logger, ct);
+                var (cliProcess, portOrNull, stderrBuffer) = await StartCliServerAsync(_options, _effectiveConnectionToken, _logger, ct);
                 _actualPort = portOrNull;
                 result = ConnectToServerAsync(cliProcess, portOrNull is null ? null : "localhost", portOrNull, stderrBuffer, ct);
             }
@@ -506,7 +527,8 @@ public async Task<CopilotSession> CreateSessionAsync(SessionConfig config, Cance
                 Traceparent: traceparent,
                 Tracestate: tracestate,
                 ModelCapabilities: config.ModelCapabilities,
-                GitHubToken: config.GitHubToken);
+                GitHubToken: config.GitHubToken,
+                InstructionDirectories: config.InstructionDirectories);
 
             var response = await InvokeRpcAsync<CreateSessionResponse>(
                 connection.Rpc, "session.create", [request], cancellationToken);
@@ -633,7 +655,8 @@ public async Task<CopilotSession> ResumeSessionAsync(string sessionId, ResumeSes
                 Tracestate: tracestate,
                 ModelCapabilities: config.ModelCapabilities,
                 GitHubToken: config.GitHubToken,
-                ContinuePendingWork: config.ContinuePendingWork);
+                ContinuePendingWork: config.ContinuePendingWork,
+                InstructionDirectories: config.InstructionDirectories);
 
             var response = await InvokeRpcAsync<ResumeSessionResponse>(
                 connection.Rpc, "session.resume", [request], cancellationToken);
@@ -1122,30 +1145,42 @@ private void ConfigureSessionFsHandlers(CopilotSession session, Func<CopilotSess
     private async Task VerifyProtocolVersionAsync(Connection connection, CancellationToken cancellationToken)
     {
         var maxVersion = SdkProtocolVersion.GetVersion();
-        var pingResponse = await InvokeRpcAsync<PingResponse>(
-            connection.Rpc, "ping", [new PingRequest()], connection.StderrBuffer, cancellationToken);
+        int? serverVersion;
+        try
+        {
+            var connectResponse = await InvokeRpcAsync<ConnectResult>(
+                connection.Rpc, "connect", [new ConnectRequest { Token = _effectiveConnectionToken }], connection.StderrBuffer, cancellationToken);
+            serverVersion = (int)connectResponse.ProtocolVersion;
+        }
+        catch (RemoteRpcException ex) when (ex.ErrorCode == RemoteRpcException.MethodNotFoundErrorCode)
+        {
+            // Legacy server without `connect`; fall back to `ping`. A token, if any,
+            // is silently dropped — the legacy server can't enforce one.
+            var pingResponse = await InvokeRpcAsync<PingResponse>(
+                connection.Rpc, "ping", [new PingRequest()], connection.StderrBuffer, cancellationToken);
+            serverVersion = pingResponse.ProtocolVersion;
+        }
 
-        if (!pingResponse.ProtocolVersion.HasValue)
+        if (!serverVersion.HasValue)
         {
             throw new InvalidOperationException(
                 $"SDK protocol version mismatch: SDK supports versions {MinProtocolVersion}-{maxVersion}, " +
                 $"but server does not report a protocol version. " +
                 $"Please update your server to ensure compatibility.");
         }
 
-        var serverVersion = pingResponse.ProtocolVersion.Value;
-        if (serverVersion < MinProtocolVersion || serverVersion > maxVersion)
+        if (serverVersion.Value < MinProtocolVersion || serverVersion.Value > maxVersion)
         {
             throw new InvalidOperationException(
                 $"SDK protocol version mismatch: SDK supports versions {MinProtocolVersion}-{maxVersion}, " +
-                $"but server reports version {serverVersion}. " +
+                $"but server reports version {serverVersion.Value}. " +
                 $"Please update your SDK or server to ensure compatibility.");
         }
 
-        _negotiatedProtocolVersion = serverVersion;
+        _negotiatedProtocolVersion = serverVersion.Value;
     }
 
-    private static async Task<(Process Process, int? DetectedLocalhostTcpPort, StringBuilder StderrBuffer)> StartCliServerAsync(CopilotClientOptions options, ILogger logger, CancellationToken cancellationToken)
+    private static async Task<(Process Process, int? DetectedLocalhostTcpPort, StringBuilder StderrBuffer)> StartCliServerAsync(CopilotClientOptions options, string? connectionToken, ILogger logger, CancellationToken cancellationToken)
     {
         // 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
@@ -1163,7 +1198,7 @@ private async Task VerifyProtocolVersionAsync(Connection connection, Cancellatio
 
         args.AddRange(["--headless", "--no-auto-update", "--log-level", options.LogLevel]);
 
-        if (options.UseStdio)
+        if (options.UseStdio == true)
         {
             args.Add("--stdio");
         }
@@ -1197,7 +1232,7 @@ private async Task VerifyProtocolVersionAsync(Connection connection, Cancellatio
             FileName = fileName,
             Arguments = string.Join(" ", processArgs.Select(ProcessArgumentEscaper.Escape)),
             UseShellExecute = false,
-            RedirectStandardInput = options.UseStdio,
+            RedirectStandardInput = options.UseStdio == true,
             RedirectStandardOutput = true,
             RedirectStandardError = true,
             WorkingDirectory = options.Cwd,
@@ -1221,6 +1256,16 @@ private async Task VerifyProtocolVersionAsync(Connection connection, Cancellatio
             startInfo.Environment["COPILOT_SDK_AUTH_TOKEN"] = options.GitHubToken;
         }
 
+        if (!string.IsNullOrEmpty(connectionToken))
+        {
+            startInfo.Environment["COPILOT_CONNECTION_TOKEN"] = connectionToken;
+        }
+
+        if (!string.IsNullOrEmpty(options.CopilotHome))
+        {
+            startInfo.Environment["COPILOT_HOME"] = options.CopilotHome;
+        }
+
         // Set telemetry environment variables if configured
         if (options.Telemetry is { } telemetry)
         {
@@ -1258,7 +1303,7 @@ private async Task VerifyProtocolVersionAsync(Connection connection, Cancellatio
         }, cancellationToken);
 
         var detectedLocalhostTcpPort = (int?)null;
-        if (!options.UseStdio)
+        if (options.UseStdio != true)
         {
             // Wait for port announcement
             using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
@@ -1324,7 +1369,7 @@ private async Task<Connection> ConnectToServerAsync(Process? cliProcess, string?
         Stream inputStream, outputStream;
         NetworkStream? networkStream = null;
 
-        if (_options.UseStdio)
+        if (_options.UseStdio == true)
         {
             if (cliProcess == null)
             {
@@ -1650,7 +1695,8 @@ internal record CreateSessionRequest(
         string? Traceparent = null,
         string? Tracestate = null,
         ModelCapabilitiesOverride? ModelCapabilities = null,
-        string? GitHubToken = null);
+        string? GitHubToken = null,
+        IList<string>? InstructionDirectories = null);
 
     internal record ToolDefinition(
         string Name,
@@ -1707,7 +1753,8 @@ internal record ResumeSessionRequest(
         string? Tracestate = null,
         ModelCapabilitiesOverride? ModelCapabilities = null,
         string? GitHubToken = null,
-        bool? ContinuePendingWork = null);
+        bool? ContinuePendingWork = null,
+        IList<string>? InstructionDirectories = null);
 
     internal record ResumeSessionResponse(
         string SessionId,

dotnet/src/Generated/Rpc.cs

@@ -831,5 +831,8 @@ internal sealed class ConnectionLostException() : IOException("The JSON-RPC conn
 /// </summary>
 internal sealed class RemoteRpcException(string message, int errorCode, Exception? innerException = null) : Exception(message, innerException)
 {
+    /// <summary>JSON-RPC 2.0 reserved error code: requested method does not exist.</summary>
+    public const int MethodNotFoundErrorCode = -32601;
+
     public int ErrorCode { get; } = errorCode;
 }