Client integration harnesses
Client integration harnesses connect supported native clients to the local gateway. They recognize an existing FCC connection, write only the client settings that FCC owns, refresh those settings when gateway state changes, and report safe status through the local admin surface. The supported set includes Claude clients, Codex, VS Code Chat, JetBrains ACP, and DSH Desktop. The integration-specific rules are collected in Client integration adapters.
Integration boundary
An integration harness is the boundary between FCC's gateway capabilities and a client that stores its own settings. The harness gives the client a local gateway URL, the required authentication data, and any client-specific model or launch information. It does not become the client: the native client still owns its user experience and local state.
Gateway connection contract
The gateway connection contract supplies a loopback proxy root URL and the configured proxy token. Claude clients receive shared Claude environment settings and model discovery. Codex receives the gateway's /v1 endpoint and a generated model catalog path. VS Code Chat receives FCC model entries that point to the gateway's Messages endpoint and carry the managed token as a request header. DSH Desktop receives an FCC provider definition, a default FCC model, and a credential reference for the local gateway. The shared URL helpers treat equivalent loopback names and trailing slashes as the same endpoint, so status does not fail only because a client stores localhost instead of 127.0.0.1.
References: src/…/server_urls.py• L8-55 src/…/claude.py• L11-24 src/…/codex.py• L35-50 src/…/vscode_chat_integration.py• L37-59 src/…/dsh_desktop_integration.py• L96-129
Capability projection
Each adapter projects gateway capabilities into the shape its client understands. Claude integrations use environment variables or gateway profile fields. Codex uses its Responses provider, a native authentication command, and a model catalog that reflects the provider models known to FCC. VS Code Chat uses the shared model catalog to publish model names, limits, input support, and reasoning support in its native model picker. DSH Desktop uses the shared model catalog to build its provider and default model entries. JetBrains ACP uses the installed Claude ACP command plus the same Claude gateway environment.
References: src/…/claude.py• L11-24 src/…/codex.py• L35-50 src/…/codex_model_catalog.py• L35-109 src/…/vscode_chat_integration.py• L8-59 src/…/dsh_desktop_integration.py• L96-103 src/…/jetbrains_acp_integration.py• L198-220
Integration lifecycle
The lifecycle has four actions: status inspects the client, connect establishes FCC-owned settings, disconnect removes those settings, and refresh updates an already recognized connection. Refresh is deliberately narrower than connect. It must not claim an unrelated or incomplete client configuration and must not select a user's model or provider for them.
Connection detection
Detection uses the client settings as evidence of ownership. The harness checks the gateway endpoint and the adapter's identifying fields before it reads or changes dependent state. An absent, changed, malformed, or externally owned configuration remains untouched unless the user explicitly asks for a connect or disconnect operation. DSH Desktop also requires its FCC provider, default model, and credential reference to match the current gateway state before it reports a connection.
References: src/…/claude_integration.py• L72-84 src/…/claude_desktop_integration.py• L272-288 src/…/codex_integration.py• L62-91 src/…/jetbrains_acp_integration.py• L79-92 src/…/vscode_chat_integration.py• L62-87 src/…/dsh_desktop_integration.py• L105-129
Configuration ownership
Connect and disconnect change only the FCC-owned part of a native configuration. User preferences, other providers, other Desktop profiles, unrelated agent entries, and other VS Code model groups remain outside the harness's ownership. DSH Desktop follows the same boundary by changing its FCC provider, FCC default selection, and FCC credential reference without replacing unrelated profile or credential data. Writes use replacement files so a failed update leaves the prior client configuration available for retry.
References: src/…/claude_integration.py• L86-112 src/…/codex_integration.py• L94-111 src/…/claude_desktop_integration.py• L291-300 src/…/vscode_chat_integration.py• L90-148 src/…/dsh_desktop_integration.py• L132-205 src/…/config_file.py• L9-33
Refresh coordination
Refresh runs during application startup and can also be requested from the local admin API. The runtime keeps one update record per integration and reports starting, ready, or failed with a change flag. A status request observes the task rather than repeating the file update. A repeated refresh is idempotent when the client already has the current gateway settings.
VS Code Chat and DSH Desktop follow the same rule when the model catalog changes. Catalog notifications mark each integration dirty, and one owned task drains that work until it has applied the latest catalog. A burst of catalog changes therefore coalesces into refresh work instead of starting one file update for every change.
This diagram shows how a provider catalog change reaches a connected client without configuring an unconnected client.
sequenceDiagram
participant R as Application runtime
participant H as Integration harness
participant C as Native client settings
participant G as Gateway catalog
R->>H: Detect existing FCC connection
alt Connection recognized
R->>G: Wait for required gateway capability
G-->>R: Current URL, token, or model catalog
R->>H: Refresh owned settings
H->>C: Write only changed FCC values
C-->>H: Updated client state
else No FCC connection
H-->>R: No change
end
R-->>R: Publish integration status
References: src/…/integration_service.py• L40-58 src/…/integration_service.py• L83-194 src/…/integration_service.py• L288-333 src/…/dsh_desktop_integration.py• L208-224 src/…/application.py• L235-275 src/…/application.py• L444-471 src/…/application.py• L663-717
Gateway readiness
Codex, VS Code Chat, and DSH Desktop refresh and connect wait for a ready model catalog because the native clients must receive current model data. The runtime checks the catalog generation or revision again before writing. If the provider set changes during the wait, the operation starts again with the newer snapshot. Claude and JetBrains updates do not use that catalog wait because their connection contract does not require a generated model file.
References: src/…/integration_service.py• L210-317 src/…/integration_service.py• L346-392 src/…/integration_service.py• L687-720 src/…/application.py• L663-690 src/…/application.py• L692-717 src/…/paths.py• L80-83
Client integration families
FCC supports several client families with different native configuration models. The common lifecycle is stable across them, while each adapter owns path discovery, markers, resource checks, and cleanup rules.
| Client | Gateway connection form | Main client-owned surface |
|---|---|---|
| Claude in VS Code | Claude environment settings and completed onboarding state | VS Code user settings and Claude state |
| VS Code Chat | FCC model group with gateway Messages URLs and request headers | VS Code Chat model group |
| Claude Desktop | Managed gateway profile selected in the Desktop configuration library | Desktop profile, selection metadata, and deployment mode |
| DSH Desktop | FCC provider, default model, and credential reference in native YAML files | DSH Desktop profile and credentials |
| Codex | FCC Responses provider and generated model catalog | Shared Codex TOML configuration |
| JetBrains ACP | Named Claude ACP agent with a discovered command and Claude environment | JetBrains ACP JSON configuration |
For the path rules, ownership markers, resource checks, and adapter-specific startup behavior, see Client integration adapters.
Integration status
The local admin page exposes status and connect, refresh, and disconnect actions for each supported family. The API requires a loopback caller and a local origin. Responses are not cached because they describe current local files and in-progress update tasks.
References: src/…/admin_routes.py• L262-304 src/…/admin_routes.py• L307-395 src/…/admin_routes.py• L398-419 src/…/integration_service.py• L126-138 src/…/integration_service.py• L196-208 src/…/integration_service.py• L345-357 src/…/integration_service.py• L385-397 src/…/integration_service.py• L483-490
Launch preparation
Some integration adapters also prepare the command and environment that a native client uses to reach the gateway. Preparation returns a launch description rather than running a process. The caller owns process execution, while the harness owns client-specific command selection, environment cleanup, and private files needed by that process. Process ownership and managed child lifetimes are described in CLI launchers and managed processes.
Native command selection
JetBrains ACP resolves the installed ACP package and a compatible Node runtime before it writes the agent entry. It prefers the prior command when it remains valid and falls back to another supported installation. If the package, script, or runtime is not usable, the existing FCC entry stays intact and the user receives an actionable setup error.
References: src/…/jetbrains_acp_integration.py• L100-136 src/…/jetbrains_acp_integration.py• L139-195 src/…/jetbrains_acp_integration.py• L198-220
Child environment
Native clients receive a copy of the parent environment with conflicting provider settings removed or replaced. The environment keeps unrelated user state and adds loopback hosts to NO_PROXY, so local gateway traffic does not use an external proxy. This boundary prevents an old provider credential or proxy rule from silently taking precedence over the FCC connection.
References: src/…/environment.py• L10-35 src/…/environment.py• L46-69 src/…/claude.py• L27-42 src/…/codex.py• L63-93
Private launch resources
Generated files such as the Codex model catalog live in a private temporary directory owned by the launch scope. The directory and files use restrictive permissions and are removed when the scope closes. This keeps short-lived client inputs separate from durable user configuration and avoids overwriting a user file with generated data.
References: src/…/resources.py• L13-41 src/…/codex.py• L63-88 src/…/launch.py• L7-21
Runtime ownership
The application runtime is the single owner of integration operations. It serializes file changes with the configuration lock, runs blocking adapter work in an owned worker boundary, and drains update tasks during shutdown so a process does not close while a native configuration write is still active.
Update isolation
Each integration has its own update state and task. VS Code Chat and DSH Desktop add a dirty flag so catalog changes that arrive during a refresh are handled by the same worker. DSH Desktop also tracks explicit action revisions, so a connect or disconnect request cannot be silently replaced by a catalog-driven refresh. A failed refresh marks only that integration as failed, hides exception details from the admin response, and leaves other integrations available. A later refresh retries the same integration without making a status request perform a write.
References: src/…/integration_service.py• L40-81 src/…/integration_service.py• L100-194 src/…/integration_service.py• L232-317 src/…/integration_service.py• L328-397
Shutdown ownership
Startup schedules integration refreshes as owned tasks after configuration initialization. Shutdown cancels background integration work, waits for those tasks, and holds the configuration lock while it closes owned resources. This ordering prevents a late refresh from writing after the runtime has started to drain.
References: src/…/integration_service.py• L95-119 src/…/application.py• L235-283 src/…/application.py• L303-329 src/…/application.py• L1011-1046
Change checklist
When these files or sections are changed, remember to consider these:
- Changes to a client connection marker must stay aligned across detection, refresh, status, connect, and disconnect. A marker that one action accepts and another action rejects can strand an FCC-owned configuration.
- Changes to the gateway URL or token contract must update every client projection. Claude environment values, Desktop profile values, Codex
/v1settings, VS Code Chat request headers, JetBrains ACP environment values, and DSH Desktop provider credentials must continue to reach the same local gateway. - Changes to Codex, VS Code Chat, or DSH Desktop model discovery must preserve catalog readiness and generation or revision checks. A client must not receive a catalog from an older provider state.
- Changes to an adapter's file writes must preserve unrelated native settings and atomic replacement. A partial update must remain safe to retry.
- Changes to startup update tasks must preserve one task and one status record per integration. A status request must remain read-only while an update is in progress.
- Changes to catalog notifications must preserve VS Code Chat and DSH Desktop dirty-drain behavior. A catalog update that arrives during a refresh must not be lost.
- Changes to DSH Desktop action handling must preserve the action revision check. An explicit connect or disconnect must not be overwritten by a concurrent catalog refresh.
- Changes to launch preparation must keep private generated resources alive until the child process no longer needs them and must keep local gateway hosts outside external proxy routing.
- Changes to admin integration routes must preserve the loopback and local-origin boundary and the no-store response policy.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A client configuration no longer matches FCC's ownership marker or gateway URL | Refresh reports no change and leaves the file alone | Each adapter recognizes its own complete connection before refresh |
| Codex, VS Code Chat, or DSH Desktop refresh starts before the model catalog is ready | The client can point at a missing or stale model catalog, provider, or model list | The runtime waits for catalog readiness and rechecks the generation or revision before writing |
| Native client settings are malformed or structurally invalid | The integration cannot be safely inspected or changed | Adapters reject the document without rewriting it and return a safe admin error |
| A configuration write fails halfway through an update | The client may otherwise lose its prior usable settings | Adapter writes use temporary files and replacement; retries reuse the durable source file |
| A provider catalog changes while VS Code Chat or DSH Desktop refreshes | The client can show a provider or model selection that does not match the current gateway state | The service marks the integration dirty and drains another refresh with a stable snapshot |
| A DSH Desktop native file is absent or its home path is not usable | FCC cannot create or update the DSH provider | The adapter checks the native package path and reports a setup error before configuration |
| JetBrains ACP has no compatible installed package or Node runtime | FCC cannot build a valid agent command | Discovery validates registry metadata, package paths, and Node version before writing |
| Claude Desktop is managed by organization policy | Local FCC changes could conflict with enforced settings | The Desktop adapter refuses managed installations |
| Claude Desktop disconnect cleanup stops partway through | FCC may remain selected or retain an owned profile | A disconnect record makes cleanup retryable and blocks reconnect until removal finishes |
| One integration refresh raises an error during startup | That client stays stale while the whole application needlessly fails | Runtime update state isolates the failure and keeps other integrations running |
| A refresh task writes while runtime shutdown closes configuration resources | A late file update can race with process teardown | The runtime owns update tasks, serializes them with the configuration lock, and waits during shutdown |
Key files
| File | Why to read it |
|---|---|
| src/…/integration_service.py | Defines integration actions, startup refresh, catalog-driven VS Code Chat and DSH Desktop updates, readiness checks, update state, and error boundaries. |
| src/…/application.py | Connects the service to runtime startup, admin actions, configuration locking, and shutdown. |
| src/…/admin_routes.py | Defines the local integration status and connect, refresh, and disconnect API surface. |
| src/…/ports.py | Defines the runtime capabilities exposed to the admin API without exposing adapter internals. |
| src/…/claude_integration.py | Shows the Claude-in-VS-Code connection contract and ownership boundary. |
| src/…/claude_desktop_integration.py | Shows the Desktop profile lifecycle, policy boundary, and retryable disconnect flow. |
| src/…/dsh_desktop_integration.py | Shows DSH Desktop provider projection, native file ownership, catalog refresh, and credential cleanup. |
| src/…/codex_integration.py | Shows Codex TOML recognition, catalog linkage, and non-destructive updates. |
| src/…/vscode_chat_integration.py | Shows the VS Code Chat model group, catalog projection, and preservation of native model settings. |
| src/…/jetbrains_acp_integration.py | Shows ACP agent ownership, installed-resource discovery, and command refresh. |
| src/…/claude.py | Defines shared Claude gateway settings used by integrations and launched sessions. |
| src/…/codex.py | Defines the Codex gateway provider settings and native launch preparation. |
| src/…/codex_model_catalog.py | Defines how gateway model metadata becomes a Codex client catalog. |
| src/…/model_catalog.py | Defines the shared model inventory and the client-facing model metadata used by VS Code Chat. |
| src/…/provider_manager.py | Defines provider generations, catalog readiness, revisions, and change publication. |
| src/…/environment.py | Defines child environment cleanup and local proxy bypass behavior. |
| src/…/resources.py | Defines private generated launch resources and their cleanup scope. |
| src/…/config_file.py | Defines atomic native configuration file replacement. |
| src/…/server_urls.py | Defines canonical local gateway URLs and equivalent URL recognition. |
| src/…/paths.py | Defines shared FCC paths for generated Codex catalog and Desktop disconnect state. |