Files
PaperClipAI/doc/harness-availability.md
T
Devin FoleyandPaperclip ae2afd525b Make harness choices deployment-configurable
Managed deployments need to control harness availability without changing Core policy. Add a generic environment contract and apply it across harness and model selectors, preserving saved supported profiles and validating import, team, and invite selections. Document deployment ownership in agent guidance.

Validation: focused local tests and typechecks passed; all applicable CI checks passed on the reviewed head. Greptile scored 5/5 with no unresolved comments.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-11-20 15:45:36 -08:00

2.4 KiB

Deployment-configured harness availability

Core owns the mechanism for filtering harness choices. The deployment owns the policy. Do not add a built-in Cloud provider allowlist to Core; change the deployment's environment configuration when its supported harnesses change.

Managed deployments can set PAPERCLIP_AVAILABLE_HARNESSES to a JSON array of canonical harness IDs, for example ["gemini_local"]. The server publishes the array as cloud.availableHarnesses on /api/health; every Cloud harness selector uses that metadata. This includes creation and direct setup links, agent configuration, issue and composer settings, bulk edits, imports, team installs, and invites. Model catalogs for excluded harnesses are not fetched by those controls.

  • Unset: no additional deployment restriction. Existing adapter availability, feature flags, and qualification rules still apply.
  • []: no harness choices.
  • Invalid JSON, non-array values, invalid IDs, more than 128 entries, or a value over 16 KiB: no choices, with a warning that omits the supplied value.
  • IDs use lowercase letters, digits, _, :, and -, start with a letter, and are at most 128 characters. Duplicates are removed. Syntactically valid unknown IDs are accepted so configuration does not require a Core registry update; they do not install or enable an adapter.

IDs follow agentRuntimeSettingsHarness in packages/shared/src/agent-runner.ts. Native Runner profiles map to their underlying harness (for example ACP Copilot is copilot_runtime), so allowing the Runner adapter alone cannot bypass a profile restriction. Existing agents can retain their stored configuration; selectors and import or install submissions cannot select an excluded profile.

Change the environment value and restart/redeploy the tenant server. The UI uses the shared health cache; reload the page after rollout to fetch the new policy. The parser also reflects changed values on subsequent health requests in runtimes that update their environment in place. No UI build is needed. Without managed Cloud metadata this setting has no effect.

This is a UI availability policy, not an execution authorization boundary. It does not revoke credentials, stop existing agents, or qualify experimental harnesses. Operators must deploy a Core revision that supports this contract before relying on it; older revisions ignore the variable.