DRAKULISWorker execution contract v1
Start an independent worker with python -m apps.worker.main. Its configuration is the control-plane URL, worker token, local model endpoint and worker-local workspace. No database credentials or shared web-server volumes are required.
| Operation | Contract |
|---|---|
| submit_task | Operator POST /conversations/{id}/messages persists one queued task and its prompt atomically; concurrent submissions for the same conversation are rejected. |
| claim_task | Worker POST /worker/claim with {worker, models} returns a compatible queued/expired task, versioned payload and fencing token. |
| heartbeat | Worker POST /worker/tasks/{id}/heartbeat with {fence, operation:"", data:{}} renews a 30-second lease. |
| report_progress | Worker POST /worker/tasks/{id}/report with {fence, operation, data} writes a bounded event, message, state or approval. |
| task_data | Worker POST /worker/tasks/{id}/data returns history, call-specific approval decisions and the submitted artifact snapshot. |
| complete/fail | Report terminal status then operation:"finalize"; terminal tasks cannot be redelivered after a crash between these steps. |
| cancel_task | Operator POST /tasks/{id}/cancel revokes the lease and pending approvals atomically. |
Worker token holders are trusted execution infrastructure for the single operator; the token currently grants access to the shared worker pool, not a tenant-specific subset. Never give it to an untrusted third party. It cannot call operator routes.
Remote control URLs must use HTTPS with standard certificate verification. Cleartext HTTP is allowed only on loopback or for Compose's exact api service when DRAKULIS_INTERNAL_HTTP=true. The database and queue are never published. TLS termination is prepared through Caddy.
Each worker handles one task at a time. Scale with distinct worker IDs and independently provisioned model endpoints/workspaces. The single-server Compose worker shares Ollama's network namespace solely to preserve a loopback-only offline model endpoint. For extraction, run the same worker image on the new host with a loopback Ollama service and point its control URL at the TLS API.
Recovery semantics are at least once, not exactly once. User prompts are recorded once per task. Tool reads and calculations are safe to replay; partial model responses and tool traces from failed attempts remain visible. Outstanding tool calls are closed with interruption observations before the next model request. Pending approvals expire on lease reassignment. After three failed lease attempts, the task stops as failed. Manual retry can start a new task after inspecting its trace.
Limits: no arbitrary code execution, write tools, automatic skill loading, dynamic tenancy, GPU scheduler or automatic worker enrollment. No claim of hostile multi-tenant isolation. Resource limits are deployment settings. Large artifact storage, task retention and automatic database compaction remain future work.
Task contract v2
New API submissions carry v2 payloads with typed privacy, workflow, success criteria and recovery limits. Worker claims advertise versions: [1, 2]. An older caller omitting this field is treated as v1-only and cannot claim v2 work. Current workers retain support for persisted v1 tasks, applying the new default local-only privacy policy.
verification_failed is a terminal state, accepted by fenced reporting, finalization, cancellation/status readers and SSE termination. Its evidence assessment is persisted in the task trace. A completed execution without criteria remains unverified. Existing queue rows do not need destructive migration.