Native I/O diverges from headless stub: stringified inputSchema / executeTool / result #12

Problem

WebMCP has two surfaces that diverge on I/O shapes. Code green in the headless postMessage stub is red in flagged Chrome (chrome://flags/#enable-webmcp-testing, allow="tools" + exposedTo/fromOrigins), and vice versa. Found in one checkout flow, but the bug lives in the kit:

1. Schema is stringified on native — document.modelContext.getTools() returns RegisteredTool.inputSchema as JSON string ("{\"type\":\"object\",…}") per skills/webmcpify/templates/webmcp.d.ts:97 + skills/webmcpify/templates/webmcp.spec.ts:67. Forwarding it as parameters to an OpenAI-compatible LLM (Groq/OpenAI) → 400 'tools.0.function.parameters' must be an object → agent loop 502. Stub returns object, so same code is green in CI.

2. Execution contract differs — stub: tool.execute(object). Native: RegisteredTool has no .execute (skills/webmcpify/templates/webmcp.d.ts:93), must be document.modelContext.executeTool(tool, JSON.stringify(args)) (skills/webmcpify/templates/webmcp.spec.ts:88). Passing object to native throws UnknownError: Failed to parse input arguments; passing string to stub fails the other way.

3. Result is stringified on native — native returns result: "{\"ok\":true,…}" (string); stub returns object. isinstance(result, dict) / typeof result === 'object' treats native success as empty (last='{}'), stalling search-catalog → show-product.

Headless postMessage bridge hides all three — only flagged Chrome surfaces them.

Proposed fix (small, backwards-compat, no new deps)

Principle: handle both shapes everywhere, keep surfaces in sync:

• Tool defs expose both parameters (OpenAI/LLM) + inputSchema (WebMCP). On native inputSchema must be minimal (type:object + properties/required, no description inside properties on strict validators). See skills/webmcpify/references/integrate.md example.
• Runner dual-path — executeTool: try ctx.executeTool(m, JSON.stringify(args)) on native, fallback to args object on Failed to parse, else m.execute(object) for stub; resultOk/search result helpers handle result as object or JSON string via JSON.parse fallback; serializableTools does JSON.parse on stringified inputSchema before sending parameters to LLM.
• Docs — references/integrate.md notes registerTool must use inputSchema for validate:true on native; references/verify.md documents 400 recipe (missing tools with tool_choice:none → tool_use_failed; stringified parameters) and fix disable_tool_validation:true with no forced tool_choice.

Verification

• Flagged Chrome manual: keyword search → /search → product page → cart badge → payment link chip via document.modelContext. Previously failing queries now count:1, show receives parsed sku.
• Headless stub stays green (object path unchanged) — no regression for postMessage + page.frameLocator('#agent-iframe') CI.

Files to touch

templates/webmcp.d.ts (optional parameters alias), templates/webmcp.spec.ts (parseResult guard), references/integrate.md, references/verify.md.