mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-30 05:16:50 +01:00
DottaandPaperclip
f60ac29cf1
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Harness selection maps supported agents to Paperclip Runner. > - The native Runner already supports Grok Build, but its migration mapping excludes Grok. > - Grok agents also have a thinking-effort setting that the native execution contract does not carry. > - This pull request adds the migration path and preserves explicit Grok effort through startup and resume. > - Operators can upgrade an existing Grok agent without silently losing its model, account, or effort. ## Linked Issues or Issue Description **What happened?** Existing Grok Build agents have no Runner selector or upgrade action. Adding only the mapping would route conversion through the Codex fallback and lose Grok execution semantics. Native execution also ignores the legacy reasoning-effort field. **Expected behavior** A qualified Grok agent can explicitly upgrade. The saved model, account, instructions, history, and supported effort remain intact. Unsupported legacy settings fail before saving. The provider must acknowledge the selected effort before inference. **Steps to reproduce** 1. Open the runtime page of an existing Grok Build agent on a qualified Linux x64 or macOS ARM64 computer. 2. Observe that the Runner selector and upgrade action are absent. 3. Compare the native execution input with the saved legacy reasoning-effort setting. Related work: #13882 introduced native Grok Build. #15422 covers the earlier default-runner work. This change extends the current shared selection contract. ## What Changed - Add the Grok harness mapping, qualified platform limits, upgrade action, and company-scoped computer qualification. - Translate Grok settings to ACPX without changing the selected account or explicit model. Resolve the legacy default model to the native default. Preserve the effective legacy search policy. Reject incompatible command, argument, permission, and turn-limit settings. - Add native execution input v10 for explicit Grok effort and search policy. Preserve historical schemas. Enforce disabled search through Grok requirements and bind it across startup and recovery. - Apply and verify ACP `reasoning_effort` before prompting. Bind the value to provider descriptors, checkpoints, runtime identity, and resume checks. - Use the Grok catalog and effort choices in the task composer. Apply task model and effort overrides while retaining the agent account and search policy. Update runtime controls, portability/default handling, documentation, and capability maps. - Advance Pi and Copilot source attestations for changed shared transport and recovery code. Keep historical identities intact and update all Rust integration fixtures. ## Verification - Migration and review regressions were reproduced before the fixes. Coverage includes the Grok mapping, default model, explicit effort, implicit search policy, task overrides, and incompatible legacy settings. The broad migration, route, immutable-input, and composer check passed 478 tests. The final catalog and task-input check passed 135 tests. - Runner startup, recovery, search policy, and profile checks passed 361 tests, with one platform skip. The final source-identity, search-admission, and transport event-pump check passed 89 tests. - All 757 Rust workspace tests passed for the broad implementation. After the final source attestation update, all 55 ACPX profile/session tests passed. - `pnpm -r typecheck` and `pnpm build` passed for the implementation. Server and Runner typecheck passed after the final production change. Server `tsc --noEmit` passed after the final test-fixture change. Docker context integrity, token gates, maps, generated protocol data, and replay goldens passed. - The v10 startup fixture initially used an ambient local Grok login and failed on CI. An explicitly empty credential home reproduced all four failures. The fixture now supplies a synthetic key and a private empty home. A separate case checks that missing credentials fail closed. All seven selected Grok v10 and Claude v9 startup cases pass without host credentials. - The full local suite could not complete because embedded PostgreSQL failed before database-backed fixture setup. The broad executor-suite attempt hit the same limit and was stopped. Neither attempt is counted as passing. Current-head CI must verify those paths before merge. - Earlier CI found missing Rust input fields, stale source attestations and exact fixture pins, a missing Docker context entry, and an outdated import expectation. Those failures were fixed and checked locally. The CI logs retain the original failures. - Different earlier CI runs also failed unchanged cleanup pagination, device-login timeout, and chat lost-response recovery cases. Later attempts passed the cleanup and login cases without changes to those implementations. Their causes remain unproven. The original evidence remains in [the first run](https://github.com/paperclipai/paperclip/actions/runs/40563402840), [the login run](https://github.com/paperclipai/paperclip/actions/runs/40571128328), and [the chat run](https://github.com/paperclipai/paperclip/actions/runs/40573072163). A passing retry does not establish a root-cause fix. - Both reviews rate current head `16fba9b4cdf12bc7945e6628912e79da42959f35` 5/5. All current-head CI gates pass in [run 40576580699](https://github.com/paperclipai/paperclip/actions/runs/40576580699). All 60 check runs completed cleanly, including the four intentional skips and the neutral 5/5 Paperclip review. The legacy security status is successful. No review threads remain unresolved. - Staging migration and a real shell task are pending deployment. This PR does not claim full Grok provider qualification. Reviewers can verify the operator path by upgrading a qualified Grok agent, checking its saved model and effort, and running a shell task through native execution. ## Risks - Explicit effort and search policy require the matching Runner and sidecar build. Older immutable execution inputs keep their existing schemas. - Providers that omit or reject the selected effort fail before a prompt. Unsupported effort does not fall back silently. - Existing agents retain their saved runner until an explicit change. New Grok agents use native execution only on qualified platforms. - Grok token and cost reporting remain unverified, as before. ## Model Used OpenAI Codex, GPT-6 family. The exact serving model ID and context-window capacity are not exposed in this session. Used reasoning, source editing, shell execution, and browser inspection. ## 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 and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and the focused suites pass; the full local suite has the environment limitation recorded above - [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>
162 lines
9.8 KiB
Markdown
162 lines
9.8 KiB
Markdown
# Grok Build native runner
|
||
|
||
Select **Grok Build** in the native runner provider selector. The stored contract is
|
||
`adapterType: "paperclip_runner"` with `provider: "acpx"`, `acpxAgent: "grok"`,
|
||
and `model: "grok-4.7"`. Existing `grok_local` agents keep their legacy adapter
|
||
until an explicit upgrade. On a qualified macOS ARM64 or Linux x64 computer,
|
||
**Harness / Runtime → Upgrade runner** preserves the agent, model, account,
|
||
instructions, and history. It starts fresh execution sessions. Advanced also
|
||
offers an explicit Runner choice. Unsupported legacy settings are rejected
|
||
before saving; select compatible settings or keep Legacy.
|
||
New Grok runner agents default to **Full auto (approve all)**
|
||
(`acpxPermissionMode: "approve-all"`) in setup and the configuration form.
|
||
API configurations that omit the permission mode use the same default. No
|
||
additional permission setting is needed for unattended execution. Explicitly
|
||
saved restrictions remain unchanged.
|
||
Grok Build's qualified harness does not require the `enableNativeRunner` flag.
|
||
|
||
Explicit thinking effort uses `reasoningEffort` (`minimal`, `low`, `medium`,
|
||
`high`, or `xhigh`). The immutable v10 execution input, provider descriptor,
|
||
and recovery identity bind this value as `grokEffort`. Before a prompt, the
|
||
Runner applies ACP `reasoning_effort` and requires Grok to acknowledge the exact
|
||
value. Missing configuration, a rejected value, or effort drift stops admission.
|
||
Omitting effort retains Grok's provider default. This setting remains outside
|
||
the model-visible task prompt. Historical execution inputs retain their schemas.
|
||
|
||
The upgrade resolves an unset model or the legacy `grok-build` default to the
|
||
native `grok-4.7` default. Task-level model and effort overrides use the Grok
|
||
catalog and keep the account and tool policy unchanged.
|
||
|
||
Migration also preserves the effective `disableWebSearch` setting, whose legacy
|
||
default is `true`. Native input v10 carries it as `grokDisableWebSearch` through
|
||
startup and recovery. Grok's private `requirements.toml` enforces disabled search
|
||
above compatible project settings. Explicit `false` retains enabled search;
|
||
unset native configurations retain their provider default. See Grok's
|
||
[configuration reference](https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/26-config-reference.md).
|
||
|
||
Grok Build speaks [ACP over stdio](https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/15-agent-mode.md).
|
||
The runner owns `grok agent --no-leader stdio` through ACPX, including session
|
||
identity, cancellation, recovery and the authenticated Paperclip MCP bridge.
|
||
ACP permission requests are approved by the runner under the default full-auto
|
||
policy. It does not add `--always-approve`: permission decisions remain under
|
||
the selected ACPX policy. Grok's ACP metadata cannot independently establish
|
||
Paperclip tool authority, so explicitly selecting `approve-paperclip` or
|
||
`approve-reads` returns the approval-required outcome; `deny-all` rejects requests.
|
||
Full auto does not bypass Paperclip's company permissions, governed approvals,
|
||
or execution-environment boundaries. Isolated ask
|
||
rules override project allow rules, and compatible always-approve settings are
|
||
locked off. Compatible hook/MCP discovery and shell login capture are disabled.
|
||
|
||
## Installation and identity
|
||
|
||
Grok support ships inside the native runner and the public Paperclip server npm
|
||
artifact. There is no separate Grok npm package, binary payload, or npm lifecycle
|
||
download. The built-in launcher is identified as `builtin:grok-acp` version 1;
|
||
its native runtime identity is `native:grok` version 1.0.13. The historical
|
||
`agentServerPackage`/`agentRuntimePackage` wire fields carry these identities,
|
||
not npm dependencies. Existing npm-backed ACP bridges retain their package pins.
|
||
|
||
Provision Grok Build 1.0.13 at
|
||
`/opt/paperclip/providers/grok/1.0.13/grok` in the selected execution environment.
|
||
The sandbox provisioning helper is explicit and is never run by npm:
|
||
|
||
```sh
|
||
sudo node packages/paperclip-runner/scripts/provision-grok.mjs /opt/paperclip/providers/grok/1.0.13/grok
|
||
```
|
||
|
||
The standard Daytona image provisions it separately from the provider pack.
|
||
Custom images and local execution hosts must provide the same prerequisite.
|
||
The runner verifies the native executable checksum before credential refresh or
|
||
ACP startup; a missing prerequisite reports the required path and version.
|
||
Only macOS arm64 and Linux x64 are qualified. No ambient `grok` from PATH is used.
|
||
ACP must report the requested exact model; mismatches fail closed.
|
||
|
||
The distribution identity change deliberately rejects resume bindings from the
|
||
former private-package profile. Start a fresh session after upgrading that
|
||
unreleased profile; do not silently reinterpret its saved identity.
|
||
|
||
Instructions use Grok ACP session rules. Assigned skills live in the isolated
|
||
Grok home. Steering and goals are unsupported. Token and cost values remain
|
||
unknown when Grok does not report them; missing usage is not zero usage.
|
||
|
||
## Authentication
|
||
|
||
Use the existing Grok company connection/login flow for subscription execution.
|
||
An explicitly selected company-secret `XAI_API_KEY` selects paid API execution.
|
||
There is no automatic subscription-to-API fallback. Remote execution cannot
|
||
borrow the operator's home credentials. Local execution can use the operator's
|
||
existing Grok login when no company login has been selected.
|
||
|
||
Only the selected credential is staged in the private runtime home. An ownership
|
||
lease fences concurrent processes. Before ACP startup, an expiring subscription
|
||
credential is refreshed through the verified Grok executable’s non-inference
|
||
`models` command. This bounded step suppresses output and prevents Grok 1.0.13
|
||
from caching a pre-refresh model list. Exact model verification still precedes
|
||
any prompt; refresh failure requires reconnecting Grok Build. After the provider exits, refreshed credentials
|
||
are copied back through Grok's existing identity and refresh checks. Runtime
|
||
credentials, refresh handoffs, and diagnostic logs are excluded from workspace
|
||
backups and removed on close. Session history remains available for resume. Host
|
||
configuration, other provider credentials and unselected keys are not forwarded
|
||
to Grok.
|
||
|
||
## Evaluation
|
||
|
||
The private `paperclip-evals` repository maintains `live-acpx-grok-4.7.json` and
|
||
`rosters/live-acpx-grok.json`. The roster covers all 39 protocol cases. Its campaign
|
||
lane remains disabled pending complete live qualification.
|
||
|
||
Product E2E exposes `runner-acpx-grok` in core local/Daytona compatibility and
|
||
local session integrity. The explicit `grok-qualification` suite covers replies,
|
||
planning approvals, structured questions, downloadable project revisions, stop/resume
|
||
and continuation after controller restart
|
||
in both environments. Run with `--suite grok-qualification`; it is excluded from
|
||
scheduled `--all`. Use the canonical Product E2E dashboard and Evalbook reports.
|
||
|
||
The separate `grok-subscription-qualification` suite covers the same workflows
|
||
with the explicit `GROK_AUTH_JSON` fixture credential. It seeds only the disposable
|
||
company's private login home and supplies no API key. It does not exercise the
|
||
interactive sign-in UI. Authentication mode remains part of the profile identity.
|
||
After a subscription upgrade, a fresh `grok login` may be needed if the existing
|
||
login still reports the previous entitlement through ACP.
|
||
|
||
`packages/paperclip-runner/scripts/grok-native-smoke.mjs` records explicit auth,
|
||
model/binary identity, MCP outcome, durable resume and restrictive permissions.
|
||
Pass `--auth subscription --auth-file /private/path/auth.json --output /private/report.json`
|
||
or `--auth api --output /private/report.json` with an explicitly supplied key.
|
||
Each attempt is retained; unknown usage and cost are null.
|
||
|
||
Qualification requires the full protocol roster, selected product workflows,
|
||
subscription and API execution locally and on Daytona, and three successful
|
||
repetitions of core tool, approval and resume cases. Deterministic tests or a
|
||
single successful browser task do not establish that qualification.
|
||
|
||
## Remote verification
|
||
|
||
Do not run Docker on a developer laptop when using remote verification. The
|
||
`Docker Runner check` workflow offers maintainer-authorized manual Linux image
|
||
builds and broad source checks without provider credentials. It records the
|
||
source revision, resolved lock digest and immutable image reference. Paid
|
||
Product E2E remains behind the protected default-branch workflow and environment.
|
||
|
||
The public npm consumer check uses a digest-pinned, unprivileged container with
|
||
no checkout or credentials mounted. It downloads dependencies with lifecycle
|
||
scripts disabled and freezes the resulting consumer lockfile. It completes the
|
||
clean install with offline `npm rebuild`, running the deferred lifecycle hooks
|
||
without re-resolving bundled optional dependencies. Networking stays disabled,
|
||
the lockfile must remain unchanged, and a sentinel proves scripts actually ran.
|
||
The pinned image includes native build tools and local Node headers so dependency
|
||
hooks can compile without network access. Both executable admission probes run
|
||
in the same isolation. The verification user provisions Grok inside the disposable
|
||
test directory without privilege elevation or host `/opt` changes. Only the
|
||
positive probe mounts that binary read-only at the canonical sandbox path.
|
||
|
||
|
||
The Cloud application image also carries the controller-owned provider pack and
|
||
sets `PAPERCLIP_RUNNER_REMOTE_PROVIDER_PACK_PATH`. Remote ACPX execution verifies
|
||
the sandbox against that pack before using it, or stages the matching pack when
|
||
needed. The Cloud controller image does not install the native Grok executable;
|
||
the selected sandbox image must provide the prerequisite above.
|
||
Cloud builds must supply the full source SHA through `PAPERCLIP_BUILD_COMMIT`
|
||
to produce that verified pack. Unstamped local Cloud builds still work for other
|
||
features, but omit the pack and cannot start remote ACPX sessions.
|