Repository navigation
Export the dev-runtime provider protocol types (start context, session, inspection envelope, generation store, MCP registry) from agent-bundle/api #485
Description
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:
- Types the
DevRuntimeProvidercontract references transitively (everything a provider must accept or return): theruntime-provider.tsandruntime-protocol.tsrows above, asexport type. These are already the wire/session protocol the Workbench consumes, so exporting them is a naming decision, not a new surface. - The two error classes
DevRuntimeUnavailableErrorandDevRuntimeGenerationConflictErroras values — a provider has to throw them to get the documented Workbench behaviour. RuntimeGenerationStoreandRuntimeMcpRegistryas values plus their option/candidate types. If keeping the classes internal is preferred,DevRuntimeStartContextshould instead hand a provider pre-constructed store/registry instances so a provider never needs to import them.- Leave
ProjectService,ArtifactService,EpochStore,resolveDevRuntimeProvider,digest,stableJsoninternal; they are reached only from the example's tests, which can move to theagent-bundle/testdev-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, andimport { DevRuntimeUnavailableError, DevRuntimeGenerationConflictError } from 'agent-bundle/api'resolves.examples/rsc-agent-runtime/src/**contains nopackages/agent-bundle/srcpath import (rg "packages/agent-bundle/src" examples/rsc-agent-runtime/srcis empty); the foursrc/dev/*.tsandsrc/runtime/contracts.tsfiles import fromagent-bundle/apiinstead.- The public-API declaration test (
packages/agent-bundle/tests/public-api.test.ts/public-api-packed.test.ts) covers the new names, andwebsite/docs/{en,zh}/reference/configuration.mdxdev.runtime.providerlinks to theagent-bundle/apitypes a provider implements. - A changeset (
patch) names the newagent-bundle/apiexports.
Found while auditing the examples against the public surface in #473.
Activity
feat(api): export the dev.runtime.provider protocol from agent-bundle…
feat(api): export the dev.runtime.provider protocol from agent-bundle…
feat(api): export the dev.runtime.provider protocol from agent-bundle…
feat(api): export the dev.runtime.provider protocol from agent-bundle…
feat(api): export the dev.runtime.provider protocol from agent-bundle…