MCPFax Agent Continuity

Mutual exclusion so two instances of the same agent do not both process one item. Returns acquired:true with a fence token (FREE), or acquired:false naming the current holder and when the lease expires. ACQUIRED:FALSE MEANS YOU DO NOT HOLD THE LOCK — you must NOT proceed, and must not treat the refusal as advisory: stop work on that resource, wait retry_after_seconds, or do something else. acquired:null means we could not determine the state, which is also not permission to proceed. YOU ARE GIVEN TWO NUMBERS AND THEY DO DIFFERENT JOBS. `fence` is a CREDENTIAL: a large integer drawn fresh and i…

Release a lease you hold so the next worker can take it immediately instead of waiting for the TTL. FREE. If you no longer hold it we REFUSE rather than free someone else's lock: a stale fence returns released:false, reason 'not_holder', naming the current holder — treat that as having lost the lock and stop work. An already-expired lease returns released:false, reason 'expired'. Neither is an error you can retry away; both mean the lock is not yours. A successful release also corrects the scope ledger, so resume_packet stops briefing a later agent that it still holds a lock it gave back. FREE…

Extend a lease you still hold, using the fence token you were given. FREE. Fails (renewed:false) if the lease expired or was taken by someone else — treat that as having lost the lock and stop work. A renewal keeps both of your numbers: the same fence and the same generation, because it is the same acquisition. A successful renewal also corrects the scope ledger, so resume_packet and the dead-man switch see the real new expiry rather than the one recorded when you first acquired it. FREE — this tool never charges. Authenticate with Authorization: Bearer <agent_secret>, or pass agent_key as an …

Create a durable identity for an agent. Returns an agent_secret (the only credential; store it in the agent's configuration the way you would an API key — an amnesiac agent cannot remember it for you), the public agent address other agents mail work to, and the namespace id. FREE. The secret is never stored here: the namespace id is its salted SHA-256 digest, so a dump of our storage cannot reveal it, and we cannot recover it for you if you lose it. FREE — this tool never charges. Authenticate with Authorization: Bearer <agent_secret>, or pass agent_key as an argument if your host cannot set h…

THE HEADLINE TOOL. Returns a briefing, not an archive: objective, last verified state, what arrived while you were gone, the single next action, files, risks, open questions, tools already used and budget remaining. Composed from your last checkpoint PLUS server-observed facts we hold ourselves — the claims you made, the leases you still hold, the watermarks you set, the mail that arrived since — so the packet is not limited to what an earlier session remembered to write down. Provider-neutral plain JSON: a checkpoint written by one model under one framework is resumable by any other. $0.002 o…

Durable retry bookkeeping, so backoff survives the session that died. Returns the attempt count, first and last attempt times, and a deterministic suggested backoff. Pass record:true to count this attempt. $0.002 ONLY when we return remembered history from an earlier session (attempts>0 before this call), and only when that attempt count has changed since you last paid for it. The very first call for a key tells you nothing you did not know, so it is free. NOTE that record:true is a WRITE: it counts a new attempt, so it produces a genuinely new answer and is billable again. Use the default rec…

Record items you have already processed. FREE. Items are stored ONLY as salted SHA-256 digests — we can test membership but cannot read, list or reconstruct what you deduped. A set holds up to 10000 entries; when full, adds are refused (never silently forgotten) and you should rotate to a new set name. FREE — this tool never charges. Authenticate with Authorization: Bearer <agent_secret>, or pass agent_key as an argument if your host cannot set headers. Equivalent HTTP route: POST /v1/seen/add.

Given a batch of items, return only the ones not already in the set — the work you actually still have to do. $0.002 ONLY when we filter at least one item out, because that is the call where we saved you work, AND only when that answer has changed since you last paid for it — asking the same question again while the set has not grown is free. If every item is new we tell you so and charge nothing. Costs $0.002 USDC per call via x402 on Base, and ONLY when filtered_count >= 1, and this exact set of already-seen items has not been billed before; otherwise the same call returns the full answer an…

Agent-to-agent mail. Queue a rich task envelope addressed to any registered agent so it finds the work waiting whenever it next starts. Nobody waits and nobody polls. FREE. You may SEND to an address but never READ another agent's mailbox — reading requires that agent's secret. The envelope carries objective, context, attachments and history so the receiving invocation can start work without rebuilding state it no longer has. A mailbox holds 1000 pending items, of which ordinary mail may occupy 968; the last 32 are reserved for the recipient's OWN dead-man alerts and barrier notifications, so …

The check a worker makes between items. $0.002 ONLY WHEN THE ANSWER IS 'no' — that is the call that saved you money, and the first caller told to stop is the only one billed for it, because every later 'no' is the same fact. A 'keep going' answer told you nothing you did not already assume, so it is FREE, always. An unknown job answers 'keep going' and charges nothing. If we cannot determine the state we fail closed with continue:null and you should retry rather than guess. Costs $0.002 USDC per call via x402 on Base, and ONLY when continue === false, and this cancellation has not been billed …

Fetch the position you last recorded for a stream, so you can ask an upstream only for what is new. $0.002 ONLY when a watermark exists AND its position has moved since you last paid for it — re-reading an unchanged position is free. Never set one? Then we tell you so and charge nothing. Costs $0.002 USDC per call via x402 on Base, and ONLY when found === true, and this exact position has not been billed before; otherwise the same call returns the full answer and settles nothing. Authenticate with Authorization: Bearer <agent_secret>, or pass agent_key as an argument if your host cannot set he…

Record how far you got through a stream, feed or table so the next invocation knows where to start. FREE. The position is an opaque string we store verbatim and never interpret. FREE — this tool never charges. Authenticate with Authorization: Bearer <agent_secret>, or pass agent_key as an argument if your host cannot set headers. Equivalent HTTP route: POST /v1/watermark/set.

Report this namespace's public address, registration time, and mailbox counts: how many items exist, how many are due right now, when the next one falls due, and how many are dead-lettered. FREE, deliberately: knowing THAT work exists must never cost money — only the envelope itself is billable. Poll this for free, then pay only when there is something to collect. FREE — this tool never charges. Authenticate with Authorization: Bearer <agent_secret>, or pass agent_key as an argument if your host cannot set headers. Equivalent HTTP route: POST /v1/whoami.

Complete an item you hold. FREE. If your lease already expired and the item went back to the queue we REFUSE with lease_lost rather than accepting a result from a worker that no longer owns the work — that is what the fence token is for. A fence-less call on an item that has been handed out more than once is refused as fence_required for the same reason; work_fail behaves identically. The optional result is opaque, is never parsed, and is returned by work_status as results_so_far so a parent can proceed on partial output. FREE — this tool never charges. Authenticate with Authorization: Bearer …

Report that an item did not work out. FREE. THIS IS ALSO THE CORRECT WAY TO HAND AN ITEM BACK WHEN NOTHING WENT WRONG — there is no work_release; retry:true (the default) returns it immediately for another worker instead of waiting out the lease. When its attempts are exhausted it is DEAD-LETTERED and SURFACED in work_status, never silently dropped. With retry:false it is marked permanently failed, stops consuming attempts, and CANNOT BE UNDONE. PASS `fence`: exactly like work_done, if your lease already expired and the item went back to the queue we REFUSE with lease_lost, a stale fence is re…

THE ALTERNATIVE TO THIS IS WRITING DISTRIBUTED WORK-DISTRIBUTION CODE YOURSELF — assignment, collision avoidance, lease expiry, retry, dead-worker recovery, straggler policy. Push 100 items in one go and exit, and keep pushing until the queue holds your whole batch; workers pull independently, with no assignment logic, no coordinator and nothing staying alive. FREE, and IDEMPOTENT PER item_id: pushing the same item_id twice adds it once, so a retrying parent cannot duplicate the fan-out. Payloads are opaque and never parsed. FREE — this tool never charges. Authenticate with Authorization: Bear…

Turn a fan-out from a black box into something you can act on: how many items are pending, leased, done, failed and dead-lettered, the results collected so far, and every dead letter with the error that exhausted it. THIS IS WHAT LETS A PARENT PROCEED WITH 4 OF 5 instead of blocking on a straggler. Counts are produced by scanning the queue, not from counters that can drift. $0.002 ONLY when there is real progress — at least one completion, failure or dead letter — and only when the answer has changed since you last paid for it. An untouched queue charges nothing and says so. The counts are exa…

Take up to n items, LEASED not deleted — the same lease semantics as lease()/renew()/release(): a holder, a fence token, an expiry. Two workers can never be handed the same item, because one single-threaded Durable Object owns the queue. IF YOUR PROCESS DIES THE LEASE SIMPLY EXPIRES AND THE ITEMS RETURN TO THE QUEUE with attempts incremented; nothing had to stay alive to notice, and that recovery is the point. EACH ITEM CARRIES ITS OWN FENCE, drawn independently on every take: the token you are given for one item tells you nothing about the token another worker was given for another item, and …