Tracking Issue: Prepared Runtime Resolution Migration

Summary

This issue tracks a staged migration to stop hot request paths from rediscovering runtime information that is already known earlier in the request.

Today, reply, tool, outbound, media, provider, TTS, and command paths can still call broad resolver machinery at request time. Those resolvers may load or scan plugin/provider/channel/runtime registries to answer questions the request already knows, such as:

• Which provider is selected.
• Which model is selected.
• Which channel is handling the reply.
• Which outbound target/channel is being used.
• Which capability family is needed.
• Which plugin/runtime facts were already loaded at startup.

The migration replaces repeated request-time rediscovery with prepared runtime facts: small typed objects produced once, carried through request context, and consumed by the exact surface that needs them.

Problem

Request-time rediscovery has several costs:

• It makes hot reply/tool paths do unnecessary work.
• It can accidentally load broader plugin/provider/channel families than the request needs.
• It makes behavior harder to reason about because resolution happens late and in many places.
• It increases the chance that one known provider/channel/model path observes unrelated configured providers, plugins, or fallback behavior.
• It makes tests rely on broad registry setup instead of the actual fact the path needs.

The target shape is explicit:

• Prepare provider/channel/model/tool/capability facts once.
• Pass those facts through typed request/runtime context.
• Make hot consumers use the prepared fact directly.
• Keep compatibility fallback behavior only where it is intentionally needed for legacy, setup, startup, standalone, admin, or other non-hot callers.

Key Terms

• Old resolver machinery: request-time calls that load, scan, or resolve broad plugin/provider/channel/capability state even though the caller already knows the relevant provider, model, channel, target, or capability family.
• Prepared runtime fact: a small typed value created earlier in the request that contains exactly the runtime information a later consumer needs.
• Producer: code that creates a prepared runtime fact.
• Consumer: code that uses a prepared runtime fact instead of rediscovering it.
• Surface: a coherent group of files that use the same kind of runtime fact.
• Compatibility fallback: old behavior that remains available only for callers that do not have prepared runtime context yet.

Invariant

If a path already knows the provider, model, channel, capability family, target, or attachment class, it must consume prepared runtime facts and must not broad-load plugin/provider/channel/capability registries to rediscover that fact.

Compatibility fallbacks are allowed only when they are explicit, documented, tested, and not used by migrated hot reply/tool/outbound paths.

Rollout Rules

1. PR 1 is the only prerequisite. Open PR 1 against main and merge it first.
2. After PR 1 lands, every later PR must be created from current main and must target main.
3. PRs 2 through 13 must be mergeable in any order after PR 1. They must not depend on another migration PR being open, merged, or reviewed first.
4. Each file belongs to exactly one PR in this rollout.
5. A PR may edit only files in its own scope.
6. If a later PR needs a reusable type, producer, context field, or adapter from a file owned by another PR, the reusable piece belongs in PR 1, or the PR boundary must be redefined.
7. If one file contains changes for multiple concerns, split the hunks before creating the PR. A file must still appear in only one PR.
8. Code cleanup that becomes safe because of a migration belongs in the same PR that removes the last use. Do not put cleanup in a later PR if that would make the cleanup PR depend on another migration PR.
9. Do not add unrelated dead-code cleanup. Cleanup must be caused by this prepared-runtime migration.
10. Every migration PR must include CHANGELOG.md.
11. AGENTS.md belongs to PR 1 only.
12. MIGRATE.md, PREPARED-RUNTIME-PR-SPLIT-PLAN.md, PREPARED-RUNTIME-TRACKING-ISSUE.md, and docs/reference/request-time-runtime-resolution.md are local planning/reference artifacts and must not be committed in any migration PR.
13. Every migration PR must include tests proving the prepared path is used.
14. Every migration PR must include proof that the migrated prepared path does not call broad resolver machinery.

Tracking Checklist

• PR 1: Prepared runtime foundation - refactor(runtime): add prepared runtime foundation #78248
• PR 2: Startup loaded/public runtime metadata - refactor(plugins): expose loaded runtime metadata #79198
• PR 3: Provider runtime handles and auth
• PR 4: Embedded runtime plan and attempt orchestration
• PR 5: Scoped model catalog resolution
• PR 6: Tool planning and skill snapshots
• PR 7: Scoped media capability resolution
• PR 8: Loaded TTS and speech runtime
• PR 9: Outbound channel runtime consumers
• PR 10: Reply channel runtime handoff
• PR 11: Prepared reply command metadata
• PR 12: Agent command and session tool delivery
• PR 13: Channel action tool runtime

PR Details

PR 1: Prepared runtime foundation (#78248)

Add all reusable prepared-runtime contracts, public SDK seams, central producers, scoped model helpers, speech/TTS runtime types, optional carrier fields, and default behavior. This PR is additive.

Add:

• AGENTS.md update for the request-time prepared-runtime rule.
• CHANGELOG.md entry for PR 1.
• Provider runtime handle contract and helpers.
• Prepared outbound channel runtime contract and producer.
• Scoped model-ref and model-catalog helper contracts.
• Public SDK exports for scoped model/catalog helpers where plugin authors need them.
• Speech/TTS prepared-runtime contracts needed by TTS, Gateway, reply command, and Telegram migrations.
• Optional prepared-runtime slots in the agent runtime plan.
• Bundled channel outbound-adapter contract support.
• Tests for default/empty prepared-runtime behavior.

Remove:

• Nothing. This PR is additive.

Do not include:

• Consumer behavior changes.
• Removal of old resolver calls.
• Any change that requires existing callers to pass prepared facts.

PR 2: Startup loaded/public runtime metadata

Make startup and loaded-runtime state expose public facts that later request-time consumers need without triggering full plugin bootstraps.

Add:

• CHANGELOG.md entry for PR 2.
• Startup plugin id handling for configured provider/channel/media facts.
• Active runtime registry and loaded public metadata support.
• Bundled channel/plugin metadata needed by prepared runtime producers.
• Prepared runtime registry lookup for tool-result middleware loading.

Remove or narrow:

• Duplicate plugin-id expansion that only exists to support request-time broad loading.
• Duplicate public artifact derivation after one canonical loaded/public metadata path exists.
• Bundled-channel discovery helpers used only for request-time plugin loading.
• Startup/bootstrap fallback paths that rebuild runtime registries for request-time consumers.

PR 3: Provider runtime handles and auth

Move selected-provider hooks and auth selection to prepared provider handles and prepared auth state.

Add:

• CHANGELOG.md entry for PR 3.
• Provider-runtime helper params that accept the prepared provider handle.
• Prepared auth selection state: auth store, profile order, locked/preferred profiles, and candidates.
• Active-runtime OAuth API-key formatting.
• Provider handle reuse for model resolution, stream setup, transport setup, transcript/replay/thinking policy, extra params, cache TTL, auth hooks, and tool schema hooks.

Remove or narrow:

• Direct selected-provider provider runtime resolution in hot helper paths.
• Owner-provider broad hook enumeration when the selected provider handle is available.
• Old string-only session auth override wrapper after callers consume prepared auth state.
• Manual preferred-profile ordering branches after one canonical helper exists.
• Hot OAuth formatting fallback to broad plugin formatting when active loaded provider runtime can format.
• Standalone/setup fallbacks only if they are accidentally used by hot selected-provider paths.

PR 4: Embedded runtime plan and attempt orchestration

Make embedded run and compaction orchestration carry prepared runtime facts through one runtime plan.

Add:

• CHANGELOG.md entry for PR 4.
• Runtime plan propagation through run, attempt, retry, compaction, resource loader, project settings, and context helpers.
• Attempt/compaction tests proving prepared facts survive retries and compaction.
• Timing or diagnostics only if they are useful beyond migration proof.

Remove or narrow:

• Attempt-local provider/channel/tool/capability rediscovery when the runtime plan already carries the fact.
• Duplicate provider/model/tool/channel params after they are represented in the runtime plan.
• Compaction fallback resolution that duplicates the main runtime plan.
• Context/resource/project-settings compatibility adapters that rebuild facts already present in the runtime plan.
• Migration-only timing helpers if they are not retained as production diagnostics.

PR 5: Scoped model catalog resolution

Stop broad model/catalog/provider discovery where a concrete provider/model ref is already known.

Add:

• CHANGELOG.md entry for PR 5.
• Canonical scoped model catalog helper.
• Central configured-model-ref collection.
• Scoped catalog use in reply model selection, reset model handling, conversation labels, side-question model resolution, cron/isolated agent selection, health checks, and relevant tests.

Remove or narrow:

• Full catalog/provider loading for explicit provider/model refs.
• Duplicate model-ref parsing and normalization helpers after canonical refs are used.
• Broad fallback selection that loads unrelated provider/model catalogs when fallback candidates are already scoped.
• Direct PI discovery for known configured model refs.

PR 6: Tool planning and skill snapshots

Make tool construction and skill snapshots lazy/prepared instead of rebuilding broad plugin/tool/skill state in request paths.

Add:

• CHANGELOG.md entry for PR 6.
• Prepared tool planning for core tools, plugin tools, optional tool families, web tools, media tools, and embedded tool policy.
• Tool policy metadata that can be resolved without channel/plugin rediscovery.
• Adapter-owned skill hydration for backends that need full skill files.

Remove or narrow:

• Broad optional tool/plugin registry construction for disabled, denied, or non-participating tool families.
• Plugin tool discovery paths that broad-load plugins after prepared plugin tool metadata is available.
• Channel resolver hits during embedded tool policy resolution when prepared policy metadata is supplied.
• Reply-time full skill-body hydration from session update/prep paths.

PR 7: Scoped media capability resolution

Make active media/model checks inspect only the active provider unless the path explicitly asks for configured fallback providers.

Add:

• CHANGELOG.md entry for PR 7.
• Strict provider scope option for capability provider resolution.
• Scoped media understanding registries and active-model capability checks.
• Scoped image/music/video generation provider lookup.
• Telegram sticker/media checks that use scoped model data.

Remove or narrow:

• Configured fallback provider loading while answering whether the active provider/model can handle media.
• Broad media provider registry construction for active-model checks.
• Old image-understanding model discovery path for explicit provider/model requests.
• Full provider-map construction for hot single-provider generation lookups.

PR 8: Loaded TTS and speech runtime

Use loaded/active speech provider state for reply and Gateway TTS instead of broad speech provider discovery.

Add:

• CHANGELOG.md entry for PR 8.
• Loaded speech provider registry behavior.
• Gateway/reply TTS paths that consume loaded provider facts.
• Loaded/prepared speech metadata for TTS command display.
• Standalone fallback behavior for callers with no loaded runtime.

Remove or narrow:

• Broad speech provider loading from reply-time and Gateway TTS paths.
• Telegram TTS dispatch fallback discovery after loaded speech runtime facts are available.
• Broad speech provider listing in TTS command handling.
• Temporary SDK compatibility helpers only if public plugin contract compatibility no longer requires them.

PR 9: Outbound channel runtime consumers

Move known-channel outbound send, target, session, action, policy, and Gateway delivery code to prepared outbound channel runtime and outbound adapters.

Add:

• CHANGELOG.md entry for PR 9.
• Outbound adapter/runtime use in direct Gateway send.
• Prepared runtime use in target/session/policy/message-action code.
• Compatibility fallback only for documented no-runtime callers.
• WhatsApp outbound adapter exposure.

Remove or narrow:

• Direct known-channel channel plugin lookups from outbound target/session/action/policy paths.
• Full channel plugin support-detection fallback where outbound adapter/runtime covers the channel.
• Plugin-derived label/hint/default-target duplication after outbound runtime owns those facts.
• Gateway agent/restart-sentinel plugin fallback when prepared runtime is available.

PR 10: Reply channel runtime handoff

Carry prepared channel runtime through normal reply execution.

Add:

• CHANGELOG.md entry for PR 10.
• One prepared channel runtime created during reply setup and passed through directive handling, runner setup, ACP delivery, route reply, followup delivery, payload building, and related reply helpers.
• Prepared channel runtime consumption for prompt hints/capabilities, reaction guidance, reply threading, group mention policy, block streaming, queue debounce, elevated allowlist formatting, and payload dedupe.

Remove or narrow:

• Prompt-facing channel plugin reads for message tool hints, prompt capabilities, native approval prompt UI, and reaction guidance.
• Reply threading/block-streaming/group/elevated/queue plugin lookups when prepared runtime exists.
• Internal channel runtime rediscovery after reply setup carries the runtime.
• Group runtime bridge after group gating no longer needs it.
• Reply dispatch import of the old runtime-plugin bridge, plus the old runtime-plugin bridge file itself after no production reply path imports it.

PR 11: Prepared reply command metadata

Move reply command parsing/execution, conversation bindings, explicit slash/admin metadata, approval capability, and command status to prepared command/channel metadata.

Add:

• CHANGELOG.md entry for PR 11.
• Prepared command metadata for native names and config-empty skip behavior.
• Prepared conversation binding runtime for session, ACP lifecycle, and subagent command behavior.
• Prepared channel metadata for command status, private route, info, allowlist, model, directive model, and approve command flows.

Remove or narrow:

• Reply-time command metadata plugin lookup.
• Conversation binding plugin lookup in command handlers.
• Inline action channel plugin reads for command metadata.
• Explicit slash/admin/status channel resolver calls when prepared metadata is supplied.
• Approval command plugin lookup when prepared approval capability is supplied.

PR 12: Agent command and session tool delivery

Move agent-command execution and session send/announce tools to prepared outbound/channel runtime during model/tool turns.

Add:

• CHANGELOG.md entry for PR 12.
• Prepared channel runtime on agent run context.
• Prepared outbound runtime use in agent command delivery.
• Prepared outbound runtime use in session announce/send tools.

Remove or narrow:

• Channel plugin/read resolver fallbacks for delivery metadata, target formatting, outbound behavior, and reply routing when prepared runtime is supplied.
• Channel resolver calls in session announce/send helpers for known tool-turn channels.
• No-runtime delivery paths from model/tool-turn execution where the target channel is known.

PR 13: Channel action tool runtime

Move channel-owned messaging action tool classification and subscription target extraction to prepared action-tool metadata.

Add:

• CHANGELOG.md entry for PR 13.
• Prepared action-tool runtime passed through embedded messaging and subscription handlers.
• Prepared extractToolSend behavior for subscription target extraction and tool execution tracking.

Remove or narrow:

• Channel plugin probing for actions and extractToolSend during normal embedded reply execution.
• Subscription target extraction fallback to channel plugin lookup when prepared action-tool runtime exists.

Final Acceptance Criteria

• Hot reply paths use prepared provider/channel/model/tool/capability facts.
• Hot tool execution paths use prepared provider/channel/outbound/action facts.
• Hot outbound paths use prepared outbound channel runtime for known channels.
• Active media capability checks do not load fallback providers unless the path explicitly asks for fallback behavior.
• Provider transport, transcript, replay, and thinking policy paths reuse selected-provider runtime facts.
• Remaining broad resolver calls are limited to setup/startup, explicit compatibility fallbacks, standalone callers, or documented admin paths.
• Each migrated surface has tests proving prepared facts are used.
• Each migrated surface has a test or mock proving broad resolver machinery is not called on the prepared path.