{"ok":true,"tool":"swarm-semaphore","module_version":"0.2.0","result":{"slug":"swarm-semaphore","name":"Swarm Semaphore","version":"0.2.0","category":"coordination","status":"beta","mode":"atomic","summary":"Bound concurrent agent work with an opaque distributed semaphore.","description":"Atomically admits up to a declared capacity of holders. Each holder permit expires independently, can be renewed idempotently, and can be released without exposing holder identities.","when_to_use":["A bounded number of agents may work on the same resource concurrently.","Each holder needs an independently expiring permit."],"do_not_use_when":["Exactly one agent must own the resource; use PennyLock instead.","The holder identifier contains secrets or personal data."],"tested_with":["HTTP/1.1","HTTP/2","MCP Streamable HTTP"],"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","oneOf":[{"type":"object","properties":{"namespace":{"type":"string","minLength":38,"maxLength":77,"pattern":"^[a-zA-Z0-9._-]{1,40}:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Private workflow namespace formatted as <scope>:<fresh UUID v4>. Generate a new UUID for each independent workflow and share it only with participating agents."},"key":{"type":"string","minLength":1,"maxLength":256},"capacity":{"type":"integer","minimum":1,"maximum":100},"holder":{"type":"string","minLength":1,"maxLength":128},"ttl_seconds":{"type":"integer","minimum":1,"maximum":3600},"action":{"type":"string","const":"acquire"}},"required":["namespace","key","capacity","holder","ttl_seconds","action"],"additionalProperties":false},{"type":"object","properties":{"namespace":{"type":"string","minLength":38,"maxLength":77,"pattern":"^[a-zA-Z0-9._-]{1,40}:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Private workflow namespace formatted as <scope>:<fresh UUID v4>. Generate a new UUID for each independent workflow and share it only with participating agents."},"key":{"type":"string","minLength":1,"maxLength":256},"capacity":{"type":"integer","minimum":1,"maximum":100},"holder":{"type":"string","minLength":1,"maxLength":128},"action":{"type":"string","const":"release"}},"required":["namespace","key","capacity","holder","action"],"additionalProperties":false},{"type":"object","properties":{"namespace":{"type":"string","minLength":38,"maxLength":77,"pattern":"^[a-zA-Z0-9._-]{1,40}:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Private workflow namespace formatted as <scope>:<fresh UUID v4>. Generate a new UUID for each independent workflow and share it only with participating agents."},"key":{"type":"string","minLength":1,"maxLength":256},"capacity":{"type":"integer","minimum":1,"maximum":100},"action":{"type":"string","const":"status"}},"required":["namespace","key","capacity","action"],"additionalProperties":false}]},"output_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"action":{"type":"string","enum":["acquire","release","status"]},"semaphore_hash":{"type":"string"},"configuration_matches":{"type":"boolean"},"capacity":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"active_holders":{"type":"integer","minimum":0,"maximum":9007199254740991},"available_permits":{"type":"integer","minimum":0,"maximum":9007199254740991},"acquired":{"type":"boolean"},"released":{"type":"boolean"},"already_held":{"type":"boolean"},"next_expiration_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"holder_expiration_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]}},"required":["action","semaphore_hash","configuration_matches","capacity","active_holders","available_permits","acquired","released","already_held","next_expiration_at","holder_expiration_at"],"additionalProperties":false},"payment":{"kind":"free"},"side_effects":["Acquire creates or renews a temporary holder permit.","Release removes the caller's temporary holder permit."],"retention":"Only hashes of the namespace, key, and holder remain in Valkey until their bounded TTLs expire. Raw identifiers are never returned or persisted in the execution ledger.","limits":{"max_capacity":100,"max_ttl_seconds":3600,"max_key_bytes":256,"max_client_requests_per_minute":30,"max_global_requests_per_minute":120},"examples":{"input":{"action":"acquire","namespace":"crawl:0c4ff3d6-ff17-411b-b275-df53ab85f431","key":"render-workers","capacity":3,"holder":"agent-a","ttl_seconds":30},"output":{"action":"acquire","semaphore_hash":"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","configuration_matches":true,"capacity":3,"active_holders":1,"available_permits":2,"acquired":true,"released":false,"already_held":false,"next_expiration_at":"2026-07-24T12:00:30.000Z","holder_expiration_at":"2026-07-24T12:00:30.000Z"},"negative":[{"scenario":"Exactly one agent must own the resource; use PennyLock instead.","expected_error":"INVALID_INPUT","charged":false}]},"execution":{"errors":[{"code":"INVALID_INPUT","retryable":false,"charged":false,"recovery":"Correct the request to match input_schema."},{"code":"TOOL_PAUSED","retryable":true,"charged":false,"recovery":"Wait for the operator to resume the tool."},{"code":"RATE_LIMITED","retryable":true,"charged":false,"recovery":"Retry after the response Retry-After interval."},{"code":"DEPENDENCY_UNAVAILABLE","retryable":true,"charged":false,"recovery":"Retry with the same idempotency identity."}],"idempotency":{"required":true,"mock_or_unpaid_header":"Idempotency-Key","x402_extension":null,"replay_retention":"up to 24 hours"}},"endpoints":{"describe":"/v1/tools/swarm-semaphore","execute":"/v1/tools/swarm-semaphore"}},"meta":{"request_id":"req_dbb97fba4e8f4ec5bcbebdd0f8ae43ad","observed_at":"2026-09-08T07:42:04.043Z"}}