github / github/copilot-sdk

[v2] Redesign process and transport configuration APIs

Đang mở
#2,523 1 bình luận 0 reaction 0 người được giao Xem trên GitHub
sdk-v2
Ngôn ngữ chính
Java
Star
10.5k
Fork
1.5k
Merge trung bình
1 ngày 11 giờ
Pull request đã merge (30 ngày)
128

Mô tả

## Summary

Implement a coherent redesign of the boundary between client-wide options, out-of-process transports, and the in-process runtime.

These items are planned v2 work carried forward from #1934. Investigation should determine the correct implementation against the current code, not independently decide whether the work is desirable. If current architecture or completed work contradicts an item, document that evidence and ask maintainers to confirm the change in direction.

## Why this work exists

Several `CopilotClientOptions` were originally implemented by lowering them to environment variables on a spawned CLI process. That is coherent for stdio/TCP clients that own an OS process, but not for an in-process FFI runtime loaded into a shared host process. A process has one ambient environment, so independently mutating it for multiple clients does not provide per-client configuration.

The original in-process implementation rejected some unsupported options while silently ignoring others. #1976 added substantial compatible forwarding and validation; preserve that groundwork and verify the current behavior while implementing the intended v2 API boundary.

## Original option and behavior inventory

The complete environment-lowered inventory recorded in #1934 was:

| Option | Environment variable(s) | Original in-process behavior |
| --- | --- | --- |
| `Environment` | Replaces the process environment block | Rejected |
| `Telemetry` | `COPILOT_OTEL_ENABLED`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, `COPILOT_OTEL_FILE_EXPORTER_PATH`, `COPILOT_OTEL_EXPORTER_TYPE`, `COPILOT_OTEL_SOURCE_NAME`, `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | Rejected |
| `GitHubToken` | `COPILOT_SDK_AUTH_TOKEN`, plus `--auth-token-env` | Silently ignored |
| `BaseDirectory` | `COPILOT_HOME` | Silently ignored |
| `Mode == Empty` | `COPILOT_DISABLE_KEYTAR=1` | Silently ignored |
| `ConnectionToken` | `COPILOT_CONNECTION_TOKEN` | TCP-only; not applicable in-process |

The following options were lowered to CLI arguments, but the original FFI `host_start` arguments were hardcoded to `[entrypoint, "--embedded-host"]` and did not forward them:

- `UseLoggedInUser` → `--no-auto-login`
- `SessionIdleTimeoutSeconds` → `--session-idle-timeout`
- `EnableRemoteSessions` → `--remote`
- `LogLevel` → `--log-level`

The original workaround was to configure the host process before constructing a client:

- set `COPILOT_SDK_AUTH_TOKEN` for authentication
- set `COPILOT_HOME` for the base directory
- set `COPILOT_DISABLE_KEYTAR=1` for empty mode
- set the corresponding `COPILOT_OTEL_*` and `OTEL_*` variables for telemetry

This workaround is historical context, not the desired v2 API.

## Required changes

- Remove client-level working-directory and environment options across SDKs, leaving process-scoped configuration on the applicable transport.
- In Rust, move `working_directory`, `env`, `env_remove`, `program`, prefix/raw arguments, and `extra_args` from `ClientOptions` to the out-of-process transport. These remained on `ClientOptions` because moving them was breaking and the existing Rust transport units/structs were not declared with the `#[non_exhaustive]`/`Default` extensibility needed to add fields compatibly.
- Make Rust's supplied process environment semantics consistent with the other SDKs. The intended behavior from #1934 is that a nonempty supplied environment replaces the inherited environment instead of adding to it.
- Rename shared "child process" connection abstractions to "out of process" where they also cover unrelated TCP processes. Unrelated-process TCP should reject path and argument settings at runtime where they do not apply.
- Replace settings lowered into environment variables or command-line arguments with coherent first-class runtime/server configuration where needed for stdio, TCP, and in-process operation. Environment variables may remain as compatibility overrides.
- Ensure the runtime consumes the `host_start` `env_json` contract for host-side reads so configuration remains per client rather than ambient to the host process.
- Validate settings that cannot apply to in-process or unrelated-process TCP connections, avoiding silent no-ops.

The first-class configuration and `env_json` work may not be possible without runtime changes. If runtime changes are required, file a single follow-up issue describing the complete runtime work and treat implementation of those runtime changes as out of scope for this SDK issue.

## Implementation preparation

- Account for relevant groundwork already merged in #1930 and #1976.
- Confirm the present behavior of all environment- and argument-lowered options listed above.
- Define the consistent public API shape and migration path in every affected SDK.
- Link the single runtime follow-up if required.
- Separate compatible groundwork that can safely land in v1 from the breaking v2 API changes.

## Historical context

- #1934
- #1901
- #1920
- #1929
- #1930
- #1976
- #1993
- Original .NET references in #1934: `dotnet/src/Client.cs` (`ValidateEnvironmentOptions`, in-process startup, child-process environment construction, `ApplyTelemetryEnvironment`, and auth argument handling) and `dotnet/src/FfiRuntimeHost.cs`

## Completion

Implement and test the required cross-SDK behavior, link the consolidated runtime follow-up where required, and document migration from every removed, moved, renamed, or behaviorally changed API. Any item not implemented requires documented contradictory evidence and explicit maintainer agreement.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Hướng nghiên cứu

Bắt đầu bằng việc xem xét dotnet/src/Client.cs và dotnet/src/FfiRuntimeHost.cs, sau đó xác nhận hành vi hiện tại dựa trên phần nền tảng trong #1930 và #1976. Theo dõi các tùy chọn client và các abstraction của transport bị ảnh hưởng xuyên suốt các SDK, đồng thời ghi lại mọi dependency runtime. Công việc được xem là hoàn tất khi hành vi cross-SDK đã được kiểm thử, tài liệu migration đã được tạo và một follow-up runtime hợp nhất đã được liên kết nếu cần.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
rust
Lĩnh vực
api, backend, developer-experience
Loại issue
Tính năng
Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức độ hoạt động
Sôi nổi
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
25/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.