Skip to content

Export the dev-runtime provider protocol types (start context, session, inspection envelope, generation store, MCP registry) from agent-bundle/api #485

Closed

Description

@ScriptedAlchemy

Problem

dev.runtime.provider is a documented configuration key (website/docs/en/reference/configuration.mdx:153) and agent-bundle/api exports the provider entry type — DevRuntimeProvider, CreateDevRuntimeProvider, AgentBundleDevRuntimeConfig (packages/agent-bundle/src/api.ts:245-249). But a provider cannot be written against that export alone: every type the start() contract hands in or expects back — the start context, the session, the inspection envelope, the MCP server descriptor, the generation store and MCP registry a session must drive — lives only in packages/agent-bundle/src/dev/**. The one example that implements a provider therefore reaches into the package source with ../../../../packages/agent-bundle/src/dev/* imports, which contradicts the "public exports only" rule for examples/* and means no out-of-tree consumer can implement dev.runtime.provider with types at all.

This is distinct from #459 (what a context provider receives at request time); this issue is about the dev-runtime provider protocol behind dev.runtime.provider.

Evidence

All import sites are in examples/rsc-agent-runtime on main (after #473 moved JsonObject/JsonValue to the root export and DevRuntimeProvider to agent-bundle/api; the rest have no public home):

Source module Names reached only through packages/agent-bundle/src/dev/** Import sites
dev/runtime-provider.ts DevRuntimeStartContext, DevRuntimeSession, DevRuntimePreparedProject, DevRuntimeEventInput, DevRuntimeClientSurfaceEndpoint, DevRuntimeMcpSession, DevRuntimeMcpSessionCloseObservation, DevRuntimeUnavailableError, DevRuntimeGenerationConflictError src/dev/rsbuild-runtime-session.ts:57-67, src/dev/generation-materializer.ts:19, tests/generation-materializer.test.ts:31; src/dev/provider.ts now derives DevRuntimeStartContext as Parameters<DevRuntimeProvider['start']>[0] to avoid the deep import
dev/runtime-protocol.ts DevRuntimeAsset, DevRuntimeAssetRequest, DevRuntimeDescriptor, DevRuntimeDiagnostic, DevRuntimeFixture, DevRuntimeInspectionEnvelope, DevRuntimeInvocationRequest, DevRuntimeMcpConnectionState, DevRuntimeMcpRegistryReconcileInput, DevRuntimeMcpServerDescriptor, DevRuntimeMcpSessionBinding, DevRuntimeReplayRequest, DevRuntimeRun, DevRuntimeStateIdentity, DevRuntimeStateResetRequest, DevRuntimeStatus, DevRuntimeSurface, DevRuntimeTraceSpan, DevRuntimeTreeNode, RuntimeVector src/dev/rsbuild-runtime-session.ts:68-86, src/dev/serialize-inspection.ts:3-7, src/runtime/contracts.ts:2-5, src/dev/generation-materializer.ts:20
dev/runtime-generation-store.ts RuntimeGenerationStore (class), RuntimeGeneration, RuntimeGenerationActivationGuard, RuntimeGenerationAsset, RuntimeGenerationCandidate, RuntimeGenerationManifestInput, RuntimeGenerationMetadataCodec, RuntimeGenerationPreparedActivation, RuntimeGenerationValidationInput src/dev/rsbuild-runtime-session.ts:43-49, src/dev/generation-materializer.ts:22-31, tests/generation-materializer.test.ts:30, tests/environment-checkpoint-store.test.ts:21
dev/runtime-mcp-registry.ts RuntimeMcpRegistry (class), RuntimeMcpConnection, RuntimeMcpConnector, RuntimeMcpExecutionContext, RuntimeMcpPreparedActivationReconcile src/dev/rsbuild-runtime-session.ts:50-56
dev/index.ts, dev/epoch-store.ts, dev/runtime-provider-loader.ts, core/digest.ts (test-only) ProjectService, ArtifactService, EpochStore, resolveDevRuntimeProvider, digest, stableJson tests/dev-provider.integration.test.ts:8-13, tests/dev-invocation.integration.test.ts:14, tests/generation-materializer.test.ts:29

The example's README already labels itself "an architecture experiment, not an agent-bundle public API", so it does not block anything today; it does mean the dev.runtime.provider key is documented without a typed way to satisfy it.

Proposed shape

Export the provider protocol from agent-bundle/api, next to DevRuntimeProvider:

  1. Types the DevRuntimeProvider contract references transitively (everything a provider must accept or return): the runtime-provider.ts and runtime-protocol.ts rows above, as export type. These are already the wire/session protocol the Workbench consumes, so exporting them is a naming decision, not a new surface.
  2. The two error classes DevRuntimeUnavailableError and DevRuntimeGenerationConflictError as values — a provider has to throw them to get the documented Workbench behaviour.
  3. RuntimeGenerationStore and RuntimeMcpRegistry as values plus their option/candidate types. If keeping the classes internal is preferred, DevRuntimeStartContext should instead hand a provider pre-constructed store/registry instances so a provider never needs to import them.
  4. Leave ProjectService, ArtifactService, EpochStore, resolveDevRuntimeProvider, digest, stableJson internal; they are reached only from the example's tests, which can move to the agent-bundle/test dev-epoch level (runDevEpochContractMatrix) or stay deep-import as test-only wiring.

TypeDoc compiles packages/agent-bundle/src directly, so the api reference page follows automatically; the pnpm docs:site:build gate applies.

Acceptance

  • import type { DevRuntimeStartContext, DevRuntimeSession, DevRuntimeInspectionEnvelope, DevRuntimeMcpServerDescriptor, /* … */ } from 'agent-bundle/api' resolves, and import { DevRuntimeUnavailableError, DevRuntimeGenerationConflictError } from 'agent-bundle/api' resolves.
  • examples/rsc-agent-runtime/src/** contains no packages/agent-bundle/src path import (rg "packages/agent-bundle/src" examples/rsc-agent-runtime/src is empty); the four src/dev/*.ts and src/runtime/contracts.ts files import from agent-bundle/api instead.
  • The public-API declaration test (packages/agent-bundle/tests/public-api.test.ts / public-api-packed.test.ts) covers the new names, and website/docs/{en,zh}/reference/configuration.mdx dev.runtime.provider links to the agent-bundle/api types a provider implements.
  • A changeset (patch) names the new agent-bundle/api exports.

Found while auditing the examples against the public surface in #473.

Activity

  1. added 5 commits that reference this issue on Sep 4, 2026
    6df6128
    424f29a
    9dd0c06
    b170732
    b2f0cbc
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestmeta-frameworkAgent Bundle compiler-coupled meta-framework

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions