nshkrdotcom / nshkrdotcom/codex_sdk

Avoid default retries for ambiguous MCP tool outcomes

Open
#2 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Elixir
Stars
27
Forks
4
PR merge metrics
No merged PRs in 30d

Description

Codex.MCP.Client.call_tool/4 currently defaults to three retries for every tools/call failure. That can replay a non-idempotent mutation when the server completed the write but the response was lost.

Current path:

  1. request/4 sends tools/call.
  2. The destination commits a write.
  3. The response times out or the transport closes.
  4. retry_or_error/8 invokes the same tool again because mcp_default_retries() is 3.

This is an ambiguous-success boundary, not a confirmed failure. Backoff does not make the replay safe.

Proposed minimal change:

  • Make automatic tools/call retries opt-in rather than the default, or require a caller-provided retry-safety predicate.
  • Keep explicit retries available for read-only or provider-idempotent tools.
  • Document that transport errors after request transmission may mean the external effect is uncertain.
  • Add a deterministic regression fixture whose first call commits a synthetic mutation and drops the response; the default path must leave the mutation count at one.

A later enhancement could use MCP readOnlyHint / idempotentHint as advisory input, but unknown or missing annotations should remain conservative. These hints cannot provide exactly-once behavior by themselves.

Reference contract and fixture semantics: https://github.com/artiehinz/Agent-Enhancer-Utilities/blob/main/docs/RELIABILITY_SIDECAR_CONTRACT_V1.md

I can prepare the focused patch and test if this direction matches the project's compatibility policy.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with Codex.MCP.Client.call_tool/4, then trace request/4, retry_or_error/8, and mcp_default_retries(). Review docs/RELIABILITY_SIDECAR_CONTRACT_V1.md for the stated reliability semantics. Add the deterministic fixture described in the issue and verify that a dropped first response leaves the synthetic mutation count at one while explicit safe retries remain available.

Written by the indexing model from the issue text.

Assessment

Tech stack
elixir
Domain
api
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.