DottaandPaperclip
adb69e8f09
## 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>
10 KiB
navigation
| navigation | ||||||
|---|---|---|---|---|---|---|
|
Onboarding and first work
An operator can start an instance, create a company, configure its first agent, and reach a real first task. Instance setup and company onboarding are separate steps.
Implementation: web wizard, CLI setup.
Agent access: companion.
Sub-features
instance: choose local instance configuration and start the server.company: create a company with its identity and initial agent.adapter: choose an available harness, model, account, and execution environment.first-task: leave setup with a task whose execution or missing prerequisite is visible.resume: return to an incomplete wizard without losing saved state.
How to get to it (user POV)
web-wizard
Open /onboarding or the onboarding launcher in an empty company context.
Use /<company-prefix>/onboarding to resume an existing company's agent setup;
the unprefixed route starts at organization naming on self-hosted instances.
Cloud-managed instances reuse their existing company for agent setup.
cli-setup
Use paperclipai onboard --help or paperclipai run --help to select an isolated data directory before setup.
Driving it with Playwright and the Paperclip CLI
Preconditions: follow the baseline. Use a new isolated data directory and record deployment mode. A configured adapter may still need account authentication.
web-wizard
Automated: wizard tests cover mocked wizard behavior; onboarding browser suite supplies its own test environment. Live model execution is a separate check.
- Create company and resume. Start a fresh empty instance and run doctor using
the verification skill. Run
node .agents/skills/verify-paperclip/scripts/onboarding-smoke.mjs --evidence-dir "$VERIFY_EVIDENCE_DIR". The helper opens/onboardingin a fresh self-hosted instance, enters a unique name ine.g. Northwind Labs, and choosesContinue. The agent-name field must appear and the saved company must have no invented goal. Reopen the company-prefixed onboarding route and reload; the agent step must appear without creating another company. Screenshots and a trace capture the real UI action and result. This proves company creation/resumption, not hiring or a first model run.
Manual: Create a disposable company and first agent. Leave midway, reopen the company's onboarding route, and finish; drafts save automatically. Follow the created first task, verify the selected agent and company, and inspect its output or explicit authentication gate. Reload both company and task.
For Codex, choose the harness and leave runner selection automatic to prove the first-agent default. On a qualified target it saves Paperclip Runner; Advanced also permits Legacy. Do not switch runners after onboarding when claiming proof of that default. Test the selected runtime and account, then complete a bounded useful task and follow-up with an independently checked file artifact. Saved execution configuration and recorded run identity must match after reload. The Codex first-task eval applies operator QA bounds before Get started through the existing agent configuration API. It verifies that only timeout and concurrency change; automatic runner, account and environment choices remain. These campaign bounds are separate from production creation defaults. Use runner validation and environment qualification for the prerequisites; a successful login alone is insufficient.
For a new Codex agent with Auto on a saved immutable OCI sandbox, Connect first uses the existing saved environment probe when authoritative qualification is absent. The board actor needs the existing instance-environment administration permission. Refresh company/environment-scoped discovery before testing the selected runtime. A denied probe, unconfirmed cleanup or setup failure must be visible; selecting Legacy remains an explicit choice. Creation and discovery themselves allocate no target. A valid measured unsupported target follows the server's Legacy default. Named Cloud snapshots remain a separate unqualified boot-identity and fresh-signup gap.
Selected native setup derives its target isolation as task execution does. The hello probe retains its read-only permission profile, approval-never policy and bounded provider turn. It skips Codex's project-instruction discovery in its new, empty private workspace; ordinary tasks still load their project instructions. Local and SSH transports retain Codex isolation. An injected environment flag cannot establish an outer sandbox identity. Verify these boundaries with the existing native setup controls and a real managed task/follow-up; source checks alone are insufficient.
The explicit manual Product E2E cell
confirmation-replies.runner-codex.daytona.task-card-accept covers this fresh
managed wizard path without fixture agent creation or a fixture preprobe. Its
existing attachment oracle checks a downloaded physical file and follow-up
continuity. Setup evidence must correlate both lease IDs with the same company,
environment and provider; missing responses or unmatched rows keep cost coverage
unknown. Run this cell only on an eligible target with separately authorized
provider, runtime and cleanup reservations. Its source and mock controls are
prepared. The literal ea6c8eb5e16d61111968f633a66748b397b64a3e live attempt
failed: the child document existed, but the physical file was attached to the
parent, and recovery stopped the completion callback before a provider turn.
The failed report remains evidence; the revised source still needs live proof.
Local cases and automatic selection remain unchanged.
For accepted file-producing work, verify exactly one self-assigned child with a self-contained description. The onboarding run must yield through the existing dependency/block disposition so the child's own execution can publish its file. Native file registration remains bound to the executing task. On completion, the original conversation must receive the actual child and downloadable file links. Document-only child work may finish inline; a plan-only request must not start implementation. Existing first-task asset controls check the instructions, not model compliance. Inspect the child's execution, document, downloaded file and source-correlated completion reply in the real journey.
Leave and resume during harness/runner setup. Confirm the draft retains the explicit choice and compatible account bindings, old native Codex setup links recover the harness and runner, and a changed harness or runner invalidates stale test results. Existing Legacy agents remain Legacy when their onboarding/setup configuration is reopened; this journey does not migrate them.
Reload both /onboarding and the company-prefixed route after the first agent is
saved but before Get started. The authorized draft must retain its current step
and that agent's execution choice. An explicit new-company opening still starts
fresh. Opening another company must clear the previous company's resource IDs;
an unauthorized account must not restore its draft. Existing component controls
cover these boundaries; they do not substitute for the managed first-task eval.
The existing mocked-login browser case reopens and reloads Connect directly. It
checks the saved company/name/harness/runner, exact active authorization session,
one login start and no hire while login is pending. This is login UI evidence,
not a provider or managed-environment qualification.
cli-setup
Automated: CLI onboarding and isolated test drive cover their setup contracts; they do not establish that every model account is usable.
Manual: Run setup in the disposable directory, open the URL it prints, and confirm the instance identity and company. Restart using that same configuration and verify saved state. Exercise an unavailable adapter and confirm an actionable error.
Gotchas
- An empty company, an empty instance, and an unauthenticated browser are different states.
- Creating an agent does not prove its provider login or first execution succeeded.
- See access for authenticated deployments and agents for later hiring.
Storybook verification
resume
Scope: ui Storybook: Restored incomplete wizard; invalid or unauthorized saved company; temporarily withheld draft; account switch; storage failure. Production: Reload company-prefixed onboarding without duplicating company; restore only authorized account/company draft and retain input after recoverable loading failure. Sources: Source: OnboardingWizard.tsx, onboarding-state.ts. Tests: OnboardingWizard.test.tsx, onboarding-state.test.ts, onboarding.spec.ts
instance
Scope: cli Storybook: No authored UI story required for host installation and startup. Production: Configure isolated data directory, start instance, confirm printed URL/identity/health, restart with saved configuration. Sources: Source: onboard.ts, onboard-service.ts. Tests: onboard.test.ts, onboard-service.test.ts, test-drive.test.ts
Documentation scope: Login, invitations, and access
Deployment modes and core login/invite/member/token paths are mapped; exhaustive identity-provider, expiry, role, and resource-policy combinations remain.