Summary

A targeted source audit on 2026-04-13 (fork HEAD 44b4f92b12) found ~19 provider/model files that had been gutted previously but were re-introduced by the sync: upstream to v2026.3.7 merge (#2298). Several restored stubs carry silent runtime regressions through dead call sites. This issue re-applies the cascade.

Context: Sync Regression Pattern

RemoteClaw replaced OpenClaw's embedded "Pi" agent engine with a subprocess-based CLI runtime architecture (Claude/Gemini/Codex/OpenCode via src/middleware/runtimes/). Multiple prior gut waves removed Pi-era model catalogs, provider helpers, and embedded-runner plumbing. The v2026.3.7 upstream sync re-introduced many of those files.

Git evidence (example: src/agents/model-catalog.ts):

9ef18943dc  sync: upstream to v2026.3.7 (893 commits) (#2298)        ← REGRESSION
caca5bb6d8  gut(models): remove vestigial model catalog... (#2151)    ← ORIGINAL GUT
0241706c9d  sync: upstream to v2026.3.2 (862 commits) (#2172)
4608a6a6cf  feat: remove in-process LLM packages... (#102)

Same pattern for src/gateway/server-methods/{models,skills}.ts, auto-reply stubs, and the src/agents/ provider catalog files. Each survives as a stub with the header comment // Gutted in RemoteClaw fork (Middleware Boundary Principle).

Hidden Runtime Regressions (Broken-But-Wired)

Three of the restored stubs have live consumers whose results are silently neutered, causing user-visible feature regressions:

Files to Re-Gut

src/agents/

Delete the file + remove all imports:

• custom-api-registry.ts — no-op stub; only live caller is tts/tts-core.ts::ensureCustomApiRegistered (dead scaffolding, safe to remove call site)
• huggingface-models.ts — empty catalog stub; only consumed by dead onboard-auth.* chain (tracked separately)
• model-catalog.ts — stub with loadModelCatalog, findModelInCatalog, modelSupportsVision; see Telegram vision cascade below
• model-compat.ts — real code but zero callers (was pi-ai compat layer; pi-ai removed in Remove pi-embedded.ts stub barrel and clean up no-op call sites #76)
• models-config.providers.ts — empty stub; only consumed by dead onboard-auth.* chain
• pi-embedded-messaging.ts — dead duplicate; canonical exports live in agents/agent-messaging.ts
• pi-model-discovery.ts — empty ModelRegistry stub; only gateway/test-helpers.mocks.ts vi.mocks it
• pi-tools.before-tool-call.ts — substantial real impl, zero importers (replaced by middleware/mcp-tools.ts + plugins/hooks.ts)
• pi-tools.before-tool-call.runtime.ts — no-op stubs; only consumer is dead pi-tools.before-tool-call.ts
• synthetic-models.ts, together-models.ts, venice-models.ts — empty provider catalog stubs (dead via onboard-auth.* chain)
• test-helpers/pi-tool-stubs.ts — zero importers

src/gateway/

• server-methods/models.ts — delete file; remove import + spread from server-methods.ts:20,78; drop models.list from server-methods-list.ts:36, method-scopes.ts:57, protocol validators
• server-methods/skills.ts — delete file; remove import + spread from server-methods.ts:25,84; drop skills.status, skills.bins, skills.install, skills.update from server-methods-list.ts:45-48, method-scopes.ts:26,61,104-105

src/auto-reply/

• reply/commands-models.ts — stub (handleModelsCommand returns undefined, buildModelsProviderData returns {}); triggers Discord/Mattermost model-picker cascade below
• reply/session-reset-model.ts — stub (applyResetModelOverride returns undefined); 1 live call site in get-reply.ts:180 passing 11 params to discard
• reply.directive.directive-behavior.model-directive-test-utils.ts — zero importers (was test util for per-message model directives — obsolete)

src/commands/

• openai-codex-model-default.ts — 58 LoC real code, zero importers; Codex runtime handles its own default model internally

src/secrets/

• provider-env-vars.ts — empty PROVIDER_ENV_VARS = {} stub; only consumed by dead commands/onboard-auth.credentials.ts (tracked separately)

Cascade Call Sites (fix alongside file deletion)

Telegram vision cascade (model-catalog.ts deletion)

• src/telegram/bot-message-context.body.ts — remove loadModelCatalog → findModelInCatalog → modelSupportsVision call chain
• src/telegram/bot-message-dispatch.ts — same pattern
• src/telegram/sticker-cache.ts — same pattern

Decision needed in PR: does Telegram vision stay in v0.1.0?

• If yes → replace capability check with runtime-reported capabilities from middleware/runtimes/*.ts::mediaCapabilities
• If no → delete vision-related paths entirely

Recommended: remove the capability check; let CLI runtime's own mediaCapabilities field gate attachments (it already does this in the media pipeline — see middleware/media-capability.ts).

Node-host skills cascade (skills.ts deletion)

• src/node-host/runner.ts — delete SkillBinsCache class + its instantiation at line 225 + remove skillBins param from handleInvoke()
• src/gateway/protocol/schema/agents-models-skills.ts — delete 8 Skill*Schema exports (SkillsStatusParamsSchema, SkillsBinsParamsSchema/ResultSchema, SkillsInstallParamsSchema, SkillsUpdateParamsSchema, SkillsSearchParamsSchema/ResultSchema, SkillsDetailParamsSchema/ResultSchema)
• src/gateway/protocol/index.ts — delete 4 skills validators
• src/gateway/protocol/schema/protocol-schemas.ts — delete registry entries

TUI listModels cascade (models.ts deletion)

• src/tui/gateway-chat.ts — delete listModels() method + GatewayModelChoice type
• src/tui/tui-command-handlers.ts:103 — delete client.listModels() call site
• src/gateway/protocol/schema/agents-models-skills.ts — delete 3 model exports (ModelChoiceSchema, ModelsListParamsSchema, ModelsListResultSchema)
• src/gateway/protocol/schema/types.ts:84 — delete ModelChoice re-export
• src/gateway/protocol/index.ts — delete validateModelsListParams + type imports
• src/gateway/protocol/schema/protocol-schemas.ts — delete registry entries

Discord/Mattermost model-picker UI cascade (commands-models.ts deletion)

• src/auto-reply/reply/commands-core.ts:24,194 — remove handleModelsCommand import + handler array entry (drops dead /models slash command)
• src/discord/monitor/model-picker.ts, model-picker.test.ts, model-picker.test-utils.ts — delete Discord model-picker UI (only source of buildModelsProviderData in Discord)
• src/plugin-sdk/mattermost.ts:20-22 — drop re-exports
• extensions/mattermost/src/mattermost/model-picker.ts, monitor.ts:1089, slash-http.ts:390 — delete Mattermost model-picker + buildModelsProviderData call sites

Session reset model cascade (session-reset-model.ts deletion)

• src/auto-reply/reply/get-reply.ts:27,180-193 — remove applyResetModelOverride import + call block
• src/auto-reply/reply/session.test.ts:15,1264-1339 — delete 3 test cases
• src/auto-reply/reply/get-reply.test-mocks.ts:45-46 — remove mock entry

Schema file split (agents-models-skills.ts)

After Models/Skills exports are deleted by the cascades above, the remaining agents-models-skills.ts is mostly LIVE Agents* and Tools* schemas. Rename/split it:

• Split src/gateway/protocol/schema/agents-models-skills.ts → agents-tools.ts (LIVE content only: AgentSummarySchema, AgentsList*, AgentsCreate*, AgentsUpdate*, AgentsDelete*, AgentsFiles*, ToolCatalog*, ToolsCatalog*, ToolsEffective*)
• Update importers in protocol-schemas.ts, protocol/index.ts, schema/types.ts

Acceptance Criteria

• All files listed above are deleted
• Each cascade call site is rewired to live equivalents or removed
• pnpm check passes (0 errors, 0 warnings)
• pnpm test passes (update mocks where deletions require)
• Telegram vision, node-host skill bins, TUI listModels: product decisions documented in PR body
• Verification: git grep -rn "model-catalog\|modelSupportsVision\|loadModelCatalog" src/ returns zero hits
• Verification: git grep -rn "models\.list\|skills\.bins\|skillsHandlers\|modelsHandlers" src/ returns zero hits
• Verification: git grep -rn "pi-model-discovery\|synthetic-models\|venice-models\|together-models\|huggingface-models\|model-compat" src/ returns zero hits
• Verification: git grep -rn "commands-models\|handleModelsCommand\|buildModelsProviderData" src/ extensions/ returns zero hits
• Verification: git grep -rn "session-reset-model\|applyResetModelOverride" src/ returns zero hits
• CI zombie-import gate (from Add CI zombie-import gate: detect imports from gutted modules #2195) passes

Out of Scope

• src/agents/pi-embedded.ts + pi-embedded-runner/* cascade — tracked under audit: review all Pi engine stub replacements for ChannelBridge compatibility #2089 (audit: review all Pi engine stub replacements for ChannelBridge compatibility). Coordinate re-gut timing via a comment on audit: review all Pi engine stub replacements for ChannelBridge compatibility #2089.
• Upstream sync filter hardening (root cause) — the fork sync pipeline needs harder EXCLUDE enforcement to prevent future regressions. Separate concern, not blocking this issue.
• onboard-auth.* cluster gut (13 files in src/commands/) — tracked as a separate issue; huggingface-models/synthetic-models/together-models/venice-models/models-config.providers in this cascade are dead because the onboard-auth cluster is dead, but their deletion is independent and belongs in this issue.
• Disposition map corrections for false EXCLUDE markers on live files — tracked separately.

Implementation Notes

• Order of operations: Delete stubs first, then fix compilation errors by removing consumer call sites. The TypeScript error cascade surfaces the full removal scope automatically.
• Split into sub-PRs if the change set is too large to review in one pass. Suggested split boundaries: (1) Telegram vision cascade, (2) Gateway models/skills + schema split, (3) Auto-reply cascade (commands-models + session-reset-model + model-directive-test-utils), (4) Agents directory stub sweep (remaining model-*, synthetic-models, etc.), (5) Secrets + commands remnants.
• Don't re-invent the gut: Prior gut PRs (gut: remove vestigial model catalog, vision check, and thinking default stubs #2151, gut: remove vestigial embedded Pi orchestrator stubs and call sites #2146, gut: sweep gutted stubs across agents, auto-reply, commands, cli (MBP audit) #2303, gut: remove dead models.list gateway method references #416, gut(skills): remove dead skills subsystem remnants #555) already proved these patterns are safe. The scope here is "apply the same delete set again, plus fix the cascade sites that still have live imports."
• Test mock updates: Many tests vi.mock(...) these stubs. Sweep test-helpers and *.test-mocks.ts files together with the deletes.
• CI zombie-import gate (Add CI zombie-import gate: detect imports from gutted modules #2195) should catch any missed consumers on PR CI — rely on it rather than exhaustive local grep.

References

• Prior gut PRs that got regressed: gut: remove vestigial model catalog, vision check, and thinking default stubs #2151 (model-catalog), feat: remove pi-embedded.ts stub barrel and clean up call sites (#76) #77 (pi-embedded — partially, see audit: review all Pi engine stub replacements for ChannelBridge compatibility #2089), gut: sweep gutted stubs across agents, auto-reply, commands, cli (MBP audit) #2303 (general sweep), gut: remove dead models.list gateway method references #416 (models.list), gut(skills): remove dead skills subsystem remnants #555 (skills), gut(config): remove dead model selection config schemas #2290 (config schemas)
• Related open work: audit: review all Pi engine stub replacements for ChannelBridge compatibility #2089 (Pi engine ChannelBridge compatibility audit), gut(auto-reply): finish thinking-level and model-selection sweep — follow-up to #2335 #2336 (thinking-level/model-selection sweep)
• CI safety net: Add CI zombie-import gate: detect imports from gutted modules #2195 (zombie-import gate)
• Audit source: targeted provider/model obsolescence audit, fork HEAD 44b4f92b12, 2026-04-13