Skip to content

API.md

Latest commit

 

History

History
258 lines (196 loc) · 6.6 KB

API.md

File metadata and controls

258 lines (196 loc) · 6.6 KB
Raw

API Guide

Last Updated: 2026-03-06
Status: BASELINE

Active Service Surfaces

Room-13 FastAPI Coordinator

Base path: services/room-13-fastapi-coordinator

Core service contracts:

  • GET /health
  • GET /ready
  • GET /version
  • GET /metrics

Task contracts:

  • POST /api/tasks
  • GET /api/tasks
  • GET /api/tasks/{task_id}
  • POST /api/tasks/claim-next
  • PUT /api/tasks/{task_id}/assign
  • PUT /api/tasks/{task_id}/start
  • PUT /api/tasks/{task_id}/complete
  • DELETE /api/tasks/{task_id}

Worker contracts:

  • POST /api/workers
  • GET /api/workers
  • GET /api/workers/{worker_id}
  • PUT /api/workers/{worker_id}
  • POST /api/workers/{worker_id}/heartbeat
  • POST /api/workers/{worker_id}/claim
  • POST /api/workers/{worker_id}/checkpoint
  • POST /api/workers/{worker_id}/resume
  • POST /api/workers/{worker_id}/release
  • POST /api/workers/{worker_id}/task/complete
  • DELETE /api/workers/{worker_id}

Additional coordinator groups:

  • /api/services
  • /api/credentials
  • /api/gateway
  • /api/captcha
  • /api/webhooks
  • /api/workflows
  • /api/n8n
  • /api/steel

Solver-18 Runtime HTTP Surface

Base path: services/solver-18-survey-worker

Observed operational routes include:

  • GET /health
  • GET /ready
  • GET /metrics
  • GET /telemetry/events
  • GET /telemetry/summary
  • GET /telemetry/audit-report
  • runtime status routes under the runtime-v2 reporting surface

Response Expectations

  • health should indicate overall status and degraded mode when relevant.
  • ready should be suitable for automation and return non-200 when the service is not ready.
  • metrics should return Prometheus-compatible plaintext where implemented.
  • task and worker payloads should remain additive so old consumers do not break when new diagnostics are introduced.

Example: Task Envelope

Representative Room-13 task fields:

  • id
  • name
  • type
  • status
  • priority
  • payload
  • metadata
  • assigned_worker
  • platform_id
  • lane_id
  • task_key
  • policy
  • expected_outcome
  • attempt
  • max_attempts
  • run_id
  • lease_epoch
  • history

Example: Worker Envelope

Representative Room-13 worker fields:

  • id
  • name
  • type
  • status
  • capabilities
  • metadata
  • worker_identity
  • persona_id
  • platform
  • current_run_id
  • claimed_task_id
  • lease_epoch
  • lease_ttl_sec
  • lease_expires_at
  • current_step
  • checkpoint_count
  • last_checkpoint_at
  • last_checkpoint
  • approval_state
  • resume_count

Alpha Backbone Pilot Contract (v1)

Frozen alpha scope for the first durable migration path:

  • pilot flow: task.create -> claim-next -> worker checkpoint/resume -> complete/fail
  • source ingress remains Room-13
  • workflow truth moves to Restate
  • transport/replay moves to JetStream
  • projections/policies/auth grants/memory metadata live in SIN-Supabase
  • Redis remains lease/cache/dedupe only and is never authoritative for pilot state

Canonical envelope fields required across the pilot backbone:

  • id
  • tenant_id
  • team_id
  • workflow_id
  • run_id
  • idempotency_key
  • causation_id
  • correlation_id
  • created_at
  • updated_at
  • authority_owner

Pilot contract objects:

  • Command: ingress intent accepted by Room-13 before workflow start
  • Event: immutable transport/replay record published to JetStream
  • Run: durable workflow instance owned by Restate
  • Checkpoint: resumable worker progress record tied to run_id
  • Approval: pause/resume gate with SLA, actor, and audit trail
  • ArtifactRef: metadata pointer to external blob/object output
  • Capability: machine-readable executor/tool/agent ability record
  • MemoryReference: pointer to semantic memory items used during execution

Pilot event types:

  • task.created
  • task.claimed
  • task.checkpointed
  • task.completed
  • task.failed
  • approval.requested
  • approval.resolved

Required alpha proof semantics:

  • duplicate task.created events must not create duplicate side effects
  • worker death must resume from the latest durable checkpoint under the same run_id
  • approval pause/resume must stop and restart real execution, not only metadata
  • degraded Redis mode must never become the source of truth for pilot workflow state

HF executor reference contract:

  • services/workers/hf_executor_contract.json defines the machine-readable alpha executor contract
  • services/workers/hf_executor_reference.py defines the Python reference envelope builders for checkpoint and terminal events

Change Rule

Whenever a new long-lived API surface is introduced, add it here and document its health, ready, version, and metrics behavior.

Gesture-backed HITL compatibility

Gesture-aware approvals must preserve the existing approval lifecycle and response model:

  • request created
  • pending
  • approved / rejected / timeout

If gesture input degrades (for example low confidence or camera unavailable), the provider must fall back to an existing manual approval lane instead of silently auto-approving.

Agent V2 Internal API

MindriftAgent

  • __init__(cdp_port: int): Initializes agent with CDP connection.
  • start(target_url: str): Connects to browser, injects fingerprinting, calibrates viewport, and starts the automation loop.
  • _run_loop(): Executes the autonomous Ponder & Press iteration.
  • _humanized_click(x: int, y: int): Performs human-like mouse movement using Bezier paths followed by click and focus/blur.

Coordinator API Reference (Legacy Import)

Legacy operator reference imported from Docs/API-Reference.md so the repo remains compliant with the Top-20 root-doc registry.

Base URL (local dev): http://localhost:8000

Health and Monitoring

  • GET / Root endpoint (API info)
  • GET /health Overall API health
  • GET /api/v1/health/rooms Room status snapshot

Authentication (legacy /api/v1 surface)

  • POST /api/v1/auth/login Authenticate and get token
  • POST /api/v1/auth/logout Invalidate token

CAPTCHA Solving (legacy /api/v1 surface)

  • POST /api/v1/solve/captcha Submit CAPTCHA image for solving
  • GET /api/v1/solve/status/{task_id} Check solving task status

Enterprise (legacy /api/v2 surface)

  • POST /api/v2/enterprise/consensus Submit task for multi-model consensus

Response Objects (legacy examples)

Room Status Object:

{
  "id": "string",
  "name": "string",
  "host": "string",
  "port": "integer",
  "address": "string",
  "status": "UP | DOWN"
}

Health Status Object:

{
  "status": "healthy | degraded",
  "models": {
    "gemini": "available | unavailable",
    "mistral": "available | unavailable",
    "yolo": "available | unavailable",
    "consensus": "available | unavailable"
  }
}