Home Original page

NullClaw | Autonomous AI Ecosystem

NullTickets Task Control Plane

Zig task-state backend for autonomous delivery systems: pipeline definitions, queueing, lease-based claiming, stage transitions, gate checks, artifacts, and operational queue analytics.

21

API route paths (`src/openapi.json`)

12

SQLite tables in initial migration

2

OTLP ingest endpoints (`/v1/traces`, `/otlp/v1/traces`)

300s

default lease TTL for claim/heartbeat

Quick Start

git clone https://github.com/nullclaw/nulltickets.git
cd nulltickets
zig build -Doptimize=ReleaseSmall
./zig-out/bin/nulltickets --port 7700 --db /tmp/nulltickets.db

# health + openapi discovery
curl -s http://127.0.0.1:7700/health
curl -s http://127.0.0.1:7700/openapi.json

# create pipeline
curl -s -X POST http://127.0.0.1:7700/pipelines \
  -H 'Content-Type: application/json' \
  -d '{"name":"dev-pipeline","definition":{"initial":"research","states":{"research":{"agent_role":"researcher"},"coding":{"agent_role":"coder"},"done":{"terminal":true}},"transitions":[{"from":"research","to":"coding","trigger":"complete"},{"from":"coding","to":"done","trigger":"complete"}]}}'

# claim work for a role
curl -s -X POST http://127.0.0.1:7700/leases/claim \
  -H 'Content-Type: application/json' \
  -d '{"agent_id":"researcher-1","agent_role":"researcher"}'

Code-Derived Snapshot

Source basis: `src/main.zig`, `src/api.zig`, `src/domain.zig`, `src/store.zig`, `src/migrations/001_init.sql`, and `src/openapi.json`.

Pipeline Validation Rules

Definitions must include valid `initial`, known transition states, at least one terminal state, and outgoing transitions for each non-terminal state.

Claim + Lease Security

Worker agents claim tasks by role, receive `lease_token`, and then must call run mutation endpoints with `Authorization: Bearer <lease_token>`.

Idempotent Writes

Write endpoints support `Idempotency-Key`; key reuse with different body returns `409 idempotency_conflict`.

Quality Gates + Ops

Stage transitions can require gates (`required_gates`) and queue-level stats are available via `GET /ops/queue` (`claimable`, `stuck`, `near_expiry`).