feat(runtime): reconcile external tool effects for idempotency-capable MCP providers

[AsperforMias]

Area

Runtime

Problem

#412 prevents a Driver or control-plane failure from automatically repeating an uncertain write-capable MCP call. Its safe outcome is a durable unknown effect that requires manual user or operator resolution.

That is correct for generic MCP, but it leaves unnecessary manual work for MCP providers that already offer an idempotency-key lookup, a durable operation receipt, or a documented compensating action. Mosoo has no provider-specific reconciliation capability, so it cannot use those provider guarantees to turn an unknown effect into a confirmed result or a confirmed non-execution.

Reproduction / current limitation

Prerequisite: apply the durable external-effect behavior from #412.

1. Use the local Driver/API fault-injection setup in apps/api/tests/driver-finalization-repair.test.ts with an MCP provider fixture that records a write by the Mosoo idempotency key and exposes a lookup by that key.
2. Execute one mcp.execute command and let the fixture commit the write.
3. Drop the provider response or Driver terminal receipt immediately after the write, then restart the Driver or finalize its control connection.
4. Re-deliver the command.
5. Observe that Mosoo correctly marks the effect unknown and does not invoke the provider again, but it also does not invoke the provider lookup. A user or operator must resolve it manually even though the provider can prove the outcome.

This path is locally reproducible with a fixture; no Cloudflare account, remote MCP server, credentials, or billable provider request is required.

Proposal

Add an opt-in provider capability for external-effect reconciliation:

• A provider adapter may declare lookup by Mosoo stable idempotency key and return a typed confirmed-success, confirmed-not-executed, or still-unknown result.
• Recovery may reconcile only effects whose provider advertises that capability. It must persist the returned receipt and result before any terminal redelivery.
• Compensation remains a separate explicit per-tool capability. Mosoo must never infer or invent a rollback.
• Providers without the capability retain fix(runtime): persist uncertainty for external tool effects #412 behavior: unknown stays fenced and no automatic retry occurs.

Keep the adapter contract small, runtime-owned, and provider-specific; do not change the generic MCP wire protocol or treat arbitrary metadata as proof of completion.

Alternatives considered

• Always retry unknown effects: unsafe because it can duplicate writes.
• Add a universal MCP receipt or compensation protocol in Mosoo: impossible without provider support and would create a private incompatible protocol.
• Keep manual resolution for every provider: safe and remains the fallback, but wastes provider capabilities when they exist.

Compatibility and migration

This is additive. Existing effects and providers remain unchanged. Only explicitly registered provider adapters may reconcile an unknown effect. Unknown effects without an eligible adapter remain terminally fenced. Any new provider configuration or operator workflow must be feature-gated and documented.

Contribution

I can submit a PR.

Checklist

• I searched existing issues before opening this request.
• I described the problem before the proposed solution.
• I kept this request focused on one improvement.