Summary

Remove 12 pi-embedded agent tool source files + 14 test files from src/agents/tools/. These tools provided web fetch/search, browser control, image analysis, TTS, and nested agent execution for OpenClaw's in-process LLM engine. RemoteClaw's CLI agents (Claude Code, Gemini CLI, Codex, OpenCode) have native equivalents — these tools are dead code.

Context

The 4 dispatch sites now route through ChannelBridge → CLI runtime (M2 complete). The old pi-embedded execution path that consumed these tools is bypassed. CLI agents have their own web fetch, browser, and image capabilities via MCP or native tooling.

Middleware Boundary Principle: "Can the agent get this capability without RemoteClaw? If yes, RemoteClaw does not provide it." All 12 tools fail this test — they're generic agent capabilities, not RemoteClaw infrastructure.

What to Remove

Phase 1: Relocate shared utilities (before deleting source files)

Two functions exported by GUT files are imported by KEEP files. They must be relocated FIRST.

1. Relocate readLatestAssistantReply from agent-step.ts

Current location: src/agents/tools/agent-step.ts (lines 7-37)

Consumers (both KEEP):

• src/agents/subagent-announce.ts:38 — import { readLatestAssistantReply } from "./tools/agent-step.js"
• src/cron/isolated-agent/subagent-followup.ts:5 — import { readLatestAssistantReply } from "../../agents/tools/agent-step.js"

Action: Move readLatestAssistantReply to src/agents/tools/sessions-helpers.ts (natural home — agent-step.ts already imports extractAssistantText and stripToolMessages from there). Update both consumer imports.

The function reads session chat history via callGateway({ method: "chat.history" }) and returns the latest assistant text. ~30 lines. It also needs the callGateway import from ../../gateway/call.js.

The other function in agent-step.ts (runAgentStep) is dead — it's the nested pi-embedded execution entry point.

2. Inline coerceImageAssistantText into media-understanding

Current location: src/agents/tools/image-tool.helpers.ts (lines 1-23)

Sole consumer (KEEP):

• src/media-understanding/providers/image.ts:7 — import { coerceImageAssistantText } from "../../agents/tools/image-tool.helpers.js"

Action: Copy the function (~20 lines) into src/media-understanding/providers/image.ts and remove the import. The function extracts text from an AssistantMessage, throwing on errors. It depends on extractAssistantText which is in src/agents/tools/sessions-helpers.ts — add that import to image.ts.

The other export (coerceImageModelConfig) is only used by image-tool.ts (GUT) — it dies with the file.

Phase 2: Delete GUT source files (12 files)

Delete these files from src/agents/tools/:

Phase 3: Delete GUT test files (14 files)

Delete these test/test-utility files from src/agents/tools/:

• agent-step.test.ts
• browser-tool.test.ts
• image-tool.test.ts
• tts-tool.test.ts
• web-fetch-visibility.test.ts
• web-fetch.cf-markdown.test.ts
• web-fetch.ssrf.test.ts
• web-fetch.test-harness.ts
• web-fetch.test-mocks.ts
• web-search.redirect.test.ts
• web-search.test.ts
• web-tools.enabled-defaults.test.ts
• web-tools.fetch.test.ts
• web-tools.readability.test.ts

Phase 4: Delete cascading GUT test file

Delete this test file outside tools/ that imports a deleted tool:

• src/agents/pi-tools.create-openclaw-coding-tools.adds-claude-style-aliases-schemas-without-dropping.test.ts — pi-embedded test suite, imports createBrowserTool from deleted browser-tool.ts. This is GUT (part of pi-tools, will be fully deleted when the pi-embedded execution engine core is gutted), but must go now to keep the build green.

Phase 5: Clean up KEEP/MODIFY imports

src/agents/openclaw-tools.ts (MODIFY)

Remove these 5 import lines and their corresponding tool creation calls in createOpenClawTools():

// DELETE these imports:
import { createBrowserTool } from "./tools/browser-tool.js";
import { createImageTool } from "./tools/image-tool.js";
import { createTtsTool } from "./tools/tts-tool.js";
import { createWebFetchTool, createWebSearchTool } from "./tools/web-tools.js";

Find and remove the tool creation calls inside the function body (e.g., createBrowserTool(...), createImageTool(...), etc.).

src/agents/subagent-announce.ts (MODIFY)

Update import path after relocation:

// BEFORE:
import { readLatestAssistantReply } from "./tools/agent-step.js";
// AFTER:
import { readLatestAssistantReply } from "./tools/sessions-helpers.js";

src/cron/isolated-agent/subagent-followup.ts (MODIFY)

Update import path after relocation:

// BEFORE:
import { readLatestAssistantReply } from "../../agents/tools/agent-step.js";
// AFTER:
import { readLatestAssistantReply } from "../../agents/tools/sessions-helpers.js";

src/media-understanding/providers/image.ts (MODIFY)

Replace import with inlined function:

// DELETE this import:
import { coerceImageAssistantText } from "../../agents/tools/image-tool.helpers.js";
// ADD import for the dependency:
import { extractAssistantText } from "../../agents/tools/sessions-helpers.js";
// ADD the inlined function (~20 lines) in the file

Phase 6: Verify clean build

pnpm build

Then verify no stale references remain:

# Should return zero results:
grep -rn "web-fetch\|web-search\|web-shared\|web-tools\|browser-tool\|image-tool\|tts-tool\|agent-step" src/agents/tools/ --include="*.ts" 2>/dev/null | grep -v sessions-helpers | grep -v node_modules
# Check no broken imports in src/:
grep -rn "from.*tools/\(web-\|browser-\|image-tool\|tts-\|agent-step\)" src/ --include="*.ts" | grep -v node_modules

Important: What NOT to Delete

• nodes-tool.ts, nodes-utils.ts, canvas-tool.ts — DEFER, not GUT. These ARE RemoteClaw-specific (companion device infrastructure) but have no consumer in v0.1.0. Handled separately.
• src/browser/ (100-file CDP/Playwright subsystem) — this is a KEEP channel capability. Only the pi-embedded tool wrapper (browser-tool.ts in src/agents/tools/) is deleted.
• src/tts/ (4 files) — KEEP. This is the audio synthesis infrastructure used by the voice-call channel pipeline. Only the agent tool wrapper (tts-tool.ts) is deleted.

Estimated Scale

Acceptance Criteria

Given all dispatch wiring is complete and skills system is gutted (#63)
When pi-embedded agent tools that are redundant with CLI capabilities are removed
Then 12 GUT tool source files + 14 test files are deleted from src/agents/tools/
And readLatestAssistantReply is relocated to sessions-helpers.ts (consumers updated)
And coerceImageAssistantText is inlined into media-understanding/providers/image.ts
And openclaw-tools.ts is updated to remove 5 deleted tool imports + creation calls
And pi-tools test file importing browser-tool is deleted
And only RemoteClaw-specific MCP tools remain (~29: sessions, messaging, cron, gateway)
And pnpm build passes