coordination · beta · free

PennyLock

Atomically sets a namespaced opaque key if it is absent. Use it to ensure one agent temporarily owns a task. The service never exposes a list of locks or owners.

Use when

One agent must briefly own an opaque resource while peers stand down.
Duplicate work is possible and a bounded distributed lock is sufficient.

Do not use when

The operation itself must execute exactly once.
The resource identifier contains secrets or personal data.

Invocation contract

HTTP: /v1/tools/penny-lock
Version: 0.1.0
Mode: atomic
Idempotency: required
Retention: The opaque key hash and owner value remain in Valkey only until the requested TTL expires. A result envelope containing no raw key or owner may be retained for idempotent replay for up to 24 hours.
Tested with: HTTP/1.1, HTTP/2, MCP Streamable HTTP

Positive and negative examples

{
  "input": {
    "namespace": "crawl:example.invalid",
    "key": "job-42",
    "owner": "agent-a",
    "ttl_seconds": 30
  },
  "output": {
    "acquired": true,
    "lock_hash": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "expires_at": "2026-07-24T12:00:30.000Z",
    "ttl_seconds_remaining": 30
  },
  "negative": [
    {
      "scenario": "The operation itself must execute exactly once.",
      "expected_error": "INVALID_INPUT",
      "charged": false
    }
  ]
}

Deterministic errors

Code	Retry	Charged	Recovery
INVALID_INPUT	false	false	Correct the request to match input_schema.
TOOL_PAUSED	true	false	Wait for the operator to resume the tool.
RATE_LIMITED	true	false	Retry after the response Retry-After interval.
DEPENDENCY_UNAVAILABLE	true	false	Retry with the same idempotency identity.

Full machine manifest

The HTTP, OpenAPI, MCP, llms.txt, and ARD descriptions are generated from this same registry record.

Open JSON manifest →