Generalize MCP App presentation over canonical ToolResult state

[yyjeqhc]

Status

Updated for the v0.4.1 architecture. WebCodex now has a substantially more mature canonical tool/result, Job, validation/evidence, Git, Artifact, and host-file-transfer substrate than when this issue was opened. The remaining work is a presentation adapter, not a new execution model.

The existing MCP App path is still primarily Computer-specific. Ordinary coding/runtime tools already return authoritative ToolResult / MCP structuredContent; that state should remain the source of truth.

Problem

Projects, Jobs, validation/evidence, Git changes, and Artifacts expose useful structured state, but most of it is still presented as ordinary tool output. Important durable states such as queued/running/reconnecting/reconciled/outcome-unknown/terminal are therefore harder for users to inspect than they need to be.

We want a coherent MCP App card layer without coupling core execution semantics to ChatGPT or to any specific host UI.

Core invariant

An MCP App card is a bounded projection of canonical WebCodex state/result/evidence. It never owns workflow truth, execution truth, authority, or effect state.

In particular:

• core ToolResult, Job, validation, Session, Artifact, and permission semantics remain host/UI-neutral;
• rendering a card cannot change a Job, validation verdict, Session, permission decision, or retry outcome;
• MCP Apps remain an optional host adapter; unsupported hosts receive the complete normal text/structured fallback;
• presentation metadata must not contain secrets, raw credentials, unbounded logs, full large diffs, screenshot bodies, or duplicated binary payloads.

Direction

Add one reusable MCP App presentation layer over canonical results rather than one bespoke App implementation per runtime tool.

Prefer deriving a small bounded presentation envelope after the authoritative result exists. The envelope may identify:

• card kind/version;
• authoritative object/result identity where one exists;
• display-safe state/summary;
• bounded file/count/duration metadata;
• safe observation/follow-up hints;
• ResourceLink/resource references for data that should not be inlined.

Do not add presentation-only fields to core model-facing schemas unless a concrete host contract requires them.

Initial scope

Start with three non-Computer families that already have strong structured contracts:

1. Job — queued/running/reconnecting/reconciled/completed/lost/outcome-unknown, duration, bounded log/evidence hints.
2. Validation — check/test status, structured counts, duration, current failures and evidence state.
3. Git / changes — status/diff summary, changed paths and bounded review metadata.

Keep the current Computer image App specialized initially; it already has native-image framing and a dedicated resource path. Artifact presentation can then compose with the existing ResourceLink/export path rather than copying large bytes into card metadata.

Durable-state UX

Cards should make production states explicit rather than collapsing them into generic success/failure, including:

• waiting for execution capacity;
• Runner temporarily unavailable while durable work remains alive;
• reconciled state after recovery;
• outcome_unknown with an observation/reconciliation next step;
• terminal completion after work outlives the initiating model turn.

Presentation must consume these states, not reinterpret them.

Acceptance criteria

• At least three non-Computer result families render through one shared MCP App resource/presentation mechanism.
• The canonical ToolResult / structured result remains sufficient without MCP Apps.
• App rendering does not mutate authoritative execution, Job, validation, Session, Artifact, or permission state.
• Unknown/reconnecting/reconciled/terminal states retain their real semantics in the UI.
• Large logs, diffs, images, and Artifacts stay behind existing bounded/native-image/resource delivery mechanisms.
• Sensitive values are absent from App metadata and host-visible diagnostics.
• Core model-facing schemas do not grow presentation-only state without a demonstrated host requirement.
• Focused host integration tests cover descriptor/resource metadata, normal fallback, and at least one durable Job state transition.

Non-goals

• redesigning the execution or Job state machine;
• making MCP Apps authoritative for workflow state;
• building a generic frontend framework unrelated to WebCodex tool results;
• expanding the runtime tool surface merely to support cards;
• automatic model continuation or Host wake delivery in this issue.