spec: Add tool registration for Apps, to be called by Host (WebMCP-style!)

[ochafik]

Summary

This PR enables Apps to register their own tools that agents can call, making apps introspectable and accessible to the model without DOM parsing.

Apps expose semantic interfaces (state queries, operations) via standard MCP tools. The agent discovers capabilities via tools/list, queries state, and drives interactions.

This is a different model from other approaches where apps keep the model informed through side channels (e.g., OAI Apps SDK sending widget state changes to the model, MCP-UI adding tool call results to chat history). Instead, the agent actively queries app state and executes operations through tools.

Example:

// Agent can query structured state
app.registerTool("get_board_state", {
  outputSchema: z.object({
    board: z.array(z.enum(['X', 'O', null])),
    currentPlayer: z.enum(['X', 'O']),
    winner: z.enum(['X', 'O', 'draw', null]).nullable()
  })
}, async () => ({
  structuredContent: { board, currentPlayer, winner: checkWinner(board) }
}));

// Agent can execute actions
app.registerTool("make_move", {
  inputSchema: z.object({ position: z.number().int().min(0).max(8) })
}, async ({ position }) => {
  board[position] = currentPlayer;
  currentPlayer = currentPlayer === 'X' ? 'O' : 'X';
  return { structuredContent: { board, winner: checkWinner(board) } };
});

Agent interaction:

// Discover → Query → Act
const { tools } = await bridge.sendListTools({});
const state = await bridge.sendCallTool({ name: "get_board_state" });
await bridge.sendCallTool({ name: "make_move", arguments: { position: 4 } });

Changes

App side (app.ts)

• registerTool() - Register tools with Zod validation
• oncalltool / onlisttools - Handle tool requests
• sendToolListChanged() - Notify on tool updates
• Tools support enable(), disable(), update(), remove()

Host side (app-bridge.ts)

• sendCallTool() - Call app tools
• sendListTools() - List app tools
• Fix: Use correct ListToolsResultSchema

Capabilities (types.ts)

• Apps: tools: { listChanged?: boolean }
• Hosts: serverTools: { listChanged?: boolean } (existing)

Tests: ✓ 27 passing, 100% coverage

Design

Reuses standard MCP messages: tools/call, tools/list, notifications/tools/list_changed

Similar to WebMCP but without turning the App (embedded page) into an MCP server - apps register tools within the App/Host architecture.

Lifecycle: App tools exist only while app loaded (ephemeral, sandboxed)

Separation: Server tools (persistent, trusted) vs App tools (ephemeral, sandboxed)

Breaking Changes

None. Purely additive.

Related

Implements the gist of #35 (WebMCP-style tool registration) while preserving the App/Host architecture.

🤖 Generated with Claude Code