mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-09 16:02:36 +01:00
Devin FoleyandPaperclip
fd4b197f83
## Thinking Path > - Paperclip lets people manage AI agents for work. > - Agent setup connects a harness, model, account, and computer. > - The system already selects a qualified runner for a new agent. > - Setup still asks users to select that internal runner. > - The runner dropdown can be the only field in Advanced. > - This PR removes the dropdown and hides an empty Advanced section. > - Users keep their saved execution settings and see fewer setup controls. ## Linked Issues or Issue Description **What existing behavior does this improve?** Agent creation, onboarding, built-in agent setup, company import, and agent configuration. **Subsystem affected** The UI, setup error messages, tests, and Storybook fixtures. **Current behavior** Users can select a runner from a dropdown. Some setup screens place only that dropdown in Advanced. Errors can direct users to that control. **Proposed behavior** Remove runner dropdowns from setup and configuration. Use the existing automatic selection for new agents. Retain saved runner settings. Show Advanced only when other fields remain. **Reason and benefit** Users can configure agents without an extra internal execution choice. Setup also avoids an empty Advanced section. **Breaking changes** Users can no longer select a runner through these UI dropdowns. The API and CLI retain their runner options. Existing agents keep their saved execution settings. **Additional context** Related: [Default new agents to the qualified runner for their harness](https://github.com/paperclipai/paperclip/pull/15422). This PR changes the existing setup UI. It adds no harness or runtime default. The master merge retains the custom gateway placement from [#19510](https://github.com/paperclipai/paperclip/pull/19510). ## What Changed - Remove the shared runner dropdown and its setup/configuration callers. - Hide Advanced when it has no remaining fields. Keep command and argument settings where supported. Preserve custom gateway setup under Advanced on the Claude and OpenAI API key paths. - Keep setup failures visible and keep the retry action outside the removed control. - Update errors and documentation that referred to the removed dropdown. - Update component tests and Storybook fixtures for the new UI states. - Make Legacy first-task evals resume an API-configured setup record. Record that path separately from fresh automatic onboarding. ## Verification - Latest master integration (`187c0f6d6e5`): 276 onboarding/provider-connection tests passed across six files. UI typecheck and build passed. Token gates, query-error rendering checks, and the Storybook catalog check passed. The conflict resolution retains master's bounded connection tests and cancellation while removing the obsolete runner instruction. The first test command used the wrong working directory and failed before collecting tests; the corrected invocation from `ui/` passed. - Earlier branch verification passed: full workspace build and typecheck, 1,037 focused UI/service tests, 49 heartbeat provider contract tests, eval typecheck, and 30 map/catalog tests. - The full local `pnpm test:run` run passed all six chat integration shards (1,931 tests). It was stopped for the master merge before the complete suite finished. The [complete CI run](https://github.com/paperclipai/paperclip/actions/runs/42264662642) passed on the previous head `72e1699`. - Current head `a097c8369d079c839e78661a2206cfa62c5210e0`: [full CI](https://github.com/paperclipai/paperclip/actions/runs/42273168268) passed. PR checks total 55 passed and 3 skipped, with none failed or pending. Greptile reviewed this head at 5/5 with no actionable findings or unresolved review threads. - Live browser/provider evals have not run. The Legacy eval change has no live qualification claim. ## Risks - Removing the dropdown changes the setup UI. Existing API and CLI runner choices remain available. - Conditional Advanced sections must retain valid command and argument fields. - Legacy first-task evals now prove setup resumption. They do not prove the fresh-agent automatic default. - No schema change or data migration is included. ## Model Used OpenAI `gpt-6.1-sol`, through Codex in T3 Code. Reasoning effort: `xhigh`. The model used file editing, shell commands, and test tools. The harness does not expose the context window size. ## 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>
201 lines
12 KiB
Markdown
201 lines
12 KiB
Markdown
---
|
||
navigation: {"section":"Getting started and access","sectionOrder":10,"order":10}
|
||
---
|
||
|
||
# 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](../../ui/src/components/OnboardingWizard.tsx), [CLI setup](../../cli/src/commands/onboard.ts).
|
||
|
||
Agent access: [companion](../agent-access-map/onboarding.md).
|
||
|
||
## 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.
|
||
|
||
The [Cloud Product onboarding journey](../../tests/runner-e2e/PRODUCT-JOURNEYS.md)
|
||
defines portal workspace creation, API-key connection, native Codex creation,
|
||
and a first downloadable artifact with an independent oracle. Its dependent
|
||
task-properties journey reuses onboarding state. This is a scripted coverage
|
||
recipe, not a claim of a completed Cloud run or strict browser-only discovery.
|
||
|
||
## 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.
|
||
|
||
First-agent onboarding offers only Claude and Codex, subject to instance adapter
|
||
availability. Other providers remain available through Add agent after onboarding.
|
||
A saved draft for another provider requires a new choice.
|
||
|
||
### `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](./README.md#before-driving-a-journey). Use a new isolated data directory and record deployment mode. A configured adapter may still need account authentication.
|
||
|
||
### `web-wizard`
|
||
|
||
Automated: [wizard tests](../../ui/src/components/OnboardingWizard.test.tsx) cover mocked wizard behavior; [onboarding browser suite](../../tests/e2e/onboarding.spec.ts) 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](../../.agents/skills/verify-paperclip/SKILL.md). Run
|
||
`node .agents/skills/verify-paperclip/scripts/onboarding-smoke.mjs --evidence-dir "$VERIFY_EVIDENCE_DIR"`.
|
||
The helper opens `/onboarding` in a fresh self-hosted instance, enters a unique
|
||
name in `e.g. Northwind Labs`, and chooses `Continue`. 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 to prove automatic first-agent runner
|
||
selection. On a qualified target it saves Paperclip Runner. The wizard has no
|
||
runner dropdown or empty Advanced section. 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](./runs-adapters.md#adapter-setup) and
|
||
[environment qualification](./execution-environments.md#environment-settings)
|
||
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](../../ui/src/components/OnboardingWizard.test.tsx) and
|
||
[runtime controls](../../packages/adapters/claude-local/src/server/sandbox-cli-version.test.ts)
|
||
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](../../ui/src/lib/qualify-claude-setup.test.ts)
|
||
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 and retryable through setup. 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](../../cli/src/__tests__/onboard.test.ts) and [isolated test drive](../../cli/src/__tests__/test-drive.test.ts) 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](./access.md) for authenticated deployments and [agents](./agents.md) 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](../../ui/src/components/OnboardingWizard.tsx), [onboarding-state.ts](../../ui/src/lib/onboarding-state.ts). Tests: [OnboardingWizard.test.tsx](../../ui/src/components/OnboardingWizard.test.tsx), [onboarding-state.test.ts](../../ui/src/lib/onboarding-state.test.ts), [onboarding.spec.ts](../../tests/e2e/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](../../cli/src/commands/onboard.ts), [onboard-service.ts](../../cli/src/onboard-service.ts). Tests: [onboard.test.ts](../../cli/src/__tests__/onboard.test.ts), [onboard-service.test.ts](../../cli/src/__tests__/onboard-service.test.ts), [test-drive.test.ts](../../cli/src/__tests__/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.
|