Bezel API api_lite_claim_contract
api_lite_claim_contract artifact · for Bezel API · status draft
api_lite_claim_contract artifact · for Bezel API · status draft
No explicit evidence field yet. Require tests, screenshots, linked PRs, or reviewed outputs before marking complete.
- mode: lite
- product: Bezel API
- purpose: Define the MVP claim-only coordination contract. Lite stores customer work data in DB/storage and uses HCS only to arbitrate/prove claims.
- version: 0.1
- state changes: claimed: object, no_tasks: object, rejected: object
- bounded attempts: rationale: string, default_limit: number, response_when_exhausted: string
- lite hcs message: principle: string, allowed_fields: object, forbidden_fields: object, proof_fields_projected_to_db: object
- primary endpoint: auth: string, path: string, method: string, request: object, responses: object
- direct task claim: note: string, path: string, status: string, use_cases: object
- idempotency rules: 4 items
- db selection rules: 6 items
- privacy tests required: 6 items
Machine-readable source fields
lite
Bezel API
Define the MVP claim-only coordination contract. Lite stores customer work data in DB/storage and uses HCS only to arbitrate/prove claims.
0.1
- insert claims row
- tasks.status = claimed
- tasks.claimed_by = agent_id
- tasks.claim_id = claim_id
- claims.hcs_proof = proof object
- usage_events records claim arbitration write
- no HCS write if no candidate was attempted
- optional poll metric only
- no HCS write unless rejection follows a submitted claim race; auth/policy rejection is DB/API only
Avoid claim-next spinning through a large queue during contention while still hiding ordinary missed races from agent clients.
3
no_tasks with short backoff or rejected:rate_limited if contention/rate policy requires it
HCS contains only claim arbitration/proof data. It must be useless as a task data leak.
producer timestamp
lite_claim_v1
role_* or hash/commitment depending privacy policy
task_* or opaque task commitment id; no title/input/brief
agt_* or agent commitment id
clm_*
queue_* or hash/commitment depending privacy policy
integer
integer
hash/workspace commitment or workspace_id if acceptable for product policy
sha256 of idempotency key
- task_title
- task_brief
- brief_ref
- task_input
- plan_json
- workflow_name
- dependency_graph
- artifact_ref
- artifact_body
- completion_summary
- model_output
- logs
- secrets
- private_memory
- topic_id
- sequence_number
- consensus_timestamp
- running_hash
- transaction_id
- claim_id
- task_id
- agent_id
workspace-scoped API key with agent:runtime scope
/queues/:queueId/claim-next
POST
agt_* required
role_*[] optional; defaults to roles assigned to agent in workspace
integer optional; defaults from role/queue policy
string required; unique per agent claim-next attempt unless intentionally replaying
task brief loaded from DB/storage after claim win
task input loaded from DB/storage after claim win
claimed
evt_*
string optional
pending|verified
task_*
clm_*
ISO timestamp
no_tasks
agt_*
queue_*
integer backoff hint
inactive_agent|unauthorized_scope|queue_not_found|agent_not_in_workspace|role_not_assigned|missing_capability|invalid_lease|rate_limited|idempotency_conflict
rejected
boolean
integer optional
Can return missed directly. Normal agents should use claim-next.
POST /tasks/:taskId/claim
secondary
- debugging
- UI explicit claim
- specific task assignment
- test fixtures
- Same workspace_id + agent_id + queue_id + idempotency_key returns the same terminal claim-next result while idempotency record is retained.
- If first request returned claimed, replay returns the same claim/task lease if still valid, otherwise returns idempotency_conflict with retry guidance.
- If first request returned no_tasks, replay returns the same no_tasks for a short TTL to prevent rapid duplicate polling.
- If request body conflicts for an existing idempotency key, return rejected:idempotency_conflict.
- Resolve workspace from API key and queue_id; reject cross-workspace access.
- Load agent and verify active status, workspace membership, and role assignment.
- Resolve candidate roles from request.role_ids intersected with assigned roles; if omitted use all assigned roles eligible for the queue.
- Find available tasks in DB where queue_id matches, required_role_id is in eligible roles, dependencies are satisfied, status is available, and required capabilities are covered by the agent snapshot.
- Order candidates by priority desc, created_at asc, then stable task id asc unless queue policy says otherwise.
- Do not return task details until claim arbitration has been won.
- Lite HCS message schema rejects task_title.
- Lite HCS message schema rejects task_input.
- Lite HCS message schema rejects brief_ref.
- Lite HCS message schema rejects plan_json.
- Lite HCS message schema rejects artifact_ref and completion_summary.
- Claimed API response can include task details only after DB claim state and HCS proof are recorded.
- claim-next returns claimed for an eligible agent with one available task.
- claim-next returns no_tasks when no eligible task exists and performs no HCS write.
- claim-next returns rejected for inactive agent and performs no HCS write.
- claim-next returns rejected for role/capability mismatch and performs no HCS write.
- claim-next attempts next candidate after an internal missed race and returns claimed when the second candidate wins.
- claim-next stops after bounded_attempt_limit and returns no_tasks/backoff.
- idempotency replay returns same claimed result.
- conflicting idempotency replay returns rejected:idempotency_conflict.
- cross-workspace queue/agent/task access is rejected before HCS write.
- Create or reuse idempotency record for claim-next request.
- Select first eligible DB candidate task according to queue policy.
- Submit minimal lite claim message to the role HCS topic for the task required role.
- Determine whether this claim is the winner by HCS topic ordering and task current claim state.
- If winner, create claims row, set task status claimed, store HCS proof, and return task details from DB/storage.
- If missed because another claim won, record internal miss and try next eligible candidate until bounded_attempt_limit is reached.
- If no candidate can be won, return no_tasks with backoff.
- If policy/auth/capability validation fails, return rejected and do not write HCS.