make-agent-idempotent-and-adapter-ported

Implements deterministic id generation and three-adapter ports for at-least-once Cloudflare Queue consumers.

Updated Jul 9, 2026
One-click install
npx skills add https://github.com/shuddl/shuddl-os --skill make-agent-idempotent-and-adapter-ported-shuddl
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: make-agent-idempotent-and-adapter-ported
Source: https://github.com/shuddl/shuddl-os/tree/main/.claude/skills/make-agent-idempotent-and-adapter-ported
Command: npx skills add https://github.com/shuddl/shuddl-os --skill make-agent-idempotent-and-adapter-ported-shuddl

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Cloudflare Queues deliver messages at-least-once, so any non-deterministic id or clock read in an agent core causes duplicate invoices, double-sent emails, and broken dedupe on redelivery. This Skill encodes the exact recipe that makes redelivery safe: deterministic ids derived from the trigger event, layered dedupe defenses, and a three-adapter port for every external vendor seam. ## Core Features & Use Cases - Deterministic id recipe: A domain-separated SHA-256 shaped into a v4-variant UUID for event ids, plus prefix_<16hex> shapes for shipment, party, and invoice ids, so a redelivered trigger reproduces identical primary keys. - Three-adapter port pattern: One Zod boundary with Deterministic, NotConfigured (loud, retriable rejection), and Live (raw fetch, injected secrets, no vendor SDK) adapters, selected only by the composition root. - Typed retriable error contract: SendError/ParseError carry retriable and status fields so the consumer routes retries without regexing provider error messages, and poison messages are acked with a loud log. - Use Case: When adding a new queue consumer in workers/agents/ or wiring a Resend/Anthropic/Stripe adapter, apply this recipe so redelivery fast-paths from committed events instead of re-judging or double-sending. ## Quick Start Use this skill to make my new queue consumer agent idempotent with deterministic event ids and a three-adapter port for its email sender.

Frequently Asked Questions about make-agent-idempotent-and-adapter-ported

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I make a Cloudflare Queue consumer idempotent?▼

Derive every id as a pure function of the trigger event id using a domain-separated SHA-256 shaped into a v4-variant UUID, take timestamps from the event's recorded_at, and add INSERT OR IGNORE plus a committed-terminal-event guard so redelivery fast-paths instead of double-writing.

How do I generate deterministic UUIDs from a SHA-256 hash?▼

Hash a domain-tagged string like `agent:domain:triggerEventId`, take the first 32 hex chars, force the version nibble to 4, and set the variant bits with (x & 0x3) | 0x8 so the result passes z.string().uuid() validation.

Should I use the Anthropic or Resend SDK inside a Cloudflare Worker?▼

No. Use a raw fetch to the vendor REST endpoint, because vendor SDKs are not reliably worker-runtime-safe and they hide the retriable verdict. Inject the API key via the adapter constructor from the composition root, never read env inside the adapter.

How do I handle retriable versus poison queue messages?▼

Throw typed errors carrying retriable and status fields, then route on those fields: retriable with 429 gets retry with delaySeconds, other retriable errors get plain retry, and poison messages like unknown tenants are acked with a loud log since redelivery cannot fix a bad shape.

When should this idempotency recipe not be applied?▼

Do not apply it in packages/ledger, where LLM and vendor calls are statically forbidden by REQ-024. It targets agent cores and their external seams in workers/agents and packages/agents, not the ledger itself.