0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-21 00:05:49 +02:00

Files

T

DottaandPaperclip adb69e8f09 feat: default new Codex agents to Paperclip Runner on Linux and macOS (#15683 )

## 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>

2026-10-14 11:33:02 -05:00

12 KiB

Raw Blame History

Hiring, agent configuration, and organization — agent access

Product map: Hiring, agent configuration, and organization.

Review date: 2026-10-12. Source commit: 58e16dbddfc9c8d0cf60867f9d9847f0feda055b. Native REST transport reconciled in this change; see the shared transport contract.

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 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.

Evidence: source-only — implementation at the reviewed commit above.

Scoped Evidence: source-only — creation policy, runner resolution, native hire binding, frozen approval activation and same-harness import preservation 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 and environment administration. 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 at the reviewed commit above.

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 at the reviewed commit above.

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 at the reviewed commit above.

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 at the reviewed commit above.

Gaps: Provisioning checks agents:create. Enabling/running its built-in routine is not the same permission path.

Scoped source review: built-in provisioning 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, service, provider, and route tests.

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, shared authority, routine receipts and Runner broker. 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.

12 KiB Raw Blame History Unescape Escape

Hiring, agent configuration, and organization — agent access

hire

instructions

organization

lifecycle

built-in

primary-agent

grok-bot

12 KiB

Raw Blame History

`hire`

`instructions`

`organization`

`lifecycle`

`built-in`

`primary-agent`

`grok-bot`