0 Fork 0

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

Files

T

Dotta 560e7e48b5 feat(runner): add SDK and developer tooling (#12608 )

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The runner package already provides the production protocol and
execution spine.
> - Contributors still need stable SDK surfaces, deterministic test
tools, and local inspection tools.
> - Those surfaces share generated contracts and must change as one
package boundary.
> - This pull request adds the package-local SDK, labs, examples, and
drift checks.
> - The benefit is a reviewable developer platform that does not change
application execution selection.

## Linked Issues or Issue Description

**Subsystem affected**

`packages/paperclip-runner` — runner SDK, conformance tools, and
developer tooling.

**Problem or motivation**

The production runner spine is present, but package consumers cannot
build deterministic integrations, inspect sessions, or verify
provider-neutral behavior through supported surfaces.

**Proposed solution**

Add browser, React, standalone, live-session, scenario, conformance, and
evaluation surfaces. Add generated contract inventories and
package-local verification scripts. Keep production application routing
unchanged.

**Alternatives considered**

We considered splitting each generated catalog, SDK surface, and demo
into separate pull requests. Those changes share exports, fixtures, and
drift gates. Splitting them would create intermediate package states
that do not build.

**Roadmap alignment**

No overlapping item appears in `ROADMAP.md`. This work extends the
runner package that is already on `master`.

## What Changed

- Add browser, React, standalone, live-session, and issue-thread SDK
surfaces.
- Add deterministic mock control-plane, scenario, conformance, replay,
and evaluation tools.
- Add bounded Codex, OpenCode, and ACPX development transports and
fixtures.
- Keep deferred managed-provider execution fail-closed. Persisted
compatibility data remains readable.
- Add generated capability inventories with their source files and drift
checks.
- Add examples, package documentation, browser checks, and
clean-consumer checks.
- Preserve the reviewed protocol bounds, replay compatibility aliases,
process environment isolation, and semantic redaction limits.
- Update the ACPX package patch that the existing workspace patch
registry already tracks.
- Do not change `pnpm-lock.yaml`, repository workflows, server runtime
selection, or the application UI.

## Verification

GitHub Actions is the verification authority for this pull request. The
repository CI, package TypeScript and Rust checks, package tests,
generated-output drift checks, browser checks, security scans, and
Greptile review must pass on the exact head.

Local test suites were not run because this series uses parallel GitHub
Actions for verification.

## Risks

This is a large greenfield package change. The main risks are public
export drift, generated-output drift, and optional React consumer
compatibility. Package boundary checks, clean-consumer checks, and
browser tests cover those risks. Production adapter selection and server
execution are outside this pull request.

## Stack

1. **This PR:** runner SDK and developer tooling.
2. [Codex production server
integration](https://github.com/paperclipai/paperclip/pull/12616).
3. [Provider-neutral task-thread
UI](https://github.com/paperclipai/paperclip/pull/12617).

## Model Used

OpenAI Codex, GPT-5, high-reasoning mode, with tool use and code
execution.

## 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 described the issue in-PR following the feature request
template
- [x] I have not referenced internal/instance-local Paperclip issues or
links
- [x] My branch name describes the change and contains no internal
Paperclip ticket id
- [ ] 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 risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

2026-08-31 21:33:11 -05:00

5.4 KiB

Raw Blame History

SDK: Run the SDK Console and Mini Consumer

What this phase is

SDK makes the accepted browser tracer reusable. It has a browser client, a React hook, reusable components, one reference console, and one small second consumer.

The two apps use public package imports. They do not import the old demo UI. Provider credentials stay in the local server.

The reference console starts in Regular chat mode. Type a message in the composer to create a direct Codex session. Open Protocol inspector to see the event stream and reducer state. Select another flow only when you want a deterministic protocol fixture.

What this phase proves

This tutorial proves that a second app can use the SDK without a private import. It also proves that live events and replay events reduce to the same state. You can run every hard state with the fake driver. You can then run a safe turn with your real local Codex login.

Run commands from the repository root.

1. Run the small SDK tests

pnpm --filter @paperclipai/paperclip-runner test:sdk
pnpm --filter @paperclipai/paperclip-runner check:browser-tokens
pnpm --filter @paperclipai/paperclip-runner check:forbidden-imports

These tests check reducer parity, components, tokens, and package boundaries.

2. Open both apps with the fake driver

pnpm --filter @paperclipai/paperclip-runner console:sdk

Open these pages:

http://127.0.0.1:4181/reference-console/
http://127.0.0.1:4181/mini-consumer/

The page header shows 🖇️ v0.1.2. Use this marker to confirm this iteration.

The fake driver is the default. It does not need a provider login.

3. Check the reference console

Use the manifest list. Run these flows:

Run Completion. Read the streaming and terminal messages.
Expand a Terminal row, then expand Debug details. Confirm the folded section contains canonical event metadata and provider payloads for the command without leaving the chat transcript. Assistant text should reveal progressively. For a real Codex semantic completion, read the clear summary first and expand Debug payload to inspect the exact structured JSON.
Run Same-turn steering. Type a new message while the turn is active. The button says Steer. Check the acknowledgement.
Run each interrupt flow. Confirm that the visible outcome names the race.
Run Command and file approvals. Resolve one request. Confirm that the card locks after the first click and later shows the canonical result.
Run Goal lifecycle. Set and clear the goal from the Goal menu.
Press Drop connection. Watch reconnect and gap recovery use the same session.
Enter replay. Step with Left and Right. Confirm the inspector says the replay matches live state.
Run Item and turn failure. Confirm that the exact server diagnostic is part of the transcript.

The clear response is a presentation of canonical provider output, not a second result model. The raw event stream remains in Protocol inspector.

Resize the browser to 390 by 844. Chat and the composer must remain the primary view. Open Menu to reach session controls, the protocol inspector, and replay. The app must not create a second hidden transcript or a horizontal page scrollbar.

4. Check the mini consumer

The mini app is intentionally small. Run a turn, steer it, stop it, resolve a request, set and clear a goal, drop the connection, and enter replay.

Look for these proof points:

Mini renderer shows the custom item-body renderer.
Mini detail shows the custom request-detail renderer.
Set goal and Clear goal use the two Composer slots.
The blue accent is a local --pcr-* token override.
Fetch and EventSource are injected by the app.
Replay parity: match appears after durable history is complete.

If the real driver says goals are unavailable, the two goal buttons stay disabled. This is correct. The SDK must not pretend the provider supports a feature.

5. Run the browser acceptance tests

On a machine with Playwright system libraries:

pnpm --filter @paperclipai/paperclip-runner test:browser:sdk

On a minimal Debian or Ubuntu machine without root access:

cd packages/paperclip-runner
bash scripts/verify-rootless-linux.sh pnpm run test:browser:sdk

This runs keyboard, accessibility, reconnect, gap-recovery, replay, fake driver, viewport measurement, and screenshot checks.

6. Run a real Codex session

Use a machine where the local Codex CLI is already authenticated.

cd packages/paperclip-runner
bash scripts/verify-rootless-linux.sh pnpm run record:sdk:codex

The test runs a safe completion through both public consumers. It checks that the browser contains no bearer token or auth.json path. The mini consumer then drops and reconnects the transport, enters replay, and confirms parity.

Real provider timing is not used to prove every race. The deterministic fake driver proves steering, interrupt, requests, and goal branches. The real run proves the same public transport and identity boundary against Codex.

7. Run the package acceptance command

pnpm --filter @paperclipai/paperclip-runner verify

Use verify:rootless if the host needs package-local browser libraries.

Expected result

All commands exit with status 0. The fake and real apps use public imports. Reconnect keeps run, session, and provider identity. Replay reports match. Provider credentials do not appear in browser state, DOM text, events, or diagnostics.

5.4 KiB Raw Blame History