refactor: move provider transports into packages/ai behind a typed host port by steipete · Pull Request #111669 · openclaw/openclaw

steipete · 2026-07-20T05:20:38Z

What Problem This Solves

packages/ai exported a wildcard ./internal/* surface consumed by ~6,700 lines of provider transports parked in src/agents — the package boundary existed but didn't isolate anything, and the transports reached back into core plugin hooks, coupling provider wire logic to the application layer.

Why This Change Was Made

The five transports (OpenAI Responses/Completions, Anthropic stream, simple-completion, provider-stream) plus 17 supporting modules and their tests move into packages/ai/src/transports/, with the plugin/runtime coupling inverted through the package's existing host-port pattern: a typed AiTransportPluginHost (provider-stream resolution, transport turn-state, simple-completion wrapping, Vertex stream construction) plus the non-plugin policies the transports need, all wired by src/llm/ai-transport-host.ts. packages/ai now has zero imports into core src/**. The wildcard internal/* export is gone; five entries remain as exact exports with cited external consumers, two became package-private. Two modules stayed in core deliberately — they are shipped plugin-SDK surface (provider-transport-runtime), and SDK removals take the deprecation path, not a refactor.

During review, a real initialization-order regression was caught and fixed structurally: import-time custom-API registration could run against the inert host and be permanently lost to module caching. Registrations made before host configuration now queue (deduplicated, bounded at 32, loud on overflow) and replay exactly once when the real registrar installs — no import-order requirement — with a regression test proving the previously-broken order. A runtime import cycle exposed by the gates was also removed (Google payload normalizer extracted; public exports preserved), deleting one stale max-lines suppression.

User Impact

No behavior change. Provider transport code now lives with its package, future provider work happens behind one typed seam, and the lost-registration failure mode is structurally impossible.

Evidence

All 25 relocations recognized by git rename detection (64–100% similarity); moved + consumer + facade + Google suites: 554 tests across 19 files passing, re-verified independently after the fix round.
pnpm build green (140 SDK declaration entries, no [INEFFECTIVE_DYNAMIC_IMPORT]); pnpm plugin-sdk:surface:check (140 entrypoints, zero forbidden subpaths) and plugin-sdk:api:check hash unchanged; changed-file gate green incl. import cycles: 0 runtime value cycles.
Autoreview: initial commit-mode review surfaced the init-order regression (fixed as above); follow-up review clean with no actionable findings.

clawsweeper · 2026-07-20T05:28:37Z

Codex review: needs real behavior proof before merge. Reviewed July 20, 2026, 3:10 AM ET / 07:10 UTC.

Summary
The branch relocates provider transport implementations into packages/ai, injects OpenClaw-specific behavior through a typed host port, and adds an @openclaw/ai/transports package entrypoint.

Reproducibility: not applicable. as a bug reproduction: this PR is an architectural refactor plus a new package API surface. The relevant proof is a configured-provider runtime exercise, which the PR body does not supply.

Review metrics: 1 noteworthy metric.

Package API exposure: 1 added public subpath exporting 21 transport helpers. This turns a relocation into a plugin/package contract decision rather than a behavior-neutral internal refactor.

Stored data model
Persistent data-model change detected: persistent cache schema: packages/ai/src/transports/anthropic-payload-policy.ts, unknown-truncated-pull-files. Confirm migration or upgrade compatibility proof before merge.

Merge readiness
Overall: 🦪 silver shellfish
Proof: 🦪 silver shellfish
Patch quality: 🦐 gold shrimp
Result: blocked until real behavior proof from a real setup is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

Resolve whether @openclaw/ai/transports is a supported plugin API or make it package-private.
[P1] Add a redacted terminal transcript or runtime log showing a configured provider path through the concrete host after the relocation.

Proof guidance:

[P1] Needs real behavior proof before merge: The PR body reports tests, build, and static gates, but no redacted after-fix runtime transcript, terminal output, recording, or diagnostic artifact demonstrates a configured provider transport using the installed host. Add real proof before merge and redact secrets, IPs, phone numbers, and non-public endpoints. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

[P1] @openclaw/ai/transports becomes an extension-visible API while exporting transport functions that depend on an OpenClaw-installed host; approving it without an explicit contract risks third-party plugins binding to internal provider, auth, and runtime-policy behavior.
[P1] The refactor changes provider-stream resolution and custom API registration ordering. Unit and CI evidence is useful, but there is no redacted after-fix runtime trace proving a configured provider path reaches the concrete host without behavioral drift.

Maintainer options:

Keep the relocation internal (recommended)
Remove the public extension-visible transport barrel and keep callers on stable facades so this lands as a bounded architectural refactor.
Adopt an explicit plugin contract
Approve a narrow supported export set, document the host lifecycle and compatibility promise, and prove an external consumer against that contract.

Next step before merge

[P1] A protected, maintainer-owned decision is required for the permanent package/plugin API shape, and the contributor must supply real configured-host behavior proof before merge.

Maintainer decision needed

Question: Should @openclaw/ai/transports be a supported extension/plugin API, or should package-owned transports remain private behind existing core and SDK facades?
Rationale: The patch makes a broad transport barrel resolvable to extensions, but its exports rely on an inert-by-default host carrying provider, authentication, and policy behavior; code review cannot safely choose the permanent external contract.
Likely owner: steipete — The proposed architecture and all supplied implementation commits are authored by steipete, making them the clearest available routing candidate for the API-shape decision.
Options:
- Keep transports package-private (recommended): Remove the extension-visible barrel and retain only the existing stable facades, so the relocation stays an internal refactor.
- Approve a narrow transport API: Retain only explicitly supported exports, document host/configuration expectations and compatibility guarantees, and add focused external-consumer coverage before merge.

Security
Cleared: The reviewed diff adds no dependency, workflow, package-install, permission, or secret-handling execution surface; the material concern is API and provider-runtime compatibility rather than a concrete security regression.

Review findings

[P1] Keep the transport barrel private until its API is approved — packages/ai/package.json:44-48

Review details

Best possible solution:

Keep transport implementations package-private unless an owner explicitly approves @openclaw/ai/transports as a supported plugin API with a narrow contract, compatibility expectations, and focused external-consumer coverage; then add redacted real runtime proof through the configured host.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction: this PR is an architectural refactor plus a new package API surface. The relevant proof is a configured-provider runtime exercise, which the PR body does not supply.

Is this the best way to solve the issue?

Unclear: the typed host-port direction is plausible, but publicly exporting the broad transport barrel is not shown to be the best solution over private package implementation plus existing stable facades.

Full review comments:

[P1] Keep the transport barrel private until its API is approved — packages/ai/package.json:44-48
./transports is now exported and mapped into the extension package boundary, making 21 host-dependent transport helpers available to extensions. This remains the prior P1 blocker at the current head: either keep this relocation behind existing stable facades or obtain explicit approval for a narrow, documented plugin contract with compatibility coverage.
Confidence: 0.94

Overall correctness: patch is incorrect
Overall confidence: 0.88

AGENTS.md: unclear because the file could not be read completely.

Codex review notes: model internal, reasoning high; reviewed against 873c2a0c3205.

Label changes

Label justifications:

P2: This is a substantial provider-runtime architecture change with bounded but meaningful compatibility and maintainer impact.
merge-risk: 🚨 compatibility: The new extension-visible transport subpath can become a long-lived plugin API and constrain future internal refactors.
merge-risk: 🚨 auth-provider: Transport execution delegates provider stream and turn-state behavior through the host, which carries provider and credential-sensitive runtime policy.
rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body reports tests, build, and static gates, but no redacted after-fix runtime transcript, terminal output, recording, or diagnostic artifact demonstrates a configured provider transport using the installed host. Add real proof before merge and redact secrets, IPs, phone numbers, and non-public endpoints. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence reviewed

What I checked:

New public package surface: The branch adds the ./transports export, and the barrel re-exports package-owned provider transport implementations rather than keeping them package-private. (packages/ai/package.json:44, a7723a3f9ae8)
Extension-visible contract: The extension package-boundary mapping resolves @openclaw/ai/transports to declarations, so this is not only an internal core import path; extensions can typecheck against it. (scripts/lib/extension-package-boundary.ts:82, a7723a3f9ae8)
Host-dependent behavior: Provider transport resolution delegates provider stream selection through getAiTransportHost().plugin, while the package README states that the default host is inert; a public transport API therefore needs an explicit supported-host contract before external use. (packages/ai/src/transports/provider-transport-stream.ts:48, a7723a3f9ae8)
Prior review continuity: The previous completed ClawSweeper cycle raised the same P1 concern about keeping the transport barrel private until its API is approved. The current head retains the public @openclaw/ai/transports export, so the blocker remains rather than being a new late finding. (packages/ai/package.json:44, 524c2d66cceb)
Current-main and release status: The PR is open and unmerged at head a7723a3f…; current main is 873c2a0c… and the latest release is v2026.7.1, so neither current main nor that release can be treated as containing this branch's implementation. (a7723a3f9ae8)

Likely related people:

steipete: The supplied history identifies this author on all four commits that introduce the typed host port, transport relocation, initialization-order repair, and current package-boundary adjustments; no independent current-main ownership trail was available in the review materials. (role: proposed architecture author; confidence: medium; commits: 67aaa5937ee9, e5f50d681635, 524c2d66cceb; files: packages/ai/src/host.ts, packages/ai/src/transports.ts, src/llm/ai-transport-host.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (2 earlier review cycles)

reviewed 2026-07-20T05:24:57.137Z sha 65ede0a :: needs real behavior proof before merge. :: [P1] Keep the transport barrel private until its API is approved
reviewed 2026-07-20T06:05:45.724Z sha 524c2d6 :: needs real behavior proof before merge. :: [P1] Keep the transport barrel private until its API is approved

…gured

…ball fixtures

steipete · 2026-07-21T06:26:05Z

Merged via squash.

Prepared head SHA: 1fe10b047e5f4f4a2b633ff8b6fc0c48cc1000b0
Landed commit: b4e27f8b3da207619aa47e25c80665d79779872a

…st port (openclaw#111669) * refactor(ai): invert plugin coupling behind the transport host port * fix(ai): queue custom transport registrations until the host is configured * refactor(ai): remove relocated transport sources from src/agents * fix(ai): source core stream types from canonical packages and fix tarball fixtures * fix(ai): invert plugin transport host wiring * fix(ai): harden managed transport projection * test(ai): register synchronous stream in transport mock * fix(ai): lazily install transport runtime host * fix(ai): preserve completion compat detection

* origin/main: (24 commits) fix(agents): keep compaction on live session model (#95713) fix(plugin-sdk): guard provider catalog live URL parsing against malformed responses (#109986) chore(cli): drop dead classifiers and single-use wrappers left by fallback removal (#112191) feat(ui): expand the lobster pet's random universe (#112073) chore(ci): audit dependency fingerprint exports (#112190) fix(ui): preserve graphemes in provider icons (#109509) fix(ui): align settings search with navigation rows (#112172) fix(agents): allow configless gateway rebind to activate standalone owner (#111841) fix(secrets): register secret targets for installed-origin plugins (#104347) improve(ui): show real machine identity in the place picker (#112162) fix: webChat scrollback history is too limited — older assistant replies and tool outputs disappear when scrolling… (#104250) test(ui): run DOM-free suites in Node (#112031) feat(nodes): make computer.act eligibility capability-based for desktop nodes (#112107) fix(apps): harden mobile gateway and watch state fix(ci): restore Z.AI API Platform validation (#112171) fix(ui): prevent Logs controls from overlapping (#112170) fix #95291: message tool fails to deliver files/images on Feishu (400 volc-dcdn / write ECONNRESET) while same Lark SDK upload succeeds standalone (#95514) refactor(cli)!: remove automatic gateway→embedded fallback from openclaw agent (#112074) refactor: move provider transports into packages/ai behind a typed host port (#111669) fix(anthropic): complete transcript reverse-scan windows across short reads (#109431) ...

…re + restore dropped fork symbols - provider-transport-fetch: adopt upstream (transports moved to packages/ai in openclaw#111669) and re-apply the fork's provider concurrency gate. - Skill Workshop: the fork deleted skill-workshop-prompt.ts, so drop the prompt section and SDK re-export upstream still carries instead of resurrecting it. - Legacy JSON store (openclaw#113075): repoint reassign-runtime, auto-title-generator and preserve-reset-discovery at session-accessor.entry / session-store-runtime. - Re-add fork-only exports the upstream rebase drops because they predate the merge base: appendJsonlEntrySync, snapshotSessionOrigin, OsSandboxSettings, BashDisciplineConfig, ToolLoopPostCompactionGuardConfig, and the chat send-timing / side-result schemas plus deltaThinking. tsgo:core 99 -> 79.

openclaw-barnacle Bot added docs Improvements or additions to documentation gateway Gateway runtime scripts Repository scripts agents Agent runtime and tooling extensions: xai size: XL maintainer Maintainer-authored PR labels Jul 20, 2026

steipete force-pushed the refactor/ai-transport-convergence branch 2 times, most recently from 7566e76 to b6eae1c Compare July 21, 2026 03:26

steipete self-assigned this Jul 21, 2026

steipete force-pushed the refactor/ai-transport-convergence branch from b6eae1c to b54a462 Compare July 21, 2026 04:51

openclaw-barnacle Bot closed this Jul 21, 2026

openclaw-barnacle Bot reopened this Jul 21, 2026

steipete force-pushed the refactor/ai-transport-convergence branch 7 times, most recently from dadf0b7 to 565201b Compare July 21, 2026 06:14

steipete added 4 commits July 20, 2026 23:18

refactor(ai): invert plugin coupling behind the transport host port

449e218

fix(ai): queue custom transport registrations until the host is confi…

ea20267

…gured

refactor(ai): remove relocated transport sources from src/agents

9caab09

fix(ai): source core stream types from canonical packages and fix tar…

d64174b

…ball fixtures

steipete added 5 commits July 20, 2026 23:18

fix(ai): invert plugin transport host wiring

69c508e

fix(ai): harden managed transport projection

8d5b3ce

test(ai): register synchronous stream in transport mock

5b06ea8

fix(ai): lazily install transport runtime host

3191270

fix(ai): preserve completion compat detection

1fe10b0

steipete force-pushed the refactor/ai-transport-convergence branch from 565201b to 1fe10b0 Compare July 21, 2026 06:18

steipete merged commit b4e27f8 into main Jul 21, 2026
121 checks passed

steipete deleted the refactor/ai-transport-convergence branch July 21, 2026 06:26

github-actions Bot mentioned this pull request Jul 21, 2026

📡 Upstream Digest — 2026-07-21 08:10 UTC curtismercier/openclaw-mods#1361

Open

lsr911-code mentioned this pull request Jul 21, 2026

fix: update stale imports to moved ai transport modules #112231

Open

0xghost42 mentioned this pull request Jul 21, 2026

fix(ai): resolve request-transport sentinels on the simple-completion plugin path #112257

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

refactor: move provider transports into packages/ai behind a typed host port#111669

refactor: move provider transports into packages/ai behind a typed host port#111669
steipete merged 9 commits into
mainfrom
refactor/ai-transport-convergence

steipete commented Jul 20, 2026

Uh oh!

clawsweeper Bot commented Jul 20, 2026 •

edited

Loading

Uh oh!

Uh oh!

steipete commented Jul 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

steipete commented Jul 20, 2026

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Uh oh!

clawsweeper Bot commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

steipete commented Jul 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

clawsweeper Bot commented Jul 20, 2026 •

edited

Loading