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

42 lines
2.4 KiB
Markdown

# 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.