Skip to content

Redesign process transport options for v2 - #2536

Draft
SteveSandersonMS wants to merge 6 commits into
mainfrom
copilot-sdk-2523-process-transport
Draft

Redesign process transport options for v2#2536
SteveSandersonMS wants to merge 6 commits into
mainfrom
copilot-sdk-2523-process-transport

Conversation

@SteveSandersonMS

@SteveSandersonMS SteveSandersonMS commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

Summary

Closes #2523.

This PR implements the v2 process/transport configuration boundary across SDKs by moving SDK-managed process launch settings off shared client options and onto the out-of-process runtime connection/transport APIs that actually spawn a runtime process.

Current-main findings

Before editing, I refreshed and inspected the latest origin/main and the issue context from #2523, parent #2522, superseded tracker #1934, and linked historical issues/PRs. Current main already contains the compatible in-process groundwork from #1930/#1976 for many first-class options, but the client-wide process launch APIs remained present and could still be configured for transports where they are inapplicable. This PR carries forward the remaining maintainer-intended v2 cleanup from #1934/#2523 rather than treating it as optional design exploration.

Breaking changes and migration

  • .NET: removed CopilotClientOptions.WorkingDirectory and CopilotClientOptions.Environment; moved them to stdio/TCP out-of-process runtime connections. Renamed ChildProcessRuntimeConnection to OutOfProcessRuntimeConnection.
  • Go: removed ClientOptions.WorkingDirectory and ClientOptions.Env; moved them to StdioConnection and TCPConnection. The unexported child-process helper is renamed to out-of-process terminology.
  • Java: removed CopilotClientOptions.cwd/setCwd and CopilotClientOptions.environment/setEnvironment; moved them to StdioRuntimeConnection and TcpRuntimeConnection as workingDirectory and environment. Java has no shared child-process base class, so this intentionally uses the two concrete out-of-process connection types.
  • Node.js: removed client-wide workingDirectory and env; moved them to the renamed OutOfProcessRuntimeConnection base used by stdio/TCP connections. Renamed ChildProcessRuntimeConnection accordingly.
  • Python: removed client-wide working_directory and env; moved them to the renamed OutOfProcessRuntimeConnection base used by stdio/TCP connections. Renamed ChildProcessRuntimeConnection accordingly.
  • Rust: moved program, prefix/raw args, extra_args, working_directory, env, and env_remove from ClientOptions to OutOfProcessOptions carried by the process-spawning transport variants. Transport::External does not expose process launch options because the SDK does not own that process.

The changelog and SDK READMEs include before/after examples for the migration path.

Runtime follow-up

The SDK-side API cleanup is implemented here. Runtime-side per-client host environment consumption remains tracked separately in #2533, the consolidated follow-up for runtime work required by #2523. This PR does not embed or acquire runtime artifacts and does not take lifecycle/SQLite work from #2524/#2525.

Validation

  • Refreshed latest origin/main before final rebase.
  • Confirmed there are no remaining cross-SDK source references to the removed client-level cwd/environment APIs (getCwd, setCwd, .cwd, CopilotClientOptions.environment, getEnvironment, setEnvironment) after the migration.
  • Earlier Java validation during implementation completed ./mvnw test-compile jar:jar, ./mvnw -pl sdk verify -Dskip.test.harness=true, and ./mvnw -pl sdk spotless:check for the environment-only phase. The follow-up cwd/full cross-SDK validation is intentionally left to CI because local E2E/Maven runs were prohibitively expensive in this sandbox.

@SteveSandersonMS SteveSandersonMS added the sdk-v2 Work planned for Copilot SDK v2 label Sep 4, 2026
@SteveSandersonMS
SteveSandersonMS force-pushed the copilot-sdk-2523-process-transport branch 2 times, most recently from e16c5cd to 2d358e0 Compare September 4, 2026 16:39
@github-actions

This comment has been minimized.

Sign in to view
@SteveSandersonMS
SteveSandersonMS force-pushed the copilot-sdk-2523-process-transport branch from 2d358e0 to a7bdc48 Compare September 10, 2026 12:06
@github-actions

This comment has been minimized.

Sign in to view
@github-actions

This comment has been minimized.

Sign in to view
@github-actions

This comment has been minimized.

Sign in to view
SteveSandersonMS and others added 5 commits September 11, 2026 10:14
@SteveSandersonMS
Redesign process transport options for v2
ad10217 
Move process-scoped launch settings from shared client options onto the out-of-process runtime connections across SDKs. Update docs, changelog migration notes, tests, and snapshots for the new v2 API boundary.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@SteveSandersonMS
Fix Go/Python regressions from process-transport rebase
d892297 
- Go: restore unconditional default of processEnv to os.Environ() when
  unset, matching pre-v2 behavior. The default previously only applied
  to out-of-process connections, which broke TestClient_EnvOptions
  under the inprocess CI matrix (COPILOT_SDK_DEFAULT_CONNECTION=inprocess)
  since the env default is harmless (and unused) for in-process
  transport but still part of the client's observable state. Removed
  the now-unused outOfProcessConnection interface and connEnv/
  connWorkingDirectory methods that only existed to support the
  removed gate.
- Python: fix two e2e tests in test_session_e2e.py that still passed
  working_directory/env as CopilotClient-level kwargs instead of on
  the RuntimeConnection, left over from an earlier pass of the v2
  process/transport migration.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@SteveSandersonMS
Revert unintended snapshot fixture drift
e6058df 
Restore all test/snapshots/**/*.yaml files to match origin/main. These
had been unintentionally altered/regenerated by earlier local e2e test
runs against a live model (recorded new conversation content that
doesn't match the checked-in mocked-proxy fixtures) and were carried
through the branch's history and this session's rebase without being
noticed, since git auto-merges YAML content without conflict.

None of this content is related to the process/transport option
redesign; the only fixtures this PR should touch are the small
'Tool ... does not exist' message truncation that varies by available
tool count, which is itself unrelated pre-existing test-environment
noise, not something introduced by option relocation. Also removed
two orphan snapshot files with no corresponding test in the current
tree (should_use_outofprocess_connection_workingdirectory.yaml and
should_report_failure_or_implemented_error_for_missing_mcp_sampling.yaml).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@SteveSandersonMS
Restore fixture for renamed .NET client-options test
8037102 
should_use_outofprocess_connection_workingdirectory.yaml backs the
.NET ClientOptionsE2ETests test that was renamed from
Should_Use_Client_Cwd_For_Default_WorkingDirectory to
Should_Use_OutOfProcess_Connection_WorkingDirectory as part of this
PR (the .NET E2E harness resolves snapshot fixtures by test method
name). This file was incorrectly removed as an apparent orphan in the
prior snapshot-cleanup commit; it is in fact required and its content
was already correct.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@SteveSandersonMS
Fix Windows Rust lifecycle transport options
89a02f1 
Update the Windows-only abrupt host termination test to read process options from the Stdio transport after the v2 process option move.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@SteveSandersonMS
SteveSandersonMS force-pushed the copilot-sdk-2523-process-transport branch from 1ea5ef7 to 89a02f1 Compare September 11, 2026 10:14
@github-actions

This comment has been minimized.

Sign in to view
@SteveSandersonMS
Fix post-rebase SDK CI regressions
06a363a 
Move remaining Node E2E process options onto out-of-process connections, use a supported resume model, and apply Rust formatter output after the Windows lifecycle migration.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@github-actions

github-actions Bot commented Sep 11, 2026

Copy link
Copy Markdown
Contributor

SDK Consistency Review — PR #2536

Verdict: ✅ Consistent across all six SDKs.

This PR moves process-scoped launch settings (working directory, environment variables) off the shared client options and onto the out-of-process connection/transport types, and it does so identically in Node.js, Python, Go, .NET, Java, and Rust:

Language Renamed type New home for workingDirectory/env
Node.js ChildProcessRuntimeConnection → OutOfProcessRuntimeConnection StdioRuntimeConnection / TcpRuntimeConnection
Python ChildProcessRuntimeConnection → OutOfProcessRuntimeConnection StdioRuntimeConnection / TcpRuntimeConnection
.NET ChildProcessRuntimeConnection → OutOfProcessRuntimeConnection StdioRuntimeConnection / TcpRuntimeConnection
Go unexported childProcessConnection → outOfProcessConnection StdioConnection / TCPConnection
Java (no shared base existed) StdioRuntimeConnection / TcpRuntimeConnection directly
Rust new OutOfProcessOptions struct Transport::Stdio(OutOfProcessOptions) / Transport::Tcp { process, .. }

Observations:

  • Each SDK removes the now-invalid "set env in both client options and connection" validation error and the in-process-transport rejection of workingDirectory/env, since those settings are structurally impossible to set on InProcessRuntimeConnection/Transport::InProcess now.
  • The CHANGELOG.md documents the breaking change separately for each language with matching before/after migration snippets, and docs/auth/server-to-server-tokens.md updates all six per-language code samples in lockstep.
  • Naming follows each language's idiom (PascalCase types in .NET/Go exported members, camelCase in Java/TS methods, snake_case in Python/Rust), consistent with the stated conventions.
  • Rust additionally fixes a related inconsistency (env replace vs. merge semantics) called out explicitly in the changelog, bringing it in line with the other five SDKs' existing behavior — a good catch, not a new inconsistency.
  • Extensive test coverage (unit + e2e) was updated in the same PR for every language, plus a new snapshot fixture (test/snapshots/client_options/should_use_outofprocess_connection_workingdirectory.yaml).

No cross-language API drift, naming mismatches, or missing-language gaps were found. This is a model example of a coordinated cross-SDK breaking change.

Generated by SDK Consistency Review Agent for #2536 · copilot · sonnet50 · 52 AIC · ⌖ 12.2 AIC · ⊞ 8.3K · ◷

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot will automatically review once the pull request is marked ready for review

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

sdk-v2 Work planned for Copilot SDK v2

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[v2] Redesign process and transport configuration APIs

1 participant

@SteveSandersonMS