[remote-copilot-sdk] Documentation so an LLM can author a manifest + agent session for a remote Copilot SDK session

[JoshuaRowePhantom]

Part of #1313

Summary

Ship the documentation that lets an LLM (or a human) author a valid agent manifest and start an agent session for the [remote-copilot-sdk] topology described by the split set: a local router + persistence on the source, a remote CopilotSdkChatClient on a user-computer-profile reached over the reverse transport, and a split executor topology where workspace-gui / workspace-entity / source-targeted agent-session / current-session tools execute LOCAL on the source while all other tools (plus the Copilot SDK's built-in tools) execute REMOTE on the SDK's user-computer-profile.

Concretely this bug delivers:

• A new example manifest (docs/examples/github-copilot-remote-chat.json) that demonstrates every field an LLM needs to emit for this topology.
• A dedicated section in the manifest reference (documentation/agent-options-providers.md — the github-copilot and BYOK openai / azure-openai entries) documenting remote hosting: how host-profile-entity-id on the resulting agent-session entity targets a user-computer-profile, and how TrustProfile.HostingWorkspacesClientInstances / TrustProfile.DefaultExecutionTarget + ExecutorTopology express the local/remote split.
• Cross-links from the design doc referenced by the master (docs/design/remote-chat-client-session.md) and the existing github-copilot-provider-support.md, session-context-tools.md, and llm-trust-profile.md.
• An entry in docs/examples/README.md for the new example.
• A test that the new example manifest loads (extending ExampleAgentDefinitionsTests).

The acceptance target is: given only the docs listed here, an LLM can emit a valid manifest for the remote Copilot SDK topology, know which fields select the remote user-computer-profile, know that its workspace-gui / workspace-entity / source-targeted agent-session tool calls will run on the source, and know that its github-copilot (or openai / azure-openai BYOK) chat client + built-in shell tool will run on the remote profile.

Dependencies

• Depends on: [remote-copilot-sdk] Split executor topology: GUI + workspace-entity + source-targeted session tools LOCAL, other tools REMOTE #1317 — the split executor topology (ExecutorTarget + ExecutorTopology mapping to TrustProfile.HostingWorkspacesClientInstances) defines the manifest surface the docs must describe. Documentation can be drafted in parallel with [remote-copilot-sdk] Split executor topology: GUI + workspace-entity + source-targeted session tools LOCAL, other tools REMOTE #1317 but is finalized once [remote-copilot-sdk] Split executor topology: GUI + workspace-entity + source-targeted session tools LOCAL, other tools REMOTE #1317 lands, because the exact field names and defaults for the topology are set there.
• Depends on: [remote-copilot-sdk] Complete + host server-side chat-client transport listener (builds CopilotSdkChatClient from AgentDefinition) #1314 — the server-side chat-client transport listener defines how the remote CopilotSdkChatClient is established (what the wire-carried AgentDefinition must contain). Docs cannot be finalized until [remote-copilot-sdk] Complete + host server-side chat-client transport listener (builds CopilotSdkChatClient from AgentDefinition) #1314's field contract is stable.
• References design: docs/design/remote-chat-client-session.md (the master [remote-copilot-sdk] End-to-end test missing: Copilot-SDK-BYOK AgentChat with source-session tool + built-in PowerShell tool + persistence round-trip #1313 design). If the design doc has not been committed yet, this sub-item includes committing / cross-linking to it.
• Does not block the capstone e2e test [remote-copilot-sdk] End-to-end integration test: SOURCE AgentChat + remote CopilotSdkChatClient + split tool routing + persistence round-trip #1319 (docs are not on the test's critical path), and [remote-copilot-sdk] End-to-end integration test: SOURCE AgentChat + remote CopilotSdkChatClient + split tool routing + persistence round-trip #1319 does not depend on this issue.

Current State / What's Missing

Investigation (paths cited relative to features/):

Existing surfaces the manifest already covers:

• docs/examples/github-copilot-chat.json — the only existing github-copilot example, but it is single-machine (no remote-hosting fields). No example demonstrates remote hosting or the split tool topology.
• docs/examples/README.md — enumerates every current example; has no entry for a remote-hosting variant.
• Phantom.Workspaces.Data.Core/JsonEntities/documentation/agent-options-overview.md — the top-level index. Does not mention remote hosting or host-profile-entity-id selection.
• Phantom.Workspaces.Data.Core/JsonEntities/documentation/agent-options-providers.md — documents github-copilot and BYOK openai / azure-openai (CopilotSdkChatClient). No mention of remote hosting or how the SDK's built-in tools land on the remote profile.
• Phantom.Workspaces.Data.Core/JsonEntities/documentation/agent-options-tools.md — documents tool kinds. Does not describe the local/remote split of tool execution.
• Phantom.Workspaces.Data.Core/JsonEntities/documentation/agent-options-connections.md — documents CopilotByokOptions connection fields for BYOK.
• Phantom.Workspaces.Data.Core/JsonEntities/documentation/agent-options-parameters.md — documents working-directory and notes the future trust-profile parameter. Needs to describe how the trust-profile parameter (with HostingWorkspacesClientInstances on the resolved llm-trust-profile) selects the remote host.
• Phantom.Workspaces.Data.Core/JsonEntities/documentation/agent-configuration.md — already documents host-profile-entity-id on agent-session as "Entity ID of the user-computer-profile hosting this session" (see also Phantom.Workspaces.Data.Core/JsonSchemas/agent-session.json:24). Needs a remote-hosting worked example.
• docs/design/github-copilot-provider-support.md — the design for the github-copilot provider (CopilotSdkChatClient). No cross-link yet to remote-chat-client-session or the split topology.
• docs/design/session-context-tools.md:28-31, 99-103, 200-206 — already correctly documents that host-profile-entity-id records where the session was last hosted but is not the source of truth for the current run; the live host's profile/user is used. This is directly relevant to the doc-set and must be cross-linked.
• docs/design/llm-trust-profile.md — currently only a stub. Needs (or must cross-link to) documentation of TrustProfile.HostingWorkspacesClientInstances (Phantom.Workspaces.Llm.Core/Trust/TrustProfile.cs:99, 137) and TrustProfile.DefaultExecutionTarget (ibid. lines 105, 143).

What is missing (this bug):

1. No example manifest exists under docs/examples/ that demonstrates the remote Copilot SDK topology (github-copilot provider + a remote user-computer-profile execution target + the split tool set). This is the single biggest gap for the LLM authoring path.
2. agent-options-providers.md has no "Remote hosting" subsection for github-copilot / BYOK explaining that (a) the resulting agent-session records host-profile-entity-id = the remote user-computer-profile entity id, (b) the SDK's built-in tools (shell, filesystem) execute on that remote host, and (c) the CLI process and Copilot session id live on the remote host while persistence stays on the source.
3. agent-options-tools.md has no description of the split executor topology: which tool kinds are ExecutorTarget.GuiLocal (workspace-gui, workspace-entity), which are ExecutorTarget.HostingInstance (source-targeted agent-session / current-session), and which are ExecutorTarget.AgentExecutor (all other tools + SDK built-ins). Cite Phantom.Workspaces.Llm.Core/Transport/ExecutorTarget.cs:9-28 and Phantom.Workspaces.Llm.Core/Transport/ExecutorTopology.cs:10-44.
4. agent-options-parameters.md needs to describe the interaction between the (future) trust-profile parameter and remote hosting: the resolved TrustProfile.HostingWorkspacesClientInstances list constrains which user-computer-profiles the session may be hosted on; TrustProfile.DefaultExecutionTarget supplies the connection descriptor when the manifest does not override it.
5. docs/examples/README.md needs a section describing the new example (matching the style of the existing github-models-chat-with-mongodb.json write-up).
6. docs/design/remote-chat-client-session.md — referenced by master [remote-copilot-sdk] End-to-end test missing: Copilot-SDK-BYOK AgentChat with source-session tool + built-in PowerShell tool + persistence round-trip #1313 as the design doc. If not already committed alongside [remote-copilot-sdk] Complete + host server-side chat-client transport listener (builds CopilotSdkChatClient from AgentDefinition) #1314/[remote-copilot-sdk] Split executor topology: GUI + workspace-entity + source-targeted session tools LOCAL, other tools REMOTE #1317, commit it here with cross-links from github-copilot-provider-support.md and llm-trust-profile.md.
7. documentation/agent-configuration.md — extend the agent-session schema section (currently only single-machine example) with a remote-hosting worked example showing host-profile-entity-id pointing at a remote user-computer-profile entity id, plus a note that agent-definition-reference still resolves against the source workspace so the same manifest reconstructs the session on resume.

Code fields the docs must cover (with paths):

• Provider strings github-copilot, openai, azure-openai — dispatched in Phantom.Workspaces.Llm.Core/AgentFactory.cs.
• Phantom.Workspaces.Llm.Core/CopilotByokOptions.cs:16-30 (Provider, BaseUrl, ApiKey) — BYOK connection fields already documented in agent-options-connections.md but must be cross-linked from the remote-hosting section.
• Phantom.Workspaces.Llm.Core/Trust/TrustProfile.cs:99, 105, 137, 143 — HostingWorkspacesClientInstances, DefaultExecutionTarget. Also the sentinels TrustProfile.LocalClientInstance (".") and TrustProfile.WildcardClientInstance ("*").
• Phantom.Workspaces.Llm.Core/Transport/ExecutorTarget.cs:9-28 (AgentExecutor / GuiLocal / HostingInstance) and Phantom.Workspaces.Llm.Core/Transport/ExecutorTopology.cs:10-44 (mapping to client instances).
• Phantom.Workspaces.Data.Core/JsonSchemas/agent-session.json:24-27 — host-profile-entity-id (uuid of user-computer-profile).
• Referencing a user-computer-profile by entity id — see documentation/user-computer-profile-schema.md.

Affected Files

Path	Change	Covers
features/docs/examples/github-copilot-remote-chat.json	create	New example manifest demonstrating github-copilot provider + trust-profile parameter + working-directory parameter targeting a remote user-computer-profile.
features/docs/examples/README.md	update	Add "Remote Copilot SDK" example section describing prerequisites (GITHUB_TOKEN on the remote profile, remote profile enrolled) and behavior (router + persistence local; SDK + built-in tools remote).
features/Phantom.Workspaces.Data.Core/JsonEntities/documentation/agent-options-providers.md	update	Add a "Remote hosting" subsection under github-copilot (and by reference under openai / azure-openai) covering host-profile-entity-id selection, split executor topology summary, and a link to the example.
features/Phantom.Workspaces.Data.Core/JsonEntities/documentation/agent-options-tools.md	update	Add a "Execution target of tool kinds" table mapping each tool kind to ExecutorTarget and, in a remote-hosted session, to source-local vs. remote-host.
features/Phantom.Workspaces.Data.Core/JsonEntities/documentation/agent-options-parameters.md	update	Expand the trust-profile (future) entry with HostingWorkspacesClientInstances / DefaultExecutionTarget semantics and how the manifest opts into remote hosting.
features/Phantom.Workspaces.Data.Core/JsonEntities/documentation/agent-options-overview.md	update	Add a "Remote hosting" bullet under top-level agent definition fields, linking to the providers and tools entities.
features/Phantom.Workspaces.Data.Core/JsonEntities/documentation/agent-configuration.md	update	Add a remote-hosting worked example alongside the existing single-machine agent-session example.
features/docs/design/remote-chat-client-session.md	ensure exists + cross-link	The master's design doc. Cross-link from github-copilot-provider-support.md, llm-trust-profile.md, and session-context-tools.md.
features/docs/design/github-copilot-provider-support.md	update	Add a "Remote hosting" section (short) linking to remote-chat-client-session.md.
features/docs/design/llm-trust-profile.md	update	Document (or link to code + remote-chat-client-session.md) HostingWorkspacesClientInstances and DefaultExecutionTarget.
features/Phantom.Workspaces.Llm.Core.Tests/ExampleAgentDefinitionsTests.cs	update	Add LoadGithubCopilotRemoteChat_ValidatesSuccessfully (see Expected Tests).
features/Phantom.Workspaces.Llm.Core.Tests/Phantom.Workspaces.Llm.Core.Tests.csproj	update	Add <EmbeddedResource Include="..\docs\examples\github-copilot-remote-chat.json" Link="github-copilot-remote-chat.json" />.

Design / Fix

Structure of the new example manifest

The new features/docs/examples/github-copilot-remote-chat.json demonstrates every field an LLM needs to emit. Sketch:

{
  "kind": "prompt",
  "name": "github-copilot-remote-chat",
  "displayName": "GitHub Copilot Chat (remote host)",
  "description": "GitHub Copilot SDK chat client hosted on a remote user-computer-profile; router and persistence stay on the source.",
  "model": {
    "id": "gpt-5",
    "provider": "github-copilot",
    "connection": {
      "kind": "key",
      "apiKey": "${GITHUB_TOKEN}"
    },
    "options": {
      "working-directory": "${working-directory}"
    }
  },
  "instructions": "You are a helpful assistant running on a remote Phantom.Workspaces user-computer-profile. The router and persistence live on the source instance; your built-in shell tool runs here.",
  "parameters": {
    "properties": [
      {
        "name": "working-directory",
        "kind": "string",
        "description": "Working directory the Copilot CLI uses on the remote host.",
        "required": true
      },
      {
        "name": "trust-profile",
        "kind": "string",
        "description": "Name of an llm-trust-profile whose HostingWorkspacesClientInstances lists the remote user-computer-profile.",
        "required": true
      }
    ]
  },
  "tools": [
    { "kind": "workspace-gui" },
    { "kind": "workspace-entity" },
    { "kind": "current-session" },
    { "kind": "filesystem" },
    { "kind": "github-cli-builtin-tools" }
  ],
  "metadata": {
    "version": "1.0",
    "tags": ["github-copilot", "copilot-sdk", "remote", "split-executor"],
    "prerequisites": [
      "The remote user-computer-profile is enrolled and reachable via the reverse-tunnel transport.",
      "An llm-trust-profile exists whose HostingWorkspacesClientInstances contains the remote profile entity id.",
      "GITHUB_TOKEN with Copilot access is available on the remote host (or the remote user is signed in to the Copilot CLI)."
    ]
  }
}

The example intentionally uses parameters (not literal values) for both working-directory and trust-profile so the Launchpad UI collects them. The trust-profile parameter is what selects the remote user-computer-profile: the resolved TrustProfile.HostingWorkspacesClientInstances names the remote instance, and TrustProfile.DefaultExecutionTarget supplies the connection descriptor. The agent-session entity written at launch records host-profile-entity-id = that remote profile's entity id (per agent-configuration.md and agent-session.json:24).

Documentation outline (structure of the new subsections)

agent-options-providers.md, new "Remote hosting" subsection under github-copilot:

1. How a session becomes remote-hosted. The trust-profile parameter resolves an llm-trust-profile whose HostingWorkspacesClientInstances names a non-"." client instance. AgentFactory records the selected host on the agent-session entity's host-profile-entity-id. On session resume, the router reads that field and forwards the chat client to the remote instance.

2. What runs where. Table:

   Component	Source (local)	Remote user-computer-profile
   AgentChat router, steering, persistence	✔
   CopilotSdkChatClient + Copilot CLI process		✔
   Copilot SDK built-in tools (shell, filesystem)		✔
   workspace-gui / workspace-entity tool calls	✔
   Source-targeted agent-session / current-session tools	✔
   Other function / mcp tools		✔ (ExecutorTarget.AgentExecutor)

3. BYOK variant. openai / azure-openai follow the same rules; the BYOK CopilotByokOptions fields (Provider, BaseUrl, ApiKey) come from the model connection and are honored on the remote host.

4. Cross-links to docs/design/remote-chat-client-session.md, session-context-tools.md, agent-options-tools.md#execution-target-of-tool-kinds, and documentation/agent-configuration.md.

agent-options-tools.md, new "Execution target of tool kinds" section:

Tool kind	ExecutorTarget	Runs on
workspace-gui	GuiLocal	source (initiating machine)
workspace-entity	GuiLocal	source
agent-session / current-session (targeting source session id)	HostingInstance	source (host of the source session)
filesystem, web_request, mcp, function, chat-history, github-cli-builtin-tools	AgentExecutor	remote profile in a remote-hosted session; source in single-machine
Copilot SDK built-in tools (shell, etc.)	(SDK self-invokes)	wherever CopilotSdkChatClient runs → remote in a remote-hosted session

agent-options-parameters.md, expand the trust-profile entry: (a) resolves an llm-trust-profile entity by name, (b) HostingWorkspacesClientInstances selects the remote host — "." = source, "*" = any (per TrustProfile.cs:131-134), any other value = a remote client instance id, (c) DefaultExecutionTarget supplies the connection descriptor used to reach the remote instance.

Cross-linking plan

• docs/design/github-copilot-provider-support.md gets a new "Remote hosting" subsection linking to docs/design/remote-chat-client-session.md.
• docs/design/llm-trust-profile.md gets a short "Hosting client instances" subsection linking to the same design.
• docs/design/session-context-tools.md already covers the "host follows the current run, not the persisted host-profile-entity-id" rule; add a cross-link from remote-chat-client-session.md.
• The example manifest's README entry links back to the two documentation entities (agent-options-providers, agent-options-tools).

Expected Tests

Documentation is not unit-tested per line, but the example manifest is machine-validated by the existing example-manifest test class Phantom.Workspaces.Llm.Core.Tests/ExampleAgentDefinitionsTests.cs (which today already contains LoadGithubCopilotChat_ValidatesSuccessfully at line 184, calling AgentDefinitionLoader.LoadAgentFromJson on the embedded resource). We extend it — we do not propose a new test class.

Test (extend ExampleAgentDefinitionsTests)

Purpose

LoadGithubCopilotRemoteChat_ValidatesSuccessfully

Loads the new github-copilot-remote-chat.json embedded resource via AgentDefinitionLoader.LoadAgentFromJson; asserts model.provider == "github-copilot", the working-directory and trust-profile parameters exist and are required, and the tools list contains at least one GuiLocal tool kind (workspace-gui) and at least one AgentExecutor tool kind. Matches the shape of LoadGithubCopilotChat_ValidatesSuccessfully.

Also requires Phantom.Workspaces.Llm.Core.Tests.csproj to add an <EmbeddedResource Include="..\docs\examples\github-copilot-remote-chat.json" ... /> entry alongside the existing example resources (lines 39-45).

Documentation acceptance checklist (verifiable by reading the merged docs)

• docs/examples/github-copilot-remote-chat.json exists and is added as an embedded resource in Phantom.Workspaces.Llm.Core.Tests.csproj.
• ExampleAgentDefinitionsTests.LoadGithubCopilotRemoteChat_ValidatesSuccessfully passes.
• docs/examples/README.md has a section describing the new example (prerequisites, behavior, split tool topology).
• documentation/agent-options-providers.md has a "Remote hosting" subsection under github-copilot covering host-profile-entity-id, the local/remote split table, and BYOK.
• documentation/agent-options-tools.md has an "Execution target of tool kinds" table covering all current tool kinds.
• documentation/agent-options-parameters.md's trust-profile entry documents HostingWorkspacesClientInstances and DefaultExecutionTarget.
• documentation/agent-options-overview.md links to the new remote-hosting section.
• documentation/agent-configuration.md includes a remote-hosting worked example for agent-session.
• docs/design/remote-chat-client-session.md exists (or is committed here) and is cross-linked from github-copilot-provider-support.md, llm-trust-profile.md, and session-context-tools.md.
• Every mention of the split topology cites ExecutorTarget / ExecutorTopology by path so future readers can find the code.

[JoshuaRowePhantom]

Design

Root cause / gap. The [remote-copilot-sdk] topology (issue #1313; landed via #1314/#1315/#1316/#1317/#1318/#1319) has code but no author-facing documentation. There is no example manifest, no docs of the split executor topology or the trust-profile parameter's remote-hosting semantics, no cross-linked design doc.

Chosen approach. Ship the documentation capstone as one commit:

1. New example manifest docs/examples/github-copilot-remote-chat.json — a valid AgentDefinition (kind: prompt, provider: github-copilot) that carries ${working-directory} and ${trust-profile} placeholders in model.options.additionalProperties, tools including workspace-gui / workspace-entity / current-session (GuiLocal / source-targeted) plus filesystem / github-cli-builtin-tools / mcp (AgentExecutor / remote), and a metadata.parameters documentation block listing the two required parameters that belong on the wrapping agent-manifest.
2. Embedded resource entry in Phantom.Workspaces.Llm.Core.Tests.csproj.
3. Extended test ExampleAgentDefinitionsTests.LoadGithubCopilotRemoteChat_ValidatesSuccessfully — asserts provider, placeholder substitution shape, parameter declarations, and split executor topology via ExecutorTargetResolver.ForKind (at least one GuiLocal tool and at least one AgentExecutor tool).
4. New master design docs/design/remote-chat-client-session.md — roles table, executor target model, trust-profile selection, host-profile-entity-id semantics, persistence flow, cross-links.
5. Doc-entity edits:
   • agent-options-providers.md — "Remote hosting" subsection under github-copilot with the local/remote split table.
   • agent-options-tools.md — new "Execution target of tool kinds" table covering every kind and source-targeted agent-session reclassification.
   • agent-options-parameters.md — expanded trust-profile entry describing HostingWorkspacesClientInstances / DefaultExecutionTarget semantics.
   • agent-options-overview.md — new "Remote hosting" bullet linking the pieces together.
   • agent-configuration.md — new "Remote-hosted agent-session" worked example.
6. Design-doc cross-links: github-copilot-provider-support.md, llm-trust-profile.md, session-context-tools.md.
7. README update — docs/examples/README.md entry for the new example.

Design alternatives considered

• Put parameters at the AgentDefinition top level (as the issue sketch suggested). Rejected: Phantom.Workspaces.Llm.Core/JsonSchemas/AgentDefinition.json has additionalProperties: false at the top level, and PromptAgent (decompiled from AgentSchema.dll) has no Parameters property — only AgentManifest does. Extending the schema + loader would be out of scope for a documentation issue. Instead the example uses ${...} placeholders in model.options.additionalProperties (matches existing patterns in github-copilot-agent-manifest.json) and carries the parameter declarations in metadata.parameters for LLM authoring reference; the wrapping-manifest form is documented in agent-configuration.md.
• Extending AgentDefinition.json to allow a parameters block anyway. Rejected: scope creep for a doc bug, and it wouldn't round-trip through PromptAgent.FromJson.

Discrepancies between issue body and the live code

• Table row for source-targeted agent-session / current-session. The issue body proposed HostingInstance for this row, but ExecutorTargetResolver.ForKindWithTargetSession (as landed in [remote-copilot-sdk] Split executor topology: GUI + workspace-entity + source-targeted session tools LOCAL, other tools REMOTE #1317, Phantom.Workspaces.Llm.Core/Transport/ExecutorTargetResolver.cs) reclassifies the source-targeted case to GuiLocal. Followed the code: documented both rows explicitly and cited the method.
• TrustProfile line numbers. Verified against the live file: LocalClientInstance at line 131, WildcardClientInstance at line 134, HostingWorkspacesClientInstances at line 137, DefaultExecutionTarget at line 143 (with TrustProfileDefinition counterparts at 99/105). Cited real line numbers.
• DefaultExecutionTarget type. Documented as JsonElement? (the actual type), not a struct — matches Phantom.Workspaces.Llm.Core/Trust/TrustProfile.cs:143.

Files that will change

• Create: docs/examples/github-copilot-remote-chat.json, docs/design/remote-chat-client-session.md.
• Update: Phantom.Workspaces.Llm.Core.Tests/Phantom.Workspaces.Llm.Core.Tests.csproj, Phantom.Workspaces.Llm.Core.Tests/ExampleAgentDefinitionsTests.cs, Phantom.Workspaces.Data.Core/JsonEntities/documentation/{agent-options-providers,agent-options-tools,agent-options-parameters,agent-options-overview,agent-configuration}.md, docs/design/{github-copilot-provider-support,llm-trust-profile,session-context-tools}.md, docs/examples/README.md.

[JoshuaRowePhantom]

Implementation notes

Commit: 9748299

Deviations from proposed design

• The example manifest omits a top-level parameters block because Phantom.Workspaces.Llm.Core/JsonSchemas/AgentDefinition.json sets additionalProperties: false at the AgentDefinition root and AgentSchema.PromptAgent has no Parameters property (only AgentManifest does). The example instead uses ${working-directory} and ${trust-profile} placeholders in model.options.additionalProperties (matches JsonEntities/defaults/agent-manifests/github-copilot-agent-manifest.json) and carries the parameter declarations in a metadata.parameters documentation block for LLM authoring reference. The wrapping-agent-manifest form (where parameters belongs) is documented in agent-configuration.md § "Remote-hosted agent-session".
• The agent-options-tools.md "Execution target of tool kinds" table has an extra row for source-targeted agent-session / current-session reclassified to GuiLocal, per ExecutorTargetResolver.ForKindWithTargetSession (as landed in [remote-copilot-sdk] Split executor topology: GUI + workspace-entity + source-targeted session tools LOCAL, other tools REMOTE #1317). The issue body's proposed row put source-targeted calls under HostingInstance — that disagrees with the code, so the code was followed.

Scope changes

• Added a small cross-link block at the top of docs/design/session-context-tools.md pointing to the new master design (issue asked for cross-links; the file was previously only referenced from outside).
• No schema/loader/runtime code changes — pure documentation + one embedded example + one test.

Test results

• ExampleAgentDefinitionsTests: Executed 14, Passed 14, Failed 0 (adds LoadGithubCopilotRemoteChat_ValidatesSuccessfully to the existing 13).
• Full fast suite (.\scripts\run-tests.ps1 -Mode fast -NoBuild): Executed 5664, Passed 5664, Failed 0.
• dotnet build --no-incremental: 0 warnings, 0 errors.

Files changed

• docs/examples/github-copilot-remote-chat.json (new) — example AgentDefinition demonstrating the split topology.
• docs/design/remote-chat-client-session.md (new) — master [remote-copilot-sdk] End-to-end test missing: Copilot-SDK-BYOK AgentChat with source-session tool + built-in PowerShell tool + persistence round-trip #1313 topology design.
• Phantom.Workspaces.Llm.Core.Tests/Phantom.Workspaces.Llm.Core.Tests.csproj — embed the new example.
• Phantom.Workspaces.Llm.Core.Tests/ExampleAgentDefinitionsTests.cs — new LoadGithubCopilotRemoteChat_ValidatesSuccessfully.
• Phantom.Workspaces.Data.Core/JsonEntities/documentation/agent-options-providers.md — "Remote hosting" subsection under github-copilot (with local/remote split table + BYOK note).
• Phantom.Workspaces.Data.Core/JsonEntities/documentation/agent-options-tools.md — new "Execution target of tool kinds" table.
• Phantom.Workspaces.Data.Core/JsonEntities/documentation/agent-options-parameters.md — expanded trust-profile entry with HostingWorkspacesClientInstances / DefaultExecutionTarget semantics.
• Phantom.Workspaces.Data.Core/JsonEntities/documentation/agent-options-overview.md — new "Remote hosting" bullet linking the pieces.
• Phantom.Workspaces.Data.Core/JsonEntities/documentation/agent-configuration.md — new "Remote-hosted agent-session" worked example.
• docs/examples/README.md — entry for the new example.
• docs/design/github-copilot-provider-support.md — appended "Remote hosting" cross-link section.
• docs/design/llm-trust-profile.md — new "Hosting client instances" section.
• docs/design/session-context-tools.md — top-of-file cross-link to the new master design.

[JoshuaRowePhantom]

Verification result

Status: ✅ Verified
Commit checked: 97482999 on fix/1320-remote-copilot-docs

Scope

Pure documentation capstone for the #1313 [remote-copilot-sdk] epic: one new example manifest, one new master design doc, expanded/cross-linked docs, one new embedded-resource test. No runtime/schema/loader changes.

Checks

• Example manifest docs/examples/github-copilot-remote-chat.json exists, is a valid AgentDefinition (kind: prompt, provider: github-copilot), loads via AgentDefinitionLoader.LoadAgentFromJson, and is registered as <EmbeddedResource> in Phantom.Workspaces.Llm.Core.Tests.csproj (line 46).
• Test ExampleAgentDefinitionsTests.LoadGithubCopilotRemoteChat_ValidatesSuccessfully genuinely asserts provider == "github-copilot", that ${working-directory} and ${trust-profile} placeholders live in model.options.additionalProperties, that metadata.parameters.properties declares both parameters as required: true, and that the tools list contains at least one ExecutorTarget.GuiLocal kind AND at least one ExecutorTarget.AgentExecutor kind (via ExecutorTargetResolver.ForKind), plus explicitly workspace-gui. Not vacuous.
• Tool-target table in agent-options-tools.md matches the live code: workspace-gui/workspace-entity → GuiLocal; source-targeted agent-session/workspace-agent-session → GuiLocal via ExecutorTargetResolver.ForKindWithTargetSession (verified in Phantom.Workspaces.Llm.Core/Transport/ExecutorTargetResolver.cs:67-81, which reclassifies HostingInstance → GuiLocal when source==target session id); different-target agent-session → HostingInstance; mcp/function/filesystem/web_*/chat-history/github-cli-builtin-tools/unknown → AgentExecutor (default at ExecutorTargetResolver.cs:36,50). Table's remote-hosted column correctly routes AgentExecutor to the remote profile per ExecutorTopology.
• TrustProfile references in agent-options-parameters.md match live code exactly: LocalClientInstance at TrustProfile.cs:131, WildcardClientInstance at :134, HostingWorkspacesClientInstances at :137, DefaultExecutionTarget at :143 typed JsonElement?; TrustProfileDefinition.HostingWorkspacesClientInstances at :99, DefaultExecutionTarget at :105. Type documented as JsonElement? (correct).
• host-profile-entity-id documented in agent-configuration.md at the correct schema location (agent-session.json:24, uuid format).
• New master design docs/design/remote-chat-client-session.md exists (6998 bytes) and is cross-linked from github-copilot-provider-support.md:584, llm-trust-profile.md:27,43, and session-context-tools.md:4.
• Discrepancy Bump actions/upload-artifact from 4 to 7 #2 (parameters placement). Independently verified: AgentDefinition.json has additionalProperties: false at root and PromptAgent has no Parameters property. The example's shape — ${...} placeholders in model.options.additionalProperties + a documentation-only metadata.parameters block — is genuinely schema-valid (the test's successful LoadAgentFromJson call proves it) and the wrapping agent-manifest form (where parameters actually belongs) is documented in agent-configuration.md §"Remote-hosted agent-session". The LLM-authoring acceptance target is met.

Minor observation (not a gap)

agent-options-tools.md's row for current-session labels it "GuiLocal (source-targeted rule)". ExecutorTargetResolver.ForKind does not name current-session (it would fall to AgentExecutor by default), and ForKindWithTargetSession only reclassifies HostingInstance (i.e. agent-session/workspace-agent-session). In practice current-session is an AIContextProvider (ToolsetFactory.cs), not a routed tool call, so the executor-target classification is largely nominal for that kind; the doc's conceptual claim (current-session runs on the source) is correct even though it doesn't map through ForKindWithTargetSession in code. Not filed as a gap because the acceptance target (author a valid manifest) is unaffected.

Tests

Ran .\scripts\run-tests.ps1 -TestNames ExampleAgentDefinitionsTests per scripts\test-results.log:

=== Test Run Summary ===
Executed : 14
Passed   : 14
Failed   : 0

Includes the new LoadGithubCopilotRemoteChat_ValidatesSuccessfully.

Outstanding gaps

None — all criteria satisfied.

needs-slow-tests

No — diff is docs + one embedded-resource unit test; no filesystem/git-layer changes.

[JoshuaRowePhantom]

Checked in

Commit: 9748299
Branch fast-forwarded: features → 9748299