Generate an Agent Bundle framework test harness on top of Rstest

[ScriptedAlchemy]

Summary

Agent Bundle already uses Rstest extensively inside its own repository. The
missing product feature is a generated, consumer-facing harness that understands
compiled routes, Agent Document rendering, MCP/CLI/script projections, browser
Apps, host artifacts, and the framework's dev/build lifecycle.

Make framework testing a first-class compiler output rather than requiring every
plugin author to reconstruct internal entrypoints or protocol clients.

The current examples show the gap at two levels:

• Audiobook Curator runs bare rstest tests, so it receives no generated
  framework-aware project configuration or route helpers.
• the full RSC runtime example carries a manual rstest.config.ts with its own
  include glob, serialized worker pool, Node environment, time scaling, and
  expanded timeout for real Rsbuild compiles and child processes.

Those are valid repository tests, but plugin authors should not have to learn or
copy that setup merely to test an Agent Bundle project.

Existing capabilities to preserve

The repository already has:

• Rstest unit and integration configurations;
• Rslib-aware compilation support;
• Rstest browser and React integration;
• Playwright-backed browser tests;
• real MCP client/server wire tests;
• packed-consumer and deleted-source artifact tests;
• Workbench and MCP App browser tests;
• native host smoke gates.

This issue packages and generates the useful framework boundaries for consumer
projects. It does not replace the repository's test infrastructure.

Goals

1. Let consumers test routes without importing generated implementation details.
2. Test the same compiled route graph used by build and development.
3. Make final documents and streaming render events directly assertable.
4. Provide real MCP, CLI, script, browser-App, and packed-artifact harnesses.
5. Make target capability and host artifact regressions visible before release.
6. Keep unit tests fast while preserving explicit end-to-end proof levels.

Proposed public surface

Agent Bundle supplies an Rstest integration and generated test module:

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

export default defineConfig({
  plugins: [agentBundleRstest()],
});

V1 ships agent-bundle/rstest and agent-bundle/test as explicit subpath
exports of the existing package with Rstest as an optional peer. A separate
package is unnecessary until dependency or release-boundary evidence requires
one.

Tests import stable framework helpers rather than source registries:

import {
  renderRoute,
  invokeMcpTool,
  invokeCli,
  runScript,
} from 'agent-bundle/test';

it('renders a bounded inventory result across MCP and CLI', async () => {
  const route = await renderRoute('mcp:curator:inventory', {
    source: fixtureRoot,
  });

  expect(route.final).toMatchAgentDocumentSnapshot();
  expect(route.events).toMatchAgentRenderSequence([
    'shell',
    'progress',
    'replace',
    'complete',
  ]);

  const mcp = await invokeMcpTool('curator', 'inventory', {
    source: fixtureRoot,
  });
  expect(mcp.structuredContent).toEqual(route.final.value);

  const cli = await invokeCli(['inventory', fixtureRoot, '--output', 'json']);
  expect(JSON.parse(cli.stdout)).toEqual(route.final.value);
});

Test levels

1. Route unit harness

• loads the compiled route contract;
• injects test capabilities, filesystem roots, environment, clock, and
  cancellation;
• renders through the real Agent renderer;
• captures shell/progress/patch/error/complete events;
• never opens a transport or builds host artifacts.

2. Projection contract harness

• offers an official SDK in-memory client/server mode for fast protocol
  contract proof and labels it in-memory;
• separately invokes the packed generated MCP server through a subprocess/stdio
  transport for process, stdout, and lifecycle proof;
• invokes the generated CLI dispatcher with captured stdout/stderr;
• executes plain and rendered scripts;
• compares final meaning across projections without requiring byte-identical
  presentation.

3. Browser harness

• compiles each MCP App or Workbench surface through its exact production-owning
  Agent Bundle/Rsbuild compiler function;
• mounts them through Rstest browser/React facilities;
• tests accessibility, bridge contracts, consent, resource binding, and render
  stream presentation;
• uses Playwright only where a real browser process or navigation boundary is
  required.

4. Artifact harness

• builds the package through the real Agent Bundle compiler;
• installs or copies the packed output into a clean consumer;
• reports packed-tarball install and copied-artifact proof as distinct modes;
• deletes project source where applicable;
• validates manifests and provenance;
• exercises CLI, MCP, scripts, Apps, and selected native host layouts.

These levels must remain visibly separate. A route-unit pass is not an artifact
or host-integration receipt.

Compiler coupling

The compiler generates a test manifest alongside the route manifest:

interface AgentBundleTestManifest {
  routes: Readonly<Record<string, TestableRouteDescriptor>>;
  projections: Readonly<Record<string, ProjectionDescriptor>>;
  apps: Readonly<Record<string, BrowserAppDescriptor>>;
  targets: readonly string[];
  artifactExpectations: ArtifactExpectationSet;
}

The Rstest integration consumes this manifest to configure transforms, aliases,
test environments, generated types, and fixture lifecycles. Consumer tests do
not manually reproduce Rslib or Rsbuild configuration.

Generated fixtures and capabilities

Framework fixtures should provide:

• isolated project and output roots;
• strict environment allowlists;
• fake clocks only when the route explicitly receives a clock capability;
• bounded child-process fixtures;
• real AbortSignal cancellation;
• deterministic MCP client/server pairs;
• render-event collection with size/rate enforcement;
• explicit target capability fixtures for text, image, audio, resources, and
  progress without pretending unsupported content is accepted;
• explicit browser origin and bridge setup;
• disposable packed-consumer directories.
• request-context provider fixtures with explicit identity provenance;
• production-driver conformance fixtures for optional durable state;
• native event projection fixtures that never claim to be host dispatch;
• notice delivery and receipt fixtures with supported/unavailable routes;

No fake transport or in-memory artifact may be presented as end-to-end proof.
Each helper states the proof level it supplies.

Matchers

Proposed matchers:

expect(document).toMatchAgentDocumentSnapshot();
expect(events).toMatchAgentRenderSequence([...]);
expect(result).toSatisfyMcpResultContract();
expect(artifact).toContainDeclaredRoute('mcp:curator:inventory');
expect(projections).toHaveEquivalentFinalValue();

Snapshots must preserve semantically important structure without pinning noisy
generated identifiers, timestamps, or bundler implementation details.

Failure diagnostics

Failures should report:

• route identity and source;
• config and generated-manifest provenance;
• active projection and target;
• last render event and boundary;
• captured stdout/stderr/logs with byte bounds;
• cancellation/timeout state;
• packed artifact path when relevant;
• a direct command for rerunning the narrow failing layer.

Migration and delivery

1. Extract stable helpers from existing internal Rstest suites without weakening
   their assertions.
2. Generate a test manifest from the new route compiler.
3. Ship route-render and event-stream harnesses first.
4. Add MCP/CLI/script projection helpers.
5. Add Rsbuild browser-App support.
6. Add packed/deleted-source consumer helpers.
7. Convert public examples to the consumer harness.
8. Update create-agent-bundle templates with one route test and one compiled
   projection test.

Acceptance criteria

• A scaffolded project runs useful framework-aware Rstest tests without copying
  Agent Bundle's internal build setup.
• Route tests use the real compiler contract and real Agent renderer.
• Fast MCP tests cross the official SDK in-memory transport, and process-level
  MCP tests separately cross the packed subprocess/stdio boundary.
• Browser tests compile through the same Rsbuild profile used by production.
• Artifact tests prove behavior after source deletion.
• Audio and other non-text content is projected only when the target capability
  fixture advertises support; fallback and fail-closed paths are both tested.
• Failure output identifies route, projection, target, and provenance.
• The harness never labels a fixture or in-memory substitute as packed,
  transport, browser, or host proof.

Design references

• Current Agent Bundle Rstest configuration
• Current RSC example's manually maintained Rstest configuration
• Current packed-release integration tests
• Rstest configuration conventions
• Rstest real-browser mode
• Rsbuild Environment API

Stack position

• Core route/render harness depends on: #93 routes, #95 context/providers, and #96 RSC renderer.
• State, event, notice, CLI/script, host-component, and lifecycle issues add
  their own conformance modules to this stable harness contract.
• #104 worktree-proximity depends on those modules and is the first
  cross-process composition proof.

Full meta-framework stack

• Foundations: #93 routes - #94 identity - #95 context - #96 renderer
• Runtime: #97 events - #98 state - #99 notices
• Host: #100 components - #101 lifecycle
• Surfaces and proof: #102 CLI/scripts - #103 Rstest - #104 proximity example - #105 Workbench