Devin FoleyandPaperclip
c5ca29dbef
## Thinking Path > - Paperclip connects agent accounts and prepares their execution environments. > - A managed sandbox image can outlive the model defaults shipped by the app. > - Claude setup skipped installation whenever a CLI was already on PATH. > - The selected model then failed its minimum-version check after sign-in succeeded. > - This pull request prepares a compatible private CLI before testing or running it. > - Cloud onboarding also stops asking customers to run inaccessible shell commands. ## Linked Issues or Issue Description **What happened?** A new managed Cloud stack completed Claude subscription sign-in. Its environment test then failed because the snapshot contained Claude Code 2.1.263, while the selected `claude-opus-5-5` model requires 2.1.280. The screen displayed Manual debug commands that a hosted customer cannot run. **Expected behavior** Paperclip prepares its managed runtime before testing the selected account. A stale image CLI does not require the customer to upgrade a server package. Failed preparation still blocks hiring. Cloud does not display manual shell debugging. **Steps to reproduce** 1. Start a managed sandbox with Claude Code 2.1.263 on PATH. 2. Connect a Claude subscription and select `claude-opus-5-5` on the CLI lane. 3. Connect the agent. Installation is skipped because the command exists, then the version gate blocks the hello test. **Paperclip version or commit** Source baseline: `6204239cfc8c3be79fc185cf3f468ebaa0ab1e3e`. **Deployment mode** Authenticated managed Cloud with a Daytona named snapshot. The correction also applies to the default CLI in other managed sandbox transports. Related work: Refs #14993 sets model/runtime requirements; Refs #15993 changes native defaults on qualified targets. Neither prepares an outdated default sandbox CLI on this path. Searches found no open duplicate. ## What Changed - Check the actual default CLI against the selected model's existing minimum version. - When a sandbox's default command is outdated, install the exact required npm package into a private versioned workspace prefix. Reuse a compatible private installation. Keep the image's global CLI intact. - Verify the private executable and use that same command for the account hello test and normal CLI runs, with matching command metadata. Probe effort support after preparing that executable so the chosen effort is retained. Keep the model, account, engine and permissions unchanged. - Return safe preparation checks to environment tests and normal run logs, distinguishing installation failure causes without returning raw installer output or credential-bearing URLs. - Exclude provider and Paperclip credentials from the installer environment. Preserve the existing failing version gate if installation or verification cannot succeed. Local, SSH and explicit custom commands remain operator-managed. - Hide Manual debug and legacy operator check hints on Cloud and while deployment metadata is unknown; preserve check messages and details. Retain self-hosted help and the detailed failed checks. Cloud copy asks for a retry instead of asking the customer to repair the environment. - Add subprocess-backed runtime controls, an account-probe regression and mounted Cloud/self-hosted wizard controls. Update development guidance and the affected capability maps. ## Verification - Passed all Claude source suites and the server Claude execution suite on head `c941ae44c22d8dafec0df033a129e39ce4ebd966`: **412 passed**, one existing opt-in test skipped. These include the new command/effort ordering, safe installer diagnostics, environment forwarding and run-log regressions. - On final head `0ecae0e9304f495a57524158b3700b8e9bc21cb8`, passed **208 tests** across all 174 mounted onboarding wizard tests and 34 Claude execution tests. The failure fixture includes the real command-bearing hint, and execution asserts both metadata command fields agree. - Passed `pnpm -r typecheck`, `pnpm build`, `pnpm check:token-gates`, `node scripts/check-maps.mjs` and `git diff --check`. Full typecheck and build were repeated successfully on final head `0ecae0e9304f495a57524158b3700b8e9bc21cb8`. [Latest-head CI](https://github.com/paperclipai/paperclip/actions/runs/39879208694) is green: 54 checks passed and two skipped, including browser E2E and serialized database suites. - The new runtime controls execute real subprocesses with a controlled installer. They cover an old CLI, an already compatible CLI, failed or ineffective installation, local/custom commands, and an unknown version. The probe regression asserts that the hello call uses the private executable. - A separate non-root local subprocess check installed the real npm `@anthropic-ai/claude-code@2.1.280` package. Its private command reported 2.1.280, the simulated image CLI remained 2.1.263, and a second preparation reused the private copy. This ran on macOS ARM64. It did not use a provider account, send a model prompt, or prove live Daytona behavior. - Attempted `pnpm test:run`. Embedded PostgreSQL initialization failed after five attempts on this Mac with `Postgres init script exited with code null`. The unchanged native-session database cases then failed. Stopped only that full-suite process tree after recording the repeated startup failure. No full local-suite pass is claimed; Linux CI must cover those tests. - The first new subprocess fixture had a quoting syntax error. It was corrected before the passing focused runs. The one-off real-package script first required an ESM extension correction, then passed. Logs retain both attempts. A new execution assertion initially inspected the final sandbox cleanup shell instead of the launched command; it now checks execution metadata. A broader directory selection also picked up generated `dist` tests whose Markdown fixtures are not copied by the build (two ENOENT failures). The explicit source-suite run above passes; no generated-test pass is claimed. - Apex review: **5/5**, reviewed final head `0ecae0e9304f495a57524158b3700b8e9bc21cb8`, all five earlier findings addressed and resolved, no new findings. - Merge, deployment and a fresh live Cloud subscription test are still required. No customer account or production runtime was changed by this branch. ## Risks - An outdated sandbox needs npm registry access and up to 120 seconds for one bounded installation attempt. A failed or unverified install continues to block execution. - The versioned package uses sandbox workspace storage. Compatible cached copies avoid repeat installation within that workspace. Existing runtime cleanup and sandbox lifecycle still apply. - The compatible version comes from the adapter's existing model-version contract. This does not add a model fallback or change the selected execution engine. - No schema, credential, permission, workflow or lockfile change. ## Model Used OpenAI Codex, based on GPT-6, assisted with implementation and verification. The exact serving model ID and context-window limit are not exposed in this session. Capabilities used: code editing, shell execution, API inspection and test execution. ## 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 - [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>
12 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.
Feature ID: onboarding.
Implementation: web wizard, CLI setup.
Agent access: companion.
Sub-features
instance:onboarding/instance— choose local instance configuration and start the server.company:onboarding/company— create a company with its identity and initial agent.adapter:onboarding/adapter— choose an available harness, model, account, and execution environment.first-task:onboarding/first-task— leave setup with a task whose execution or missing prerequisite is visible.resume:onboarding/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 managed Cloud setup, an outdated default Claude CLI is prepared automatically in a private versioned runtime directory before its hello test. Verify that the selected model and account stay unchanged and that the compatible executable is actually used. A failed installation still blocks hiring. Cloud failures must not display Manual debug shell commands or legacy operator hints; self-hosted failures retain that help. Wizard controls and runtime controls cover these boundaries. They do not establish live Cloud onboarding success.
For a new Claude agent on an explicit immutable sandbox image or a Daytona named snapshot, 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. Daytona resolves the selected snapshot to its immutable provider ID before creating the measured lease; native execution pins that same ID. Mutable image tags and other providers’ named templates remain unqualified. 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
Capability ID: onboarding/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
Capability ID: onboarding/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.