MCP semantic data contract: normalize CallToolResult into payload data

[RhysSullivan]

Stacked on #1768. The structural fix from the design review (independently confirmed by the fresh-eyes Codex report): ToolResult.data is the tool's SEMANTIC payload on every transport — the MCP CallToolResult envelope no longer reaches sandbox code, telemetry, or shape inference.

Contract (core-owned, tool-result-normalization.ts): per successful MCP call — structuredContent IS data; else a lone exact-JSON text block parses into data (the Linear case); else lone prose is the string; else the ordered content-block array. Non-duplicate blocks ride in result.content (the spec-mandated serialized duplicate of structuredContent is suppressed — payloads stop being paid for twice); _meta moves to result.meta. isError handling unchanged.

Mechanism: persisted tool.result_encoding column (direct | mcp-call-tool-result-v2, NULL = direct) stamped by the MCP plugin at catalog sync; executor.execute applies the encoding after invocation, before telemetry and shape observation. The MCP plugin now persists the server's declared output schema DIRECTLY (it types data), no synthesized envelope — schemaless MCP tools fall under the plain observed-shape serve rule with contract-scoped recall (#1768).

No data migration: MCP catalogs re-sync on a 15-minute TTL, so rows stamp themselves with the encoding on their next use — per-row atomic (NULL = fully old behavior, stamped = fully new), fleet-converged within minutes of the deploy. Old envelope-shaped learned shapes are invalidated by contract-scoped recall, no deletion pass. Migrations here are the additive nullable column only (drizzle for both hosts + the sqlite boot safety net, following the origin_redirect_uri precedent).

Describe surface: the result union models see becomes { ok: true; data: T; content?: ToolContentBlock[]; meta?: unknown; http?: ToolHttpMeta } | …; execute skill text documents the contract ("never look for data.content[0].text").

Evidence: e2e journey passing on selfhost AND cloud — cold describe data: unknown with no envelope, sandbox code receives { value: "hi", length: 2, ok: true } directly, warm describe serves the observed payload type with provenance. MCP plugin suite 147 passing with contract assertions rewritten (prose→string, structured→semantic+side channels, multi-block→array). Full typecheck 44/44; every package suite green in isolation (the fully-parallel local run flakes on 5s OAuth-fixture timeouts in varying packages, as on prior PRs — CI shards adjudicate).

Blast radius (enumerated in the design discussion): ephemeral sandbox scripts self-heal via describe; ~10 of 117 saved artifacts read envelope fields and will need edits after this deploys; console/apps-shell reads only the outer execute envelope, unaffected.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	executor-marketing	d2a8758	Commit Preview URL Branch Preview URL	Aug 27 2026, 08:18 AM

[github-actions]

Cloudflare preview

Torn down — the PR is closed.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	executor-cloud	d2a8758	Aug 27 2026, 08:19 AM

[pkg-pr-new]

Open in StackBlitz

@executor-js/cli

npm i https://pkg.pr.new/@executor-js/cli@1769

@executor-js/config

npm i https://pkg.pr.new/@executor-js/config@1769

@executor-js/execution

npm i https://pkg.pr.new/@executor-js/execution@1769

@executor-js/sdk

npm i https://pkg.pr.new/@executor-js/sdk@1769

@executor-js/codemode-core

npm i https://pkg.pr.new/@executor-js/codemode-core@1769

@executor-js/runtime-quickjs

npm i https://pkg.pr.new/@executor-js/runtime-quickjs@1769

@executor-js/plugin-file-secrets

npm i https://pkg.pr.new/@executor-js/plugin-file-secrets@1769

@executor-js/plugin-graphql

npm i https://pkg.pr.new/@executor-js/plugin-graphql@1769

@executor-js/plugin-keychain

npm i https://pkg.pr.new/@executor-js/plugin-keychain@1769

@executor-js/plugin-mcp

npm i https://pkg.pr.new/@executor-js/plugin-mcp@1769

@executor-js/plugin-onepassword

npm i https://pkg.pr.new/@executor-js/plugin-onepassword@1769

@executor-js/plugin-openapi

npm i https://pkg.pr.new/@executor-js/plugin-openapi@1769

executor

npm i https://pkg.pr.new/executor@1769

commit: d2a8758

[RhysSullivan]

Codex review findings addressed: the content side-channel type is inlined in the result union instead of a named definition (a provider's own $defs.ToolContentBlock can no longer be shadowed), per-invocation encoding state moved inside Effect.suspend so concurrent runs of one Effect value can't share a row read, and the testing-helper contract suite no longer blesses the removed envelope shape. Rebased on the updated #1768.