# Contrato API worker — versão 1

Base `${BRIDGE_SERVER_URL}/api/worker`. Todas as chamadas exigem
`Authorization: Bearer <BRIDGE_WORKER_TOKEN>`. Não use o token OAuth aqui.
Um único worker é configurado no servidor; tentativa e tarefa identificam a propriedade
por reserva. HTTP 400: payload inválido; 401/403: autenticação; 404: desconhecida;
409: conflito/ownership; 413: corpo muito grande; 422: schema; 429: frequência.

| Método / rota relativa | JSON de entrada | Saída |
|---|---|---|
| POST /register | worker_id, protocol="1", version, workspaces=[IDs] | protocol, lease_seconds |
| POST /heartbeat | {} | ok |
| POST /claim | {} | task (inclui attempt) ou null |
| GET /tasks/{id}?attempt=... | — | tarefa pertencente à tentativa |
| POST /tasks/{id}/renew | attempt | state atual |
| POST /tasks/{id}/progress | attempt, state, thread_id?, turn_id? | ok |
| POST /tasks/{id}/events | attempt, event_id, payload={} | ok; dropped quando limite atingido |
| POST /tasks/{id}/finish | attempt, state, result?, error? | ok |
| POST /tasks/{id}/reconcile | attempt, state terminal, confirm_no_active_turn=true | ok |

O último endpoint é uma decisão administrativa **local**, depois de inspecionar a
execução. Não há ferramenta MCP para essa operação.

Eventos usam IDs aleatórios duráveis no outbox. Repetir ID com payload diferente é
conflito. Finalização é idempotente para o mesmo resultado; um resultado conflitante
não pode substituir o anterior. A sequência dos eventos é um cursor crescente global;
consultas filtram a tarefa antes de retornar a página. Listagens são crescentes por
criação; next_cursor deve ser enviado como after. Páginas vazias conservam o cursor.

Limites atuais: instrução 32.000 caracteres, timeout 1..3.600 segundos, corpo 128 KiB,
evento 16 KiB, até 2.000 eventos por tarefa, resposta 64.000 caracteres, erro 4.000,
página de 1..100 itens, 240 requests/minuto por principal autenticado, 10.000 tarefas.
Heartbeat/renew a cada ~1 segundo durante execução; polling padrão 2 segundos com
jitter, backoff até 60 segundos. Intervalo configurável por BRIDGE_POLL_SECONDS.
Status e IDs têm limites adicionais no schema. Reservas de 45 segundos.

Health /healthz é público e só retorna ok. Detalhes operacionais estão em bridge_status
ou na API autenticada. Metadata OAuth pública não contém tokens, usuário ou banco.