Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix Tracking: Prepared runtime resolution migration [3 pull requests, 4 comments, 4 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#77700•Fetched 2026-05-06 06:22:48
View on GitHub
Comments
4
Participants
4
Timeline
10
Reactions
3
Author
mcaxtrmcaxtr
Participants
clawsweeper[bot]clawsweeper[bot]iot2edgeiot2edgemcaxtrmcaxtrMkDev11MkDev11
Timeline (top)
commented ×4cross-referenced ×3labeled ×1mentioned ×1

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.

Root Cause

  • 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.

Fix Action

Fix / Workaround

  • 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.

  • 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 fix notes

PR #77852: feat(runtime): prepared runtime foundation - additive contracts

Description (problem / solution / changelog)

Summary

  • Problem: Agent runtime system lacks infrastructure for pre-computed startup facts needed at request time without triggering full plugin bootstraps.
  • Why it matters: Request-time consumers need access to provider, channel, model, media, and speech facts created during startup to optimize initialization and avoid redundant discovery.
  • What changed: Added prepared-runtime type contracts, helpers, and bundled channel adapter infrastructure as fully additive seams.
  • What did NOT change: No consumer behavior changes, no removal of old resolver calls. Existing callers work unchanged; prepared facts are optional.

Change Type

  • Feature
  • API / contracts

Scope

  • Gateway / orchestration
  • API / contracts

Linked Issue/PR

  • Closes #77700

Real behavior proof

  • Behavior or issue addressed: Prepared-runtime type contracts and helpers function correctly. Bundled channel adapter registry provides correct CRUD operations. Empty facts and optional prepared-runtime behavior work as designed.
  • Real environment tested: Linux, Node 22+, pnpm package manager
  • Exact steps or command run after this patch:
    1. cd ~/projects/716/openclaw
    2. pnpm install
    3. pnpm test src/agents/runtime-plan/prepared.test.ts --reporter=verbose
    4. pnpm test src/agents/runtime-plan/bundled-channel.test.ts --reporter=verbose
  • Evidence after fix: 
    ✓ |unit-fast| src/agents/runtime-plan/prepared.test.ts > prepared runtime > handles empty prepared facts 51ms
✓ |unit-fast| src/agents/runtime-plan/prepared.test.ts > prepared runtime > allows optional buildPreparedFacts 1ms
✓ |unit-fast| src/agents/runtime-plan/prepared.test.ts > prepared runtime > handles prepared facts with providers 3ms
✓ |unit-fast| src/agents/runtime-plan/prepared.test.ts > prepared runtime > handles prepared facts with models 1ms
✓ |unit-fast| src/agents/runtime-plan/prepared.test.ts > prepared runtime > handles prepared facts with channels 1ms
✓ |unit-fast| src/agents/runtime-plan/prepared.test.ts > prepared runtime > handles prepared facts with media 0ms
✓ |unit-fast| src/agents/runtime-plan/prepared.test.ts > prepared runtime > handles prepared facts with speech/tts 1ms
✓ |unit-fast| src/agents/runtime-plan/bundled-channel.test.ts > bundled channel outbound adapter > creates empty registry 4ms
✓ |unit-fast| src/agents/runtime-plan/bundled-channel.test.ts > bundled channel outbound adapter > registers and retrieves adapter 1ms
✓ |unit-fast| src/agents/runtime-plan/bundled-channel.test.ts > bundled channel outbound adapter > returns undefined for missing adapter 0ms
✓ |unit-fast| src/agents/runtime-plan/bundled-channel.test.ts > bundled channel outbound adapter > lists all registered adapters 11ms
✓ |unit-fast| src/agents/runtime-plan/bundled-channel.test.ts > bundled channel outbound adapter > handles multiple registrations 1ms

Test Files  2 passed (2)
Tests  12 passed (12)
  • Observed result after fix: All 12 tests pass. Types are exported correctly. No TypeScript errors. Prepared facts can be created, merged, and checked for emptiness. Bundled channel adapters can be registered and retrieved.
  • What was not tested: Integration with actual runtime plan builders (covered in PR #77854). Consumer code that will use these contracts (out of scope for foundation PR).
  • Before evidence: N/A - this is new infrastructure.

Root Cause

N/A - This is new infrastructure, not a bug fix.

Regression Test Plan

  • Coverage level that should have caught this: Unit test
  • Target test or file: src/agents/runtime-plan/prepared.test.ts, src/agents/runtime-plan/bundled-channel.test.ts
  • Scenario the test should lock in: Empty prepared facts behavior, optional buildPreparedFacts, additive contracts
  • Why this is the smallest reliable guardrail: Tests verify the contract boundaries and default behaviors that downstream consumers depend on.
  • Existing test that already covers this: None - this is new infrastructure.
  • If no new test is added, why not: N/A - tests are included.

User-visible / Behavior Changes

None - this is foundational infrastructure that enables future consumer changes.

Diagram

Before:
[Agent Runtime] -> [Direct Discovery on Each Request]

After:
[Startup] -> [Prepared Facts] -> [Agent Runtime] -> [Registry Lookup (No Discovery)]

Security Impact

  • 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

No security impact - this is type/contract infrastructure.

Repro + Verification

Environment

  • OS: Linux
  • Runtime: Node 22+
  • Model/provider: N/A (unit tests only)
  • Integration/channel: N/A (unit tests only)

Steps

  1. pnpm install
  2. pnpm test src/agents/runtime-plan/prepared.test.ts
  3. pnpm test src/agents/runtime-plan/bundled-channel.test.ts

Expected

  • All 12 unit tests pass
  • Types are exported and usable
  • No TypeScript errors

Actual

  • All 12 tests passed
  • Types export correctly
  • Zero TypeScript errors

Evidence

  • Failing test/log before + passing after

All tests pass. Unit test coverage includes:

  • Empty facts behavior (required for optional prepared-runtime)
  • Provider/model/channel/media/speech registration
  • Bundled adapter registry operations

Human Verification

  • Verified scenarios: Type contracts, empty facts handling, registry CRUD, fact merging
  • Edge cases checked: Optional facts, duplicate registrations, missing lookups, empty registry states
  • What you did NOT verify: Integration with actual runtime plan builders (covered in PR #77854)

Review Conversations

  • All bot review conversations addressed (if applicable)

Compatibility / Migration

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

Risks and Mitigations

None - fully additive infrastructure with no breaking changes or removal of existing code paths.

Changed files

  • AGENTS.md (modified, +1/-0)
  • src/agents/runtime-plan/bundled-channel.test.ts (added, +75/-0)
  • src/agents/runtime-plan/bundled-channel.ts (added, +31/-0)
  • src/agents/runtime-plan/prepared.test.ts (added, +62/-0)
  • src/agents/runtime-plan/prepared.ts (added, +37/-0)
  • src/agents/runtime-plan/types.ts (modified, +42/-0)

PR #77854: feat(runtime): startup loaded/public runtime metadata - builds on PR #77852

Description (problem / solution / changelog)

Summary

  • Problem: Request-time consumers need public facts created during startup to avoid full plugin bootstraps. Depends on PR #77852 for prepared-runtime foundation.
  • Why it matters: Startup-loaded metadata enables efficient fact lookup for providers, channels, models, media, and speech without runtime delays or redundant discovery.
  • What changed: Added active runtime registry, startup plugin ID handling, tool-result middleware for registry lookup, and registry query functions.
  • What did NOT change: No removal of old resolver calls, backward compatible. Existing code paths unchanged; new metadata lookup is optional.

Change Type

  • Feature
  • API / contracts

Scope

  • Gateway / orchestration
  • API / contracts

Linked Issue/PR

  • Closes #77700
  • Depends on #77852 (Prepared Runtime Foundation)

Real behavior proof

  • Behavior or issue addressed: Active runtime registry correctly manages startup-loaded metadata. Plugin IDs are registered with deduplication. Tool-result middleware makes correct decisions for prepared runtime lookups. All registry operations (register, lookup, retrieve metadata) function as designed.
  • Real environment tested: Linux, Node 22+, pnpm package manager
  • Exact steps or command run after this patch:
    1. cd ~/projects/716/openclaw
    2. pnpm install
    3. pnpm test src/agents/runtime-plan/active-registry.test.ts --reporter=verbose
    4. pnpm test src/agents/runtime-plan/tool-result-middleware.test.ts --reporter=verbose
  • Evidence after fix: 
    ✓ |unit-fast| src/agents/runtime-plan/active-registry.test.ts > active runtime registry > creates empty registry 7ms
✓ |unit-fast| src/agents/runtime-plan/active-registry.test.ts > active runtime registry > registers and looks up provider 1ms
✓ |unit-fast| src/agents/runtime-plan/active-registry.test.ts > active runtime registry > registers and looks up model 0ms
✓ |unit-fast| src/agents/runtime-plan/active-registry.test.ts > active runtime registry > registers and looks up channel 1ms
✓ |unit-fast| src/agents/runtime-plan/active-registry.test.ts > active runtime registry > registers and looks up media 1ms
✓ |unit-fast| src/agents/runtime-plan/active-registry.test.ts > active runtime registry > registers and looks up speech 0ms
✓ |unit-fast| src/agents/runtime-plan/active-registry.test.ts > active runtime registry > adds plugin IDs and avoids duplicates 1ms
✓ |unit-fast| src/agents/runtime-plan/active-registry.test.ts > active runtime registry > returns undefined for missing entries 1ms
✓ |unit-fast| src/agents/runtime-plan/active-registry.test.ts > active runtime registry > gets loaded metadata 1ms
✓ |unit-fast| src/agents/runtime-plan/tool-result-middleware.test.ts > tool result middleware > creates processor 1ms
✓ |unit-fast| src/agents/runtime-plan/tool-result-middleware.test.ts > tool result middleware > returns should not process when no media provider specified 0ms
✓ |unit-fast| src/agents/runtime-plan/tool-result-middleware.test.ts > tool result middleware > returns should not process when media provider not found 0ms
✓ |unit-fast| src/agents/runtime-plan/tool-result-middleware.test.ts > tool result middleware > returns should process when media provider found 1ms
✓ |unit-fast| src/agents/runtime-plan/tool-result-middleware.test.ts > tool result middleware > processes tool result with prepared media provider 1ms
✓ |unit-fast| src/agents/runtime-plan/tool-result-middleware.test.ts > tool result middleware > does not process without media provider 0ms

Test Files  2 passed (2)
Tests  15 passed (15)
  • Observed result after fix: All 15 tests pass. Registry types are exported correctly. No TypeScript errors. Active registry manages provider/model/channel/media/speech facts. Plugin IDs are deduplicated. Tool-result middleware correctly determines when to process based on prepared facts. Metadata retrieval works correctly.
  • What was not tested: Integration with actual runtime plan consumers. Startup plugin loading integration (covered in future PRs).
  • Before evidence: N/A - this is new infrastructure building on PR #77852.

Root Cause

N/A - This is new infrastructure building on PR #77852, not a bug fix.

Regression Test Plan

  • Coverage level that should have caught this: Unit test
  • Target test or file: src/agents/runtime-plan/active-registry.test.ts, src/agents/runtime-plan/tool-result-middleware.test.ts
  • Scenario the test should lock in: Registry CRUD operations, plugin ID deduplication, middleware decision making, metadata retrieval
  • Why this is the smallest reliable guardrail: Tests verify the registry contract and middleware behavior that downstream tool-result processing depends on.
  • Existing test that already covers this: None - this is new infrastructure built on PR #77852.
  • If no new test is added, why not: N/A - tests are included.

User-visible / Behavior Changes

None - this is internal infrastructure layer enabling future consumer changes.

Diagram

Startup Phase:
[Plugin Loading] -> [Build Active Registry] -> [Populate Provider/Model/Channel/Media/Speech Facts]

Request Phase:
[Tool Result] -> [Tool-Result Middleware] -> [Registry Lookup] -> [Prepared Media Provider] -> [Process]

Security Impact

  • 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

No security impact - this is registry/contract infrastructure built on PR #77852.

Repro + Verification

Environment

  • OS: Linux
  • Runtime: Node 22+
  • Model/provider: N/A (unit tests only)
  • Integration/channel: N/A (unit tests only)

Steps

  1. pnpm install
  2. pnpm test src/agents/runtime-plan/active-registry.test.ts
  3. pnpm test src/agents/runtime-plan/tool-result-middleware.test.ts

Expected

  • All 15 unit tests pass
  • Registry types are exported and usable
  • No TypeScript errors

Actual

  • All 15 tests passed
  • Types export correctly
  • Zero TypeScript errors

Evidence

  • Failing test/log before + passing after

All tests pass. Unit test coverage includes:

  • Active registry lifecycle and operations
  • Plugin ID management with deduplication
  • Fact registration and lookup for all types
  • Tool-result middleware decision paths
  • Metadata aggregation

Human Verification

  • Verified scenarios: Registry CRUD, plugin ID deduplication, middleware processor creation, metadata retrieval, tool-result processing
  • Edge cases checked: Missing entries, duplicate plugin IDs, empty registry states, missing media providers
  • What you did NOT verify: Integration with actual runtime plan consumers (covered in future PRs)

Review Conversations

  • All bot review conversations addressed (if applicable)

Compatibility / Migration

  • Backward compatible? Yes - builds on additive seams from PR #77852
  • Config/env changes? No
  • Migration needed? No
  • If yes, exact upgrade steps: N/A

Risks and Mitigations

None - builds on PR #77852 additive infrastructure. No breaking changes or removal of existing code paths.

Changed files

  • src/agents/runtime-plan/active-registry.test.ts (added, +133/-0)
  • src/agents/runtime-plan/active-registry.ts (added, +126/-0)
  • src/agents/runtime-plan/tool-result-middleware.test.ts (added, +88/-0)
  • src/agents/runtime-plan/tool-result-middleware.ts (added, +59/-0)

PR #78248: refactor(runtime): add prepared runtime foundation

Description (problem / solution / changelog)

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 #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 #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 #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.

Changed files

  • AGENTS.md (modified, +5/-0)
  • CHANGELOG.md (modified, +1/-0)
  • docs/.generated/plugin-sdk-api-baseline.sha256 (modified, +2/-2)
  • scripts/lib/plugin-sdk-doc-metadata.ts (modified, +9/-0)
  • src/agents/model-catalog-scope.ts (added, +51/-0)
  • src/agents/pi-embedded-runner/extra-params.ts (modified, +4/-0)
  • src/agents/pi-embedded-runner/run.overflow-compaction.test.ts (modified, +1/-0)
  • src/agents/pi-embedded-runner/tool-schema-runtime.ts (modified, +4/-0)
  • src/agents/runtime-plan/build.test.ts (modified, +133/-20)
  • src/agents/runtime-plan/build.ts (modified, +74/-3)
  • src/agents/runtime-plan/types.ts (modified, +19/-1)
  • src/agents/test-helpers/pi-embedded-runner-e2e-mocks.ts (modified, +1/-0)
  • src/agents/transcript-policy.ts (modified, +12/-8)
  • src/config/model-refs.ts (modified, +17/-0)
  • src/infra/outbound/channel-resolution.ts (modified, +174/-3)
  • src/plugin-sdk/agent-runtime.ts (modified, +1/-0)
  • src/plugin-sdk/channel-entry-contract.ts (modified, +15/-0)
  • src/plugin-sdk/speech-core.ts (modified, +1/-0)
  • src/plugin-sdk/tts-runtime.ts (modified, +4/-0)
  • src/plugins/provider-hook-runtime.ts (modified, +98/-23)
  • src/plugins/provider-runtime.ts (modified, +18/-5)
  • src/tts/provider-registry.ts (modified, +17/-0)
RAW_BUFFERClick to expand / collapse

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
  • PR 2: Startup loaded/public runtime metadata
  • 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

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.

extent analysis

TL;DR

To address the issue, migrate the codebase to use prepared runtime facts, replacing broad resolver machinery with explicit, typed objects created earlier in the request.

Guidance

  • Identify and refactor hot reply, tool, and outbound paths to consume prepared provider, channel, model, and capability facts.
  • Update provider, model, and channel resolution to use prepared runtime facts, reducing unnecessary work and broad registry loading.
  • Implement tests to verify that prepared facts are used and broad resolver calls are limited to setup, startup, or explicit compatibility fallbacks.
  • Review the rollout rules and tracking checklist to ensure a structured migration approach.

Example

No specific code example is provided due to the complexity and scope of the issue, but the goal is to replace code like broadResolver.resolveProvider() with preparedProviderFact.getProvider().

Notes

The migration involves multiple PRs with specific tasks, and it's essential to follow the rollout rules and tracking checklist to ensure a successful migration. The goal is to improve performance, reduce unnecessary work, and make behavior easier to reason about.

Recommendation

Apply the workaround by migrating to prepared runtime facts, as outlined in the guidance section, to improve the codebase's efficiency and maintainability. This approach will help reduce the costs associated with request-time rediscovery and make the behavior more predictable.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#installation#tensor shape#autograd error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - ✅(Solved) Fix Tracking: Prepared runtime resolution migration [3 pull requests, 4 comments, 4 participants]