Nicky LeachandPaperclip
79b2bf78dd
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Core onboarding selects an agent and connects its provider account. > - The current flow creates the agent record after authentication. > - Setup needs a stable agent identity as soon as the user submits its name. > - This PR saves a paused setup record on name submission and finishes the hire on that same record. > - The existing sandbox authentication and approval paths continue to apply. ## Linked Issues or Issue Description **Subsystem affected** Core agent lifecycle, shared validators, and onboarding UI. **Current behavior** Onboarding creates the database record at the final hire step. Earlier authentication and saved setup have no agent record. **Proposed behavior** Create a paused agent with a setup hold when the user submits its name. Do this before adapter selection or authentication. Update that same record after adapter selection. Reuse its ID on retries and saved setup. Finish that record through the existing hire path. **Reason and benefit** Give setup a stable identity without coupling this refactor to computer provisioning or a new execution backend. **Breaking changes** Incomplete setup now leaves an inactive agent record. Existing clients can still create and hire agents without the new optional fields. The sandbox authentication flow and API key support remain in place. **Additional context** Requested Core-only refactor. Related work: #15422 changes runner defaults. This PR preserves those choices. No duplicate early-record refactor was found in the issue and PR search. ## What Changed - Save the agent when the user submits its name in both onboarding entry points. Use a provisional adapter until the user chooses one. Reopen name-only drafts at adapter selection. - Add retry-safe setup creation and same-record hire completion. Keep approval checks at final hire. - Save and restore setup configuration in both onboarding entry points. Show Finish setup for paused setup agents. - Restrict setup changes to authorized board users. Block generic resume until setup finishes. - Add lifecycle, authorization, connection, and UI coverage. Update the specification and feature maps. ## Verification - Latest focused server run: 126 lifecycle and AI-connection tests passed after the Apex fixes. An earlier broader run passed 301 lifecycle, instruction, adapter-validation, and AI-connection tests. Earlier authentication, retry, cross-company, and direct-create regressions also passed. - Name-save verification: 336 tests across the wizard, naming dialog, New agent, action-button, and wizard-step suites passed. Coverage includes retry identity, repeated submission, closing during a save, saved-model restoration, and a disabled process adapter. - Shared, server, and UI TypeScript checks passed. The latest UI package check and direct server TypeScript check passed. The server package preparation command could not finish locally because Cargo is unavailable; full build preparation runs in CI. Map checks, token gates, and `git diff --check` passed; each pushed diff was scanned for credentials and PII. - All six onboarding browser tests passed together with installed Chrome against a fresh throwaway instance after the Apex fixes. They include numbered duplicate names, first-time Copilot without a connected account, and Grok’s saved model. They verify early persistence in both entry points, closing and reopening a name-only draft, same-record adapter selection, sandbox sign-in, login reload, and failed-connection gating. Provider responses are simulated; Core persistence is real. - Regression coverage includes incomplete Copilot creation versus final validation, Kimi settings through redacted responses, stale local drafts, company switches during creation, saved environments, and provider changes with personal/shared old bindings. - Apex found five name-only setup gaps: numbered names, early Copilot account validation, the Grok model default, same-name draft ownership, and provisional runner restoration. The fixes preserve server names, defer implicit account binding until hire, set Grok’s model, avoid name-based reuse of unfinished records, and restore Auto for pending adapter choices. UI, database, and browser regressions cover these cases. - Standard Greptile found a Grok provider mismatch in the new adapter save. The save now uses ACPX with the Grok profile. Both the 129-test dialog/setup run and a real-API browser regression passed after the fix. The first browser attempt stopped on an ambiguous empty-roster button selector; it now scopes the click to the toolbar. - Moving the save point exposed a saved-model reset and timing assumptions in the same-name and portal fixtures. The source choice now preserves the restored model, and tests cover same-name recovery without a second hire. - Initial CI exposed direct-create compatibility, concurrent setup effects, fixture assumptions, and a missing-fields assumption in the provider-validation guard. These were fixed and verified locally. Review findings were addressed with authorization, recovery, credential-persistence, and restored-configuration regressions. - The final desktop capture passed after host resource cleanup. A repeat first failed before Core started because macOS had exhausted shared-memory IDs. Standalone PostgreSQL initialization reproduced the same error. Releasing only unattached control segments from this task’s stopped test databases allowed the unchanged revision to pass. No Core or system setting changed. - Local database tests required port access outside the sandbox. Missing declared development dependencies were supplied outside the branch. No live provider sign-in was tested locally. - [Full monorepo CI](https://github.com/paperclipai/paperclip/actions/runs/39522434236) is green on `82b82fec189a172a885d4dd565ae2f4a18c73efc`. Standard Greptile scored 5/5 with zero new comments (check `118969424903`). The subsequent Apex review also scored 5/5 with zero new comments (check `118972866331`) on that same commit. All review threads are resolved. - The separate Superagent Security scan returned neutral/inconclusive because its pinned merge-base checkout failed or timed out. GitHub returned 404 for check and suite rerun requests. This is not a successful security scan; the CI workflow and other security checks passed. ## Risks - Users can leave inactive setup records behind, including after name submission alone. These records cannot run until hire completes. - Setup completion touches hiring and approval boundaries. Tests cover retries, company isolation, creator permissions, and approval snapshots. - An uncertain credential-save result retains its new secret reference for retry. A confirmed client rejection removes only credentials staged by that attempt. - No schema migration or VM provisioning change is required. Agent-computer integration is out of scope. ## Model Used OpenAI Codex, based on GPT-6, with repository search, code editing, and tool execution. The exact deployment ID and context window 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 - [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] Apex Greptile is also 5/5 on the same commit as standard review and green CI - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
14 KiB
navigation
| navigation | ||||||
|---|---|---|---|---|---|---|
|
Hiring, configuration, and organization
Operators hire agents, configure their identity and instructions, assign reporting relationships, and manage their lifecycle. Built-in agents have their own setup and lifecycle constraints.
Feature ID: agents.
Implementation: hiring, configuration, organization.
Agent access: companion.
Sub-features
hire:agents/hire— choose identity, harness, model, and required account settings; edit reporting relationships through the agent configuration afterward.grok-bot:agents/grok-bot— experimental existing-Bot agent setup through remote OAuth, routine credentials, and an authenticated two-way challenge; current contact, stop and explicit recovery.instructions:agents/instructions— edit agent configuration and instruction files with durable revisions.organization:agents/organization— inspect and change reporting relationships through supported controls.primary-agent:agents/primary-agent— choose a personal primary agent for the company, confirm replacement, and inspect its roster/sidebar and task/chat defaults.lifecycle:agents/lifecycle— pause/resume or retire an agent while preserving history.built-in:agents/built-in— configure required agents without treating them as ordinary removable hires.api-keys:agents/api-keys— create and inspect named agent credentials, copy a new token once, and revoke it without changing agent identity.managed-agent-setup:agents/managed-agent-setup— probe, create, or adopt a qualified Anthropic managed-agent profile with pinned provider resources and retention acknowledgement.
How to get to it (user POV)
hire-agent
Use New agent from the roster or /agents/new.
Submitting the name creates an inactive record before adapter selection or account setup. A name-only draft returns to adapter selection when reopened. Save & exit keeps its configuration; Finish setup on the agent returns to the same record. Final submission requests approval when required, then follows the existing preparation and verification lifecycle.
agent-configuration
Open /agents/:agentId and the configuration/instruction surfaces it exposes.
organization
Use the roster’s organization view; /org redirects to the roster in the streamlined shell.
personal-primary-agent
Open an agent profile and choose Set as my primary. Inspect its crown on the profile/roster and its position in the Agents sidebar, then open a new task or Chat.
agent-api-keys
Open /agents/:agentId/api-keys → API Keys with an authenticated person who can manage agents. The operator CLI also supports paperclipai token agent create -C <company-id> --agent <agent-id> --name <label>, token agent list -C <company-id> --agent <agent-id>, and token agent revoke <key-id> -C <company-id> --agent <agent-id>.
managed-agent-cli
Use the operator command paperclipai managed-agent setup --company-id <company-id> --profile-key <key> --display-name <name> --api-key-secret-id <company-secret-id> --acknowledge-retention --json. Supply ANTHROPIC_API_KEY through the process environment. Use --agent-id, --agent-version, and --environment-id to adopt resources, or --probe for provider reads without profile persistence. The optional session-list cost ceiling is --max-session-list-cost-usd.
Driving it with Playwright and the Paperclip CLI
Preconditions: follow the baseline. Use a disposable company and supported adapter; hiring may require a formal approval.
hire-agent
Automated: new agent page and configuration form cover mocked UI behavior.
Manual: Hire an agent with a distinct name and role. Complete any required approval, reload the roster, and open its configuration. Confirm manager, adapter, and model persisted; run a small task to prove execution readiness.
For a new Codex hire, choose the Codex harness. Automatic selection uses Paperclip Runner on a qualified selected target; Advanced offers an explicit Legacy runner override. Record the persisted runner and underlying harness, rather than treating the displayed Codex name as execution proof. See runtime selection and validation and target qualification.
Repeat with an explicit Legacy Codex hire. If approval is required, compare its reviewed execution configuration before and after restart and activation; approval must retain the reviewed runner. Test an existing Legacy and native agent through an unrelated edit, reload and restart: neither is automatically upgraded.
Creation defaults also apply to API/CLI hires, built-ins, plugins and new team imports. Exports preserve resolved execution choices; a package without a runner choice uses the new-agent default, while updating an existing same-harness agent preserves its execution. For a native Codex import, edit a model or account binding and verify unchanged runtime settings survive; an explicit clear must stay cleared. Use the portability recipe for package preparation and boundaries.
For Claude Code on qualified macOS or GNU/Linux x64/ARM64, submit without a
runner override and inspect
saved configuration: paperclip_runner, provider: acpx, acpxAgent: claude,
and ordinary model claude-opus-5-5. The Advanced runner selector can explicitly
choose Legacy. Keep explicit model/account choices and saved runners on edits.
Verify useful output and a follow-up after a controller restart; setup success
alone does not establish session continuity. Unsupported architectures/libc and unknown environment qualification retain
Legacy. Darwin SSH also defaults to Legacy until automatic matching assets are
qualified; explicit matching native assets and saved native configurations remain
supported. Linux ARM64 cloud-image production remains deferred.
The current hiring wizard assigns the first hire CEO and subsequent hires General reporting to the CEO. Change manager/role afterward through supported configuration. Process/HTTP agents can be created through API/CLI but are excluded from the hiring picker; API fixture creation does not prove this UI journey.
agent-configuration
Automated: instruction service and instruction revisions cover file/revision contracts.
Manual: Save a harmless instruction edit, reload, and verify its revision and effect in the next eligible run. Pause and resume the disposable agent; confirm pause prevents new work and does not erase previous runs.
For failed setup, use an unavailable model or invalid command on a disposable agent. Confirm the profile names the failed verification step and gives a relevant action. Check that it explains automatic retry and offers Retry now. Fix the configuration, retry, and reload; the failure must disappear only after readiness commits. Provider output and credentials must not appear in the lifecycle message.
An explicit runner change is a configuration change, with normal revisions and session invalidation. Incompatible settings must produce a field-specific error; selecting another runner must not silently discard them or change an active run's recorded execution. Keep runner choice in Advanced and verify the next eligible run separately from historical transcripts.
organization
Automated: org chart is component evidence. Built-in setup also has configuration modal tests.
Manual: Inspect a manager and report, change the relationship through the offered controls, and reload both views. Exercise a rejected invalid relationship. Configure a built-in agent and verify it retains its required identity and restrictions.
personal-primary-agent
Automated: primary-agent context and primary-agent routes cover selection, company/user scope, and request contracts.
Manual: Select an available agent, reload, and inspect the retained personal choice. Replace it and verify confirmation is required. Leave or terminate the selected agent through permitted controls and inspect the unavailable/cleared state. Switch company/user to check isolation. Open a task and Chat with a valid draft or recent selection; verify those explicit choices take precedence over the primary fallback. Opening Chat must not start execution.
agent-api-keys
Automated: CLI token tests mock create/list/revoke. Cross-tenant routes, agent permissions, and authentication middleware cover company/key ownership, management permission, responsible-user binding, and denial. They do not prove a browser-created key working against a live instance.
Manual: As an authenticated person with agents:create, create a named key for an eligible disposable agent and copy it privately from the once-only display. Make a harmless same-company agent request with that bearer, then reload the Keys tab and verify only metadata remains. Revoke the key through UI or CLI, reload, and retry the exact same bearer: authentication must fail. Inspect key-created/key-revoked activity without token values. Test a board person lacking agent-management permission, an agent caller, another company’s agent, a different agent’s key ID, and a pending-approval/terminated target. A created key without a real responsible-user binding is a failed acceptance prerequisite, not a working credential.
Sources: Keys tab, key routes, key service, authentication, and CLI token commands.
managed-agent-cli
Automated: Managed-agent CLI uses mocked provider/API responses. Profile route authorization and remote profiles cover actor/company checks and qualification. They do not establish provider provisioning or a useful managed task.
Manual: Start with known adopted provider IDs in an authorized disposable provider account. Run --probe and verify only provider reads: no resources are created and no Paperclip profile is written. Reject unsafe tools/network/package configuration, an unsupported model, duplicate profile matches, a missing retention acknowledgement, and a malformed secret UUID. During persistence, reject missing, inactive, or foreign-company secret references. Then create or adopt a locked profile in a disposable company; inspect its pinned version, model, environment, retention attestation, and cost ceiling through the profile API. Repeat setup and verify resource reuse. Reject viewer/agent writes and foreign-company references. Qualify useful task execution separately through the runtime recipe; a successful probe is not execution acceptance.
Sources: Managed-agent CLI, profile routes, profile service, and runtime validation.
Gotchas
-
Managed-agent probing is read-only at the provider and does not persist a Paperclip profile. The explicit retention acknowledgement remains required even for probe.
-
Agent keys, human CLI tokens, and personal assistant OAuth grants are different credentials. Never include a key’s plaintext token in screenshots, logs, or verification artifacts.
-
A roster entry is not proof of an authenticated or invokable adapter.
-
Pending hires may live in approval/task surfaces rather than the active roster.
-
Skill and tool grants are separate: see skills and app permissions.
-
A personal primary agent is a per-user/company preference. It does not change reporting lines, stars, permissions, or another person's primary agent.
connect-grok-bot
Choose Invite an external agent → Grok Bot, identify the Bot by its desktop name, connect its remote MCP plugin, configure a webhook-only routine, and verify delivery plus authenticated reply. Save & exit resumes the same agent. Keep pairing codes in browser authorization and routine credentials in Paperclip’s fields. A working Bot web URL is not required.
Prerequisites: authenticated public HTTPS, Assistant connections (MCP), Paperclip Runner and Grok Bot experimental settings. Cloud uses its normal managed Runner environment. Provider usage is unknown. Routine uncertainty blocks new assignments until explicit inspection and recovery; stopping work revokes Paperclip authority without confirming remote termination.
Evidence: source implementation and focused protocol tests; real provider assigned/proactive workflows and deployed managed acceptance remain release gates.
Documentation scope: Agents, organization, and runtime setup
Per-harness/model/account capabilities, every instruction-file error, and complete built-in-agent lifecycle variants remain separate qualification matrices.