Connection check
verified live · 28h ago
ratchet
An effect gate for AI agents: at-most-once side effects, spend limits, and signed receipts.
Tools
15
GitHub stars
—
Installs / wk
—
Licence
Apache-2.0
Transport
streamable-http, stdio
Last checked
28h ago
Tools & capabilities
15 toolsRead from the running server on 28h ago.
ratchet_begin_effect
run_idvendorpayloadagent_idgroup_keydimensions
+6
Call this IMMEDIATELY BEFORE performing any side effect that touches the outside world (sending a message, charging a card, creating a resource, writing to someone else's system).… Call this IMMEDIATELY BEFORE performing any side effect that touches the outside world (sending a message, charging a card, creating a resource, writing to someone else's system). Returns a decision you MUST obey. If the response carries budget_warning, a spend ceiling exists but nothing was counted toward it — surface that to the operator rather than ignoring it. If it carries integration_warning, you have been beginning effects without reporting them: call ratchet_report_effect after every action, and tell the operator, because the effects already begun will start being blocked. Decisions: - "execute": you hold the lease. Perform the action now, then call ratchet_report_effect. If the response carries vendor_idempotency_key, send that key to the vendor as ITS own idempotency key (the response says where it goes). Where enforced is true the vendor itself will then refuse a duplicate, which protects the action even if some other caller skips this gate entirely. - "duplicate": this action ALREADY HAPPENED. Do NOT perform it. Use the returned `result` as though you had just done the work. - "in_flight": another process is doing it right now. Do NOT perform it. Wait `retry_after_seconds` and ask again. - "blocked": an earlier attempt may or may not have taken effect. Do NOT perform it. Tell the user what is unresolved, or verify at the vendor and call ratchet_resolve_effect. - "approval_required": a human must approve. Do NOT perform it. - "denied": policy or budget refused it. Do NOT perform it. The idempotency_key must be derived deterministically from the work itself so that a retry of the same logical action produces the same key. Never use a random value or the current time.
ratchet_extend_lease
effect_id*lease_token*extend_seconds
Call this periodically during a long action you were authorised to perform, before the lease expires. It tells Ratchet you are alive and extends your hold. Use it when work turns o… Call this periodically during a long action you were authorised to perform, before the lease expires. It tells Ratchet you are alive and extends your hold. Use it when work turns out to take longer than the lease you asked for — a slow vendor, a large export, a retrying upload. Without it, the lease expires while you are still working, the effect is recorded as having an UNKNOWN outcome, and your report is then refused. If it fails with lease_expired or lease_lost, STOP. Your hold is gone and the outcome is already recorded as unknown. Do not keep going and do not retry the action — call ratchet_begin_effect to find out where things actually stand.
ratchet_get_circuit
read-only
Call this when a begin returned "approval_required" or "denied" and the reason mentions a circuit breaker. A breaker opens when an effect type is being performed far more often tha… Call this when a begin returned "approval_required" or "denied" and the reason mentions a circuit breaker. A breaker opens when an effect type is being performed far more often than its configured hourly ceiling — usually because something is looping. What to do with the answer: - If a breaker is open, STOP creating effects of that type. Retrying will not help and each attempt is recorded. - resets_at tells you when it closes itself. If it is null, a human opened it deliberately and only a human will close it — do not wait, and do not poll. - Report the reason to your operator and stop. Do not attempt to work around it by renaming the effect type, splitting the work across keys, or using a different idempotency key: that defeats a safety control that exists to protect the people your actions reach. - effect_type "*" means every effect type in the workspace is stopped.
ratchet_get_effect
read-only
effect_type*idempotency_key*
Look up the recorded state of an action WITHOUT reserving a lease and without consuming your plan allowance. Use it to answer "did I already do this?" — for example when resuming a… Look up the recorded state of an action WITHOUT reserving a lease and without consuming your plan allowance. Use it to answer "did I already do this?" — for example when resuming after a crash, or when a user asks whether something went through. To actually perform work, use ratchet_begin_effect instead; this tool never grants permission.
ratchet_get_group
read-only
group_key*
Shows every step in a multi-step unit of work: what succeeded, what can still be undone, what has already been undone, what is irreversible, and what has an unknown outcome. Use it… Shows every step in a multi-step unit of work: what succeeded, what can still be undone, what has already been undone, what is irreversible, and what has an unknown outcome. Use it to answer "where did this workflow actually get to?" after a crash, without changing anything.
ratchet_get_policy
read-only
effect_type*
Shows how this workspace has configured a given effect type: whether it is allowed, how long a lease lasts, the attempt ceiling, spend limits, the approval threshold above which an… Shows how this workspace has configured a given effect type: whether it is allowed, how long a lease lasts, the attempt ceiling, spend limits, the approval threshold above which an action waits for a human, and — most importantly — what happens when an attempt ends indeterminate. Check this before designing a retry strategy.
ratchet_get_prevented_loss
read-only
Counts duplicate actions refused in the last 30 days and what they would have cost. Only counts refusals where a cost was declared on the effect, so it under-reports rather than fl… Counts duplicate actions refused in the last 30 days and what they would have cost. Only counts refusals where a cost was declared on the effect, so it under-reports rather than flatters. IMPORTANT: pass estimated_cost_micros on ratchet_begin_effect or this reads zero — the number is only as good as what callers declare. This is money not spent at your vendors, never money paid to Ratchet.
ratchet_get_run
read-only
run_id*
Recall the work already gated under a run id, before doing anything that might repeat it. Call this FIRST when resuming a task — after a restart, a handoff, or when your context ha… Recall the work already gated under a run id, before doing anything that might repeat it. Call this FIRST when resuming a task — after a restart, a handoff, or when your context has been compacted and you are no longer certain what you did. It returns what succeeded with the recorded results, what is still in flight, what failed, and — separately, because it is the only category that can hurt you — what has an unknown outcome. Anything under "done" has already happened: use its result rather than performing it again. Costs about a seventeenth of the context of listing the same effects.
ratchet_get_usage
read-only
Returns the current plan, remaining included effects for the month, prepaid credit balance, and today's declared external spend against each budget ceiling. Use it to warn a user b… Returns the current plan, remaining included effects for the month, prepaid credit balance, and today's declared external spend against each budget ceiling. Use it to warn a user before a long run exhausts an allowance or a budget.
ratchet_list_effects
read-only
limitstaterun_ideffect_type
Review recent effects for this workspace, optionally filtered by state or run. Use it to find unresolved work — filter by state "indeterminate" to see every action whose outcome is… Review recent effects for this workspace, optionally filtered by state or run. Use it to find unresolved work — filter by state "indeterminate" to see every action whose outcome is unknown and still needs verification.
ratchet_list_receipts
read-only
effect_id*
Returns a signed receipt for every decision made about one effect, refusals included. Each signature is over the exact bytes in `body` and verifies offline against the Ed25519 key… Returns a signed receipt for every decision made about one effect, refusals included. Each signature is over the exact bytes in `body` and verifies offline against the Ed25519 key published at /.well-known/ratchet-receipt-key — you do not have to trust this server to check them. Use this when a human asks you to PROVE an action was or was not authorised, rather than asserting it.
ratchet_reconcile_effects
read-only
keys*effect_type*
Given the idempotency keys for actions a vendor says actually happened, returns which ones went through Ratchet and which it has never seen. The unseen ones are code paths that act… Given the idempotency keys for actions a vendor says actually happened, returns which ones went through Ratchet and which it has never seen. The unseen ones are code paths that acted WITHOUT asking, so a retry there can act twice — a bug the operator almost certainly does not know about. Send references only; never send credentials.
ratchet_report_effect
resultoutcome*effect_id*lease_token*failure_reasonactual_cost_micros
Call this IMMEDIATELY AFTER performing an action that ratchet_begin_effect authorised. Pass the lease_token you were given. Report "succeeded" with a result — future duplicate call… Call this IMMEDIATELY AFTER performing an action that ratchet_begin_effect authorised. Pass the lease_token you were given. Report "succeeded" with a result — future duplicate callers replay that result instead of repeating the action. Report "failed" ONLY when you are certain the action did NOT reach the outside world (for example, a validation error before the request was sent). That permits a clean retry. If you are UNSURE whether it went through — a timeout, a dropped connection, an ambiguous error — do NOT report anything. Say so to the user. Letting the lease lapse records an honest "indeterminate", which is far safer than a false "failed" that licenses a duplicate.
ratchet_resolve_effect
resultoutcome*evidenceeffect_id*
Use ONLY after you have checked the third-party system and now know what really happened to an effect that was left "indeterminate". Record "succeeded" if the action did occur, "fa… Use ONLY after you have checked the third-party system and now know what really happened to an effect that was left "indeterminate". Record "succeeded" if the action did occur, "failed" if it did not, or "cancelled" to abandon it. Include how you verified it in `evidence`. Never guess: resolving incorrectly is exactly the duplicate or lost action this service exists to prevent.
ratchet_unwind_group
reasongroup_key*