MCPFax Agent Continuity

Fan work out to N agents and have the LAST one to finish wake the joiner. FREE. A BARRIER THAT WAITS FOR ALL N IS A HANG WAITING TO HAPPEN, so stragglers are the normal case here, not an edge case: set min_count and/or deadline_seconds and we fire on whichever comes first, ALWAYS naming the participants that did not report. Exactly ONE envelope is queued to notify_address, carrying every participant's payload; that delivery is billed by the existing inbox_poll rule, so there is no new charge. If nothing has fired by the TTL we queue a `barrier_timeout` envelope naming the missing participants — a timeout is information and is delivered, never silently dropped. REUSING A BARRIER_ID IS THE NORMAL PATTERN: while a join is still open this call is idempotent and refuses to reset it (created:false), because a retrying agent must not be able to reset a join others are signalling — but once it has fired or timed out, calling barrier_create with the same id opens a NEW GENERATION with your new roster, and that generation gets its own notification. 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/barrier/create.

Report that one participant finished, optionally attaching a payload the joiner will receive. FREE and IDEMPOTENT PER PARTICIPANT — the same participant_id signalling twice counts once and never double-fires the join. The barrier is a single Durable Object, so N simultaneous signals produce exactly one notification. A signal to a join that ALREADY FIRED on min_count is still recorded and reported in barrier_status, but it cannot fire a second notification — the joiner was already told, and was told exactly who was missing. A signal to a join that has TIMED OUT or passed its TTL is REFUSED with signalled:false, reason 'expired': your payload did NOT reach the joiner, so do not assume it did. That barrier_id is not locked — call barrier_create with it to open a new generation of the join. 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/barrier/signal.

Progress on a join point: how many of the expected participants have signalled, which ones, who is still outstanding, and whether the completion or timeout envelope has been queued. $0.002 ONLY when there is real progress to report (at least one signal) AND the answer has changed since you last paid for it — an untouched barrier, or a repeat of an answer you already bought, costs nothing and says so. Costs $0.002 USDC per call via x402 on Base, and ONLY when signals >= 1, and this exact progress state 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 headers. Equivalent HTTP route: POST /v1/barrier/status.

What this unit of work has actually cost across every session, with a per-label breakdown and a lifetime total. If a limit is set (or you pass one here) we report over_limit — WE REPORT, WE NEVER BLOCK: enforcement is the caller's decision and we will not pretend to an authority we do not have. Amounts come back byte-exact in the units you supplied. $0.002 ONLY when there is recorded history in the window; an empty ledger tells you so and costs nothing, and asking again for an unchanged total is free. Costs $0.002 USDC per call via x402 on Base, and ONLY when count >= 1 in the requested window, and this exact total 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 headers. Equivalent HTTP route: POST /v1/budget/check.

An agent cannot see its own spend across sessions, so runaway cost is invisible until the bill arrives. Append one amount to this scope's ledger. FREE and APPEND-ONLY — nothing is overwritten and nothing is silently dropped; when the ledger is full, adds are REFUSED. The amount is an OPAQUE DECIMAL STRING stored byte-exact as you send it: we never convert a currency, never assume six decimals and never touch a float. Totals are summed as exact integers at the widest scale you actually used. 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/budget/record.

Fetch the last checkpoint verbatim — what was stored, with no briefing composed around it. Most callers want resume_packet instead, which folds in what arrived while you were gone and what we observed you doing. $0.002 ONLY when a checkpoint exists AND its version has changed since you last paid for it — re-reading an unchanged checkpoint is free. If there is none we say so and charge nothing. Costs $0.002 USDC per call via x402 on Base, and ONLY when found === true, and this exact checkpoint version 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 headers. Equivalent HTTP route: POST /v1/checkpoint/get.

Save where the work got to, in a STRUCTURED shape so the next invocation can actually act on it. FREE. `objective` and `next_action` are REQUIRED and a checkpoint without them is refused — a vague checkpoint produces a vague briefing, so the schema is the guardrail. Work state is small: aim for a few kilobytes, not a transcript. The ENVELOPE (objective, next_action, status, files, risks and the rest) is cleartext and is what resume_packet synthesizes from. The BODY (`body`, `state`, `provider_extras`) is opaque — never parsed, indexed or logged in any mode. Set privacy_mode:'client_key' and encrypt the body yourself if it is sensitive; we then cannot read it and never hold your key. 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/checkpoint/put.

Exactly-once guard for work that costs money or has side effects. The first call for a key returns granted:true and is FREE. Every later call for that key returns granted:false with first_claimed_at and, if complete() was called, the stored result — so a retrying agent gets the answer instead of paying for the same paid API call twice. $0.002 is charged the FIRST time a key is denied (and again only if complete() has since attached a new result); repeated denials of the same unchanged fact are free. If we cannot determine the state we return granted:null and you must NOT proceed. Costs $0.002 USDC per call via x402 on Base, and ONLY when granted === false, and this exact denial 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 headers. Equivalent HTTP route: POST /v1/claim.

Attach the outcome to an idempotency CLAIM you hold — NOT for finishing a mailbox task (use inbox_ack) or a queue item (use work_done). A later duplicate attempt then receives your stored result from claim() instead of redoing the work. FREE — this is a write, and we never bill for storing. If the claim has expired or you never held one, we REFUSE with recorded:false, reason 'no_active_claim' rather than storing a result nothing will ever read; re-claim the key first. The result is an opaque blob: we never parse, index or log it. 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/complete.

AN AGENT CANNOT DETECT ITS OWN DEATH — from the inside, 'I stopped' and 'I am about to do the next step' are the same thing. Only something outside the process can tell them apart. Each call records a beat and arms a durable alarm for expect_within_seconds. Beat again in time and the alarm simply re-arms. Miss it and the expiry actions run EXACTLY ONCE: release_leases (the same release path a live agent uses), queue_alert (one envelope into a mailbox address you nominate), mark_failed (so resume_packet reports the death as an OBSERVED fact, not a self-report). FREE — it is a write. The alert is billed only when it is collected, by the existing inbox_poll first-delivery rule; there is no second charge. 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/heartbeat.

Acknowledge a task you finished. FREE and idempotent — acking twice is not an error. If the task was a repeating schedule, the next occurrence is queued now. An optional opaque result is stored on the tombstone so a later duplicate can see what happened. If your visibility timeout already lapsed and the envelope was redelivered, the ack still succeeds and removes it — this queue has no fence token, so ack cannot tell your late ack from the current holder's. Ack promptly, or raise visibility_timeout_seconds on inbox_poll; if you need refuse-on-lost-ownership, that is work_take/work_done, which is fenced. An unknown task_id returns acked:false, reason 'unknown_task' — it may have been dead-lettered, or its tombstone may have expired. 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/inbox/ack.

Explicitly return a claimed task to the queue instead of waiting for its visibility timeout, optionally deferring it. FREE. Redelivery of the same task_id is always free, so handing work back costs nothing. 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/inbox/nack.

Collect the next due task envelope from your mailbox. One envelope per call. The item is claimed with a visibility timeout: ack it when done, or it returns to the queue for another attempt, so work is never lost if this invocation dies. $0.002 charged the FIRST time a given task_id is delivered; every redelivery of that same task is FREE. Nothing due? We say so and charge nothing. Costs $0.002 USDC per call via x402 on Base, and ONLY when an envelope was delivered for the first time (redelivery is free); 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 headers. Equivalent HTTP route: POST /v1/inbox/poll.

Leave work for your own next invocation — the same as send() addressed to yourself. FREE. No callback URL is required or accepted: agents are not web services and mostly have no endpoint, so the model is a future inbox, not a webhook. Whenever your next invocation starts, inbox_poll finds this waiting. 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/inbox/schedule.

There is otherwise NO WAY TO TELL FIVE RUNNING AGENTS TO STOP — they finish and bill you for work you no longer want. This sets a durable stop flag on the job. FREE and idempotent. work_take on a cancelled job hands out nothing (and charges nothing), and should_continue answers 'no'. We do not kill anything: workers cooperate by checking, which is the only honest thing a service outside your process can offer. 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/job/cancel.

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 independently for every acquisition, so it is never 1, never a step from the fence you held last time, and not computable from any number of fences you have ever been given. Treat it as a secret — it is the one thing that tells you apart from another instance using your holder label. `generation` is the ORDER: a counter that strictly increases on every fresh acquisition and never resets, not on expiry and not on release. It is not a secret, it is the number to compare and the number to hand to an external store that must reject stale writers. A revived holder from an earlier generation therefore cannot renew or release a lease someone else now holds — not because its number is smaller, but because it does not have the new one. RE-ACQUIRING A LEASE YOU HOLD IS A RENEWAL ONLY IF YOU PRESENT ITS `fence` — a holder LABEL is not proof, because two instances of the same agent are exactly the callers most likely to share one, and we will not hand the same lock to both. A live lease requested under its own label without the fence is REFUSED with acquired:false, same_holder_label:true and held_by, never silently renewed. A renewal keeps your fence and stays free. $0.002 is charged the first time you are refused by a given holder; being refused again by the SAME holder is free. Costs $0.002 USDC per call via x402 on Base, and ONLY when acquired === false, and this refusal by this holder…

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 — 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/lease/release.

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 argument if your host cannot set headers. Equivalent HTTP route: POST /v1/lease/renew.

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 headers. Equivalent HTTP route: POST /v1/register.

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 only when there is a real packet to return AND that briefing has changed since you last paid for it — recomposing the same briefing is free. An empty scope tells you so and costs nothing. Costs $0.002 USDC per call via x402 on Base, and ONLY when the packet carries something — a checkpoint, new events since it, or server-observed facts — and this exact briefing 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 headers. Equivalent HTTP route: POST /v1/resume.

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 record:false to read the history without changing it. Costs $0.002 USDC per call via x402 on Base, and ONLY when attempts_before_call >= 1 (remembered history from an earlier session), and this exact attempt count 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 headers. Equivalent HTTP route: POST /v1/retry-state.

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 and settles nothing. 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/check.

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 filling someone's mailbox can never silence their safety notifications. 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/mail/send.

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 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 headers. Equivalent HTTP route: POST /v1/job/should-continue.

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 headers. Equivalent HTTP route: POST /v1/watermark/get.

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 <agent_secret>, or pass agent_key as an argument if your host cannot set headers. Equivalent HTTP route: POST /v1/work/done.

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 refused as not_holder, and a fence-less call on an item that has been handed out more than once is refused as fence_required — because accepting it would let a revived worker dead-letter an item another worker is processing right now. 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/work/fail.

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: Bearer <agent_secret>, or pass agent_key as an argument if your host cannot set headers. Equivalent HTTP route: POST /v1/work/push.

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 exact and never paged; the results and dead-letter ARRAYS are windowed at 50 rows each and hand you a page token when there is more, so every dead-lettered item is genuinely reachable rather than merely flagged as missing. Paging is free — you are charged per distinct progress state, not per page. Costs $0.002 USDC per call via x402 on Base, and ONLY when done + failed + dead_lettered >= 1, and this exact progress state 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 headers. Equivalent HTTP route: POST /v1/work/status.

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 it is not the previous holder's token plus one. The item's ORDER is `generation` (identical to `attempts`, the number of times it has been handed out) — that is the number to compare and the number to hand to an external store; the fence is the secret. $0.002 when at least one item is handed to you for the FIRST time; a re-take after your own lease expired is free, exactly like mailbox redelivery. An empty or cancelled queue returns nothing, says so, and costs nothing. Costs $0.002 USDC per call via x402 on Base, and ONLY when at least one item was handed to a worker for the FIRST time (a re-take after a lease expired is free); 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 headers. Equivalent HTTP route: POST /v1/work/take.