0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-21 00:05:49 +02:00

Files

T

DottaandPaperclip adb69e8f09 feat: default new Codex agents to Paperclip Runner on Linux and macOS (#15683 )

## Thinking Path

> - Paperclip is the open source control plane for agent companies.
> - People choose a harness when creating an agent.
> - The server should resolve that harness to a qualified runner.
> - Codex is the first harness in the staged default rollout.
> - Saved agents must retain their execution choices.
> - New Codex agents therefore use Paperclip Runner on qualified
macOS/Linux targets, with an explicit Legacy override.

## Linked Issues or Issue Description

Refs #16028, #15555, #15673, #15422, #15631, #15926, #15932, #16149.

The runtime/install prerequisite and release repair are merged. This
slice owns Codex creation, setup, configuration and preservation. Other
harness defaults remain unchanged. It adds no database migration;
incoming master migrations, required maps and regression coverage are
retained.

## What Changed

- Resolve `runner: auto | paperclip | legacy` at the common creation
boundary across onboarding, API/CLI, hires, built-ins, plugins and
imports. Freeze pending hires and export resolved execution choices.
- Preserve existing runners on upgrades, unrelated edits and import
updates, including compatible accounts, workspace settings, Codex effort
and intentional clears.
- Use the underlying harness picker and branding; put the runner
override in Advanced. Use the shared dropdown and update
production-component stories and creation contracts.
- Support qualified Apple Silicon, Intel Mac, Linux x64 and Linux ARM64.
Linux requires GNU libc 2.39+. Disabled, external, unsupported and
unqualified combinations retain their applicable Legacy execution.
- Test the selected runtime/account/model/environment. Ordinary Connect
probes eligible immutable managed targets and refreshes scoped
discovery. Creation/discovery do not provision. Auth, dependency,
incompatible-setting and cleanup failures remain actionable without
changing runners.
- Keep setup probes read-only, preserve local/SSH isolation and resolve
packaged assets before staging credentials. Bound cleanup reads by the
remaining absolute deadline; physically close every owned ingress socket
before endpoint release. Unconfirmed cleanup retains recovery state.
- Preserve validated completed-onboarding callbacks through startup
recovery. First file-producing work belongs to the child task and uses
the existing dependency/block handoff and task-scoped registration.
- Reuse existing E2E fixtures, artifact checks, reporting and controls.
Keep Docker/Cargo/native compilation remote. Paperclip tarballs contain
no Codex payloads; official optional npm platform dependencies remain.

## Verification

Current tested head: `1c03a8815672d82c264a9b08d4ea1984e8fae107`.
**Merge-ready: required CI, fresh review, package qualification, Mac
core acceptance and Test task/follow-up acceptance pass.** The existing
attachment and native-continuity oracles independently verify both Test
downloads, run attribution and unchanged native/provider/workspace
identities. The maintainer authorized a code-owner-review exception for
this PR only. The first Test setup failure and normal Board
completion-review friction are retained below. Actual post-merge
packages and private Cloud distribution remain separate qualification
gates.

- [Current
CI](https://github.com/paperclipai/paperclip/actions/runs/38564241625):
all 48 ordinary jobs and required verify/E2E pass. Attempt 1 retained
six simultaneous host-shutdown cancellations. One failed-only retry
passes those six lanes and two aggregates, preserving 40 successes.
Actual integration checkout `53104c1` combines this head with master
`c80`; it is not relabeled as the branch tree. Fresh exact-head Greptile
5/5, 30 resolved threads, no actionable findings.
- [Exact-source package
qualification](https://github.com/paperclipai/paperclip/actions/runs/38565287239):
nine applicable jobs pass, nine conditional jobs skip. Four remote
native producers; Linux x64 clean install; Intel Mac, Apple Silicon and
Linux ARM64 native startup/physical cleanup controls. All 18
tarballs/four daemon source/hash/manifest bindings and 343 migrations
through 0344 verify. No Codex payload is packed. These hosted tarballs
are not a published npm canary.
- Normal Apple Silicon installation and credential-free native
startup/cleanup pass using the packaged daemon, with no source build or
provider turn. Fresh installed DB initialization passes. Upgrade
651a→1c03 preserves all three complete execution configs, accounts, ten
recorded run profiles, paused budgets, active incidents, cost summaries
and two historical unpriced events. Historical recovery state is
retained.
- Cleanup regressions: four delayed-read baseline failures become 15
passing deadline/authority controls. No-acknowledgement and prior-error
socket ownership regressions become 12 passing controls. Direct
runtime/server types, maps: 35 areas / 176 IDs, diff checks and
independent reviews pass. Permission/auth/reconnect policy and the
10-second setup budget remain intact.
- Existing source coverage includes creation/selection/imports, pending
approvals, recovery, account/lifecycle handling, mounted forms,
dropdowns and E2E support. Full typechecks/tests/build/token and
applicable Storybook checks pass in the recorded current CI; no
duplicate suite or weakened grader.
- Literal 9546 live Mac proof: ordinary Auto Codex onboarding, useful
document, real completed-child callback/reply, seven successful native
runs, manual follow-up and independently downloaded1,101-byte child
file. Existing Legacy title edit/reload preserves execution; two real
Legacy runs produce independently checked15/34-byte files. These remain
historical source records.
- Current literal 1c03 Mac core acceptance passes independent checks:
ordinary Auto native Codex onboarding without runner override; only
timeout 180 seconds/concurrency 1 saved; six successful native runs and
six serialized turns (maximum overlap 1); both same-task continuity
checks and five mechanical callback checks; actual rendered parent reply
and exact child downloads. The useful handoff advances from revision 1
to 2. Both files are 48 bytes, SHA-256
`8b742bd4e8123a7c078f0a8d9f3449fbfa8a320d7d90be641a2818db3c53d92c` and
`f42db9774fa06e804ab7d596fc8b922a2b638921c418b87d0111151d290a6afe`;
exactly one byte changes and old history remains. The agent is paused
with zero active runs/errors. Both artifact work products have
`isPrimary=false`, and descriptive titles fail a stricter title-helper
assumption; these retained results are scoped editorial follow-up, not
new merge gates. Six source-bound screenshots are uploaded and verified
in the private primary QA report.
- [Literal 9546 managed
proof](https://d1p6rlowie26tp.cloudfront.net/runner-e2e/campaigns/gha-38485488621-1/index.html):
original 19 assertions and completed judge pass, four native turns,
child-bound240-byte file and session/workspace continuity. Checkout
reports a verified generated target-lock mutation; full final porcelain
was not retained. Signed execution-image identity remains separate from
Core source.
- Actual 651a Test deployment succeeds on one owned/pinned target. One
ordinary Auto API-key Connect then fails native cleanup before hire.
Controller turn/drain/suspend completion and service-recorded
environment cleanup are observed; they do not certify physical deletion
or native authority retirement. Failure/recovery/unknown holds are
retained. No Legacy switch or unchanged paid retry. The two source
repairs above require actual treatment.
- [Current immutable Core
preview](https://github.com/paperclipai/paperclip/actions/runs/38570365725)
and matching DB/shared artifacts pass. One owned, pinned Test target
serves exact `1c03`; identical migration history correctly skips the
migrator. Ordinary Auto Codex Connect succeeds and hires native; saved
native selection and QA bounds survive reload. The initial child
preparation attempt fails before provider work, with actual stdout
identifying `renewal_deadline`; its trigger remains unknown and the
failure is retained. Normal Board **Try again** and **Resume** recover
the child to Done, producing a browser-verified 44-byte file, SHA-256
`0a8458b1efcc2d7a0d815689458c4caab039a46c7c7a3e5805de6bc8b1a96ecc`. The
actual parent callback reports the completed child document/file. The
existing validator requires a parent-owned attachment, so recovery
enters normal Review; after byte checking, normal **Approve completion**
reaches parent Done. No forced status or duplicate parent file is used.
The validator is unchanged from integrated and current master.
Autonomous initial callback-to-Done is not proven. The same-child
follow-up completes document revision 2 and publishes a second
independently downloaded 44-byte file, SHA-256
`22022257300fae762784632d08d3bbe0bab61e2ce81f91864a14dcd7aa464591`; only
the revision digit changes. The unchanged existing native-continuity and
attachment oracles pass. All ten recorded runs are terminal: nine native
successes and the retained pre-provider setup failure. The QA agent is
paused with zero active runs. The pre-existing parent evidence scope
mismatch is a separate follow-up, with ordinary completion review
exercised rather than a forced status or relaxed validation. This
unsigned Core preview remains distinct from post-merge private Cloud
composition.

## Risks

- Saved agents are not migrated. Explicit runner changes use normal
configuration/session rules; historical runs retain their recorded
execution.
- Native readiness depends on verified assets and server-owned target
qualification. A Legacy probe, HTTP200 or successful account save cannot
prove native readiness.
- Recovery exceptions remain restricted to validated
completed-onboarding reports; process-loss, ownership and terminal-state
safeguards remain active. Unexecuted live journeys stay open.
- Linux ARM paid tasks, Windows, Alpine and 32-bit ARM remain deferred.
Cold Cargo cache misses are recorded; no warm-cache speedup is claimed.
- Historical invoices/physical cleanup remain unconfirmed and held.
After merge, exact published npm canary, signed standard image/migrator,
private composition and serving/live acceptance still require
qualification. Production deployment/default promotion is not
authorized.

## Model Used

OpenAI Codex, GPT-6 family, with reasoning, tools, code execution and
parallel agents. Exact serving snapshot and context-window size are not
exposed.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used with available 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 linked public issues or PRs above
- [x] I have not referenced internal/instance-local Paperclip issues or
links
- [x] My branch name describes the change and contains no internal
ticket id
- [x] I have run the stated focused tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation
- [x] I have considered and documented risks
- [x] All Paperclip CI gates are green on the current candidate
- [x] Greptile is 5/5 with no open findings on the current candidate
- [x] I will address all reviewer comments before requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

2026-10-14 11:33:02 -05:00

11 KiB

Raw Blame History

Onboarding and first work — agent access

Product map: Onboarding and first work.

Review date: 2026-10-12. Source commit: f981fa3cc10cb8663a87dec60345fbff46d54d0a.

This is a source-reviewed baseline of representative operations and known gaps. Each capability needs operation-level review before its entire scope can be qualified. No live agent execution is claimed. Follow the map contract for format, permission checks, evidence and maintenance.

Scoped runner-default source review: 2026-10-12 at eee0534154eaf5d0d3f2bbc97c1e24d86f34a5a5, limited to first-agent selection, selected-runtime validation and draft restoration. Unrelated baseline entries retain the original source commit; no live agent verification is added.

`instance`

Review: baseline.

API: not-applicable — Bootstrapping an instance cannot depend solely on an API served by that not-yet-running instance.

Agent access: operator-only — Existing CLI onboard/run/doctor / test-drive.

Policy: Instance setup is operator work; company creation is board; agent creation/task creation retain their individual permissions.

Evidence: source-only — implementation at the reviewed commit above.

Verification: not-run — exercise the listed local workflow in an authorized, owned operator environment. Verify its isolation and result; do not count local machine authority as company-agent API access.

Gaps: Bootstrapping an instance cannot depend solely on an API served by that not-yet-running instance.

`company`

Review: baseline.

API: present — representative operation IDs:

POST /api/companies.
POST /api/companies/{companyId}/agents.

Agent access: partial — Board company creation; authorized in-company agent hiring API.

Policy: Instance setup is operator work; company creation is board; agent creation/task creation retain their individual permissions.

Evidence: source-only — implementation at the reviewed commit above.

Verification: not-run — exercise a listed permitted operation with actual agent credentials/run context; inspect its result and applicable persistence/attribution. Assert the relevant denied actor, owner, company or mode from Policy. Review the remaining operations before qualifying the whole capability.

Gaps: API building blocks exist; an ordinary agent cannot create its parent company with a company key.

`adapter`

Review: baseline.

API: present — representative operation IDs:

GET /api/companies/{companyId}/adapters/{type}/models.
POST /api/companies/{companyId}/adapters/{type}/test-environment.

Agent access: partial — Permitted agent/model API; operator provider-account/environment setup.

Policy: Instance setup is operator work; company creation is board; agent creation/task creation retain their individual permissions.

The wizard selects the Codex harness and lets the server resolve an automatic new-agent runner; explicit Legacy remains available. Supported-platform and immutable sandbox evidence follow environment probe policy. Creation/discovery do not provision a target to determine this default. Adapter setup validation requires agents:create, plus saved-agent update access when testing an existing agent; interactive account login additionally requires a board user and owner-bound session. An agent's right to hire is not login or instance-environment administration authority.

For fresh managed Codex Auto setup, the wizard's explicit Connect path can call POST /api/environments/{environmentId}/probe?companyId={companyId} before selected-runtime testing, then refresh scoped adapter discovery. This reuses the existing board instance-admin/local-implicit probe gate; agents:create alone is insufficient. A 403, absent proof, changed configuration, missing response identity or unconfirmed cleanup remains visible. No probe is added to creation or discovery, no agent/company grant is broadened, and provider authentication errors never cause an automatic runner switch.

Native setup derives outer sandbox isolation from the server-resolved execution target, as task execution does. This is an internal transport choice, not a request/configuration permission. Local and SSH setup keep Codex isolation; caller-supplied environment flags do not authorize an external sandbox. Existing company, account, probe and registration-cleanup gates still apply. The bounded hello probe retains read-only permissions and no dynamic tools. Its trusted launch skips project-instruction discovery in the new, empty setup workspace. This grants no filesystem or networking permission and does not change instruction discovery for ordinary task execution.

Scoped source review: 2026-10-13, exact baseline 1a0ca66242121e39d88455aa2b52a07acc4a07d9 plus the privately composed onboarding correction. Wizard controls and existing Product E2E observer controls exercise mocked allowed/denied setup and sticky unknown cost coverage. They do not prove live actor authorization or provider execution. The explicit manual confirmation-replies.runner-codex.daytona.task-card-accept case requires an eligible immutable OCI target and the existing probe authority, two identified setup leases and separately authorized paid/cleanup reservations. Its fixture neither prequalifies the environment nor creates the agent. Actual Cloud named snapshot binding, warm/cold signup and live allowed/denied agent checks remain not-run.

Evidence: source-only — implementation at the reviewed commit above.

Scoped Evidence: source-only — wizard/default selection, creation resolver and setup/login authorization at the scoped commit. Existing agent/approval execution preservation follows hiring access; no live onboarding proof is claimed here.

Gaps: Account authorization, environment administration and model selection need separate checks.

Verify automatic onboarding without a post-hire runner change, explicit Legacy, saved configuration after reload and the actual selected runtime's useful task plus follow-up. Assert denied agent login/probe and foreign-company account or environment access separately. These agent-context checks remain not-run.

`first-task`

Review: baseline.

API: present — representative operation IDs:

POST /api/companies/{companyId}/issues.

Agent access: available — Native create_task / agent REST / CLI issue.

Policy: Instance setup is operator work; company creation is board; agent creation/task creation retain their individual permissions.

Evidence: source-only — implementation at the reviewed commit above.

Gaps: Task creation is agent-accessible where permitted; scheduling/readiness does not follow from successful creation. The Codex first-task fixture's operator cost guard uses the existing board agent-configuration PATCH before admitting work. This is not evidence of agent permission to update its runtime; the listed agent-context checks remain not-run.

Scoped source review: 2026-10-13, the first-task asset correction against ea6c8eb5e16d61111968f633a66748b397b64a3e. The existing first-task instructions send file-producing work through the child's own execution and existing dependency/block controls. Native register_deliverable retains its current-task binding; this adds no cross-task file-registration authority or permission. Document-only work may use the existing child-document API inline, and plan-only approval does not authorize implementation. The existing asset tests check wording only. The literal baseline live attempt failed child-file delivery and completion reporting; revised live authorization and execution remain not-run.

`resume`

Review: baseline.

API: not-applicable — No server onboarding-draft API for this browser-local state; classify explicitly or intentionally make it a cross-client product feature.

Agent access: not-applicable — Browser localStorage wizard draft; persisted resources use their domain APIs.

Policy: Instance setup is operator work; company creation is board; agent creation/task creation retain their individual permissions.

Evidence: source-only — implementation at the reviewed commit above.

Verification: not-run — use the product recipe for the local/developer surface. Verify listed shared-resource reads separately; local presentation alone is not agent API evidence.

Gaps: No server onboarding-draft API for this browser-local state; classify explicitly or intentionally make it a cross-client product feature.

Scoped source review of draft restoration preserves harness/runner intent and invalidates obsolete setup-test results after a selection change. Browser draft continuity is not API or live-agent evidence, and opening a saved Legacy agent does not apply new-agent defaults.

The initial matching route opening preserves the authorized saved wizard step on bare and company-prefixed reloads. Explicit new-company or changed-company openings retain their navigation override and clear foreign company resource IDs. Existing component controls exercise these presentation and account boundaries. This scoped correction adds no server draft API, agent grant or proof of live actor authorization. The managed first-task eval still reloads before Get started and remains a separate live acceptance gate. The existing mocked-login browser case also checks the same company-scoped active session and saved selection through route reopening and a real reload, with one login start and no pending-login hire. These fixture assertions do not prove server authorization or live credential use.

11 KiB Raw Blame History

Onboarding and first work — agent access

instance

company

adapter

first-task

resume

11 KiB

Raw Blame History

`instance`

`company`

`adapter`

`first-task`

`resume`