mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-07 16:35:48 +01:00
DottaandPaperclip
adb69e8f09
## Thinking Path > - Paperclip is the open source control plane for agent companies. > - People choose a harness when creating an agent. > - The server should resolve that harness to a qualified runner. > - Codex is the first harness in the staged default rollout. > - Saved agents must retain their execution choices. > - New Codex agents therefore use Paperclip Runner on qualified macOS/Linux targets, with an explicit Legacy override. ## Linked Issues or Issue Description Refs #16028, #15555, #15673, #15422, #15631, #15926, #15932, #16149. The runtime/install prerequisite and release repair are merged. This slice owns Codex creation, setup, configuration and preservation. Other harness defaults remain unchanged. It adds no database migration; incoming master migrations, required maps and regression coverage are retained. ## What Changed - Resolve `runner: auto | paperclip | legacy` at the common creation boundary across onboarding, API/CLI, hires, built-ins, plugins and imports. Freeze pending hires and export resolved execution choices. - Preserve existing runners on upgrades, unrelated edits and import updates, including compatible accounts, workspace settings, Codex effort and intentional clears. - Use the underlying harness picker and branding; put the runner override in Advanced. Use the shared dropdown and update production-component stories and creation contracts. - Support qualified Apple Silicon, Intel Mac, Linux x64 and Linux ARM64. Linux requires GNU libc 2.39+. Disabled, external, unsupported and unqualified combinations retain their applicable Legacy execution. - Test the selected runtime/account/model/environment. Ordinary Connect probes eligible immutable managed targets and refreshes scoped discovery. Creation/discovery do not provision. Auth, dependency, incompatible-setting and cleanup failures remain actionable without changing runners. - Keep setup probes read-only, preserve local/SSH isolation and resolve packaged assets before staging credentials. Bound cleanup reads by the remaining absolute deadline; physically close every owned ingress socket before endpoint release. Unconfirmed cleanup retains recovery state. - Preserve validated completed-onboarding callbacks through startup recovery. First file-producing work belongs to the child task and uses the existing dependency/block handoff and task-scoped registration. - Reuse existing E2E fixtures, artifact checks, reporting and controls. Keep Docker/Cargo/native compilation remote. Paperclip tarballs contain no Codex payloads; official optional npm platform dependencies remain. ## Verification Current tested head: `1c03a8815672d82c264a9b08d4ea1984e8fae107`. **Merge-ready: required CI, fresh review, package qualification, Mac core acceptance and Test task/follow-up acceptance pass.** The existing attachment and native-continuity oracles independently verify both Test downloads, run attribution and unchanged native/provider/workspace identities. The maintainer authorized a code-owner-review exception for this PR only. The first Test setup failure and normal Board completion-review friction are retained below. Actual post-merge packages and private Cloud distribution remain separate qualification gates. - [Current CI](https://github.com/paperclipai/paperclip/actions/runs/38564241625): all 48 ordinary jobs and required verify/E2E pass. Attempt 1 retained six simultaneous host-shutdown cancellations. One failed-only retry passes those six lanes and two aggregates, preserving 40 successes. Actual integration checkout `53104c1` combines this head with master `c80`; it is not relabeled as the branch tree. Fresh exact-head Greptile 5/5, 30 resolved threads, no actionable findings. - [Exact-source package qualification](https://github.com/paperclipai/paperclip/actions/runs/38565287239): nine applicable jobs pass, nine conditional jobs skip. Four remote native producers; Linux x64 clean install; Intel Mac, Apple Silicon and Linux ARM64 native startup/physical cleanup controls. All 18 tarballs/four daemon source/hash/manifest bindings and 343 migrations through 0344 verify. No Codex payload is packed. These hosted tarballs are not a published npm canary. - Normal Apple Silicon installation and credential-free native startup/cleanup pass using the packaged daemon, with no source build or provider turn. Fresh installed DB initialization passes. Upgrade 651a→1c03 preserves all three complete execution configs, accounts, ten recorded run profiles, paused budgets, active incidents, cost summaries and two historical unpriced events. Historical recovery state is retained. - Cleanup regressions: four delayed-read baseline failures become 15 passing deadline/authority controls. No-acknowledgement and prior-error socket ownership regressions become 12 passing controls. Direct runtime/server types, maps: 35 areas / 176 IDs, diff checks and independent reviews pass. Permission/auth/reconnect policy and the 10-second setup budget remain intact. - Existing source coverage includes creation/selection/imports, pending approvals, recovery, account/lifecycle handling, mounted forms, dropdowns and E2E support. Full typechecks/tests/build/token and applicable Storybook checks pass in the recorded current CI; no duplicate suite or weakened grader. - Literal 9546 live Mac proof: ordinary Auto Codex onboarding, useful document, real completed-child callback/reply, seven successful native runs, manual follow-up and independently downloaded1,101-byte child file. Existing Legacy title edit/reload preserves execution; two real Legacy runs produce independently checked15/34-byte files. These remain historical source records. - Current literal 1c03 Mac core acceptance passes independent checks: ordinary Auto native Codex onboarding without runner override; only timeout 180 seconds/concurrency 1 saved; six successful native runs and six serialized turns (maximum overlap 1); both same-task continuity checks and five mechanical callback checks; actual rendered parent reply and exact child downloads. The useful handoff advances from revision 1 to 2. Both files are 48 bytes, SHA-256 `8b742bd4e8123a7c078f0a8d9f3449fbfa8a320d7d90be641a2818db3c53d92c` and `f42db9774fa06e804ab7d596fc8b922a2b638921c418b87d0111151d290a6afe`; exactly one byte changes and old history remains. The agent is paused with zero active runs/errors. Both artifact work products have `isPrimary=false`, and descriptive titles fail a stricter title-helper assumption; these retained results are scoped editorial follow-up, not new merge gates. Six source-bound screenshots are uploaded and verified in the private primary QA report. - [Literal 9546 managed proof](https://d1p6rlowie26tp.cloudfront.net/runner-e2e/campaigns/gha-38485488621-1/index.html): original 19 assertions and completed judge pass, four native turns, child-bound240-byte file and session/workspace continuity. Checkout reports a verified generated target-lock mutation; full final porcelain was not retained. Signed execution-image identity remains separate from Core source. - Actual 651a Test deployment succeeds on one owned/pinned target. One ordinary Auto API-key Connect then fails native cleanup before hire. Controller turn/drain/suspend completion and service-recorded environment cleanup are observed; they do not certify physical deletion or native authority retirement. Failure/recovery/unknown holds are retained. No Legacy switch or unchanged paid retry. The two source repairs above require actual treatment. - [Current immutable Core preview](https://github.com/paperclipai/paperclip/actions/runs/38570365725) and matching DB/shared artifacts pass. One owned, pinned Test target serves exact `1c03`; identical migration history correctly skips the migrator. Ordinary Auto Codex Connect succeeds and hires native; saved native selection and QA bounds survive reload. The initial child preparation attempt fails before provider work, with actual stdout identifying `renewal_deadline`; its trigger remains unknown and the failure is retained. Normal Board **Try again** and **Resume** recover the child to Done, producing a browser-verified 44-byte file, SHA-256 `0a8458b1efcc2d7a0d815689458c4caab039a46c7c7a3e5805de6bc8b1a96ecc`. The actual parent callback reports the completed child document/file. The existing validator requires a parent-owned attachment, so recovery enters normal Review; after byte checking, normal **Approve completion** reaches parent Done. No forced status or duplicate parent file is used. The validator is unchanged from integrated and current master. Autonomous initial callback-to-Done is not proven. The same-child follow-up completes document revision 2 and publishes a second independently downloaded 44-byte file, SHA-256 `22022257300fae762784632d08d3bbe0bab61e2ce81f91864a14dcd7aa464591`; only the revision digit changes. The unchanged existing native-continuity and attachment oracles pass. All ten recorded runs are terminal: nine native successes and the retained pre-provider setup failure. The QA agent is paused with zero active runs. The pre-existing parent evidence scope mismatch is a separate follow-up, with ordinary completion review exercised rather than a forced status or relaxed validation. This unsigned Core preview remains distinct from post-merge private Cloud composition. ## Risks - Saved agents are not migrated. Explicit runner changes use normal configuration/session rules; historical runs retain their recorded execution. - Native readiness depends on verified assets and server-owned target qualification. A Legacy probe, HTTP200 or successful account save cannot prove native readiness. - Recovery exceptions remain restricted to validated completed-onboarding reports; process-loss, ownership and terminal-state safeguards remain active. Unexecuted live journeys stay open. - Linux ARM paid tasks, Windows, Alpine and 32-bit ARM remain deferred. Cold Cargo cache misses are recorded; no warm-cache speedup is claimed. - Historical invoices/physical cleanup remain unconfirmed and held. After merge, exact published npm canary, signed standard image/migrator, private composition and serving/live acceptance still require qualification. Production deployment/default promotion is not authorized. ## Model Used OpenAI Codex, GPT-6 family, with reasoning, tools, code execution and parallel agents. Exact serving snapshot and context-window size are not exposed. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used with available 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 linked public issues or PRs above - [x] I have not referenced internal/instance-local Paperclip issues or links - [x] My branch name describes the change and contains no internal ticket id - [x] I have run the stated focused tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation - [x] I have considered and documented risks - [x] All Paperclip CI gates are green on the current candidate - [x] Greptile is 5/5 with no open findings on the current candidate - [x] I will address all reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
233 lines
12 KiB
Markdown
233 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`.
|
||
|
||
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.
|