DottaandPaperclip
1cc45086d3
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Several people can send instructions to the same agent and task. > - A fixed GitHub token in the provider process can keep the first person's access after another person's message is accepted. > - Task ownership cannot select credentials for each accepted instruction or preserve the identity of an operation already in progress. > - This pull request records ordered execution identity contexts and resolves credentials when managed Git, gh, or GitHub tools start. > - The benefit is automatic personal GitHub access for shared agents, with durable continuation rules and no teammate credential fallback. ## Linked Issues or Issue Description **Subsystem affected** Cross-cutting: orchestration, connection grants, database, runtime adapters, native runners, and run details. **Problem or motivation** A shared agent must use the person whose instructions it has accepted. A queued message must retain its author. A retry or approval without new instructions must retain the originating identity. GitHub must remain optional for ordinary work. **Proposed solution** Persist execution identity separately from task ownership. Give new processes a run-scoped broker capability and token-free managed launchers. Capture identity at operation start. Keep an explicit dedicated-agent grant as an override. Show redacted diagnostics in run details. **Alternatives considered** Per-task ownership, fixed provider tokens, and mutable repository author configuration do not handle accepted steering or concurrent operations. A manual account-selection action would add unnecessary setup to each turn. **Roadmap alignment** This completes the existing Multiple Human Users, MCP Tool Gateway & Apps, Secrets Manager, and Self-healing Runs capabilities. The implementation follows the maintainer-approved plan. Related work: Refs #12843, Refs #12907. Existing proposals #4618 and #8945 cover per-agent or per-worktree author configuration. This change instead follows the accepted human instruction across runtime types. Refs #11831 for governed personal connection delegation; this change preserves connection audience checks and does not use standing delegation as a personal credential fallback. ## What Changed - Add durable, ordered identity contexts and active run references. Preserve message authors through consolidation, steering, retries, delegation, approvals, routines, and restart. - Add an authenticated operation-time GitHub credential broker and local/remote managed git and gh launchers. Keep personal tokens out of the long-lived provider process. - Resolve GitHub gateway and server-side Git operations through the same responsible-person or dedicated-grant selection rules. - Make absent and unavailable GitHub credentials non-blocking at generic startup. Clear host and prior-person credentials. Keep anonymous Git access where supported. - Add run-detail identity history and the dedicated-account warning. Keep task ownership and queue-versus-steer decisions unchanged. - Preserve personal OAuth declarations through connection edits. Retain exact selected grants in the gateway. - Fix continuation races found during real acceptance: verify a warm owner before credential rotation, and wait for bounded durable runner suspension before the next run starts. - Make migrations replay-safe. Retain identity through agent/run deletion, remove it with its company, and clean terminal launcher directories before releasing execution environments. Document coordinated release and rollback. ## Verification - Full workspace typecheck, build, and token gates passed. The complete local suite passed in its normal test groups: 17,120 passing tests, including all 143 serialized server suites. After integrating the newly merged runner API work, full local typecheck and build passed again, along with 890 focused integration tests. All 31 checks on the integrated revision passed, including build, browser E2E, release registry, canary dry run, typecheck, security and all test suites. Greptile is 5/5 with all review threads resolved. - Current focused checks passed: 142 native executor tests, 67 runtime lifecycle tests, 9 durable identity tests, 75 credential/routine tests, 19 low-trust/resumption tests, and the executable migration replay test. - Authenticated browser acceptance with two Paperclip users and two GitHub accounts on one shared native agent passed. Real commits and pushes followed A → B accepted steering → queued A continuation in the same saved conversation. GitHub commit author and committer identities matched all three operations. Both runs succeeded and task ownership stayed unchanged. - Real GitHub MCP calls switched from A to B after accepted steering. A delegated subtask retained its originating identity across a server restart. - Disabling B's GitHub connection left ordinary work successful. Managed gh was unauthenticated and the provider had no inherited GH_TOKEN or GITHUB_TOKEN. - The browser displayed run-detail diagnostics and the exact dedicated-account warning. A final controller-restart check followed by another-person continuation retained the conversation, selected the correct GitHub login and Git author, and removed each terminal launcher directory. - Company-lifetime migration and all five previously failing CI suites passed locally (167 tests). Same-token gateway A → B → A and six broker/launcher boundary tests passed. - Remote callback, launcher, sandbox, and runtime contract tests passed. Both native and legacy Codex completed actual Daytona executions on the integrated revision ([campaign results](https://github.com/paperclipai/paperclip/actions/runs/34155056509)). The remote package-manager shim staging regression also passed locally. ## Risks - Deploy the migrations, server broker, launchers, and runner artifacts together. Existing processes finish with their original contract. New managed processes need the broker endpoint for GitHub operations. - Finish or stop new managed executions before rolling application code back. Keep the additive schema and identity history during rollback. - Scripts that require a persistent raw GH_TOKEN must use managed git, gh, or GitHub gateway tools. Run capabilities authorize code executing within that run to acquire its current identity; this is not hostile-code isolation within one execution principal. Managed commands prevent automatic credential carryover; arbitrary code deliberately copying a credential is outside that boundary. - Uncertain steering acknowledgement deliberately holds new credential acquisition until reconciliation. Already-started operations retain their captured identity. - GitHub private access and provider outages can still fail the specific operation that needs them. Dedicated grant failure does not fall back to personal access. ## Model Used OpenAI GPT-6 through Codex assisted implementation, review, shell execution, and browser acceptance. The exact model variant and context-window size are not exposed in this session. Tool use included TypeScript and Rust tests, database integration tests, GitHub CLI, and authenticated browser control. ## 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>
Paperclip Native Runner
This package is the standalone development boundary for Paperclip's native
runner protocol, process supervision, durable transport, provider drivers, and
normalized session backends. Rust owns the production runner under runner/;
TypeScript provides the control-plane reference, browser SDK, scenario tools,
and conformance oracle.
The package includes one coherent set of capabilities: PRP v1 validation and replay, a supervised local runner with a scripted fake harness, durable WebSocket delivery and recovery, qualified Codex, OpenCode, ACPX, Claude Managed, and AWS AgentCore drivers, live session and issue-thread surfaces, a public browser/React SDK, a standalone adapter demo, and a deterministic mock control plane. None of these surfaces imports or starts Paperclip's server, UI, CLI, or production database.
Public package surfaces
@paperclipai/paperclip-runner— production contracts, clients/backends, PRP validation/replay, canonical catalog/dispatcher, and compatibility check.@paperclipai/paperclip-runner/testing— deterministic mocks plus PRP and semantic conformance kits. Tests and external conformance consumers import this explicitly.@paperclipai/paperclip-runner/evals— versioned native-attempt metadata, fail-closed package/binary compatibility checks, and explicit runnerd artifact resolution for eval consumers.
The package root has no mock or scenario exports. Generic credential-free
matrix orchestration lives in the workspace-private
@paperclipai/paperclip-eval-kernel; scenario content and provider-backed eval
campaigns remain outside the runtime package.
See ADR 0001.
The two conformance surfaces intentionally prove different contracts. The
existing runControlPlanePortConformance suite checks narrow PRP run/event
persistence. CAPABILITY_HIGH_RISK_SEMANTIC_VECTORS and
runSemanticConformanceKit compare normalized tool authorization, state,
effects, audit, retries, conflicts, redaction, continuation, and terminal
decisions. The production adapter stays App-owned and invokes Paperclip's real
route/service authorities; it does not copy those rules into this package.
Quick start
The package also builds paperclip-runner-acpx-sidecar. This bounded v2
stdin/stdout bridge admits the pinned Claude and Codex ACPX profiles. It
validates the exact model, session identity, tool catalog, structured input,
and terminal settlement at the process boundary. Pi remains unavailable.
Runnerd selects only qualified provider profiles. Claude Managed and AWS AgentCore receive immutable company-profile snapshots with explicit retention, spend, and invocation limits. No provider process receives a Paperclip API credential or unrestricted server environment.
Claude Managed resolves its API key from the company secret bound to the selected profile. AWS AgentCore uses workload identity only; long-lived static AWS access keys are intentionally removed from the runner environment.
The Rust core includes a bounded client for the sidecar protocol. It enforces request identity, event order, frame and queue limits, timeouts, redacted diagnostics, and process-group cleanup. Runnerd selects this package-local transport only through an exact qualified provider descriptor.
Before a later provider adapter consumes a valid sidecar event, the Rust core also requires its optional or mandatory run and turn scope to match the active execution. Process and diagnostic events can remain global. All operational, tool, input, permission, and terminal events require the exact active binding.
A package-local payload boundary decodes events only after that scope check. It validates control identities, terminal status, question sets, and the admitted runtime event types and bounded fields. It redacts diagnostic and retained event values again before they can enter provider state.
Validated ACPX runtime events normalize into the same provider-neutral activity families as the direct Codex transport. Reasoning contents stay private. Tool targets are resolved within the workspace under the provider host's path semantics and receive a versioned sidecar boundary marker before becoming bounded, display-only PRP safe paths. Raw or unmarked provider locations fail closed. URI-scheme and Windows drive-shaped values require a separate sidecar attestation backed by an existing in-workspace entry or, for a not-yet-created edit target, an existing in-workspace parent. This preserves real POSIX colon filenames without treating arbitrary URI text as a path. Windows separators are canonicalized, and consumers must not reinterpret the display value as file-access authority. Operational semantic-result and terminal events remain reserved for the stateful adapter rather than being duplicated.
The ACPX provider reducer preserves that order while it tracks one active turn, bounded assistant text, semantic results, and pending tool or input correlations. Terminal events flush the final assistant message first and clear unresolved turn-scoped requests.
The package-local session bootstrap starts the bounded sidecar transport, verifies the qualified capability handshake and effective model, opens one identity-bound session, and confirms its run attachment. Any failed bootstrap terminates the process; session shutdown preserves persistent provider state. The session can then start one immutable-workspace turn, request interruption, and reduce polled events through the scope-first state boundary. A mismatched command acknowledgement or invalid event terminates the session fail closed. Polled semantic calls pass through the run-scoped authorized tool bridge before they can be returned to a caller. Before a follow-up turn releases settled tool receipts, runner-core suspends and reaps the idle sidecar/provider generation, then resumes the same verified persistent identity in a fresh generation. This prevents a late session-lifetime MCP callback from inheriting the next turn's event authority.
The Rust question-response validator checks the versioned response envelope against the exact persisted question IDs, answer modes, options, required answers, custom-answer policy, and text constraints before provider delivery. Tool results and structured question responses then use two-phase resolution: validate retained identity and schema, require the exact sidecar acknowledgement, and only then clear pending local state. Codex permission requests violate its pinned sidecar policy and terminate the session fail closed. Safe suspension is available only with no active turn or pending request. The sidecar must return the exact persistent session identity before runnerd terminates the local process. Already validated ACPX reducer events project into provider-neutral durable events only with an exact run, session, turn, and item binding. Raw sidecar envelopes and permission requests are not admitted at this boundary. A safely suspended session can be recorded as a bounded private checkpoint. The checkpoint binds the exact provider identity, run, catalog revision, and catalog digest and is replaced atomically before a later recovery attempt. Recovery releases the stored identity only after those bindings match the prospective session configuration exactly.
Run the complete contract gate with:
pnpm install --filter @paperclipai/paperclip-runner --lockfile=false --offline --ignore-scripts --dev
pnpm --filter @paperclipai/paperclip-runner verify
The verification command requires a stable Rust toolchain with cargo on
PATH, in addition to Node.js 24.11+ and pnpm 9+.
Minimal Debian/Ubuntu hosts without root access can extract the required Playwright browser libraries into a user-owned cache and run the same acceptance sequence with:
pnpm --filter @paperclipai/paperclip-runner verify:rootless
The tracer's final line is stable:
{
"schemaVersion": "paperclip.runner.conformance.output.v1",
"runIdentity": {
"runId": "run_conformance_0001",
"sessionId": "session_conformance_0001"
},
"result": {
"status": "succeeded",
"summary": "Standalone Conformance fixture accepted."
}
}
Run only the tracer with:
pnpm --filter @paperclipai/paperclip-runner trace:conformance
Replay the Replay happy path, run a Local session, or open the browser devtool:
pnpm --filter @paperclipai/paperclip-runner replay:fixture
pnpm --filter @paperclipai/paperclip-runner trace:local-runner -- --scenario happy-path
pnpm --filter @paperclipai/paperclip-runner trace:codex
pnpm --filter @paperclipai/paperclip-runner demo:live-console -- --host 127.0.0.1 --port 4174
# Live console: chat with a live session in the browser.
pnpm --filter @paperclipai/paperclip-runner console:live-console
pnpm --filter @paperclipai/paperclip-runner browser:dev --host 127.0.0.1 --port 4179
# SDK: open the public-SDK reference console and mini consumer.
pnpm --filter @paperclipai/paperclip-runner console:sdk
# Standalone: run the standalone legacy/native/kill-switch tracer and page.
pnpm --filter @paperclipai/paperclip-runner trace:standalone
pnpm --filter @paperclipai/paperclip-runner trace:standalone -- --feature-flag enabled
pnpm --filter @paperclipai/paperclip-runner trace:standalone -- --feature-flag enabled --kill-switch enabled
pnpm --filter @paperclipai/paperclip-runner demo:standalone
Live console provider-backed routes are loopback-only and reject wildcard/LAN
binds. Browser mutations require same-origin Fetch Metadata, matching Origin,
and JSON content; see the protocol-server tutorial for direct curl examples.
Direct live protocol qualification
The canonical direct live protocol suite lives in the separate
paperclip-evals repository under evals/paperclip-runner/. Its
live-mini.json roster is the complete 35-case Codex qualification lane. Build
this package's TypeScript output, release paperclip-runnerd, package tarball,
and dist-issue-thread viewer, then use the roster runner documented in that
repository. The package ships the required orchestration entry point as
paperclip-runner-eval-session (dist/cli/eval-session.js). Evalbook owns the
consistent HTML matrix and read-only attempt drill-down pages.
The hosted full-campaign workflow, parallel matrix, credential boundaries,
canonical report merge, and versioned S3 index are documented in
docs/runner-protocol-live-evals.md.
This direct protocol qualification is separate from the stress-derived Runner workflow schedule below and from the full-stack browser model E2E suite.
Stress-derived workflow, chaos, and AWS AgentCore operations
The deterministic workflow scorer and the chaos schedule do not require provider credentials:
pnpm --filter @paperclipai/paperclip-runner test:runner-workflow-evals
pnpm --filter @paperclipai/paperclip-runner report:runner-chaos-evals
report:runner-live-evals is a paid, provider-backed command. Native Codex and
the ACPX Codex profile require OPENAI_API_KEY; ACPX Claude requires
ANTHROPIC_API_KEY; OpenCode candidates require OPENROUTER_API_KEY. The live
matrix admits no Pi profile and does not persist credential values. Set
PAPERCLIP_EVAL_MAX_CAMPAIGN_COST_USD to a positive finite number to bound
additional scheduling after the observed campaign total reaches that value:
PAPERCLIP_EVAL_MAX_CAMPAIGN_COST_USD=12 \
PAPERCLIP_EVALS_ROOT=/path/to/paperclip-evals \
pnpm --filter @paperclipai/paperclip-runner report:runner-live-evals
# Run two scheduled native Codex executions only.
PAPERCLIP_EVALS_ROOT=/path/to/paperclip-evals \
pnpm --filter @paperclipai/paperclip-runner report:runner-live-evals -- \
--candidate codex-luna --limit 2
GitHub-hosted live campaigns additionally require the default branch, an
allowlisted numeric actor ID, the protected runner-e2e-paid environment, and
an explicit repository variable before scheduled runs are enabled. Manual
dispatches accept the same candidate, case, and execution-limit selectors. The
paid job uses the reviewed RunsOn Fleet label when RUNNER_E2E_AWS_ENABLED=true
and otherwise stays on ubuntu-latest. Uploaded reports contain redacted
observations and trace digests, not raw provider
frames, prompts, credentials, tool arguments, or hidden reasoning.
The AgentCore proof-of-concept uses an AWS CLI v2 profile to provision a
dedicated invocation role and scoped resources. Its local mode-0600 metadata
file contains no access keys; probes assume short-lived STS credentials and
clear them after use. Validate locally, provision or inspect the stack, run the
bounded lab/smoke, and tear it down explicitly with:
pnpm --filter @paperclipai/paperclip-runner test:aws-agentcore-provisioning
pnpm --filter @paperclipai/paperclip-runner aws-agentcore:provision -- --dry-run
pnpm --filter @paperclipai/paperclip-runner aws-agentcore:provision
pnpm --filter @paperclipai/paperclip-runner aws-agentcore:probe
pnpm --filter @paperclipai/paperclip-runner aws-agentcore:lab
pnpm --filter @paperclipai/paperclip-runner smoke:capability:aws-agentcore
pnpm --filter @paperclipai/paperclip-runner aws-agentcore:destroy -- --yes
To admit the hosted direct-eval workflow, provision with the account-local GitHub Actions OIDC provider and keep the default exact repository and protected environment binding:
pnpm --filter @paperclipai/paperclip-runner aws-agentcore:provision -- \
--aws-profile paperclip-dev \
--github-oidc-provider-arn arn:aws:iam::<account-id>:oidc-provider/token.actions.githubusercontent.com
This adds only repo:paperclipai/paperclip:environment:runner-e2e-paid as a
web-identity subject on the scoped invocation role. The generated nonsecret
profile records that role as both the local invocation role and the hosted
execution role.
Provisioning can incur Bedrock, AgentCore Runtime/Memory, storage, and private
networking charges. Provisioning refuses to modify a colliding stack unless its
Paperclip ownership tags and template description match. A verified
ROLLBACK_COMPLETE stack still requires --replace-failed-stack plus an
interactive confirmation (or --yes) before it can be deleted and recreated.
Destruction requires --yes and refuses to remove a stack with an active
recorded lab unless --force is also supplied.
Package-owned commands
| Command | Purpose |
|---|---|
build |
Compile the TypeScript public surface, Rust workspace, and browser devtool. |
typecheck |
Check TypeScript, Rust, generated schema sources, and browser types. |
test |
Run Rust/TypeScript fixture, supervisor, fake-driver, live/replay, and boundary tests. |
check:forbidden-imports |
Reject TypeScript imports and Cargo path dependencies that cross into Paperclip core. |
check:tracked-imports |
Reject tracked imports and package.json entry points that only resolve against untracked files, so a clean checkout of any commit builds. |
check:numbered-milestones |
Reject numbered construction-milestone names in tracked package paths and source. |
check:package-boundaries |
Enforce the acyclic runtime/testing/eval dependency and manifest boundary. |
check:clean-consumers |
Pack the runner and install its root, evals, and testing exports in a clean consumer. |
test:eval-slice |
Run the credential-free eval bundle, scoring, and behavior/fault slice. |
test:runner-workflow-evals |
Run the deterministic provider-neutral workflow matrix. |
report:runner-workflow-evals |
Validate deterministic fail-closed results and write JSON, Markdown, JUnit, and GitHub-safe reports. |
report:runner-live-evals |
Execute the paid provider schedule and render its immutable attempts with the canonical paperclip-evals HTML grid. |
report:runner-chaos-evals |
Write the credential-free eight-scenario chaos schedule. |
test:aws-agentcore-provisioning |
Validate the AgentCore template and wrapper safety contracts without provisioning. |
aws-agentcore:provision / probe / lab / destroy |
Manage the scoped AgentCore proof-of-concept lifecycle. |
smoke:capability:aws-agentcore |
Exercise the qualified AgentCore profile through the capability harness. |
check:conformance-parity |
Require byte-for-byte equivalent Rust and TypeScript tracer output. |
check:replay-goldens |
Require all reducer snapshots and cross-language summaries to match checked goldens. |
check:replay-parity |
Run TypeScript and Rust against the same Replay fixture summaries. |
check:browser-tokens |
Reject component-local visual literals and require the standalone token layer. |
docs:validate |
Validate local documentation links. |
trace:conformance |
Run the Rust mock-core tracer, print the stable result, and exit. |
trace:conformance:typescript |
Run the TypeScript reference tracer directly. |
replay:fixture |
Validate and reduce a fixture to a final snapshot. |
trace:local-runner |
Run one native local session through the Rust runner and fake harness. |
trace:codex |
Run the mock core with a real, local skillless Codex app-server session. |
demo:live-console |
Start the package-local HTTP/SSE server with server-only Codex authentication. |
console:live-console |
Start the standalone browser devtool with the Live console on 127.0.0.1:4180. |
console:sdk |
Start the public-SDK reference console and mini consumer on 127.0.0.1:4181. |
test:sdk |
Run targeted browser-client, reducer-projection, and React component contract tests. |
test:browser:sdk |
Exercise both consumers with the fake driver, keyboard/a11y checks, reconnect/replay, measurements, and screenshots. |
record:sdk:codex |
Run both public consumers against a safe real Codex session and capture live screenshots. |
check:capability-contract |
Verify the generated capability, legacy MCP, and eval traceability contract. |
check:semantic-contracts |
Verify the provider-neutral semantic tool contract is current. |
trace:live-runner |
Run the real runnerd/Codex semantic loop against the mock control plane. |
demo:scenarios |
Start the Capability scenario explorer over the mock control plane on 127.0.0.1:4183. |
console:issue-thread |
Start the Paperclip-style issue thread on 127.0.0.1:4184. |
test:scenarios |
Run the scenario index, run-artifact, parity, explorer component, and route tests. |
test:browser:scenarios |
Exercise both the scenario explorer and issue-thread browser contracts. |
browser:dev |
Start the standalone live/replay browser devtool. |
test:browser |
Exercise static replay and live scenarios, then capture temporary screenshots under ignored test output. |
verify |
Run the complete deterministic Conformance through SDK acceptance sequence. |
verify:rootless |
Extract Debian/Ubuntu browser libraries without root, then run verify. |
Navigate
- Architecture and dependency boundary
- ADR 0001: runner and testing package boundaries
- Tutorial index
- Conformance hand-run tutorial
- Replay hand-run tutorial
- Local runner hand-run tutorial
- Local protocol reference
- Durable transport reference
- Codex skillless Codex tutorial
- Codex skillless Codex driver reference
- Live console protocol/server tutorial
- Live console protocol/server reference
- Live console tutorial
- Live console reference
- SDK console tutorial
- SDK browser SDK reference
- SDK component decision record
- Capability semantic catalog and authorization
- Capability live runnerd/Codex loop
- Capability issue-thread UI
- PRP compatibility/versioning policy
- Adding a harness and permission-mode requirements
- PRP v1 expressiveness audit
- Cumulative end-to-end tutorial
Codex adds the package-local real-model reference driver, Live console adds the package-local browser console, and SDK extracts a reusable public SDK plus two standalone consumers. Runtime production Paperclip integration remains deferred; the App-owned production conformance adapter is test-only.
The SDK reference console opens in direct chat mode. Enter a normal prompt,
then open the protocol inspector to review events and reducer state. Expand a
Terminal row and its nested Debug details disclosure to inspect every
canonical event retained for that command. The header marker 🖇️ v0.1.2
identifies the current console iteration.