Bezel API api_role_topic_coordination_model
internal prototype · canonical JSON + Dreamborn Forge HTML
internal generated
api_role_topic_coordination_model · supabase_json

Bezel API api_role_topic_coordination_model

api_role_topic_coordination_model artifact · for Bezel API · status draft

Planning Surface

Use this to decide what happens next.

Status

draft

Agent Handoff
Start Here

api_role_topic_coordination_model artifact · for Bezel API · status draft

Completion Evidence

No explicit evidence field yet. Require tests, screenshots, linked PRs, or reviewed outputs before marking complete.

Artifact Shape
  • deferred: 2 items
  • examples: 3 items
  • rationale: Role topics are where claim contention happens. Agents race only with agents eligible for the same role.
  • product modes: lite: object, verified: object
  • optional later: 3 items
  • claim responses: missed: string, claimed: string, no_tasks: string, rejected: string
  • agent runtime loop: flow: object, primary_endpoint: string, direct_task_claim: string, normal_agent_responses: object
  • hcs topic decision: one HCS topic per workspace role in v1
  • lite hcs claiming model: decision: string, task_storage: string, claim_next_flow: object, hcs_role_topic_contains: object, hcs_role_topic_must_not_contain: object
  • verified hcs lifecycle model: decision: string, hcs_contains: object, still_forbidden: object
Structured Payload

Machine-readable source fields

deferred
  • shared multi-tenant role topics
  • direct topic management exposed to normal users
examples
  • wk_acme.roles.researcher -> topic 0.0.x
  • wk_acme.roles.writer -> topic 0.0.y
  • wk_beta.roles.researcher -> topic 0.0.z
rationale

Role topics are where claim contention happens. Agents race only with agents eligible for the same role.

product modes
lite
value

Lowest-friction hosted coordination: verified claim races without publishing customer task data to HCS.

principle

Use HCS only for claim arbitration/proof. Do not store task briefs, task details, plan details, lifecycle summaries, or artifact details in HCS.

db content
  • workspace
  • roles
  • agents
  • queues
  • workflow_definitions.plan_json
  • workflow_runs
  • tasks
  • claims read model
  • artifacts
  • usage
hcs content
  • claim_attempted minimal commitment
  • claim_won/claim_result proof metadata or minimal claim decision
  • optional receipt anchor
verified
value

Full verified ledger replay for higher-trust/enterprise workflows.

principle

Use Agent Wire v1.1 for broader lifecycle/task/artifact reference events on HCS.

hcs content
  • task.created/available refs
  • claim lifecycle
  • artifact.ready refs
  • task.complete/fail summaries and verification refs
  • workflow/reducer events
optional later
  • workspace ledger/index topic
  • per-queue topics for high-volume or enterprise isolation
  • customer-owned HCS account/topics
claim responses
missed

internal or direct-task-claim outcome when an eligible claim attempt lost to another valid claim; claim-next should usually continue to next candidate before responding

claimed

agent won the claim race and owns returned task lease

no tasks

no eligible task is currently available for this agent/role/queue; not written to HCS

rejected

agent/runtime request is invalid or not eligible

agent runtime loop
flow
  • Agent wakes up or receives schedule tick.
  • Agent calls claim-next with agent_id, optional role_ids, lease_seconds, and idempotency_key.
  • API finds the next eligible available task for the agent from DB/read model and role-topic state.
  • API attempts the HCS-backed claim on behalf of that agent.
  • If claim wins, API returns claimed with task brief/ref and lease.
  • If a candidate task is lost during the race, API records that miss internally and tries the next eligible candidate within bounded attempt limits.
  • If no claimable task remains, API returns no_tasks with backoff guidance.
  • If the agent is inactive, unauthorized, missing required capability, or invalid for the queue, API returns rejected with reason.
primary endpoint

POST /queues/:queueId/claim-next

direct task claim

POST /tasks/:taskId/claim remains for UI/debug/specific assignment. It is not the default polling loop.

normal agent responses
claimed

Do the returned task.

no tasks

Sleep/backoff or keep watching role topic.

rejected

Stop, refresh registration/config, or report the reason.

hcs topic decision

one HCS topic per workspace role in v1

lite hcs claiming model
decision

Lite role topics are claim arbitration topics, not task information topics.

task storage

Tasks, dependencies, plan_json, inputs, outputs, and artifact refs live in Bezel DB/storage only.

claim next flow
  • API finds eligible available task in DB.
  • API submits minimal HCS claim arbitration message without task details.
  • HCS ordering/proof determines winner.
  • If won, API returns full task brief/details from DB to winning agent over authenticated API response.
  • If lost, API can try another DB-eligible task within bounded attempts.
  • If none won, API returns no_tasks/backoff.
hcs role topic contains
  • minimal claim candidate or task commitment id
  • agent claim attempt with task_id or opaque claim target id
  • claim result/winner proof
  • HCS sequence/consensus timestamp for arbitration
hcs role topic must not contain
  • task title
  • task brief
  • task input
  • plan_json
  • dependency graph details
  • artifact contents/details
  • completion summaries
  • customer secrets
verified hcs lifecycle model
decision

Bigger paid/verified version may use full Agent Wire v1.1 lifecycle events on HCS.

hcs contains
  • task lifecycle refs
  • artifact refs/hashes
  • completion verification refs
  • workflow reducer events
still forbidden
  • raw model logs
  • large bodies
  • secrets
  • private memory