DottaandPaperclip
45b67f1d93
## Thinking Path > - Paperclip lets users choose an agent harness and account. > - The server resolves the runner for new agents. > - Claude still needs the same ordinary native-default journey as Codex. > - Existing agents must retain their runner, model and account. > - This PR defaults new Apple Silicon Claude agents to Paperclip Runner with Opus 5.5. > - Users can connect and work without a runner override. ## Linked Issues or Issue Description Refs #15683. This PR depends on #15994 and precedes #15997. Related scope: #15422, #13978 and #15224. ## What Changed - Resolve new Apple Silicon Claude agents to `paperclip_runner`, `provider: acpx`, `acpxAgent: claude`. Keep explicit Legacy, models, provider routing and saved execution. - Use `claude-opus-5-5` for ordinary Claude defaults and retain explicit overrides. - Reuse existing API-key/subscription connections, credential storage and checks. Generalize the shared Advanced runner control with Claude branding. - Carry configured effort into the shared v9 contract. Preserve compatible permissions, instructions, skills, timeouts and session behavior. Require Legacy for unsupported settings. - Qualify a new immutable managed Claude target at explicit Connect through the existing permission-gated probe. Use fresh scoped discovery for test and hire. Discard stale results and require an explicit Connect after settings change. - Retain merged Codex onboarding recovery, auth preparation, import/effort corrections and Grok Bot gates. - Check the Claude first-task wizard's saved default directly. Update configuration/runtime documentation and exact Opus 5.5 accounting. - Align hire fixtures with the merged host-environment restriction. Native agent-authenticated hires cannot inject host env settings; both creation endpoints verify that no extra agent is saved. ## Verification - Updated onto master `9179d8dcc3e908c217fde4f63c9d08ccf8132eeb` through #15994. Native input v9 carries effort while preserving v7 home modes and v8 Muse. Codex defaults remain unchanged. - Focused local verification passed 285 server tests, 323 UI tests, 124 setup/registry tests, and two v9 permission-pin transport cases. Direct server/UI TypeScript checks passed. An initial 30-second hook timeout was resolved by serial verification with a longer hook budget: all 122 credential/permission cases and 232 snapshot/environment cases pass. Direct server TypeScript checking also passes. - Ordinary web creation with the experiment disabled saved native Claude, Opus 5.5 and High effort without runner/model overrides. The actual product task and follow-up both succeeded on integrated source `b2c9fe43f9cd3bc5dd9d22552da0148845ba71a4` with the cloud-built daemon from `04e0202ca81387b17cbe7fd094a8338648356fe9`. The final master reconciliation also changes shared runtime source. Historical proof retains its source identity; a final-source cloud qualification is running before refreshing the preview daemon. - Both actual browser downloads were checked: v1 has three sections/six checkboxes (451 bytes); v2 preserves the original body and adds two Rollback checks (612 bytes). The original attachment stayed byte-identical. The follow-up records session resume and the same provider session. Total estimated API usage: $0.518432800, with no pending/unpriced usage in the successful fixture. - Fixed the live-discovered setup incompatibility: native API-key validation no longer depends on the global Legacy Claude CLI. The existing provider endpoint verifies the key without a paid prompt; subscription/custom routing probes remain intact. - Fixed security review's native-hire credential redirection: agent-supplied URLs, proxy/launch settings and other host environment controls are rejected before inheritance. Native credential references remain supported and partial edits use the saved harness. Added create/hire/update regression coverage. - Current-head cloud CI is green. All three stack PRs have fresh Greptile 5/5 reviews and zero unresolved review threads. Required typecheck, test and build gates ran in cloud CI; Docker work stayed remote. Earlier failed checks remain in their original runs. - Docker and native release builds ran in cloud infrastructure. An inadvertent local Rust prerequisite was stopped; no local Docker build was run. - The final master merge preserves task-loading, permission, skill-retention and OpenRouter changes. Pi uses a fresh combined profile 27, preserving both historical profile-24 declarations; Copilot remains profile 22. Focused protocol checks passed 155 cases (one skipped), the updated Pi attestation check passed 18 (one skipped), and 91 evaluation/catalog checks passed. - Latest-application manual continuation passed in 37.942 seconds on `695e5c005a85bddc8711d3fcddcaf6b7e1fb64d0`, with High effort, native Opus 5.5, Anthropic API attribution, the same resumed Claude session, an independently checked 635-byte file and persisted Done status. It uses the earlier verified Mac daemon; the preceding-source package qualification passed at `dca62c7aeb4b45f0dd91a8e18d386a16a2658ef8`. That package run predates the small TypeScript startup fix and is not relabeled as qualification for it. - Upgrade limitation: changed compiled sidecar identity rejected old durable launch state and recovery hit session-open bounds before eventually resuming. That attempt was operator-cancelled and retained; the successful manual continuation does not qualify seamless upgrades. - Local latency profile, Opus 5.5/High unchanged: three alternating real-ACP loopback samples per variant reduce median provider-ready time from 5.081s to 4.034s. The matched real API task startup improves from 5.533s to 4.348s, but total reply time changes from 17.933s to 20.221s because agent work varies. This establishes a startup saving of about one second, not a consistent total-reply speedup. A real candidate follow-up passed in 20.146s and resumed the same saved session. The loopback fixture makes no external model requests; failed initial probes remain retained. - The startup change passes 107 focused runtime/effort/lease tests, 53 profile checks (one skipped), TypeScript checking and the TypeScript-only runtime build. Native hire fixture checks pass 70 tests; their first local run retained a socket-hangup failure and stale OpenCode expectation, both accounted for before the passing rerun. Broader required checks run in cloud CI. ## Risks - Missing packages, authentication rejection, unsupported settings and unavailable models must fail explicitly. Existing agents retain saved execution; explicit runner changes use existing revision/session invalidation. - Subscription follow-up remains unverified; remaining live acceptance uses API keys per human steering. Historical accounting holds and the separate $50 ceiling remain intact. - The subscription acceptance limit remains explicit for review. No Claude database migration is introduced. ## Model Used OpenAI Codex, GPT-6 family, with reasoning, repository tools, code execution and browser testing. The exact serving model ID and context-window size are not exposed in this session. ## 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 - [ ] Focused local tests and final cloud verification 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 - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
11 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 or Claude, 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 Claude agent on an explicit immutable sandbox image, use Connect to qualify the selected environment through the existing permission-gated probe. Do not preprobe outside onboarding when claiming this first-use path. Fresh scoped discovery determines the runner for both the account test and hire; the measured Legacy result remains valid. An instance-admin denial, incomplete cleanup, missing lease or changed configuration stops setup before the adapter test or hire. Named snapshots and mutable image tags do not gain qualification through this flow. Helper controls and mounted wizard/new-agent tests use mocks; live managed acceptance remains a separate gate. 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.