feat(mcp): support safe order reconciliation

[namtran1812]

Summary

Improve order submission recovery in the MCP server by distinguishing definitive Gemini API rejections from ambiguous transport failures and allowing order status lookup by client_order_id.

This prevents the market-order fallback path from issuing a second order when the original submission's outcome is unknown.

Problem

An order submission can fail at the transport layer after the request has been sent but before the client receives a response. In that case, the client cannot safely assume that the order was rejected: Gemini may already have accepted it.

Previously, order submission errors were represented as generic Error instances, and the market-order fallback identified InvalidOrderType through error-message matching. The order-status tool also required the exchange-assigned order_id, which may be unavailable when the submission acknowledgement is lost.

Changes

• Add GeminiApiError for definitive non-2xx Gemini API responses.
• Add GeminiTransportError for request-level transport failures.
• Restrict the market-to-limit fallback to definitive InvalidOrderType API responses.
• Do not replay or fall back after an ambiguous transport failure.
• Allow /v1/order/status lookup by either order_id or client_order_id.
• Enforce that exactly one order identifier is supplied to gemini_get_order_status.
• Add regression coverage for API-error classification, transport ambiguity, client-order-ID reconciliation, and mutation-count behavior.

Gemini's OrderStatusRequest supports client_order_id as an alternative to order_id and specifies that the two identifiers cannot be supplied together.

Safety invariant

A transport failure during order submission does not imply that the order failed.

Accordingly, an ambiguous submission is never automatically replayed. Callers that supplied a client_order_id can instead reconcile the original submission through gemini_get_order_status before deciding whether another order should be placed.

Validation

• pnpm typecheck
• pnpm build
• pnpm test — 296/296 passing
• git diff --check

[hubenforcer-gemini]

Please enable commit signing by following the commit signing setup guide. If you have additional questions, reach out to #git-commit-signing.

Reveal/hide commits without valid signatures

{"commit_hash": "f784c266dbec229d98ede667a386fc568be19aa3", "has_valid_signature": false, "author": {"name": "namtran1812", "email": "158846154+namtran1812@users.noreply.github.com", "github_username": "namtran1812"}, "committer": {"name": "namtran1812", "email": "158846154+namtran1812@users.noreply.github.com", "github_username": "namtran1812"}}

[nostradamus-bot]

Nostradamus Risk Rating — Medium

The PR modifies order submission and status-lookup logic in datasources/orders.ts and tools/orders.ts (high-sensitivity financial transaction paths), but all changes are defensive: they tighten the market-to-limit fallback to fire only on definitive GeminiApiError responses (never transport failures), and add Zod-enforced mutual exclusivity for the new client_order_id lookup parameter. No new external attack surface or trust-boundary crossings are introduced.

[sdlc-pr-bot]

Change Control Evidence Check

Authorization — ❌ Fail

Evidence:

• Linear ticket: ⚠️ No ticket linked
• Change owner: namtran1812
• Type of change: Normal

Testing — ⚠️ Incomplete

Evidence:

• Tests from CI checks: ➖ No tests ran
• Security scans: ⚠️ Not configured — Semgrep OSS, scan_for_secrets, Scan with Semgrep, Socket Security: Pull Request Alerts not found
• Testing summary: ✅ Found in PR description
  • Summary: TypeScript type checking, build compilation, and unit tests (296/296 passing) were executed successfully, with no whitespace or formatting issues detected via git diff.
• Evidence link: View run

Approval — ⏳ Awaiting approval

Evidence:
(no approvers yet)

Segregation of Duties — ⏳ Awaiting approval

Validated:

• PR author: namtran1812

---

Last checked: 2026-09-19 03:23 UTC

↩ Re-run Clarissa if tickets, CI, or approvals have changed.

[namtran1812]

Hi maintainers — this is ready for review. The local MCP test suite passes 296/296, along with typecheck and build. It looks like the remaining Semgrep/secret-scan workflows require maintainer approval to run, and the SDLC check is also looking for an internal Linear ticket. Happy to address any feedback or make changes if needed. Thanks!