mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-04 19:28:46 +01:00
Dotta
b030683ca2
Co-Authored-By: Paperclip <noreply@paperclip.ing> * codex/claude-runner-default: (85 commits) feat: default new Codex agents to Paperclip Runner on Linux and macOS (#15683) docs(skills): add slow-query diagnosis and fix skill (#16303) feat(sentry): add opt-in run failure reporting with saved run references (#16300) refactor(server): isolate provider message admission and runtime policies (#16289) refactor(server): isolate provider webhook lifecycle decisions (#16283) fix(workspaces): keep cleanup Git scans fresh and dedupe page reads (#16302) fix(sentry): keep provider-rejected Grok wakes out of run failure reports (#16297) fix(runner): report Runner disconnect age when a Dot bridge exits (#16296) refactor(server): isolate chat conversation and control policies (#16276) perf(recovery): use indexed execution identity lookups (#16291) perf(runs): bound history and reduce repeated context reads (#16286) fix(native-runtime): report which close barrier failed (#16298) feat(skills): select and validate tracked GitHub branches (#16288) fix(observability): sample native runs independently of triggers (#16285) fix(github): retry and recover review publication (#16284) perf(workspaces): wake terminal cleanup from committed changes (#16282) fix(mcp): deduplicate discovered tool descriptors (#16281) perf: remove history scans from task and chat queries (#16278) docs(skills): add maintenance bot setup workflow (#16279) fix(observability): time execution configuration steps (#16236) ... # Conflicts: # scripts/verify-grok-npm-install.mjs
241 lines
12 KiB
Markdown
241 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.
|
||
|
||
Creation requests can use `runner: auto | paperclip | legacy`; the server resolves
|
||
and persists execution configuration. Claude Auto selects the native ACPX profile
|
||
on qualified macOS and GNU/Linux x64/ARM64 targets; unknown environment
|
||
qualification remains Legacy. Darwin SSH defaults to Legacy while preserving
|
||
explicit native assets and saved execution. Saved runner/model/provider overrides survive edits
|
||
and approval activation. This selection does not grant connection access or
|
||
bypass hiring authorization. Source: [runner resolver](../../server/src/services/agent-runner-selection.ts).
|
||
|
||
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`.
|
||
|
||
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.
|