[mavam]

🔍 Problem

Agents can't use MCP servers or tools from other extensions, such as Webfox's web search. Pi runs those tools only inside its own sessions, it has no durable version of them, and we can't change Pi.

🛠️ Solution

• Tool twin: pi-agents runs a headless Pi session in the same process with Pi's public SDK (createAgentSession, DefaultResourceLoader, createMcpExtension). It loads only Pi's MCP extension and the packages listed in piAgents.twinExtensions, and shares Pi's mcp.json and sign-ins.
• Proxies: one durable extension holds a proxy per twin tool, and every agent selects it.
  • MCP tools Pi declares only to codemode stay deferred. Their namespaces feed agents' codemode, and a prompt section lists them, as Pi's mcp_servers section does.
  • Calls run the twin's tool_call hooks first, so MCP waits until the server is ready.
  • A call is replayed after a crash only for tools marked readOnlyHint or idempotentHint.
• Lifecycle: the twin opens before the harness and waits up to 10 s for servers, so tool calls that resume find their tools. Servers that connect later reach agents at their next request. It is skipped when there's no mcp.json and nothing is shared.
• Selection: agents now store a { remove } tool filter instead of naming their tools, so twin tools that appear later reach them. Naming a twin tool in an allowlist changes nothing.
• Docs: the README drops the caution and shows the twin inside pi-agents in the architecture diagram.

💬 Review

• Stacked on Adopt the next pi-durable: crash-ended runs, continue, turn limits, and windowed views #119. Checked end to end on the published Pi 1.5.0 too: an agent found the Cloudflare docs server and called web_search from one script.
• Verified end to end against Pi built from upstream main, with your 11 HTTP MCP servers (309 tools) and npm:webfox. An agent found the Cloudflare docs server through the namespace section and answered from it; another called an MCP tool and web_search from one script. Opening the twin took about 0.5 s, plus about 2 s until the servers were ready.
• The twin's own connections duplicate the session's: one more HTTP session per server, one more child process per stdio server.
• Known gaps:
  • Agents created before this change keep their named tools and get no twin tools.
  • Servers that extensions register at runtime aren't mirrored.
  • Scripts get the text of results, not structuredContent: pi-durable strictly validates structured output against a declared schema, and Pi doesn't.
  • Twin tools render as generic cards in the attach view.
  • /mcp changes reach agents after a restart.
• Removing the twin later means deleting src/host/twin*.ts and its call in the harness.