Idempotency Key Manager for Agent Actions

An agent retries a tool call after a timeout, a dropped connection, or its own re-planning. Without an idempotency key the action runs twice -- two charges, two emails, two rows.

WITH A BADLY DERIVED KEY IT IS WORSE. A key that includes a timestamp or a random value NEVER matches on retry, so it protects nothing while appearing to. A key that is too coarse collides between genuinely different actions, so the second is silently dropped as a duplicate and never runs at all. The first over-charges; the second silently loses work. Both look fine from outside.

KEYS ARE DERIVED FROM SEMANTIC CONTENT ONLY -- the operation and its arguments, canonicalised first so key order and insignificant formatting cannot change the hash. Never a timestamp, never a random value, never a request id. That single rule is what makes the mechanism real rather than decorative.

THREE STATES ARE KEPT DISTINCT: never seen, in flight, and completed. A replay of an in-flight action must not re-execute and must not return a wrong answer -- it reports in-flight so the caller can wait or fail deliberately. A completed key returns the ORIGINAL RESULT rather than re-running, which means the outcome is recorded against the key, not merely the fact of an attempt.

Scoped per organization or per agent, so two tenants performing the same action do not collide. In-memory store with TTL behind a small interface, so a real backing store drops in without touching the derivation. Clock injected; fully deterministic.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function canonicalize(value: unknown): string;
  export function deriveKey(action: ActionInput): string;
  export function scopeOrg(id: string): Scope;
  export function scopeAgent(id: string): Scope;
  export function serializeError(err: unknown): SerializedError;

  export type RunResult<T> = | { readonly key: string;
  export type Scope = | { readonly kind: "org";
  export type Outcome<T = unknown> = | { readonly ok: true;
  export type RecordStatus = "in_flight" | "completed";