TonioandClaude Opus 5.5
8ea240218d
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The agent page is where an operator reads and changes one agent. > - The page grew one tab at a time. Ten tabs sit in one flat list, the header holds many buttons, and the audit links leave the agent. > - A design pass, called Refine-v2, made a calmer layout for this page. It ran in a prototype on fixture data only. > - This pull request moves the Refine-v2 layout and behavior into the live agent page. Where the prototype and the live page differ, the live behavior stays. For example, the floating save bar stays on screen. > - The benefit is a shorter navigation, edits in place, and audit data that stays inside the agent. ## Linked Issues or Issue Description Refs #13716 Refs #9166 Both pull requests mount plugin tabs or slots on the agent page. They touch the same files, so one of the three needs a rebase after the others merge. **Subsystem affected** The agent detail page in `ui/` (`ui/src/pages/AgentDetail.tsx`, its sidebar, header actions, and the shared agent config form). **Problem or motivation** The agent page is hard to scan. The navigation shows ten items in one list. The header shows Run now, Pause, Clear error, and Assign task as separate buttons. The name, title, and manager are form fields deep in the Harness tab. Activity, Runs, Costs, and Budgets open company-wide pages, so the operator loses the agent context. Each tab uses a different card and table style. **Proposed solution** Use one layout system for every agent tab. Group the navigation into Agent and Audit. Edit the name and title in the header. Move the work actions into the actions menu. Show audit views inside the agent. Keep the persistent save bar and add a status dot to it. **Alternatives considered** We considered a flag that lets operators opt in to the new layout. We did not use a flag, because two layouts on one page double the test surface. We also considered moving the save button to the end of the scrolling content, as the prototype did. We kept the floating save bar, because it is always visible. **Roadmap alignment** `ROADMAP.md` has no item for the agent page. This change is a UI refinement of an existing page. It adds one optional field to an existing API request and no database schema change. ## What Changed - **Navigation.** The agent sidebar shows two groups. Agent has Overview, Identity, Harness / Runtime, Secrets & variables, Permissions / Trust, and Advanced. Audit has Activity, Runs, Costs, and Budgets. Skills, Tools, Channels, and API Keys leave the navigation. Their URLs still open. The Instructions tab is now Identity, at `/identity`. The old `/instructions` URL redirects. - **Header.** The agent character shows at a larger size. The name and title edit in place. Enter or blur saves. Escape cancels. An error restores the old value. A rename updates the URL. While a tab has unsaved changes, the header refuses the edit and asks the operator to save or discard first. The third line shows the title and a link to the manager. A crown button to the right of the name replaces the "Set as my primary" link and the separate primary indicator. It is outlined and dimmed until the agent is your primary, then fills with a short pop. Replacing an existing primary asks for confirmation first, and the pop plays after the dialog closes. Reduced motion skips the pop. Run now, Pause or Resume, Clear error, and Agent history move into the actions menu. Assign task is the primary button. For an agent that still needs setup, Finish setup is the primary button and Assign task moves into the menu. - **Agent history.** A new dialog in the actions menu replaces the Revisions entry. Each row shows a plain-language summary, the person or agent who made the change, the date, and Restore. Restore asks for confirmation. A failed restore shows its reason inside the confirmation. - **Overview.** Four metric tiles show activity this week, runs this week, costs this month, and budget used. Each tile links to its audit view. When the list behind a count is capped, the tile shows a lower bound, for example 200+. The activity tile follows live updates. Profile, Skills, and Recent tasks panels follow. The Profile panel lists direct reports under their label in at most two rows, then a "+N more" button that expands the list. The Latest run card is removed. - **Identity.** The file preview shows the raw text. A pencil button switches to a plain text editor. Copy and Delete are icon buttons. A chip next to the file name says "Managed by you" or "Managed externally". Per-file history and unsaved edits stay. - **External instructions.** "Advanced settings" opens Root path and Entry file fields and a Load profile button. Load profile asks the server to switch only if the root directory and the entry file already exist. If either is missing, the server refuses and the panel shows the reason. The entry file can have any name inside the root. - **Instructions bundle API.** `PATCH /agents/:id/instructions-bundle` accepts an optional `requireExistingEntry` flag (`packages/shared` validator, `server` service, `ui` client). With the flag, the server checks the root directory and entry file before it creates or copies anything. Without the flag, the behavior does not change. - **Harness / Runtime.** The config form gets a `panels` layout: Harness and Execution side by side, then the runtime test, then environment variables. The identity and run-policy sections are hidden from this tab. - **Secrets & variables and Advanced.** These tabs use the same filled panels and table headers. - **Permissions / Trust.** The trust presets show as selectable cards. An Allowed connectors panel shows up to three connector logos and links to Apps, filtered to installed connectors. Capabilities sit in their own panel. Changes on this tab save at once, with no save bar. - **Audit inside the agent.** Activity, Runs, Costs, and Budgets render inside the agent page. Runs is locked to the current agent. A failed budget incident action shows its reason under the incident. - **Save bar.** The floating save bar stays. It shows an amber dot for unsaved changes and a green dot with "Changes saved" after a save. Discard stays. - **Leave guard.** If the form has unsaved changes and the operator clicks a link, a dialog asks to keep editing or discard the changes. Browser back and the header actions keep the native confirm. - **Apps.** `/apps?source=installed` opens the Apps page on the Installed filter. - **Tokens.** New `--agent-detail-*` tokens in `ui/src/index.css` hold every spacing and fill value. Each fill is a mix of foreground into background, so one value works in light and dark themes. - **Tests and maps.** Tests cover the navigation model, sidebar, header menu, Overview layout, Identity editor, and helpers. The agent-configuration recipe in `maps/feature-map/agents.md` describes the new page. ## Verification - `cd ui && npx vitest run`: 849 test files and 10,081 tests pass. - `cd server && npx vitest run src/__tests__/agent-instructions-routes.test.ts src/__tests__/agent-instructions-service.test.ts`: 40 tests pass. - `npx playwright test --config tests/e2e/playwright.config.ts tests/e2e/onboarding.spec.ts tests/e2e/chat-adapters-ui-providers.spec.ts`: 26 tests pass. - `cd ui && pnpm typecheck` passes. This includes the Storybook catalog check. The `server` and `packages/shared` typechecks pass. - `cd ui && pnpm build` passes. - `pnpm run check:token-gates` reports all gates clean. - `node scripts/check-maps.mjs` and `node scripts/storybook-catalog.mjs --check` pass. - Manual check on a local instance, in light and dark themes: 1. Open an agent. Confirm the sidebar shows the Agent and Audit groups. 2. Click the agent name in the header. Type a new name and press Enter. Confirm the URL changes. Rename it back. 3. Open the actions menu. Open Agent history. Confirm the rows and the Restore confirmation. 4. Open Identity. Click the pencil. Change a line. Confirm the save bar shows the amber dot. Click a sidebar link. Confirm the discard dialog. Click Keep editing, then save. Confirm the green dot. 5. Open Harness / Runtime, Secrets & variables, and Permissions / Trust. Confirm the panels and the trust cards. 6. Open Runs under Audit. Confirm the list shows only this agent and the page stays inside the agent. ## Risks - This changes a high-traffic page for every operator at once. There is no flag to switch back. - Run policy and Reports to are no longer editable on the agent page. The header shows the manager as a link only. - Skills, Tools, Channels, and API Keys are reachable by URL only. Operators who use them from the sidebar must use the URL. - The pull request conflicts with #13716 and #9166 in `AgentDetail.tsx` and the agent sidebar. - Storybook stories for the agent page and `DESIGN.md` are not updated in this pull request. - The new `requireExistingEntry` flag is opt-in. Existing API callers keep the old behavior, which creates a missing external directory and entry file. - I ran two e2e spec files locally, not the full `pnpm test:e2e` or `pnpm test:release-smoke`. CI runs the full e2e suite. I did not run the repo-wide `pnpm -r typecheck`, because the local toolchain has no Rust. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Anthropic Claude Opus 5.5 (`claude-opus-5-5`), in Claude Code, with reasoning and tool use (shell, file edits, and a browser for visual checks). A person directed every design decision. ## 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 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
25 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. Open an unfinished agent from the roster to reach its header. The header shows Finish setup instead of Run or Resume, including during computer preparation and verification. Terminating agents cannot reopen setup. Final submission requests approval when required, then follows the existing preparation and verification lifecycle. The confirmation shows Finishing agent setup until the foreground detail query observes actual readiness. Assign a Task then hands that current record to the composer, so its status does not come from an older paused draft. Manual/import pauses and required hire approval remain blocking states.
When the native Runner adapter is available, Google Antigravity appears in the ordinary adapter picker. Before runtime acceptance, its card says Not available yet. Selecting it opens Google account setup and model configuration without saving an unqualified native execution configuration. The existing inactive draft stays held; Test and Finish remain unavailable, and the page says model and connection settings are not saved. The selected adapter is retained with the draft: Back to agents, reload, and Finish setup return to the same Google setup. Pending roster rows identify Google Antigravity without implying a configured connection or runnable model. Change adapter returns to the picker with the saved choice selected and allows switching that same held draft to another supported adapter. Verify discovery, Google-specific setup, draft preservation and the disabled actions separately from a successful Antigravity hire or task run.
On an isolated host with a current operator candidate authorization, company-scoped adapter inventory can expose Candidate with one exact model. That company can connect, save, reopen, Test and Finish setup while the global release stays pending. Test verifies native account/model admission and cleanup without a model turn. Other companies, remote targets, expired authority and other models stay blocked. Verify this scoped path separately from production qualification and real task acceptance.
The explicit-only Antigravity agent journey protects the ordinary roster/picker path, saved personal Google subscription, native Test, actual ready handoff, Instructions-only file marker, task and same-task follow-up. Its fixed driver starts from the dashboard and creates the new agent through visible controls. The current runnable cell attaches to a self-hosted target with the admitted local macOS ARM64 candidate and exact low model. Saved-account reuse does not qualify fresh OAuth, other platforms or global provider release; registration and synthetic controls are separate from the retained exploratory and fresh fixed-driver results.
Agent-owned plugin environments prepare the saved draft in the background when
their driver declares requiresAgent. The draft waits in verifying with its
setup hold until hiring finishes. Changing environments keeps the selected
account and Configure step, saves the selection, and invalidates its test.
Preparation and failed-save retries remain visible without reconnecting.
Companies requiring hire approval save the account with pending verification;
resource allocation waits for approval.
agent-configuration
Open /agents/:agentId and the configuration/instruction surfaces it exposes.
The agent nav has two sections: Agent (Overview, Identity at
/agents/:agentId/identity, Harness / Runtime, Secrets & variables,
Permissions / Trust, Advanced) and Audit (Activity, Runs, Costs, Budgets),
which render inside the agent, filtered to it. Skills, Tools, Channels, API Keys
and Revisions are not in the nav but still open by URL. Edit the name and title
in place in the header (Enter or blur saves, Escape cancels); while a tab has
unsaved changes, the header refuses the edit and asks to save or discard first.
Assign task is the header's one button (Finish setup while setup is pending);
Run now, Pause/Resume, Clear error, Agent history (a dialog listing
revisions with a confirmed Restore), Duplicate, Copy ID, Reset sessions and
Terminate are in the actions menu. On Identity, Advanced settings →
Load profile switches to an external root only when the root directory and
entry file already exist; otherwise the server refuses and the panel shows why.
Open Advanced at /agents/:agentId/advanced for the compact agent
YAML configuration. Edit a name, budget,
runtime setting, and adapter key; save, reload, and check the ordinary settings
and Agent history. Try malformed YAML, an unknown field, omitted settings, a removed adapter key,
and a concurrent settings edit. Errors must retain the draft; stale saves return
a conflict. Unchanged secret markers must preserve their stored values. Following
a link away from a draft must open the Discard unsaved changes? dialog; Back/Forward
keeps the browser confirmation. Reload saved
discards the draft. Also edit instruction text, skill pins, direct tool installs,
channel settings/resources, permissions/trust/project boundaries, secret operations,
and API key operations. Verify each result in its owning tab. Revision restore is
an isolated save. Default YAML excludes catalogs, inherited definitions, history, and instruction
contents. Verify profile-key references, named instruction-file patches (null
deletes one file), omitted-setting preservation, and explicit clears. Adding
unrelated company profiles must not grow this agent’s YAML. Inherited access and
history remain in their owning tabs. An
interrupted multi-resource save must report partial progress, preserve returned
one-time keys, and require reload before another save. Domain APIs retain their
existing authorization; a multi-resource save is not atomic.
For a low-trust agent, open Permissions / Trust → Allowed projects. An operator with agent-management permission can select additional projects and explicitly save them. Existing projects and other containment restrictions remain intact. Cancel discards the draft; a failed save retains it. Reload to verify persistence. This does not start or retry a task.
In /agents/all, select roster checkboxes and choose Edit connection & model.
A mixed selection offers one action per harness. Each field is opt-in. The editor
previews each changed value and excludes agents already at the target value.
Models must be compatible with every selected connection. Failed writes show
per-agent errors; Retry touches only the remaining agents. Connection pools and
externally managed agents are not editable through this shortcut.
Verify connection-only, model-only, both fields, mixed-harness selection, hidden selections, no-op counts, incompatible models, partial failure and retry. Reload the roster and compare stored settings, including unrelated heartbeat and adapter fields. A concurrent configuration edit must return a conflict. Shared runtime validation, access checks, revisions and audit logging still apply. Live runs retain their existing settings; model changes can reset saved sessions. Connection adoption can require an explicit reset of existing sessions.
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 the outlined crown beside its name (Set as my primary). Inspect the filled crown on the profile, the crown on the 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 (by URL; it is not in the agent nav) 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.
For an agent-owned plugin environment, verify preparation before connecting, same-agent probes, account preservation after an environment change, failed selection-save retry, and switching back while the computer stops. Confirm the setup hold still blocks ordinary work and API key creation before finishing. Start through the name/adapter dialog with a managed-only or forced Kubernetes policy and a draft that inherits its environment. Once preparation completes, confirm the auth choices, Advanced gateway, and saved subscription remain usable. The setup lifecycle tests exercise durable transitions with synthetic plugin resources; they do not prove live VM provisioning.
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.
The AI account field regression checks duplicate provider names, account identity in choices and adoption confirmation, the exact selected grant, and disabled unavailable accounts with authorized metadata fixtures. Manually compare a personal API key and shared subscription with the same name in Harness / Runtime. Confirm their method, scope and available identity before saving. Reload the saved choice and verify the next eligible task uses it; labels alone do not establish credential validity or change account access.
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 a failed configuration test explains that automatic verification is paused and offers Retry now. Repeated refreshes must not start another test. Timeouts and temporary test-environment failures still retry automatically. 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. Obsolete Claude tuning options (including maxTurnsPerRun) are ignored with a field-specific warning; permission, network, filesystem and command incompatibilities still produce an error. Selecting another runner must not silently discard security settings or change an active run's recorded execution. Keep runner choice in Advanced and verify the next eligible run separately from historical transcripts.
Existing legacy Claude, Codex, and Grok Build agents on qualified default environments, or
probe-capable Daytona snapshots / immutable sandbox images, show Upgrade runner above their configuration. Verify a company owner with agents:configure and no instance-admin role can qualify the saved computer and upgrade. A caller without configuration permission must be denied before a probe starts. Exercise that action with
pending edits and an environment-variable draft. An unsaved change to a different
effective computer must disable the action and explain that the computer change
must be saved first; restoring the saved target must re-enable it. Reopen the page and compare the
saved harness, model, account bindings, instructions, and run policy. Check a
Grok upgrade with an unset or grok-build model: it must use grok-4.7.
Compare effective search policy before and after, including the implicit disabled
default and explicit enabled search. Verify task model and effort changes use the
Grok catalog and reach execution while retaining the account and search policy. Check a
saved maxTurnsPerRun: 1000: upgrade must warn and remove it. Test an initially
unqualified Daytona Paperclip Computer: click must probe, record qualification,
refresh availability, and only then save. A failed probe or changed selection must
leave the agent on Legacy. Check a rejected permission setting, repair it, and retry. Verify a real task before
and after migration, including its output, preserved history, and fresh session.
The notice must stay absent for native agents, other harnesses, and unsupported
targets. Discovery failure must not imply that an upgrade is available.
Navigate to another agent while an upgrade is pending. Its result must stay with
the original agent, without showing success on the new page or redirecting back.
Focused coverage: save receipt
and configuration form.
For an existing native agent on a Daytona snapshot or immutable sandbox image, use Test in its saved Harness or Runtime configuration after a managed computer update. This action qualifies the saved computer under the existing agent configuration permission before testing the runtime. A current proof must remain unchanged. A missing proof requires a real successful probe and verified cleanup. Failed qualification must stop the runtime test. Unsaved configuration or a different computer must not qualify a draft target. A company owner must not need instance-admin permission, and the generic environment probe must remain restricted. Existing runs retain their recorded allocation and snapshot binding.
Storybook: Runner upgrade mounts the production page and shell with mutable HTTP fixtures for both harnesses, pending, failure/retry, incompatible settings, repair, native/unsupported states, and mobile/light presentation. Fixture success does not establish real migration or provider execution.
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, the profile crown and primary-agent routes cover selection, replacement confirmation, 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.