com.mcpscores/agent-continuity

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 nev…

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. Po…

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 pa…

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…

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 ref…

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…

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 loc…

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 — t…

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 f…

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 fo…

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…

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.0…

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 n…

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 questi…

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…

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…

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 wait…

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; ev…

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 an…

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 p…

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 r…

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…

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. Amo…

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 partici…

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…

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 pai…

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…

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 R…

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 th…

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…

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.…

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…

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 i…