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

Bezel API api_agent_wire_contract

api_agent_wire_contract artifact · for Bezel API · status draft

Planning Surface

Use this to decide what happens next.

Status

draft

Agent Handoff
Start Here

api_agent_wire_contract artifact · for Bezel API · status draft

Completion Evidence

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

Decision

Bezel API adopts the existing RedKey Agent Wire v1.1 hardening work as its customer task wire baseline. Do not invent a separate Bezel wire protocol.

Structured Payload

Machine-readable source fields

product

Bezel API

version

0.1

decision

Bezel API adopts the existing RedKey Agent Wire v1.1 hardening work as its customer task wire baseline. Do not invent a separate Bezel wire protocol.

lite profile
decision

Lite does not submit full Agent Wire task.created/task.available/task.complete details to HCS. Agent Wire contracts still govern internal DB events and validation, but HCS payloads are reduced to minimal claim arbitration/proof.

hcs allowed
  • minimal claim attempt
  • minimal claim result/winner proof
  • receipt anchor
hcs forbidden
  • task title
  • brief_ref if it reveals task data
  • task input
  • plan_ref/plan_json
  • artifact_ref/details
  • task completion summary
api response after claim

Winning agent receives task details from Bezel API/DB after claim is proven, not from HCS.

bezel profile
compatibility rule

Core event body remains Agent Wire v1.1-compatible. Bezel-specific customer/product fields live in extensions.bezel until Agent Wire v1.2 formally adds tenant/workflow fields.

required extension

extensions.bezel

extension fields for customer tasks
queue id

queue_* coordination domain. Required for task.created/task.available.

plan task id

stable task id from customer plan.json when plan-derived.

workspace id

wk_* tenant boundary. Required for all Bezel customer runtime task events.

api actor scope

human session scope or API key scope that authorized the event.

idempotency key

required on externally-originated create/claim actions.

workflow run id

wfr_* when task belongs to a workflow run.

required artifacts

artifact contracts the task must satisfy before completion.

dependency task ids

materialized upstream task ids or plan_task_ids.

required capabilities

capability ids used for claim eligibility.

workflow definition id

wfd_* when task came from customer plan.json.

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
receipt policy
customer api

Normal API users see receipt status and receipt URL. Raw HCS metadata can be shown in receipt detail but is not required for ordinary coordination calls.

receipt maps

event_id -> wire_id -> stream_id -> stream_seq -> HCS topic_id -> sequence_number -> consensus_timestamp

artifact policy
storage

Large artifact bodies stay in storage chosen by the product/customer. HCS carries refs and hashes only.

declaration

Required artifacts are declared before dispatch from plan.json or simple task contract.

ready event

artifact.ready carries artifact_id, artifact_type, artifact_ref, version, hash when available, and task_id.

completion gate

task.complete must reference all required final artifact ids and include verification.mechanical=pass.

open schema gap

Existing v1.1 RedKey schemas currently require client_id/role/brief_ref and do not require Bezel workspace_id/workflow_run_id/plan_task_id in the core payload. Bezel v1 should extend through extensions.bezel rather than fork the core schema.

source contracts
tests
  • tests/conformance/agent-wire/*
  • tests/reducers/agent-wire/*
schemas

schemas/agent-wire/v1.1/*.schema.json

fixtures

fixtures/agent-wire/v1.1/*.json

contracts

contracts/agent-wire/v1.1/*.json

hardening spec

docs/specs/2026-05-06-agent-wire-v1-1-a2a-hardening.md

deterministic standard

docs/specs/2026-05-06-deterministic-spec-artifact-standard.md

verified profile
baseline

contracts/agent-wire/v1.1/hcs-transport-contract.json

decision

Verified/Pro mode uses full Agent Wire v1.1 HCS transport contract for lifecycle/replay.

task event policy
claim next

Primary agent runtime operation is claim-next: API selects the next eligible available task and attempts claim on behalf of the agent. Misses during candidate selection are internal observability unless no task can be claimed or the caller used direct task claim.

claim attempts

Claim attempts must include agent id, lease seconds, idempotency key, and capability snapshot. Outcomes are claimed, missed, or rejected.

direct task claim

Direct task claim remains supported for explicit task IDs, UI/debug flows, and specific assignments. It can return claimed, missed, or rejected.

simple role tasks

May emit task.created and task.available without workflow_definition_id/workflow_run_id/plan_task_id, but must include workspace_id, queue_id, role, brief_ref, and Bezel idempotency metadata.

missed vs rejected

missed means eligible but another valid claim won; rejected means not eligible, invalid lease, inactive agent, missing capability, unsatisfied dependency, or invalid task state.

plan derived tasks

Must include workflow_definition_id, workflow_run_id, plan_task_id, dependencies, required_role, required_capabilities, acceptance criteria, and required artifact contracts.

adopted invariants
  • Every HCS submit body must be a valid Agent Wire v1.1 event.
  • Every event stream must reduce successfully before submission is accepted.
  • Every event type has JSON Schema, fixtures, conformance tests, and reducer tests before production emission.
  • HCS carries coordination facts, routing facts, lifecycle events, artifact references, review/gate events, and compact health/capacity only.
  • Raw model output, drafts, scratch notes, transcripts, verbose logs, private memory, secrets, and document bodies are not HCS content.
  • Supabase/product DB materializes HCS messages for reads but must not become a competing work queue.
  • Terminal task states are immutable.
  • task.complete is invalid before working state and invalid without required artifact references and verification.mechanical=pass.
required bezel follow up contracts
  • Define schemas/bezel-agent-wire/v1/customer-task-extension.schema.json for extensions.bezel.
  • Add valid/invalid fixtures for simple role task and plan-derived task using Agent Wire v1.1 envelope plus extensions.bezel.
  • Add conformance tests proving Bezel extension validation composes with schemas/agent-wire/v1.1/envelope.schema.json.
  • Add reducer tests for workflow_run task release: only dependency-ready tasks emit task.available.
  • Add claim outcome tests for claimed/missed/rejected and idempotency replay.
  • Add claim-next contract tests: claimed when eligible task exists, retries bounded candidates after internal missed race, no_tasks when none available, rejected when agent invalid, idempotency replay returns same claim-next result.
  • Add Lite HCS claim-only schema/fixture tests proving no task title/input/brief/plan/artifact/completion summary can be serialized into Lite HCS claim messages.