Files
PaperClipAI/packages/paperclip-runner
DottaandPaperclip f2c5e54dca fix(runner): preserve handoff work and publish requested files (#13355)
## Thinking Path

> - Paperclip lets people manage AI agents and their tasks.
> - A task keeps its instructions, progress, and files when its assigned
agent changes.
> - The replacement runner lost the interrupted run's context and could
overwrite an existing draft.
> - A saved message also stayed attached to the former agent and could
reopen the task after the replacement finished.
> - File tasks could report Done with only a local path that the user
could not open.
> - This pull request transfers handoff context and saved messages, and
makes requested files accessible through the existing attachment
contract.
> - Users can change agents and collect completed work without repeating
instructions or confirming bookkeeping.

## Linked Issues or Issue Description

Refs #13338. Builds on merged #13354 for queue admission and #13353 for
remote workspace retry. #10123 concerns restricted recovery-model
escalation; this change instead covers ordinary native handoff and file
completion.

**What happened?**

Codex wrote a draft before a user assigned the task to Claude. The
replacement lacked continuation context and replaced the draft. A queued
user message could later restart the former agent and reopen the
completed task. Separately, a runner could finish a requested file but
return only a machine-local path. Remote native runs had no bound file
publication tool.

**Expected behavior**

The replacement reads and preserves existing work, receives saved
messages once, and keeps each message's author. The former agent stays
stopped. A requested file has a working attachment or accessible work
product before Done. Text-only tasks do not require attachments.

**Steps to reproduce**

1. Ask Codex to save three newsletter names and then wait.
2. Queue an instruction to keep those names and expand the draft.
3. Use Interrupt and assign to select Claude.
4. Verify the original names survive, the result has a working download,
and only the source and replacement runs exist.
5. Ask either provider for a Markdown checklist and open the file from
its completed response.

## What Changed

- Carry the exact same-task interrupted run's summary, semantic
receipts, and history into handoff context. Tell the replacement to
inspect existing files before editing.
- Adopt saved ordinary task comments into the successor's receipt under
the task lock. Preserve authors and separate mention, chat, and
interaction contracts.
- Prevent a former-assignee comment wake from reopening a completed task
or starting a stale execution.
- Reject workspace-only, fabricated, and cross-task file completion
references with actionable runner feedback. New file output also needs a
matching current-run publication receipt and asset filename/size/hash,
or an accessible work product registered by the current run. Prior
output can remain context alongside a current file, or be verified and
re-registered internally. Authorized chat attachment reuse retains its
verified current-run clone receipt; older receipt shapes require an
intact matching source.
- Bind remote file reads to the active environment runner and reuse the
existing attachment and work-product publication path.
- Enforce workspace confinement, regular single-link files, stable
identity, a 10 MiB limit, and exact size and SHA-256 checks. Rotate the
native session fingerprint for the updated tool contract.
- Contain rejected remote signals and protocol-failure cleanup,
including logging failures. Preserve the original cleanup rejection for
its owner; a rejected operation never supplies stop acknowledgement or
cleanup proof.
- Allow exactly one maximum-size base64 file through the native SSH
command adapter, preserving a finite output cap.
- Document handoff and accessible file completion rules.

## Verification

- Each observed bug has a failing regression before its fix. Final
post-rebase integration passed 732 tests across 13 files before the
final receipt and signal guards; final affected results are below.
- Publication provenance and compatibility: 8 provenance regressions and
2 compatibility regressions failed before their fixes; the final four
affected suites pass 53 tests, including mixed old/new references and
real authorized chat reuse. Controls cover old attachments and work
products, filename/size/hash/origin mismatch, missing/wrong receipts,
current-run publication, same-run durable proof, internally
re-registering preserved bytes, and no-new-file follow-ups.
- Remote signal rejection: the real Node subprocess previously exited 1
when the production launcher signalled a deleted sandbox. It now stays
alive for both a failed signal and failed logging; all 349 executor
tests pass. The failed signal still provides no termination proof.
- Remote file reader and SSH command boundary: 33 tests passed,
including real Linux descriptor reads and the actual SSH adapter
subprocess output cap (network executable replaced by a deterministic
fixture). Exact 10 MiB bytes pass, one byte beyond the encoded cap
fails.
- Live local Claude and Codex Stop journeys preserve the saved file,
deliver queued instructions once, and reach Done with two total runs.
The handoff journey preserves the original names and download with
exactly two runs. Both local providers deliver exact checklist files
without a completion confirmation.
- Live combined Daytona verification passed: the original failed task's
Retry reused its sandbox; a selected Git subfolder produced an exact
downloadable file; warm and deliberately resumed Claude runs took about
33 seconds. Codex produced a 240-byte download in 33.1 seconds after 134
seconds of contention/backoff. Both cloud downloads retained exact bytes
after the two owned sandboxes were deleted.
- The sandbox-deletion retest identified a separate ignored promise in
protocol-failure cleanup. Two real Node subprocess regressions failed
under fatal unhandled-rejection policy before the fix; all 36 protocol,
lifecycle, and integrity tests now pass. The original close promise
still rejects to its owning runtime. The final live retest passed: a
normal Claude Daytona task completed in 132.352 seconds, then its
sandbox was deleted. Thirteen samples over 361 seconds confirmed the
same controller stayed healthy, the task stayed Done with unchanged run
IDs, and its attachment retained exact bytes. The post-deletion browser
download passed with zero page errors; all five owned sandboxes are
confirmed absent.
- Full repository typecheck and build passed on final commit
`de64d16f1`. Final-head Greptile is 5/5 with no unresolved threads.
[Final-head
CI](https://github.com/paperclipai/paperclip/actions/runs/34736623758)
passed: 32 successful checks and two conditional skips. The earlier
mixed-source full local test invocation was deliberately stopped before
rebase, so no pristine green full local aggregate is claimed. Its known
failures passed in later affected suites.

## Risks

- Handoff may adopt only ordinary comments from its validated former
owner. Other delivery contracts must remain independent.
- File verification fails closed if a remote file changes during
reading. The runner must retry publication or explain a blocker.
- The updated session fingerprint starts a fresh provider process where
needed to install the new tool contract.
- No schema migration or historical status reconciliation is included.

## Model Used

OpenAI `gpt-6-astra` through Codex, with reasoning, code execution,
browser testing, and tool use. The context-window size is not exposed in
this task.

## 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>
2026-09-13 08:41:20 -05:00
..

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

Native provider debug-trace correlation uses an incremental index owned by its transport. Pending event lookups read only newly appended bytes, with a 1 MiB read budget per lookup; they retry until the observed suffix is indexed. Partial records remain pending, and trace replacement or truncation invalidates the index. Closing a transport clears its index. Other active transports cannot evict its progress. Records over 64 KiB are skipped by the correlation index without buffering or parsing their full contents; the original trace file retains them. Do not restore a full synchronous trace scan for each pending event: it blocks event delivery and can leave the board showing an active run after the provider turn has already ended.

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

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.