Summary

• Problem: hot reply, tool, outbound, media, provider, TTS, and command paths still have many opportunities to rediscover runtime facts that are already known earlier in the request, such as selected provider, model, channel, target, capability family, or attachment class.
• Why it matters: repeated request-time rediscovery makes the reply path harder to reason about, encourages broad plugin/provider/channel registry scans, and creates pressure to add scattered cache layers instead of moving canonical runtime facts earlier.
• What changed: this PR adds the prepared-runtime foundation: reusable contracts, carrier fields, and producers for provider runtime handles, agent runtime plans, scoped model references, outbound channel runtime facts, and TTS/speech runtime facts.
• What did NOT change: this PR does not migrate existing reply/tool/outbound consumers yet, does not remove legacy resolver behavior, and does not introduce the gateway-runtime loaded registry lookup. That follow-up belongs to the startup loaded/public metadata PR tracked in Tracking: Prepared runtime resolution migration #77700.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Related Tracking: Prepared runtime resolution migration #77700
• This PR fixes a bug or regression

Details

This is PR 1 in the prepared runtime resolution migration.

It introduces the shared vocabulary and typed objects that later, smaller migration PRs can consume without each surface inventing its own cache or compatibility wrapper:

• AgentRuntimePlan gains prepared-runtime slots for auth, prompt, tools, transcript, delivery, outcome, transport, and observability.
• buildAgentRuntimePlan(...) produces a reusable plan around the selected provider/model/runtime facts.
• ProviderRuntimePluginHandle carries the selected provider plugin once so provider hook helpers can reuse it.
• Provider hook helpers accept an existing runtime handle while preserving fallback behavior for callers that do not have prepared facts yet.
• Scoped model helpers collect configured model references without broad model catalog work.
• Outbound channel runtime helpers expose prepared channel facts and bundled outbound adapter support.
• TTS/speech SDK contracts gain the runtime types needed by later loaded-speech migrations.
• AGENTS.md now names the request-time rediscovery rule directly: if a hot path already knows the provider/model/channel/target/capability/attachment fact, pass that fact forward instead of broad-loading registries to rediscover it.

The important architectural line is that this PR is foundation-only. Existing callers can still omit prepared facts. Later PRs will migrate one surface at a time to consume these objects, prove the prepared path is used, and then remove duplicate lookup branches only when their last migrated caller no longer needs them.

Real behavior proof (required for external PRs)

N/A. Maintainer-authored internal refactor foundation; no user-facing runtime path is migrated in this PR.

Root Cause (if applicable)

• Root cause: repeated runtime lookup work has been spread across request-time consumers because there was no shared, canonical object for carrying already-known provider/model/channel/tool/runtime facts through the reply path.
• Missing detection / guardrail: root guidance did not clearly distinguish prepared facts from broad request-time rediscovery, so new code could reasonably call broad loaders even when the request already knew the exact fact.
• Contributing context: compatibility fallback behavior is still needed for startup, setup, admin, standalone, and legacy callers, so the migration needs additive foundation before consumer behavior can move safely.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/agents/runtime-plan/build.test.ts
• Scenario the test should lock in: the runtime plan exposes stable defaults, provider runtime handle reuse, tool schema hooks, transcript policy, transport extra params, and delivery helpers without requiring existing callers to pass prepared facts.
• Why this is the smallest reliable guardrail: this PR is a foundation PR, so the useful boundary is the plan producer and its default behavior rather than a full reply-path migration.
• Existing test that already covers this (if any): N/A.

User-visible / Behavior Changes

None. This PR adds foundation contracts and guidance only. Existing runtime consumers continue to work through their current paths.

Diagram (if applicable)

Before:
[selected provider/model/channel known] -> [later consumer broad-loads registry again] -> [uses one fact]

After this PR:
[selected provider/model/channel known] -> [prepared runtime object can carry fact] -> [later PRs consume it]

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: Linux
• Runtime/container: Node 22 / pnpm
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): N/A

Steps

1. pnpm docs:list
2. pnpm test src/agents/runtime-plan/build.test.ts
3. pnpm build
4. git diff --check

Expected

• Runtime-plan tests pass.
• Build passes.
• Diff hygiene is clean.

Actual

• Runtime-plan tests passed.
• Build passed.
• git diff --check passed.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Evidence is the local targeted test/build proof above. The earlier standalone PR1 build failure from referencing the later gateway-runtime surface was resolved by keeping PR1 scoped to existing loaded surfaces and tracking the gateway-runtime handle lookup for PR2.

Human Verification (required)

• Verified scenarios: runtime-plan unit coverage, full build, diff hygiene, PR branch contains exactly the foundation commit plus changelog/AGENTS guidance.
• Edge cases checked: existing callers can omit prepared facts; resolveProviderRuntimePluginHandle(...) does not require the later gateway-runtime surface in this PR; unrelated dirty system-prompt local files are not committed.
• What you did not verify: live Gateway reply benchmark, because this PR does not migrate the live reply path yet.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: later migration PRs may accidentally depend on a reusable field or helper not present in this foundation.
  • Mitigation: AGENTS.md now documents the prepared-runtime rule, and Tracking: Prepared runtime resolution migration #77700 tracks each migration surface. Missing reusable contracts should move into this foundation before later PRs consume them.
• Risk: reviewers may expect this PR to improve request-time performance directly.
  • Mitigation: the scope is explicit: this PR introduces the reusable objects only. Consumer migration and performance proof happen in later PRs.