mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-21 16:27:18 +02:00
DottaandPaperclip
250429942e
## Thinking Path > - Paperclip helps people manage AI agents for work. > - New agents must pass setup and execution checks before they can run. > - The lifecycle worker saved the same retry message for every failure. > - Users could not identify the failed step or correct its configuration. > - The UI also described failed work as work still in progress. > - This pull request names the failed step and gives a safe corrective action. > - Users can identify configuration problems and understand automatic retries. ## Linked Issues or Issue Description **What happened?** A new hire showed a paused status and “The lifecycle step failed. Retry the operation.” Repeated retries did not explain the failure. A successful retry cleared the original error. This change cannot recover an error that an older server already cleared. **Expected behavior** Name the failed setup step. Give a useful action for known execution test failures. Explain automatic retry. Keep provider output and credentials out of lifecycle errors. **Steps to reproduce** 1. Create a disposable agent with an unavailable model or invalid execution command. 2. Open its profile while verification fails. 3. Inspect the error, correct the configuration, and select Retry now. 4. Confirm that the failure disappears after the agent becomes ready. Related change: https://github.com/paperclipai/paperclip/pull/16155 shows pending setup progress in creation and assignment. This change improves the cause and action shown when setup fails. ## What Changed - Save the failed lifecycle phase and step in the existing lifecycle error field. - Classify authentication, model, command, directory, timeout, and response failures from execution test check codes. - Use fixed error messages. Do not retain raw provider messages, check details, or credentials. - Share the allowed failure codes with the lifecycle log. - Show failed-state labels and automatic retry guidance. Rename Retry to Retry now. - Extend worker, database, and UI regression coverage. Update the agent verification maps. ## Verification - Passed 105 focused tests across lifecycle diagnostics, database lifecycle commands, saved harness verification, and AgentLifecycleStatus. - Passed server TypeScript compilation with `pnpm --filter @paperclipai/server exec tsc --noEmit`. - Passed UI typecheck and production build. - Passed module boundary checks, token gates, character sync, map validation, and `git diff --check`. - Used Playwright to inspect the production component with a simulated model failure. Confirmed the failure text, retry guidance, retry callback, and recovered state. Captured a screenshot. This component check does not prove a live provider run. - Attempted `pnpm -r typecheck` and `pnpm build`. Both require Rust cargo, which is not installed in the local execution environment. - Started `pnpm test:run` locally. No final local suite result was recorded before handoff. The complete PR CI workflow passed. - Passed all latest-commit CI gates, including typecheck, build, general and serialized tests, Rust checks, and all eight browser test shards: https://github.com/paperclipai/paperclip/actions/runs/38726198774 - Greptile scored the latest commit 5/5 with no findings. There are no review threads to resolve. ## Risks - Failure classification depends on existing adapter check codes. Unknown codes use a safe fallback message. - A known code can describe only the checks reported by the adapter. - No database migration is required. The error field remains a string. - Retry schedules, leases, readiness, approvals, and budget controls keep their current behavior. - Full build verification requires a runner with Rust cargo. ## Model Used - OpenAI GPT-6 through Codex. Used reasoning, code editing, browser checks, and tool execution. The runtime does not expose the exact deployment ID or context window. ## 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>
235 lines
12 KiB
Markdown
235 lines
12 KiB
Markdown
# Hiring, agent configuration, and organization — agent access
|
||
|
||
Product map: [Hiring, agent configuration, and organization](../feature-map/agents.md).
|
||
|
||
Review date: 2026-10-12. Source commit: `58e16dbddfc9c8d0cf60867f9d9847f0feda055b`.
|
||
Native REST transport reconciled in this change; see the
|
||
[shared transport contract](README.md#native-rest-transport).
|
||
|
||
This is a source-reviewed baseline of representative operations and known gaps.
|
||
Each capability needs operation-level review before its entire scope can be
|
||
qualified. No live agent execution is claimed. Follow the [map contract](../README.md)
|
||
for format, permission checks, evidence and maintenance.
|
||
|
||
Scoped runner-default source review: 2026-10-12 at
|
||
`eee0534154eaf5d0d3f2bbc97c1e24d86f34a5a5`, limited to creation/configuration,
|
||
approval activation, built-in provisioning and import preservation described
|
||
below. The original baseline commit above still governs unrelated entries; this
|
||
update does not claim operation-complete review or live agent verification.
|
||
|
||
## `hire`
|
||
|
||
Review: `baseline`.
|
||
|
||
API: `present` — representative operation IDs:
|
||
|
||
- `POST /api/companies/{companyId}/agent-hires`.
|
||
- `POST /api/companies/{companyId}/agents`.
|
||
|
||
Agent access: `partial` — Native hire_agent; REST / CLI agent; runtime inheritance for
|
||
native hires.
|
||
|
||
Policy: Agent creation/configuration uses action grants, resource policies and change
|
||
consent; some controls require a board actor.
|
||
|
||
The creation boundary resolves the request-level runner before adapter validation
|
||
and credential normalization. Omitted/automatic new Codex selection uses the
|
||
qualified target's default; explicit Legacy is retained. Disabled adapters and
|
||
external overrides affect new selection, while missing credentials/runtime or
|
||
incompatible settings remain errors. Existing agents and reviewed pending hires
|
||
retain their recorded execution. Native `hire_agent` explicitly inherits its
|
||
caller's runtime and remains subject to permission and credential restrictions;
|
||
it is not an arbitrary host-configuration or login tool. REST/CLI creation and
|
||
hire runner options use the [shared request contract](../../packages/shared/src/validators/agent.ts).
|
||
|
||
Evidence: `source-only` — [implementation](../../server/src/routes/agents.ts#L1395) at
|
||
the reviewed commit above.
|
||
|
||
Scoped Evidence: `source-only` — [creation policy](../../server/src/services/agent-hiring.ts),
|
||
[runner resolution](../../server/src/services/agent-runner-selection.ts),
|
||
[native hire binding](../../server/src/services/native-runtime/paperclip-runner-tool-authority.ts),
|
||
[frozen approval activation](../../server/src/modules/agent-lifecycle/adapters/approvals.ts)
|
||
and [same-harness import preservation](../../server/src/services/company-portability.ts)
|
||
at the scoped commit. No permitted-agent journey was executed for this map update.
|
||
|
||
Verification: `not-run` — exercise a listed permitted operation with actual agent
|
||
credentials/run context; inspect its result and applicable persistence/attribution.
|
||
Assert the relevant denied actor, owner, company or mode from Policy. Review the
|
||
remaining operations before qualifying the whole capability.
|
||
|
||
For this scope, compare automatic and explicit Legacy creation, assert foreign
|
||
company/environment and missing-grant denials, then compare pending approval
|
||
configuration across restart and activation. An unrelated edit/import update must
|
||
not change existing execution; a new package without a runner choice receives
|
||
creation defaults. Do not count a board call or component test as agent evidence.
|
||
|
||
Gaps: Identity/persona hiring works. Operator account login and sensitive
|
||
adapter/environment configuration are separate guarded actions.
|
||
|
||
The runner request does not grant new account, environment-probe or native API
|
||
fallback authority; see [validation access](./runs-adapters.md#validation) and
|
||
[environment administration](./execution-environments.md#probe). Full access
|
||
qualification remains not run.
|
||
|
||
## `instructions`
|
||
|
||
Review: `baseline`.
|
||
|
||
API: `present` — representative operation IDs:
|
||
|
||
- `GET /api/agents/{id}/instructions-bundle/file`.
|
||
- `PUT /api/agents/{id}/instructions-bundle/file`.
|
||
|
||
Agent access: `available` — Native read/update/history/restore instruction tools; REST /
|
||
CLI.
|
||
|
||
Policy: Agent creation/configuration uses action grants, resource policies and change
|
||
consent; some controls require a board actor.
|
||
|
||
Evidence: `source-only` — [implementation](../../server/src/routes/agents.ts#L1395) at
|
||
the reviewed commit above.
|
||
|
||
Verification: `not-run` — exercise a listed permitted operation with actual agent
|
||
credentials/run context; inspect its result and applicable persistence/attribution.
|
||
Assert the relevant denied actor, owner, company or mode from Policy. Review the
|
||
remaining operations before qualifying the whole capability.
|
||
|
||
Gaps: Canonical entry file, revision guard, company boundary, and protected-change
|
||
policy apply.
|
||
|
||
## `organization`
|
||
|
||
Review: `baseline`.
|
||
|
||
API: `present` — representative operation IDs:
|
||
|
||
- `GET /api/companies/{companyId}/org`.
|
||
- `PATCH /api/agents/{id}`.
|
||
|
||
Agent access: `available` — list_agents/get_agent; native call_api for permitted
|
||
configuration fields; REST / CLI.
|
||
|
||
Policy: Agent creation/configuration uses action grants, resource policies and change
|
||
consent; some controls require a board actor.
|
||
|
||
Evidence: `source-only` — [implementation](../../server/src/routes/agents.ts#L1395) at
|
||
the reviewed commit above.
|
||
|
||
Verification: `not-run` — exercise a listed permitted operation with actual agent
|
||
credentials/run context; inspect its result and applicable persistence/attribution.
|
||
Assert the relevant denied actor, owner, company or mode from Policy. Review the
|
||
remaining operations before qualifying the whole capability.
|
||
|
||
Gaps: Reporting-line changes need configuration authorization; a title alone gives no
|
||
authority.
|
||
|
||
## `lifecycle`
|
||
|
||
Review: `baseline`.
|
||
|
||
API: `present` — representative operation IDs:
|
||
|
||
- `POST /api/agents/{id}/pause`.
|
||
- `POST /api/agents/{id}/resume`.
|
||
- `POST /api/agents/{id}/terminate`.
|
||
- `POST /api/agents/{id}/lifecycle/retry`.
|
||
- `GET /api/agents/{id}` returns the safe failed phase/step and action in `lifecycleError`.
|
||
|
||
Agent access: `partial` — REST / native `call_api` resume under agent_config:update
|
||
change-grant authorization; pause and termination remain board-only.
|
||
|
||
Policy: Agent creation/configuration uses action grants, resource policies and change
|
||
consent; some controls require a board actor.
|
||
|
||
Evidence: `source-only` — [implementation](../../server/src/routes/agents.ts#L1395) at
|
||
the reviewed commit above.
|
||
|
||
Verification: `not-run` — exercise a listed permitted operation with actual agent
|
||
credentials/run context; inspect its result and applicable persistence/attribution.
|
||
Assert the relevant denied actor, owner, company or mode from Policy. Review the
|
||
remaining operations before qualifying the whole capability.
|
||
|
||
Gaps: Resume has a generic native REST path. Pause and termination remain
|
||
enforced actor restrictions.
|
||
|
||
## `built-in`
|
||
|
||
Review: `baseline`.
|
||
|
||
API: `present` — representative operation IDs:
|
||
|
||
- `POST /api/companies/{companyId}/built-in-agents/{key}/provision`.
|
||
|
||
Agent access: `partial` — REST / native fallback for eligible provisioning; built-in
|
||
routine controls require board.
|
||
|
||
Policy: Agent creation/configuration uses action grants, resource policies and change
|
||
consent; some controls require a board actor.
|
||
|
||
Evidence: `source-only` — [implementation](../../server/src/routes/agents.ts#L1395) at
|
||
the reviewed commit above.
|
||
|
||
Verification: `not-run` — exercise a listed permitted operation with actual agent
|
||
credentials/run context; inspect its result and applicable persistence/attribution.
|
||
Assert the relevant denied actor, owner, company or mode from Policy. Review the
|
||
remaining operations before qualifying the whole capability.
|
||
|
||
Gaps: Provisioning checks agents:create. Enabling/running its built-in routine is not
|
||
the same permission path.
|
||
|
||
Scoped source review: [built-in provisioning](../../server/src/services/built-in-agents.ts)
|
||
recognizes the underlying Codex harness of a native company agent. New configured
|
||
provisioning resolves the runner, while unrelated reconciliation and same-harness
|
||
edits retain existing execution. Verify explicit runner changes preserve compatible
|
||
saved settings; the general creation/access policy above still applies. This is
|
||
source-only evidence at the scoped commit, not a live provisioning result.
|
||
|
||
## `primary-agent`
|
||
|
||
Review: `baseline`.
|
||
|
||
API: `present` — GET and PUT /api/companies/{companyId}/primary-agent/me.
|
||
|
||
Agent access: `restricted` — this is the authenticated human's personal
|
||
preference. Agent keys and native call_api use agent identity and are denied by
|
||
the board gate; no dedicated agent selection tool is present.
|
||
|
||
Policy: Requires board user identity, company access and active membership,
|
||
except implicit-local board or instance administrator. Viewers may choose their
|
||
own primary. Selection requires a same-company readable, available agent and
|
||
is scoped to actor user ID; the request cannot select another user's preference.
|
||
Explicit null selection is rejected; leave/termination can clear an unavailable
|
||
choice. Initialization stays recorded so clearing does not silently replace it.
|
||
|
||
Evidence: `source-only` — reviewed on 2026-10-13 at
|
||
`60bc0d5fee9a6e48db08fc016521fee3d9f57d67`:
|
||
[routes](../../server/src/routes/primary-agent.ts),
|
||
[service](../../server/src/services/primary-agent.ts),
|
||
[provider](../../ui/src/context/PrimaryAgentProvider.tsx), and
|
||
[route tests](../../server/src/__tests__/primary-agent.test.ts).
|
||
|
||
Verification: `not-run` — select and read the preference as two company users;
|
||
assert isolation, wrong-company/unreadable targets, pending/terminated agent
|
||
rejection and agent-key denial. Verify replacement confirmation and fallback
|
||
precedence in the UI; inspect the cleared state after permitted leave/termination.
|
||
|
||
Gaps: No agent mutation path for another person's preference. Live human/agent
|
||
access is unverified; UI fixture callbacks do not establish persistence or task
|
||
and Chat default resolution.
|
||
|
||
## `grok-bot`
|
||
|
||
Review: `baseline`.
|
||
|
||
API: `present` — `POST /api/companies/{companyId}/grok-invitations`, operator-owned Grok invitations and agent-scoped `/grok-binding` setup, routine, verify, stop, recover and disconnect endpoints. Direct HTTPS `/mcp/runner` uses fixed named-agent OAuth. Grok tools expose durable assignment operations and task-bound upload/download grants.
|
||
|
||
Agent access: `available` — `paperclip_grok_*` through the dedicated agent grant. First-party Paperclip operations execute through the shared Rust Runner. The Bot retains its own apps; Paperclip workspace and third-party app tools are unavailable.
|
||
|
||
Policy: company/agent/client/resource/authorizer binding; current manage-agent permission for consent and subsequent calls; normal task ownership, controller lease, governance, pause, revocation and recorded budget checks. Execution and file transfers require current task-bound sessions. Secret credentials remain in encrypted secret storage and are redacted from HTTP logs.
|
||
|
||
Evidence: `source-only` — [routes](../../server/src/routes/grok-bot.ts), [shared authority](../../server/src/services/external-bot-authority.ts), [routine receipts](../../server/src/services/grok-bot/routine.ts) and [Runner broker](../../server/src/services/dot-runner-broker.ts). Temporary actual-client OAuth and an outbound routine wake are qualified separately; they do not prove this candidate’s acceptance.
|
||
|
||
Verification: `not-run` — deployed acceptance pending; focused protocol/authorization and actual Rust backend tests; run fresh/saved setup, assigned and proactive tasks, duplicate calls, stale sessions, restart, ambiguous delivery, stop and recovery through the real client on the serving managed candidate.
|
||
|
||
Gaps: deployed two-way work and unattended first-time onboarding remain unqualified; remote termination, provider transcript streaming and usage accounting are unavailable.
|