[per-component-executor] - Default split-executor Copilot manifest + OAuth-local validation

[JoshuaRowePhantom]

Default split-executor Copilot manifest + OAuth-local validation

Part of design: #1432 ΓÇö per-component-executor-binding
Design document: https://github.com/JoshuaRowePhantom/Phantom.Workspaces/blob/design/docs/design/per-component-executor-binding.md

Scope

Add defaults/agent-manifests/copilot-split-executor with: one kind:"executor" resource worker (id parameter ΓåÆ worker-profile); a worker-profile parameter (kind executor) + a working-directory parameter; a model with options.executor:"worker"; workspace-gui / workspace-entity tools with no executor (inherit local); a GitHub web MCP tool with no executor (local, for OAuth). Add load-time validation that rejects/warns an OAuth-interactive MCP whose executor is non-local. Cross-check the exact tool/model/connection JSON shapes against features/docs/examples/github-copilot-remote-chat.json.

Files

Phantom.Workspaces.Data.Core/JsonEntities/agent-manifests/copilot-split-executor.json (new); the manifest/validation code that enforces the OAuth-local rule.

Detailed design

Requirement 11 ΓÇö Default split manifest. Ship a default manifest entity (defaults/agent-manifests/...) implementing this split: the Copilot-SDK chat client runs remotely; the chat router, the workspace tools (workspace-gui / workspace-entity), and the GitHub web MCP server run locally.

Requirement 12 ΓÇö No web-vs-non-web distinction. An MCP server with no executor simply runs on the local session executor. There is no special "web tools go remote" rule.

Requirement 13 ΓÇö OAuth interactivity rationale. MCP servers using interactive OAuth (authorization-code with a loopback/localhost redirect + a browser) MUST run on the machine that can open the user's browser and receive the loopback redirect ΓÇö i.e. the local executor. Therefore OAuth-interactive MCP servers MUST be pinned local; the default manifest pins the GitHub web MCP local for this reason (and because that is where the user authenticates). A key/PAT-authenticated web MCP does not strictly require local, but the default ships it local. Validation note: an MCP tool whose connection uses interactive OAuth combined with a non-local executor MUST be rejected or warned at load/validation time.

The worker-profile parameter is of kind executor (see #1434): at launch the user picks the worker executor by choosing either a trust-profile entity or a user-computer-profile entity (the latter synthesizing an implicit trust profile). The worker executor resource's parameter strategy references worker-profile and resolves through the selected/implicit trust profile's DefaultExecutionTarget.

New file (applicable):

• Phantom.Workspaces.Data.Core/JsonEntities/agent-manifests/copilot-split-executor.json ΓÇö the default split-executor manifest entity.

Contradiction note (shape reference):
3. github-copilot-remote-chat.json is an AgentDefinition, not a manifest. It is kind:"prompt" and drives remoting via model.options.additionalProperties.trust-profile (features/docs/examples/github-copilot-remote-chat.json:6-22,78-94) ΓÇö the OLD per-kind approach. It is a useful shape reference for tool/model/connection JSON, but it does not use kind:"executor" resources or an executor field.

Tests

CopilotSplitExecutorManifestTests (Phantom.Workspaces.Data.Core.Tests)

• Manifest_Loads
• Manifest_WorkerProfileParameter_Resolves
• Manifest_ModelBoundToWorker_ResolvesRemote
• Manifest_WorkspaceToolsAndGithubWebMcp_ResolveLocal
• Validation_OAuthInteractiveMcpWithNonLocalExecutor_IsRejected

SplitExecutorIntegrationTests (Phantom.Workspaces.Tests)

• DefaultManifest_Session_RecordsExecutorBindings_CopilotWorker_WorkspaceLocal
• DefaultManifest_Topology_RoutesComponentsAccordingly

Testing strategy ΓÇö Default manifest + validation: The default manifest loads; the worker-profile parameter resolves; the model resolves to the remote worker; the workspace tools and the GitHub web MCP resolve local. A validation test asserts that an OAuth-interactive MCP with a non-local executor is rejected/warned at load. ΓåÆ CopilotSplitExecutorManifestTests.

Testing strategy ΓÇö Full split-executor integration: Using the default manifest, assert the resulting session records executor-bindings with copilot → worker and workspace/github-web → ".", and that the reconstructed topology routes accordingly. ΓåÆ SplitExecutorIntegrationTests.

Dependencies

Depends on: #1433 ΓÇö Executor resource schema + model
Depends on: #1434 ΓÇö executor parameter kind
Depends on: #1435 ΓÇö PhantomMcpTool.Executor field
Depends on: #1436 ΓÇö Executor-resource resolver
Depends on: #1437 ΓÇö Explicit session executor + executor-bindings persistence + resume
Depends on: #1438 ΓÇö Per-tool MCP execution over transport + production remote MCP host

[JoshuaRowePhantom]

Depends on #1433
Depends on #1434
Depends on #1435
Depends on #1436
Depends on #1437
Depends on #1438

[JoshuaRowePhantom]

Design

Root cause / goal (Commit 9 of EPIC #1432). Wave A–D landed the executor primitives (executor resources, ExecutorBindings, per-component executor fields, session executor-bindings persistence). This commit ships the first default manifest that actually exercises a split topology plus the load-time OAuth-local guard (Requirement 13).

Approach.

1. defaults/agent-manifests/copilot-split-executor.json — a real, schema-valid default manifest modeled on github-copilot-agent-manifest.json:
   • Parameter worker-profile (kind: executor, required) + working-directory (kind: string, optional).
   • resources[]: one kind:"executor" resource worker (id: parameter, options.parameter: worker-profile); workspace-entity / workspace-gui / current-session (fixed) and github (mcp-server-entity) tools — none carry an executor, so they inherit the local session executor.
   • The prompt template binds the chat client to the worker via model.options.executor: "worker".
     Result: the Copilot SDK chat client runs on the launch-selected remote worker; the workspace tools and the interactive-OAuth GitHub web MCP stay local.
2. OAuthExecutorBindingValidator — reasons over the same type-discriminated connection-descriptor a binding resolves to (no new schema). Interactive OAuth = an OAuthConnection not in the non-interactive host-pinned entra-pinned mode; a non-local descriptor is any type other than local. Wired into AgentChat right after boundExecutor is resolved and guarded by if (boundExecutor is { } bound) so it's a no-op when no bindings are wired (behavior-preserving). Interactive OAuth + non-local ⇒ InvalidOperationException.

No new executor schema/type — an executor binding is a transport connection-descriptor; ParameterValue/ExecutorDescriptor are out of scope. The OAuth-local runtime path from #1445–#1447 is not touched (this only adds a load-time guard).

Test-project deviation (as in #1442). The issue names manifest-resolution tests in Phantom.Workspaces.Data.Core.Tests, but that project can't reference Phantom.Workspaces.Llm.Core (where AgentManifestLoader/ExecutorBindings/ExecutorResource live). Resolution + validation tests therefore live in Phantom.Workspaces.Llm.Core.Tests (CopilotSplitExecutorManifestTests) alongside the sibling GitHubCopilotAgentManifestParameterTests; the end-to-end session round-trip lives in Phantom.Workspaces.Tests (SplitExecutorIntegrationTests).

Files.

• Phantom.Workspaces.Data.Core/JsonEntities/defaults/agent-manifests/copilot-split-executor.json (new)
• Phantom.Workspaces.Llm.Core/Manifest/OAuthExecutorBindingValidator.cs (new)
• Phantom.Workspaces.Llm.Core/AgentChat.cs (wire the guard)
• Phantom.Workspaces.Llm.Core.Tests/CopilotSplitExecutorManifestTests.cs (new) + csproj embed
• Phantom.Workspaces.Tests/SplitExecutorIntegrationTests.cs (new) + csproj embed

[JoshuaRowePhantom]

Implementation notes

Committed as 5e20a958 on batch/1442-and-1-more (one commit for this issue).

What shipped

• Phantom.Workspaces.Data.Core/JsonEntities/defaults/agent-manifests/copilot-split-executor.json — default split-executor manifest. worker executor resource (id: parameter, options.parameter: worker-profile); model bound via model.options.executor: "worker"; workspace tools + github web MCP carry no executor (inherit local). Entity-id ee99ee19-de6f-4f51-b4a8-9561b9b7e98f, names ["defaults","agent-manifests","copilot-split-executor"].
• Phantom.Workspaces.Llm.Core/Manifest/OAuthExecutorBindingValidator.cs — IsInteractiveOAuth / IsNonLocalExecutor / Validate / EnsureValid. No new schema: it inspects the resolved type-discriminated connection-descriptor. entra-pinned OAuth and key/anonymous connections are exempt.
• Phantom.Workspaces.Llm.Core/AgentChat.cs — calls OAuthExecutorBindingValidator.EnsureValid(tool, bound) immediately after boundExecutor is resolved, guarded by if (boundExecutor is { } bound) so it is a no-op when no bindings are wired (behavior-preserving).
• Tests — CopilotSplitExecutorManifestTests (5: loads, worker-profile resolves, model→remote, workspace/github→local, OAuth-interactive+non-local rejected) and SplitExecutorIntegrationTests (2: session records bindings [worker→remote, session→local, selection round-trips]; topology routes). Both manifest JSONs embedded in the respective test csprojs.

Validation

• Build: 0 warnings / 0 errors (Llm.Core, Llm.Core.Tests, Phantom.Workspaces.Tests).
• Targeted: CopilotSplitExecutorManifestTests + SplitExecutorIntegrationTests + ExecutorAuthoringGuideTests = 11/11; AgentChatTests = 84/84 (no regression from the wiring).
• Stability: CopilotSplitExecutorManifestTests, SplitExecutorIntegrationTests, AgentChatTests, ExecutorAuthoringGuideTests, SchemaPopulatorTests, SchemaDocumentationTests — 10/10 consecutive passes (127 tests each run).

Scope guardrails honored

• No new executor schema/type introduced — a binding is a transport connection-descriptor; ParameterValue/ExecutorDescriptor remain out of scope.
• Only a load-time guard was added; the [MCP OAuth] - Loopback sign-in page should show which application/server was authorized and login-session details #1445–Disable MCP tools after initialization failure instead of retrying every message #1447 OAuth-local runtime path is untouched.
• Test-project placement deviates from the issue text for the layering reason noted in the design comment.

[JoshuaRowePhantom]

Verification result

Status: ✅ Verified
Commit checked: 5e20a958 — Add default split-executor Copilot manifest + OAuth-local validation (#1441)

Feature coverage (against Requirements 11–13)

• Req 11 — Default split manifest. defaults/agent-manifests/copilot-split-executor.json ships as an agent-manifest entity (names ["defaults","agent-manifests","copilot-split-executor"]). It defines one kind:"executor" resource worker (id: parameter, options.parameter: worker-profile); a worker-profile parameter (kind: executor, required) plus a working-directory string parameter; the model binds the Copilot SDK chat client to the worker via model.options.additionalProperties.executor: "worker"; and workspace-entity / workspace-gui / current-session / github (web MCP) tools carry no executor, so they inherit the local session executor. ✔
• Req 12 — No web-vs-non-web distinction. The GitHub web MCP is local purely because it has no executor; no special "web goes remote" rule exists. ✔
• Req 13 — OAuth-local validation. OAuthExecutorBindingValidator (IsInteractiveOAuth / IsNonLocalExecutor / Validate / EnsureValid) rejects an interactive-OAuth MCP bound to a non-local executor. Interactive OAuth = an OAuthConnection NOT in the entra-pinned mode; non-local = any descriptor type other than local. Key/PAT and entra-pinned connections are correctly exempt. ✔

Architecture constraints (all satisfied)

• No new ExecutorDescriptor type/schema. The validator reasons over the same type-discriminated connection-descriptor JsonElement a binding already resolves to; no parallel executor schema was introduced. ✔
• Typed parameter-selections. Selection flows through ExecutorParameterSelection.ForUserComputerProfile → typed JsonElement; parameter-values (string→string) is not widened. ✔
• [per-component-executor] - Typed manifest parameter values (beyond string→string) #1444 (typed ParameterValue) out of scope — not required, correctly deferred. ✔
• No MCP-OAuth runtime regression ([MCP OAuth] - Loopback sign-in page should show which application/server was authorized and login-session details #1445/[MCP OAuth] - All OAuth requests and results must be logged (with #1408 redaction) #1446/Disable MCP tools after initialization failure instead of retrying every message #1447). The new work is a load-time guard only. It is wired into AgentChat immediately after boundExecutor resolution and guarded by if (boundExecutor is { } bound), so it is a strict no-op when no executor bindings are wired — the OAuth local-loopback runtime path is untouched. Confirmed by AgentChatTests (84/84, no regression). ✔
• Correct split topology. Manifest binds only the Copilot chat client (model) to the launch-selected remote worker, while workspace tools + interactive-OAuth GitHub web MCP inherit the local session executor. Integration test DefaultManifest_Session_RecordsExecutorBindings_CopilotWorker_WorkspaceLocal proves worker → user-computer-profile (remote), session → local, and selection round-trip. ✔

Test coverage

All 7 issue-specified tests exist and pass:

• CopilotSplitExecutorManifestTests (5): Manifest_Loads, Manifest_WorkerProfileParameter_Resolves, Manifest_ModelBoundToWorker_ResolvesRemote, Manifest_WorkspaceToolsAndGithubWebMcp_ResolveLocal, Validation_OAuthInteractiveMcpWithNonLocalExecutor_IsRejected (also covers the exempt local/entra-pinned/key branches).
• SplitExecutorIntegrationTests (2): DefaultManifest_Session_RecordsExecutorBindings_CopilotWorker_WorkspaceLocal, DefaultManifest_Topology_RoutesComponentsAccordingly.

The validator's branches (interactive+non-local reject, local pass, entra-pinned pass, key pass) are each covered. No disabled/quarantined tests, no timing-dependent synchronization, no TODOs, no blocking .Result/.Wait()/.GetAwaiter().GetResult(). The test-project placement deviation (resolution tests in Llm.Core.Tests rather than Data.Core.Tests) is justified by a project-reference constraint and disclosed.

The diff touches no filesystem or Git repository layers, so no slow-suite run is required.

Outstanding gaps

None — all criteria satisfied.

Tests

.\scripts\run-tests.ps1 -TestNames CopilotSplitExecutorManifestTests,SplitExecutorIntegrationTests,AgentChatTests
Passed!  - Failed: 0, Passed: 89, ...  Phantom.Workspaces.Llm.Core.Tests.dll
Passed!  - Failed: 0, Passed:  2, ...  Phantom.Workspaces.Tests.dll
=== Test Run Summary === Executed: 91  Passed: 91  Failed: 0

[JoshuaRowePhantom]

Checked in

Commit: 5e20a95
Branch fast-forwarded: features → 5e20a95