# Retry-outcome resolution dedup proxy — TextForAgents LLC

A timeout is UNKNOWN, not FAILED. A hosted claim-before-execute dedup proxy for side-effecting agent tool calls.

## Start (self-serve, no operator step)
1. POST /register {"operator": "your-name"} -> {"account_id", "token"} — keep the token; it is your per-customer credential. Registering again under the same normalized operator identity (case/whitespace variants included) returns the same account and does NOT re-grant the trial.
2. POST /execute {"tool": "charge_payment", "args": {"invoice_id": "inv-1", "recipient": "vendor@example.com", "amount_cents": 4999, "attempt_id": "uuid-1"}, "scope_fields": ["invoice_id", "recipient", "amount_cents"], "provider_mode": "ok", "supports_status": true} with Authorization: Bearer <token>. The proxy claims the semantic-identity slot BEFORE the effect fires. Fixture provider modes simulate your provider: ok / timeout_after_effect / timeout_before_effect / definitive_failure; supports_status=false models a provider with no status surface (UNKNOWN -> ESCALATED, re-fires refused).
3. Retry semantics: a retry sends a FRESH attempt_id with the same scope fields and payload — a COMMITTED operation returns {"outcome": "replayed", receipt: <original>} and never re-fires (effect_count stays 1). A different payload under the same identity returns outcome "conflict". A timed-out operation resolves by status query: "resolved_committed" (true receipt) or exactly one re-fire on a not_happened verdict ("refired_after_not_happened"). No status surface: outcome "escalated" and every re-fire is refused until POST /resolve closes it with a committed verdict.
4. POST /receipt {"tool", "args", "scope_fields"} returns YOUR stored claim/receipt for an identity (another operator's claims are invisible: not_found). POST /resolve performs the manual status check on an ESCALATED claim.
5. POST /census {"servers": [ {"name": "...", "tools": [{"name": "pay", "write": true, "annotations": {"idempotentHint": true}}], "has_status_endpoint": true} ]} — guard census over operator-supplied server descriptors. SELF_GUARDED_VERIFIED requires a checkable status endpoint; a schema hint alone is never safe (CLAIMS_GUARD_UNVERIFIED); invisible guards read NO_VISIBLE_GUARD. A descriptor may carry "status_url": it is fetched only if it resolves to a public address (SSRF guard, validated at census time); a non-public status_url is never fetched and the endpoint counts as not checkable.
6. Billing: the first 100 claims are free, one time per operator; then per-claim $0.001 via x402 (X-PAYMENT header), or included under an active plan — Operator $9/mo (up to 50,000 claimed operations/mo), Fleet $29/mo (up to 500,000 claims/mo + per-server guard census reports). POST /subscribe {"tier": "operator"|"fleet"} with an x402 X-PAYMENT header for $9.00 / $29.00 activates that plan for 30 days.
7. MCP: POST /mcp (JSON-RPC) — tools dedup_execute, dedup_receipt, dedup_resolve, guard_census — same account token and billing.
8. Receipt verification: execute responses carry receipt_sig (HMAC under the product's signing key); POST /receipts/verify checks one, GET /verify-key lists accepted key fingerprints (rotation keeps archived keys verifiable).

## PENDING lease tuning guidance
Default lease 300s, resolve-before-takeover, single-winner stale-guarded takeover. Fast calls: 60–300s. Long-running effects: 900–3600s, above the longest legitimate tool call. Never below the tool's own timeout.

## Framework adapters (shipped integrations, source at /adapters/)
CrewAI (adapters/crewai_adapter.py): DedupTool, a real crewai BaseTool for the agent's tool list — claims via /execute before the proxied effect fires; retries re-enter with a fresh attempt_id and identical scope fields and consume the stored verdict. LangGraph (adapters/langgraph_adapter.py): make_dedup_node / build_retry_graph — the claim inside the side-effecting node under a RetryPolicy; checkpoint resumes re-enter the same claim. Shared stdlib client: adapters/dedup_client.py. Raw MCP: dedup_execute mirrors the wrapped tool's arguments plus declared scope_fields. Proven end-to-end: a claim executed inside a real CrewAI tool-calling loop and a real LangGraph retry path with the effect firing exactly once.

## Limits
Claim states: PENDING / COMMITTED / UNKNOWN / ESCALATED / FAILED_CONFIRMED / NOT_HAPPENED. Verdict meanings: executed / replayed / resolved_committed / refired_after_not_happened / failed_confirmed / in_progress / conflict / escalated / unknown_refused. Support: support@textforagents.com.

## Prices
Operator $9/mo per operator · Fleet $29/mo per operator · Per-claim API $0.001/claim (x402). First 100 claims free, one time per operator. No perpetual free tier.