Jannik/PaperClipAI
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip.git synced 2026-11-04 19:28:46 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
fd4da0bf5ef2ea7dfc3da566567444ca3e87d1a2
PaperClipAI/maps/feature-map/agents.md
T
DottaandPaperclip dcc0878b32 perf(agents): save healthy account settings without a runtime probe (#18690) 
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The agent runtime page saves account, model, and environment
settings.
> - The save handler starts a computer and runs a live account test
before it writes the edit.
> - A slow computer or provider can make a healthy account save take
tens of seconds.
> - Saved account health, access, installation, and compatibility can be
checked without a runtime test.
> - This pull request uses those checks for ordinary configuration
saves.
> - Legacy adoption, task adoption, and Copilot model checks keep live
verification.
> - The benefit is a fast save while Test and execution retain runtime
checks.

## Linked Issues or Issue Description

**What happened?**

Saving a new AI account selection on an existing agent can take 20–30
seconds. Model edits can take the same path. The configuration PATCH
acquires a computer, prepares account credentials, runs a
provider/runtime probe, and releases the computer before it saves.

**Expected behavior**

A healthy installed account can be saved after current access and
compatibility checks. A save confirms persistence. Test verifies the
runtime. An unverified legacy account must still pass live adoption
checks.

**Steps to reproduce**

Run the PostgreSQL regression with a 20-second controlled delay at
computer allocation. On the original route, a successful save takes
20,191 ms and calls allocation and the runtime probe once. With the
first patch, the same fixture takes 51 ms; with the environment-guard
correction, it takes 37 ms and calls neither operation. Each timing has
one sample. This is a local fault experiment with real HTTP and
PostgreSQL. It is not a hosted latency measurement.

Related: #17760 addresses binding comparison and prospective probe
environment resolution. This change deliberately removes the live probe
from ordinary healthy-account saves. It keeps live checks for legacy and
task adoption. #17965 fixes the result of an explicit managed Runner
test. Neither change removes this save-time wait. #18687 optimizes a
different Apps configuration read.

## What Changed

- Replace the internal probe boolean with explicit none, legacy, and
always modes.
- Use legacy mode for ordinary configuration saves. Keep current account
health, access, installation, compatibility, environment, audit, and
revision checks.
- Keep the environment company check before the live-probe branch. Keep
the live task-adoption transaction and Copilot model checks.
- Add twelve real PostgreSQL save-route regressions, including
company-bound environment checks. Keep the existing inherited-sandbox
adoption fixture for legacy and task adoption.
- Cover healthy and legacy settings changes separately. Keep provider
rejection and reconnect tests on the legacy save path.
- Update the specification and feature/access maps to distinguish saving
from runtime verification.

The configuration route owns this policy. The account service still owns
account access and health. The existing environment test service still
owns live probes. No new endpoint, migration, dependency, background
job, or provider protocol is added.

## Verification

Base: `3f8ebfff8aa9febd0733c6f65b07485dcadfd0e2`.

- Original route with initial regressions: three failures and two
passes. Healthy saves reached computer allocation. The controlled
20-second baseline saved successfully but failed the no-allocation
assertion.
- Initial save/adoption/Copilot selection: 21 passed. The name filter
excluded 141 unrelated tests. The seven new cases cover persistence,
revision and activity records, model edits, roster edits and stale
retries, missing installation, revoked grants, legacy verification, and
controlled allocation latency.
- Explicit Test-route suite: 55 passed. The first attempt reached the
30-second import hook limit. The same suite passed with a 90-second hook
limit.
- Saved harness preflight suite: six passed. Account revocation,
compatibility, probe failure and target release checks remain.
- `node scripts/check-maps.mjs` and `git diff --check`: passed.
- Review revision: both full save/account suites passed, 96 tests total.
The controlled save took 37.08 ms with zero computer allocations and
zero provider probes. The five new environment checks passed after the
three foreign-environment cases failed against the first patch.
- Local full `pnpm -r typecheck`: unavailable because cargo is missing.
- Local full `pnpm build`: unavailable at the verified Copilot runtime
prerequisite. Server typecheck preparation also reaches missing cargo.
- Local full `pnpm test:run`: stopped after concurrent broad checks
exceeded the container memory limit. No full-suite pass is claimed.
Direct server TypeScript checking and its bounded retry were also killed
by the container memory limit. The first remote Typecheck + Release
Registry check passed; the next head still requires fresh CI.

Reproduce the controlled timing:

```sh
cd server
PAPERCLIP_CONFIG_SAVE_PROFILE_DELAY_MS=20000 pnpm exec vitest run src/__tests__/agent-configuration-save.test.ts --hookTimeout 90000
```

The fixture keeps real Express, authorization, account selection,
PostgreSQL persistence, revisions and audit writes. Only remote
allocation and the provider probe are controlled. The default tests do
not contact a provider. Successful configuration saves no longer depend
on either controlled operation. A later explicit Test or task must still
verify the actual runtime.

Review follow-up: the first Greptile review found that the new
healthy-account path skipped the environment company guard. The
corrected route checks the effective environment before it decides
whether to probe. Five real PostgreSQL cases cover foreign, same-company
and global environments, inherited defaults, and an existing account
binding. Against the first patch, the three foreign-environment cases
returned 200 and failed their expected 403 assertions; the two allowed
cases passed. Initial fixture attempts hit unique environment
constraints; the fixture now uses distinct sandbox rows and names.

The first CI server shard found 11 tests that required a live probe for
every save. Those expectations are changed to the documented
healthy/legacy split, with additional healthy-selection cases. The build
and Runner jobs were cancelled after this test failure. Their logs show
no separate compile or test verdict. No cancelled check is counted as a
pass.

Latest commit `6257e9e67f289e1c650a8b4c2b818fcca37e2800`: [CI run
41542980091](https://github.com/paperclipai/paperclip/actions/runs/41542980091)
passed typecheck, build, all test shards, Runner checks, and E2E. All 55
check runs are complete: 52 passed and 3 were skipped by their workflow
conditions. The commit status check also passed. [Greptile
review](https://github.com/paperclipai/paperclip/pull/18690#issuecomment-6590555746)
is 5/5 for this commit with no new findings. The earlier environment
ownership thread is resolved. These remote results complete the checks
that the local tool and memory limits prevented. The earlier local
failures remain recorded above.

## Risks

A healthy saved account can become invalid at the provider before the
next runtime use. Ordinary saves no longer detect that through a live
test. They still reject unhealthy, revoked, incompatible, or uninstalled
accounts in current storage. Explicit Test and execution retain provider
authentication and project-authentication checks. Legacy-account
adoption, task connection adoption, and Copilot account-specific model
checks keep their existing live validation.

There is no migration. Reverting the route change restores the earlier
synchronous probe behavior.

## Model Used

OpenAI Codex, GPT-6 family, with repository tools and code execution.
This runtime does not expose the exact model ID, context-window size, or
reasoning setting. Those values are not inferred.

## 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 and contains no internal
Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass (focused suites; full-suite
limits are above)
- [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>
2026-11-03 16:56:11 -06:00

341 lines
25 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
navigation: {"section":"Agents and reusable capabilities","sectionOrder":30,"order":10}
---
# 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](../../ui/src/pages/NewAgent.tsx), [configuration](../../ui/src/components/AgentConfigForm.tsx), [organization](../../ui/src/pages/OrgChart.tsx).
Agent access: [companion](../agent-access-map/agents.md).
## 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.
For **Cursor Cloud**, choose its card in Cloud when native Runner is enabled and
the qualified controller is available. Its held setup draft uses the API
controller without a Computer, before model or credential selection. Local
operators can choose **Paperclip Runner** in Advanced. Bind a Cursor Cloud
API key, enter the exact model and select a repository/ref or a named Cursor
cloud environment. Cursor hosts the agent's environment; this native setup has
no Paperclip Computer selection. Save, reopen, and run Test. Test checks the
account catalog and callback authentication gate without a prompt; the effective-model
warning remains visible for this experimental integration. Finish setup repeats
that account check and reaches Ready without preparing or leasing a Computer,
even when the instance has a default plugin Computer. The Cursor lifecycle stays
per-turn. Assign a real task
and verify its output, question continuation, Plan approval and Stop separately.
Managed-sandbox-only policy stays enabled. It continues to deny local agent code.
Kubernetes-only execution is not supported by this API controller.
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.
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`
On Harness / Runtime, select an installed healthy AI account or change its model
and save. The save checks current access and compatibility without starting a
computer or provider hello test. **Test** still verifies the runtime. Unverified
legacy accounts, task connection adoption and Copilot model checks retain live
validation. Verify saved configuration separately from runtime readiness.
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](../../doc/agent-configuration-yaml.md). 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`
Native API discovery explains this human-only profile/crown control and the
replacement confirmation. The Chat agent picker opens a conversation; it does
not set the person's primary preference. This guidance grants no agent write
authority.
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** (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](./README.md#before-driving-a-journey). Use a disposable company and supported adapter; hiring may require a formal approval.
### `hire-agent`
Automated: [new agent page](../../ui/src/pages/NewAgent.test.tsx) and [configuration form](../../ui/src/components/AgentConfigForm.render.test.tsx) 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.
The [setup lifecycle tests](../../server/src/modules/agent-lifecycle/__tests__/setup.test.ts)
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](./runs-adapters.md#adapter-setup)
and [target qualification](./execution-environments.md#environment-settings).
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](./companies.md) 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](../../server/src/__tests__/agent-instructions-service.test.ts) and [instruction revisions](../../server/src/__tests__/agent-instruction-revisions.test.ts) cover file/revision contracts.
The [AI account field regression](../../ui/src/components/ai-connections/AiConnectionField.test.tsx)
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 it explains that verification is paused 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. 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
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](../../ui/src/pages/AgentRunnerUpgrade.test.tsx)
and [configuration form](../../ui/src/components/AgentConfigForm.render.test.tsx).
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](../../ui/storybook/stories/agents/codex-runner/upgrade.stories.tsx)
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](../../ui/src/pages/OrgChart.test.tsx) is component evidence. Built-in setup also has [configuration modal tests](../../ui/src/components/ConfigureBuiltInAgentModal.test.tsx).
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](../../ui/src/context/PrimaryAgentProvider.test.tsx)
and [primary-agent routes](../../server/src/__tests__/primary-agent.test.ts)
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](../../cli/src/__tests__/token.test.ts) mock create/list/revoke. [Cross-tenant routes](../../server/src/__tests__/agent-cross-tenant-authz-routes.test.ts), [agent permissions](../../server/src/__tests__/agent-permissions-routes.test.ts), and [authentication middleware](../../server/src/__tests__/agent-auth-middleware.test.ts) 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](../../ui/src/pages/AgentDetail.tsx), [key routes](../../server/src/routes/agents.ts), [key service](../../server/src/services/agents.ts), [authentication](../../server/src/middleware/auth.ts), and [CLI token commands](../../cli/src/commands/client/token.ts).
### `managed-agent-cli`
Automated: [Managed-agent CLI](../../cli/src/__tests__/managed-agent.test.ts) uses mocked provider/API responses. [Profile route authorization](../../server/src/__tests__/managed-agent-profile-routes-authz.test.ts) and [remote profiles](../../server/src/services/remote-agent-profiles.test.ts) 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](../../cli/src/commands/managed-agent.ts), [profile routes](../../server/src/routes/managed-agent-profiles.ts), [profile service](../../server/src/services/managed-agent-profiles.ts), and [runtime validation](./runs-adapters.md).
## 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](./skills.md) and [app permissions](./app-permissions.md).
- 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.
Reference in new issue View Git Blame Copy Permalink