feat(routes): generate typed provider declarations and augment the runtime (#95)

[ScriptedAlchemy]

Summary

Closes the last open #95 acceptance item — "a project-defined provider adds a typed context property without compiler modification" — and the delivery step "generates the augmented context type".

• @agent-bundle/runtime: AgentProviderValues becomes an augmentable interface (readonly [key: string]: unknown plus the optional framework-owned processLifetime, exported as AgentProcessLifetime). Runtime behavior is unchanged.
• agent-bundle typegen: .agent-bundle/routes.d.ts now declares AgentBundleProviders, ProviderKey, and ProviderValue<Key> from each conventional src/providers/* factory's awaited return type (camel-cased keys, in the exact order generated scopes execute them) and augments @agent-bundle/runtime so (await agent()).providers.<key> is typed with no cast. Provider-free graphs emit no augmentation (never references a module the project has no reason to depend on); a graph with providers but no executable routes keeps the file instead of deleting it.
• Examples: worktree-proximity and audiobook-curator providers adopt the public AgentProviderContext type from agent-bundle instead of hand-rolled local interfaces (the worktree provider now narrows the discriminated invocation union).
• Docs: docs/framework-mode.md gains a "Request context and providers" section (same context on every surface, provider contract, AB4940–AB4942, typegen + tsconfig include, test fixture seam); docs/diagnostics.md records the provider declarations beside the route typegen contract. Changeset: @agent-bundle/runtime minor, agent-bundle minor.

Evidence

• packages/agent-bundle/tests/route-graph.test.ts — new "generates provider declarations and the runtime augmentation in execution order" (deterministic output, key-ordered imports, exact augmentation block) and the existing typegen test now pins that provider-free graphs emit no provider surface. 33/33.
• packages/agent-bundle/tests/provider-typegen.test.ts (new, integration pool) — real inspect() publishes the declarations for a two-provider project, then a TypeScript program against the built @agent-bundle/runtime declarations proves ProviderKey, ProviderValue<'library'>, and (await agent()).providers.library/.buildNumber/.processLifetime?.hits type-check with no casts, undeclared keys stay unknown, and assigning providers.library to number is rejected ("Type 'LibraryContext' is not assignable to type 'number'"). 1/1.
• After rebase onto ccb9cd18a: pnpm typecheck green, pnpm lint 0/0, pnpm test:projection 63/63, pnpm test:route-unit 35/35, targeted integration (provider-typegen, cli-routes-build, worktree-proximity-journeys, generated-route-server, state-packaging) all green.
• pnpm test:unit: 2665 passed, 2 failed — mcp-probe-service teardown timing and native-claude-contract 5s timeout; both reproduce identically on pristine origin/main under load average >120 (stash A/B), unrelated.

Test plan

• typegen unit + program-level integration proof
• typecheck, lint, projection, route-unit
• CI

[changeset-bot]

🦋 Changeset detected

Latest commit: 324819d

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

This PR includes changesets to release 2 packages

Name	Type
@agent-bundle/runtime	Minor
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-03T05:41:18.183806Z	e9e923c	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.

[pkg-pr-new]

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle@382

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@382

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/@agent-bundle/runtime@382

commit: e9e923c

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e9e923caf2

ℹ️ 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".

[chatgpt-codex-connector]

Do not require providers in contexts where they can be omitted

When the generated declaration is included, this required member merges globally into AgentProviderValues, but AgentRequestInit.providers remains optional and runAgentRequest converts an omission to {} (packages/rsc-runtime/src/agent-request.ts:184,415). Consequently, a custom invocation or renderRoute test can omit provider fixtures while (await agent()).providers.library is still typed as present, leading to an unchecked undefined dereference at runtime. Make generated keys optional for such contexts, or distinguish generated scopes from contexts that do not install providers.

Useful? React with 👍 / 👎.

[ScriptedAlchemy]

Agreed — addressed in follow-up #409 (2d1cd86). Rather than weakening handler types, the contexts that do not run providers now carry the obligation: once the generated augmentation adds required keys to AgentProviderValues, AgentRequestInit.providers (AgentRequestProvidersInit), the harness options argument (HarnessOptionsArguments) and context (RenderRouteContextInit) become required in that program. provider-typegen.test.ts proves omitting providers, a declared key, or the options argument is a compile error while a complete custom scope typechecks; provider-free projects and generated scopes are unchanged.

[ScriptedAlchemy]

Fixed on main by #409 (62138ef, the #95/#100 follow-up lane): harness and test contexts that do not run providers now require the provider fixtures the augmentation declares, and docs/framework-mode.md/docs/entry-conventions.md document the contract; #408 had only clarified the docs and dropped that change in favour of #409 during rebase.