feat(test): route-unit consumer test harness (#103 stage 1)

[ScriptedAlchemy]

Closes the stage-1 slice of #103: route modules can now be tested without building an artifact.

Shipped

agent-bundle/rstest — agentBundleRstest(options?) returns a plain Rstest configuration object (thin defineConfig input; no plugin surface yet):

import { defineConfig } from '@rstest/core';
import { agentBundleRstest } from 'agent-bundle/rstest';

export default defineConfig(await agentBundleRstest());

It runs one compiler pass — the same ProjectService.prepare() the build and inspect use, which owns route-graph compilation — and projects that graph into a test manifest. No second compile, no artifact build. The manifest and per-route loaders are written to a generated setup module under the project's gitignored .agent-bundle/test/, so the bundler transforms the route .tsx modules the same way the build does.

agent-bundle/test — renderRoute(routeId | module, { input, args, context, limits, progress, signal }) executes a route through the runtime's public final-only Flight dispatcher (#144) and request store (#113) and resolves to the final Agent Document (#140), the ordered render events, the resolved provenance, and the resultSchema-parsed value. expectDocument(...) matchers: toHaveStatus, toContainMarkdown, toContainText, toHaveValue, toHaveError, toHaveNodeKinds. testManifest() exposes the compiled route inventory so per-route assertions iterate in process. Every failure names the route id, target kind, module, project root, and route-graph digest.

Proof level discipline. One level ships, labeled route-unit in the manifest, in every provenance record, and in the failure text. No placeholders for the transport, packed, or browser levels.

Packaging. @agent-bundle/runtime, @rstest/core, and react are optional peers. The existing packed boundary test now asserts a skills-only consumer installs none of them (and that no directory for them exists on disk); its tree walk previously counted unmet optional peers as installed, which is fixed here. Declaring the peers is also what keeps them external in the published bundle — before this, dist/ vendored a 410 KB copy of the Flight server whose bundler-injected RSC manifest was not the consumer project's, which is exactly how the audiobook adoption test failed until the peer was declared.

Pools. The level needs Node's react-server condition, a per-process flag, so it runs as its own pool (pnpm test:route-unit, built from the shipped helper) and the workspace pools exclude tests/route-unit/**. No new build or pack is added to any pool; the adoption example reuses the single examples:check build.

Adoption proof

• examples/audiobook-curator/tests/route-unit/routes.test.ts renders the migrated prompt:curator/curate route (feat(routes): migrate audiobook curator to public authoring #150) with renderRoute and asserts status, text, and structured value, plus the manifest compile with no build. 2 tests.
• packages/agent-bundle/fixtures/route-harness/ is the framework's own fixture project (tool, event, resource, app routes) driving 10 route-unit tests: context overrides, progress capture, refused kinds, unknown routes, render errors, and result-schema rejection.

Stage-1 follow-ups (deliberately not here)

• In-memory MCP transport, packed-artifact, and browser proof levels (Generate an Agent Bundle framework test harness on top of Rstest #103 later stages).
• Event-stream matchers (assertions today read the final document; the events are returned but unmatched).
• A real Rstest plugin surface, alias/environment plumbing beyond the react-server condition and JSX runtime, and any docs beyond the README section.
• Broader audiobook coverage: only the prompt route is asserted; the 15 tool routes need fixture roots or fakes for their filesystem and ffprobe operations.

Scoped results

• pnpm test:unit — 141 files, 1972 tests, 0 failures
• pnpm test:route-unit — 10 passed
• examples/audiobook-curator: pnpm test:routes — 2 passed; pnpm test 35 passed; pnpm typecheck clean
• rsc-runtime-optional-packaging (packed) — 1 passed
• public-api (integration, loads every public subpath) — 7 passed
• pnpm lint, pnpm typecheck, pnpm lint:package (publint x3) — clean

[changeset-bot]

🦋 Changeset detected

Latest commit: c34feb3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
agent-bundle	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-01T08:49:46.431001Z	7b07c9d	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7b07c9d237

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".