DottaandPaperclip
734c265339
## Thinking Path > - Paperclip manages AI agents and their work. > - Users choose a harness during agent setup. > - Claude, Codex, and OpenCode already receive their qualified Runner default. > - Pi has a qualified native integration but new Pi agents still use the direct adapter. > - This change gives new Pi agents the native default on supported targets. > - Saved agents keep their runner and compatible settings. Legacy remains available in Advanced. ## Linked Issues or Issue Description Refs #17120, #14921, #14922, #14923, #14924, and #14956. Related generic default work: #15422. This PR is the separate Pi follow-up to the merged OpenCode change. **Current behavior** Choosing Pi for a new agent saves the direct Pi adapter. The native Pi integration remains behind the generic experimental flag. **Proposed behavior** Default new Pi agents to ACPX Pi on macOS ARM64/x64 and GNU/Linux x64 with supported glibc. Keep unsupported targets and explicit Legacy selections on the direct adapter. Require an explicit provider/model before test or hire. Permit model-free inactive setup drafts. **Reason and benefit** Users choose Pi once and receive its qualified runner. Saved agents retain their identity and settings. Conversions reject unsupported legacy thinking and launch settings instead of dropping them. ## What Changed - Add Pi to the shared platform/default contract and server creation selection. - Admit native Pi without the generic experimental flag. - Preserve provider models, credentials, workspace settings, exact thinking, and saved native policies. - Add Pi runner controls, branding, setup resume, onboarding, built-in configuration, and import handling. - Add managed Pi OpenRouter routing and matching native provider API-key accounts. Keep subscription and custom gateway exclusions. Clear alternate credentials and reject custom Pi provider overrides. - Keep Pi draft models empty instead of applying Claude's default model. - Verify setup against the pinned Pi runtime. For native Pi on the official OpenRouter route, reverify the API key live without requiring a global Legacy Pi CLI. - Match Pi’s bounded controller close window to its native snapshot cleanup and lifetime verification, preserving explicit caller deadlines and the mandatory drain/suspension proof. - Bind Pi sidecars to the package that owns the pinned native assets, including source and vendored server layouts. Other providers retain their existing package authority. - Keep protocol-owned finish/block tools out of the ACPX forwarded catalog. The trusted bridge installs these tools itself; the complete Rust authorization catalog and terminal receipt ledger remain intact. This fixes actual Pi session startup and applies to other ACPX consumers. - Advance Copilot’s shared-source attestation to v58 because it pins the shared files touched by Pi. Preserve immutable v57 bytes and historical decoding; Pi’s own release identity is unchanged. - Add regression coverage and update the paired maps and developer documentation. ## Verification - Passed: full repository typecheck and full production build on final head656d304783, including the generated attestation repair. - Passed: focused shared/server/UI suites covering default selection, platform fallback, conversion preservation, inactive drafts, managed account compatibility, credential isolation, OpenRouter routing/model IDs, exact thinking controls, and saved-account selection. Relevant batches include 375 server/conversion tests, 267 account/routing tests, and 110 UI setup/account tests. - Passed: 179 attestation, historical-profile, qualified-profile, and native-execution contract tests after CI identified stale Copilot source hashes. The identity generator check passes; the only delta after the passing Pi browser run is this Copilot attestation/history repair. - Passed: 145 managed-account tests, including actual service preparation and API-key adoption/rejection for native Pi without the Legacy CLI; 6 pinned-installation probe tests. - Red then green: an actual task failed session.open because its 54-operation catalog included the bridge-owned terminal tools. The regression with those tools failed before the filter; all 399 Rust library tests pass after it. The full product retry exposed an additional package-authority mismatch. Four authority tests failed before that repair; 11 authority checks and 14 installation/asset checks pass afterward. Direct real Pi session initialization with the corrected package root and catalog succeeds. No model prompt was sent by that diagnostic. - Red then green: real Pi posted Hello from Pi but its controller closed before native cleanup could finish. The cleanup-budget test failed with the old default and passes with the bounded Pi window. All 46 selected suspension, drain, and package-authority tests pass after building their native fixture. - Passed: token gates, paired map checks, Rust formatting, and git diff --check. - Passed real browser acceptance on macOS ARM64, generic native runner flag disabled, sourcea433748a12(Pi code unchanged afterward): the UI selects Paperclip Runner by default, retains Pi and the selected model/account, and verifies the pinned runtime plus live OpenRouter key. A fresh UI-created task, assigned to the UI-created native Pi agent, posted exactly `Hello from Pi` and reached Done without retry or restart. The native run and workspace finalization succeeded; the response and Done persisted after Reload. - Evidence: 8 preserved browser attempts, including the final passing 18-step journey with all screenshots. Prior failures remain recorded. The earlier failed checkpoint run recovered on server restart; that recovery is separate from the fresh final task’s clean success. - Preserved browser failures: missing account control/inherited Claude draft model; incompatible managed-account/model-prefix handling; generic npm probe for Pi; Legacy CLI hello check; duplicate terminal tools and wrong provider-package authority at actual native session.open; a real Hello from Pi comment followed by premature checkpoint cleanup timeout. Each failure has retained screenshots/logs and a corresponding focused repair. The fresh final task proves these repairs end to end. - The exact Runner Vitest shard was also run locally after the attestation fix: the stale-hash failure is gone; 1,833 tests passed, 10 skipped, and two Codex retained-control settlement scenarios failed with `native_cleanup_maintenance_unproven` during terminal ACK/suspension replay. Both scenarios passed in an isolated rerun (2/2), and the same 19-test file passed in the preceding Linux CI run. The precise full-shard timing cause is not established. These Codex scenarios are outside the changed Pi paths; the original local failures are retained; no complete local Runner-shard pass is claimed. The corresponding Runner shard now passes on the final head in hosted Linux CI. All 60 final-head check runs are now terminal and clean (55 successful, 1 neutral, 4 skipped), and the legacy Snyk status is successful. - Local full repository tests were attempted but not completed: provisioning briefly confused a workspace symlink, then a later run was stopped before browser-driven repairs. No full local-suite pass is claimed. Final-head hosted CI is green and fresh Greptile review is 5/5 with all review threads resolved; earlier jobs canceled by runner shutdown are not counted as a pass. ## Risks - Pi cleanup has a finite 45-second default window, accounting for the native 30-second snapshot cleanup and 5-second lifetime fence. Other providers and explicit caller deadlines retain their prior behavior. - Pi requires explicit operator setup with `paperclipai runtime setup pi` on the execution host. This PR does not add automatic downloads. - Linux ARM64, Windows, musl, and unqualified targets retain Legacy. - Legacy thinking levels minimal, medium, and xhigh cannot be translated exactly. Native max thinking, warm lifecycle, or restricted permissions cannot be dropped during a return to Legacy. - Copilot’s bound profile advances to v58 with exact current launch admission; v57 remains decodable for recovery. No historical identity is rewritten. - Existing agents and immutable run descriptors are not migrated. Cloud Pi availability is unchanged. ## Model Used OpenAI GPT-6 through Codex with reasoning, code editing, command execution, and browser use. The exact serving model ID and context-window size are not exposed in this session. ## 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>
12 KiB
navigation
| navigation | ||||||
|---|---|---|---|---|---|---|
|
Runs, harnesses, and model accounts
Operators choose an agent harness and model account, inspect execution history and transcripts, and distinguish a working configuration from a successful task result.
Feature ID: runs-adapters.
Implementation: adapter manager, run host, configuration.
Agent access: companion.
Sub-features
availability:runs-adapters/availability— discover installed adapters and available models/accounts.validation:runs-adapters/validation— test an adapter in the selected execution environment and surface authentication failures.runs:runs-adapters/runs— inspect run status, events, output, costs, and the source task.session:runs-adapters/session— preserve or reset execution context through supported lifecycle actions.
How to get to it (user POV)
adapter-setup
Open an agent’s model/adapter configuration or the instance adapter settings page when permitted.
run-history
Open an agent run at /agents/:agentId/runs/:runId from the agent or task activity.
For latency diagnosis with an operator OTLP endpoint, search the hashed run ID
without restricting the root span name. Compare workspace preparation with its
workspace_<step> intervals. Measure controller readiness separately through
controller.startup.<phase>. A recovery pause or deployment drain is not model
execution time. See the tracing contract.
These source-level diagnostics do not establish a live response-time budget.
Inspect native.controller.<phase> for backend construction, assigned-tool
discovery and post-turn cleanup. Compare those intervals with the actual model
turn; do not count a nested discovery interval twice.
Driving it with Playwright and the Paperclip CLI
Preconditions: follow the baseline. Record adapter, model, account, native/legacy runtime, and environment. Capabilities vary; one harness result is not a matrix-wide qualification.
adapter-setup
Automated: adapter validation routes and model refresh cover server behavior.
Claude native setup uses the existing Anthropic API-key or subscription connection flow. Record the selected account separately from successful execution; unavailable models/authentication and unsupported Legacy-only options must fail visibly.
Manual: Select the intended adapter and account, refresh model choices, and run its environment test. Save, reload, then execute a small task. Repeat with a deliberately unavailable account and verify the failure remains visible.
Choose Codex as the harness; the UI displays its name/icon for both runners. Advanced identifies the automatic default and offers Paperclip Runner or Legacy. New Codex agents default to the native runner on supported macOS or GNU/Linux targets; the shared selection contract and runtime prerequisites define the platform/libc boundary. Windows and Alpine/musl remain Legacy. Claude follows its qualified rollout described above. Disabled adapters, external overrides, and selected-target qualification also affect availability.
Choose OpenCode with the native-runner experimental flag off on a qualified
macOS or GNU/Linux x64 target. Linux ARM64 must retain Legacy because its pinned
OpenCode runtime is not qualified. Advanced should show Paperclip Runner as the
automatic default on qualified targets. Save an inactive draft without a model,
resume it, select an explicit provider/model,
test, finish setup, and reload. Verify the saved provider is opencode. Repeat
with explicit Legacy and an existing Legacy agent; neither should migrate on an
unrelated edit. Check that saved native permission/lifecycle choices survive
resuming setup. Custom commands, arguments, variants, and inherited permissions
must give Legacy remediation when native is selected. A live task with the
selected account is separate proof from these setup and persistence controls.
Repeat with Pi on macOS or GNU/Linux x64 after explicit operator setup of the
pinned runtime (paperclipai runtime setup pi). Linux ARM64 retains Legacy.
Resume an inactive model-free draft, connect an account, choose a provider/model,
and finish setup with the generic native flag off. Verify Pi branding and native
ACPX Pi execution by completing a simple assigned task. Preserve saved native
thinking/permission/lifecycle settings on resume and unrelated edits. Native
thinking supports off, low, high, max; legacy aliases must give remediation,
and returning to Legacy must reject settings it cannot honor.
On a fresh forced-Kubernetes instance without an environment row, inspect discovery
and create with automatic selection. Both must retain Legacy without provisioning;
an explicit Paperclip request must give target-qualification guidance. Begin the
ordinary task to exercise the existing lazy environment path. This live journey
remains separate from the resolver's source controls.
For sandbox defaults, follow the environment probe recipe first. Discovery/creation read company-bound immutable-image evidence without allocating a target. A mutable image or snapshot name does not establish native compatibility. Then test the actual selected runtime with its selected account/model: a legacy CLI or authentication probe alone cannot establish native readiness. For an image-provided Codex harness, verify both final executables after concurrent artifact preparation on an eligible provider. Repeat with a failed runner probe and confirm the harness work has settled before failure returns. Providers without concurrent sync and explicit harness installs remain serial. The real-shell artifact controls cover these source contracts; they do not establish live reply latency. For remote native Codex with managed GitHub access, inspect the controller preparation spans for overlapping GitHub setup and assigned MCP discovery. Provider startup must wait for both. Force either preparation to fail while the other is pending; confirm that the pending operation settles and run-owned access is released before failure returns. Repeat a warm follow-up and retain its actual reply time. The executor controls cover ordering, failure drain and credential projection; they do not qualify a live response-time target. Missing dependencies, failed authentication, invalid models and incompatible custom settings must remain actionable errors without silent runner switching. Saved unchanged execution can still be tested without applying new selection policy, but runtime/account validation must still run.
Verify an automatic Codex hire and an explicit Legacy control through a useful file artifact, follow-up and reload. Preserve Codex reasoning effort and account isolation; retain explicit Legacy permission choices, including false. Reopen an existing agent, make an unrelated edit, and confirm both its persisted runner and next run stay unchanged. Use hiring/import preservation for approval and portability controls.
Test native Codex with a saved subscription whose setup auth file is a managed
link, as well as a regular file and an API-key account. Setup must seed the
isolated probe from the checked account without exposing credentials or changing
its saved runner. With subscription authentication, an unbound configured
CODEX_HOME with linked credentials must fail setup with managed-account or explicit Legacy guidance; it must not claim
readiness when task isolation would omit the file. Dangling or incorrectly owned
credentials must also fail clearly. A selected CODEX_API_KEY or
OPENAI_API_KEY takes precedence over an unrelated subscription file. Test valid,
dangling and invalid subscription links with that selected key; setup must test
the key without reading or refreshing the unrelated account. The private probe copy must be removed after confirmed retirement following success,
failure or cancellation. Unconfirmed shutdown remains a cleanup failure.
Exercise an unavailable local daemon and a preparation failure before probe
handoff. No owned temporary credential copy may remain, and original account
files must be unchanged. A probe whose shutdown is unconfirmed must retain its
recovery state; do not treat it as a preparation-only failure.
Existing setup controls use fake credentials; real account execution remains
a separate acceptance requirement.
run-history
Automated: live run routes and run event sequencing cover run data contracts.
Manual: Start a disposable task, open its running transcript, and follow it to a terminal outcome. Reload and compare task/run IDs, status, output, and cost. Verify a failed run remains distinguishable from a completed run with useful output.
An explicit runner change starts a configuration revision and invalidates the eligible session. Active runs, restart recovery and historical transcript parsing retain their recorded execution configuration; do not infer their runner from a later edit to the agent. Account/harness branding and execution identity are different observations, both required in the evidence.
For an onboarding child-completion callback, verify actual session/turn events
and the source-correlated reply. A succeeded row alone is insufficient: the
literal ea6c8eb5e16d61111968f633a66748b397b64a3e managed attempt was marked
successful during startup without a provider turn. The recovery correction
preserves the existing validated Done-parent handoff; process-death and ownership
checks remain active. Its PostgreSQL controls are separate from the required
revised-source live onboarding and follow-up proof.
Gotchas
-
Model accounts are managed in Apps and inline agent account controls.
/company/settings/connectionsconfigures decision/fast-response models, not the general model-account library. -
The run log is instance database data; it is not the opt-out first-party Telemetry system or operator-configured OpenTelemetry tracing.
-
Authentication/model discovery does not establish tool, image, steering, or resumption capability parity.
-
Use recovery for interrupted runs and execution environments for local/SSH/sandbox differences.
Native setup retirement joins owned startup before cleanup can be confirmed. Transport ownership controls hold preparation or registration without launching a provider, then check bounded close, rejected duplicate requests, no later launch and retention of unconfirmed state. Readiness observes shutdown; resumed startup cannot reactivate ingress after close. These are lifecycle controls, separate from installed provider proof. The real daemon readiness and recovery controls require their existing native fixtures in hosted CI; passing credential-free controls does not qualify them. A primary setup timeout remains a failure even when teardown also fails.
For remote setup shutdown, verify that each durable-state read respects the
remaining suspension deadline. A late result cannot establish suspension or
queue a replacement command after that deadline. An intentional ingress close
must observe physical socket closure before retiring its connection owner and
releasing the endpoint; an unresponsive peer must not extend the setup budget.
The existing transport and ingress suites exercise these conditions without a
provider. Repeat the actual managed setup and useful task journey separately;
the literal 651a3de64fc943216cc414b64b1443809f9499da Test attempt failed
cleanup before hire and retains its unconfirmed recovery state.