Files
PaperClipAI/docker/daytona-runner
eaac8ed0f7 feat(adapters): add Claude Fable 5.2 and GPT-6.2 with CLI floors, and refresh sandbox CLI pins (Nov 18 audit) (#22222)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agents run on coding harnesses. Each adapter has a model catalog,
and sandboxes contain pinned CLIs.
> - Anthropic released Claude Fable 5.2 and OpenAI released GPT-6.2 Sol
and GPT-6.2 Astra for Codex. Both need newer CLIs than the Paperclip
Runner provider pack ships.
> - A stale catalog hides valid models. A model that needs a newer CLI
fails with an opaque backend error.
> - This pull request adds the verified model IDs with their CLI floors,
names the version gap in Paperclip Runner, and refreshes the sandbox CLI
pins.
> - The benefit is that operators can select current models and get a
named version error instead of a backend failure.

## Linked Issues or Issue Description

Refs #20774 and #21636 (both add parts of Fable 5.2 support; see
"Overlap" below).
Refs #18486 (adds GPT-6.1 Terra; this PR does not duplicate it).
Refs #16708 (adds Claude Haiku 5.5 to `claude_local`; this PR does not
duplicate it).

**What happened?**

Claude Fable 5.2 (`claude-fable-5-2`) and GPT-6.2 Sol / Astra
(`gpt-6.2-sol`, `gpt-6.2-astra`) are generally available. The
`claude_local`, `codex_local`, and OpenCode pickers do not list them.
Claude Code 2.1.321 is the first release with Fable 5.2. Codex 0.169.1
is the first release whose bundled catalog lists GPT-6.2. The Paperclip
Runner provider pack bundles Claude Code 2.1.286 and Codex 0.160.0.

**Expected behavior**

The pickers list the new models. A run on a CLI below the model minimum
stops with the detected and required versions, or falls back to a
compatible model with a visible message.

**Proposed change**

Add the models and their per-model CLI floors. Gate ACPX Claude in
Paperclip Runner on the Claude Code version that its Agent SDK bundles.
Refresh the sandbox CLI pins with verified digests. Record the audit.

## What Changed

- Claude Code (`claude_local`):
- Add `claude-fable-5-2` (label "Claude Fable 5.2") at the top of the
picker. `claude-fable-5-1` stays selectable after the current-generation
models.
- Add Bedrock `global.anthropic.claude-fable-5-2`. Anthropic documents
only this global ID for Bedrock.
  - Fable 5.2 offers all five efforts (`low` to `max`).
- `minimumClaudeCliVersionForModel("claude-fable-5-2")` returns
`2.1.321`. The existing CLI-lane Test and launch checks use this floor.
On a managed sandbox, the CLI lane installs a private Claude Code at
this version, as it does for the other floors.
- Paperclip Runner (ACPX Codex): `resolvePaperclipRunnerProviderProfile`
rejects a model whose Codex floor is above the qualified ACPX Codex
runtime (`0.160.0`). The error code is
`paperclip_runner_codex_cli_version_incompatible`, and the message gives
both versions.
- Paperclip Runner (ACPX Claude):
`resolvePaperclipRunnerProviderProfile` rejects a model whose Claude
Code floor is above the version that the qualified Agent SDK bundles.
The error code is `paperclip_runner_claude_cli_version_incompatible`.
The message gives both versions. A new helper,
`claudeCodeVersionForAgentSdk`, maps SDK `0.3.N` to Claude Code `2.1.N`
(the SDK's `claudeCodeVersion` field) and returns `null` for any other
line.
- Codex (`codex_local`):
- Add `gpt-6.2-sol` and `gpt-6.2-astra` at the top of the picker, in the
bundled catalog order.
  - Both offer Fast mode and the `low` to `ultra` efforts.
- Both have a CLI floor of `0.169.1`. On the native Codex provider with
the pinned Codex 0.160.0, the existing fallback moves `gpt-6.2-sol` to
`gpt-6.1-sol` and `gpt-6.2-astra` to `gpt-6-astra` with a visible
message.
  - The default stays `gpt-6.1-sol`.
- OpenCode fallback catalog: add `openai/gpt-6.2-sol`,
`openai/gpt-6.2-astra`, `anthropic/claude-fable-5-2`,
`google/gemini-4-carbon`, and `google/gemini-4-hydrogen`.
- Evaluation image sandbox layer (`docker/daytona-runner`):

  | CLI | Before | After |
  | --- | --- | --- |
  | Grok CLI | 1.0.70 | 1.0.89 |
  | Gemini CLI | 0.65.0 | 0.68.0 |
  | Cursor CLI | 2026.10.22-27dcf5f | 2026.11.17-f532c45 |
  | GitHub CLI | 2.103.3 | 2.105.0 |

- Add `doc/adapter-model-audit-2026-11-18.md` with sources,
compatibility findings, and deferred items. Add a note on above-window
Codex floors to `doc/architecture/paperclip-runner-compatibility.md`.

No saved agent changes model, effort, or spending settings. No picker
entry is removed.

### Managed sandboxes

On Paperclip Runner, Fable 5.2 and GPT-6.2 stay unusable until the
provider pack moves to Claude Code 2.1.321 or later and Codex 0.169.1 or
later. A sandbox image that carries that provider pack must also be
promoted. This PR does not change the provider pack (see "Deferred
items" in the audit). Native remote Codex accepts only `>=0.149.0
<0.161.0`, so GPT-6.2 also needs that window to move.

### Overlap

- #21636 sets the Fable 5.2 floor to `2.1.290`. The [Claude Code
changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)
adds Fable 5.2 in 2.1.321. `git merge-tree` merges the two without a
text conflict, but #21636's line becomes unreachable after this PR's
line, and its test then fails. Rule: keep `2.1.321`. Merge this PR
first. Then close #21636 or change its floor and test to `2.1.321`.
- #20774 (draft) lists `claude-fable-5-2`. It conflicts in
`packages/adapters/claude-local/src/index.ts` and
`server/src/__tests__/adapter-models.test.ts`. Rule: keep this PR's
catalog order and Bedrock ID.
- #18486 adds `gpt-6.1-terra`. It conflicts in
`packages/adapters/codex-local/src/index.test.ts` and
`src/server/codex-args.test.ts` (the ordered ID list and the Fast-mode
message). Rule: keep both sets of models in the bundled catalog order
(`gpt-6.2-sol`, `gpt-6.2-astra`, `gpt-6-astra`, `gpt-6.1-sol`,
`gpt-6.1-terra`, ...). Either PR can merge first; the second rebases.
- #16708 adds Claude Haiku 5.5. It conflicts in
`packages/adapters/claude-local/src/index.test.ts` (adjacent test cases)
and `doc/DEVELOPING.md`. Rule: keep both test blocks.

## Verification

Research date: November 18, 2026. Sources are listed in the audit doc.

- `vitest run src/index.test.ts src/server/model-order.test.ts
src/server/cli-capabilities.test.ts src/server/test.remote.test.ts` in
`packages/adapters/claude-local`: 40 passed. `execute.remote.test.ts`
(29), `test.probe.test.ts` (21), `sandbox-cli-version.test.ts` (15),
`acp.auth.test.ts` (25), and `acp.test.ts` (47, with
`--testTimeout=60000`) also passed when run one file at a time.
- `vitest run src/index.test.ts src/server/codex-args.test.ts
src/ui/build-config.test.ts src/server/test.remote.test.ts` in
`packages/adapters/codex-local`: all passed (155). `acp.test.ts` (49),
`acp.cli-version.test.ts` (4), and `execute.test.ts` (10) also passed
one file at a time.
- `vitest run` in `packages/adapters/opencode-local`: 94 passed.
- `vitest run src/services/native-runtime/acpx-qualification.test.ts
src/services/native-runtime/codex-model-fallback.test.ts
src/__tests__/adapter-models.test.ts
src/__tests__/heartbeat-model-fallback-warning.test.ts` in `server`: all
passed. The new cases cover the ACPX Claude and ACPX Codex version
errors and the native GPT-6.2 fallback on Codex 0.160.0.
- `vitest run src/lib/agent-setup-fields.test.ts
src/lib/codex-reasoning-effort.test.ts` in `ui`: 11 passed.
- `tsc --noEmit` in the three adapters and `pnpm typecheck` in `server`:
passed.
- Cursor archive SHA-256
`189ed41d8963cd22dcdafbbd62f072cc55ac08374c922dbd04aee525f4018ab6` is
computed from the versioned Linux x64 tarball. The extracted binary
reports `2026.11.17-f532c45`, the version that
`https://cursor.com/install` resolves.
- GitHub CLI SHA-256
`79e7ab5db738c48777b696e374f8b428f0647debfb424f44d2f426370407fe2f`
matches `gh_2.105.0_checksums.txt`.
- Grok CLI 1.0.89 and Gemini CLI 0.68.0 installed from npm report those
versions. The flags that Paperclip uses are in `--help` (`-m`,
`--effort`, `grok models`; `-m`, `-p`, `--output-format`,
`--approval-mode`, `--yolo`).
- Host baseline: tests that create an AI provider need the host's empty
`ANTHROPIC_BASE_URL` unset. Under full-package parallel runs, SSH and
sandbox fixture tests time out at 5 seconds on this host; each file
passes alone. The audit doc records both.
- Not run locally: the full `pnpm -r typecheck`, `pnpm build`, browser
suites, and the image build. CI runs these. No live model inference ran.

## Risks

- Low risk for saved agents: no default, saved model, effort, or
spending setting changes.
- The new Paperclip Runner checks reject `claude-fable-5-2` on ACPX
Claude and `gpt-6.2-*` on ACPX Codex (and any later model whose floor is
above the bundled runtime) before launch. Without this PR, the turn
would start and fail at the backend.
- The `0.3.N` → `2.1.N` mapping covers only the current SDK line. Any
other line returns `null`, and the check is skipped.
- The sandbox CLI pins change only the evaluation image. The fleet image
change is separate.
- Rollback: revert this PR. No data migration.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, through Claude Code
with tool use (shell, web fetch, file edits).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: devinfoley <139239+devinfoley@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 14:27:00 -08:00
..

Paperclip Daytona runner image

Ordinary provider packs now include pinned Cursor assets for Linux x64; no --candidate-providers=cursor flag is needed. Cursor admission is enabled after the production readiness gates passed. The public CLI installation command is paperclipai runtime setup cursor; it runs explicitly on the execution host and is never an npm installation hook.

This image is the Paperclip Cloud fleet sandbox image plus a source-built paperclip-runnerd and immutable provider pack. The pack contains Node 24.11, OpenCode 1.18.34, the compiled OpenCode proxy, ACPX 0.22.0 sidecar, qualified ACP agents, and the production lockfile. Its manifest digests each executable bridge and records the runner source revision as provenance. Its interface declaration allows compatible app releases to reuse it without uploading or installing a pack.

The fleet pins are intentionally copied from paperclip-cloud/fleet-sandbox-image/Dockerfile. Update both definitions together until the fleet base is published as a stable image that this Dockerfile can extend directly.

Harness versions

The October 2026 refreshes pin Codex 0.160.0, Claude Agent SDK 0.3.286 (Claude Code 2.1.286), and OpenCode 1.18.34 in the shared provider pack. Claude Code 2.1.280 is the minimum for Opus 5.5 and 2.1.284 is the minimum for Sonnet 5.5; the pinned runtime also supports Fable 5.1. Fable 5.2 needs Claude Code 2.1.321, so it does not run on Paperclip Runner with this image until the provider pack moves past that version. Codex 0.160.0 ships bundled metadata for the GPT-6.1 Sol, GPT-6 Sol, and GPT-6 Luna model IDs; GPT-6.2 Sol and Astra need Codex 0.169.1. The sandbox layer pins Grok CLI 1.0.89, Gemini CLI 0.68.0, Kimi Code 2.3.3, Cursor CLI 2026.11.17-f532c45, and GitHub CLI 2.105.0 (November 2026 refresh). The native Cursor provider uses its separately verified distribution, pinned to 2026.09.26-dd393fe; it does not use the sandbox layer’s global Cursor executable. Grok CLI 1.0.89 supports the current Grok 4.7 model family. Hermes stays at 0.19.0, the newest release on PyPI.

Keep the patched ACP bridge versions separate from their CLI runtime pins. Their executable digests do not change when only the runtime dependency changes. Refresh the runtime executable digests from integrity-verified npm release archives for every supported platform, and keep the native runner, provider manifest, and remote controller version checks aligned.

Build and verify

Run pnpm --filter @paperclipai/paperclip-runner test:opencode:qualification after installing dependencies to exercise the actual pinned OpenCode executable. It checks health/version, session creation and retrieval, SSE messages, an async prompt, and session deletion against a loopback mock provider. It uses an isolated home, starts no paid model request, and retires its process group. Set PAPERCLIP_TEST_OPENCODE_BINARY to the materialized Linux executable when qualifying an assembled provider pack.

The fleet image is currently amd64-only because the pinned Cursor and GitHub CLI checksums cover amd64.

content_id="$(pnpm --silent test:e2e:runner:image-id)"
docker buildx build \
  --platform linux/amd64 \
  --build-arg PAPERCLIP_RUNNER_CONTENT_ID="${content_id}" \
  --build-arg PAPERCLIP_RUNNER_SOURCE_REVISION="$(git rev-parse HEAD)" \
  --build-arg PAPERCLIP_RUNNER_LOCK_SHA256="$(shasum -a 256 pnpm-lock.yaml | cut -d ' ' -f 1)" \
  --tag "paperclip-daytona-runner:e2e-content-${content_id}" \
  --load \
  --file docker/daytona-runner/Dockerfile \
  .

docker run --rm --platform linux/amd64 \
  --entrypoint paperclip-runnerd \
  "paperclip-daytona-runner:e2e-content-${content_id}" \
  --build-metadata

The metadata must advertise dial_ws_loopback, dial_wss, and listen_ws. The explicit entrypoint is needed only for this local probe because Daytona's base image uses its own long-running sandbox entrypoint.

test:e2e:runner:image-id hashes the audited Docker build dependency closure, target platform, the immutable Dockerfile syntax-frontend digest, and every immutable FROM reference. It fails before the paid workflow can build when the frontend or a base is not pinned to a sha256 digest. When updating the syntax version, resolve and review its registry digest and update both values in the first Dockerfile line. Git commits that do not change those inputs reuse the same content tag.

PAPERCLIP_RUNNER_SOURCE_REVISION remains the full Git SHA that built the first published copy and is retained as provenance rather than cache identity.

Use in Paperclip

Publish the image to a registry Daytona can pull, or use the environment editor's Configure image flow to produce a Daytona snapshot. Set the environment image to that immutable tag or snapshot. Paperclip probes the sandbox user's PATH for paperclip-runnerd and codex and checks /opt/paperclip-runner/provider-pack for OpenCode and ACPX. It uses the pack when its selected provider interface and platform are compatible. App source revisions and unrelated provider pins do not force an update. Startup reads the small manifest in the existing runner metadata query. It does not scan the pack, run a version command, or transfer files on this path. Otherwise it stages the pack configured by PAPERCLIP_RUNNER_REMOTE_PROVIDER_PACK_PATH. Remote OpenCode and ACPX never fall back to host-local processes.

src/live/provider-pack-contract.json in the Runner package declares the OpenCode and ACPX interface revisions. Change a revision only for an incompatible runner/pack boundary change, and qualify the new pack before publishing it. Bumping a revision also retires every older image pack. The pack build also records a contractDigest, computed by scripts/contracts/contract-fingerprints.mjs from the JSON contracts under protocol/ and generated/, from Rust serde shapes, payload keys, match literals and env keys, and from the Runner's ACPX patch, rather than from source bytes. An image pack is reused only when its digest equals the controller's bundled pack; comments and refactors leave it unchanged, so a mismatch means a contract changed and the controller uploads its bundled pack. Packs without a digest are not reused. Define a new runner/pack contract in a schema under protocol/ and generate the TypeScript from it, as the sidecar's session.open parameter allowlist is generated from acpx-sidecar.schema.json; TypeScript-only definitions are not part of the digest. Dependency versions and Git SHAs remain build provenance. ACPX retains its selected agent's qualified profile checks.

The image build makes the pack root-owned and non-writable to the execution user. Fast admission requires protected ancestors and manifest, with no writable path alias. Task-owned packs and older packs without an interface declaration keep full content verification. An attached session retains the exact pack and daemon identity admitted at launch. Publish one new image with the interface declaration to enable reuse across later compatible app releases.

Do not promote paperclip-runner-e2e-20260826-v2 for OpenCode or ACPX. Build a new immutable image or snapshot from a clean committed revision and pass that full Git SHA as PAPERCLIP_RUNNER_SOURCE_REVISION.

Do not bake provider credentials, Paperclip bootstrap tickets, or Daytona preview tokens into this image. They remain per-run secret material.

The provider-pack build pins the official Linux x64 Node 24.21.0 image by manifest digest. Its bundled Undici is 7.29.1, which fixes GHSA-3wwx-pv8p-q78v. Pi separately verifies its private Node executable and nested npm dependency; changing the outer interpreter does not replace either provider-owned pin.

Provider CLI updates are manifest-only changes: repository CI owns the root lockfile. Resolve the complete workspace manifest graph in the build context before invoking Docker, matching CI when a source commit precedes the lockfile bot. The trusted workflow supplies this resolved lockfile as an immutable artifact. The complete resolved lockfile must match PAPERCLIP_RUNNER_LOCK_SHA256 before package installation or lifecycle execution. Review and refresh that digest with source dependency changes; registry-time resolution drift fails closed. The Product E2E workflow resolves one lockfile before the image build. It verifies the downloaded artifact, then passes that artifact's SHA-256 as the PAPERCLIP_RUNNER_LOCK_SHA256 build argument. The Dockerfile checks the resolved lock against this value before installation. The Dockerfile has no default digest: standalone builds pass the SHA-256 of the lockfile in their build context, and a missing or malformed value fails before installation instead of surfacing as a checksum mismatch. When a source change needs a fresh lockfile, resolve it from the clean tracked lockfile using the exact pnpm install --resolution-only --ignore-scripts --no-frozen-lockfile command, and verify a second resolution preserves the digest. A lockfile left by a filtered or incremental install can retain stale importer patch identities. Refresh exact runtime versions and qualification digests together; do not download dependencies when a task starts.

Candidate ACP qualification assets

Provider branches can build their pinned assets with node packages/paperclip-runner/scripts/build-provider-pack.mjs /absolute/pack --candidate-providers=cursor (or copilot or pi). The source revision must include the named provider's builder. Assets are installed at build time under provider-assets/<provider>/<platform>-<architecture>. The pack manifest binds each complete asset tree. Runtime admission separately checks the provider's source-owned closure pins and copies a verified launch snapshot. A pack with candidate assets does not qualify or enable that provider.

For an isolated Linux x64 Daytona qualification image, pass --build-arg PAPERCLIP_RUNNER_CANDIDATE_PROVIDERS=cursor with the normal build arguments. Compute its content ID with the same selection: pnpm --silent test:e2e:runner:image-id --candidate-providers=cursor. Candidate assets and the default pack have distinct image identities. Never reuse the default image's content ID for a candidate build. Use each provider branch's recorded version and explicit model. Keep credentials out of images. Paid qualification requires bound provider and Daytona credentials, inspectable spend, and the shared $100 ceiling recorded in the capability report.

The pack builder tests its copied Node interpreter after relocation. Use a standalone Node distribution if the host interpreter depends on a package manager's private shared libraries. Pi additionally pins its complete portable interpreter and npm dependency graph. Refresh exact runtime versions and qualification digests together; never download dependencies when a task starts. Grok's additive native ACP profile keeps its qualified 1.0.13 executable at the verified sandbox prerequisite path. It does not replace the legacy adapter's grok command on PATH.

Native Grok is an image prerequisite at /opt/paperclip/providers/grok/1.0.13/grok. Its checksum-verified provisioning is separate from the provider pack, which ships only the built-in launcher. Public npm installation never downloads this binary.