Expose a minimal REST and SSE API for the remote MVP loop

[4nass]

Context

The local engine already has a durable CLI queue and #30 defines the OpenClaw typed-tool contract. The missing product surface is a small authenticated HTTP boundary that a gateway can call and that a phone client can reconnect to safely.

Scope

Provide a minimal REST plus Server-Sent Events (SSE) API. REST handles commands; SSE handles reconnectable progress/events. WebSocket is explicitly out of scope for the first version.

MVP endpoints

• POST /v1/jobs - submit a request using a project id and idempotency key.
• GET /v1/jobs/{id} - compact status, budget and outcome.
• GET /v1/jobs/{id}/events?cursor=... - replayable lifecycle events.
• POST /v1/jobs/{id}/cancel - cooperative cancellation.
• POST /v1/jobs/{id}/approval - approve or deny a pending decision.
• GET /v1/jobs/{id}/artifacts - authenticated branch, diff, log and preview references.

Acceptance criteria

• The API uses the authenticated principal from Provide an authenticated transport and verified remote principals #44 and delegates policy to the existing engine gates.
• Mutating submissions require a project id, idempotency key and authorized operation; paths and arbitrary shell commands are not accepted.
• Events have stable sequence/cursor ids and reconnect without duplication or loss.
• Status and artifacts are compact and safe for mobile channels; large content uses authenticated pagination or expiring references.
• Cancellation is cooperative, idempotent and auditable.
• API errors do not disclose project paths, prompts, secrets or unrelated runs.
• Contract tests cover restart/reconnect, duplicate submission, cancellation, approval and authorization failure.
• OpenClaw Expose ai-platform to OpenClaw through asynchronous typed tools #30 consumes this API rather than reimplementing job orchestration.

Relationship

This is the transport implementation for the MVP. It depends on #29 and #44 and is consumed by #30.

[4nass]

Delivery update

Implemented in PR #60:

• authenticated WSGI REST/SSE application using the Provide an authenticated transport and verified remote principals #44 principal contract;
• allowlisted project IDs, durable idempotency and authenticated dispatch;
• status, events, cancellation, approvals and artifact references with principal isolation;
• cursor-based SSE replay and Last-Event-ID reconnect support;
• strict body and JSON validation, generic safe errors and no path or prompt disclosure;
• development server credentials sourced from the environment.

Validation: 810 tests passed, with two pre-existing collection warnings.

Residual: production deployment still requires a TLS-terminating proxy, rate limiting and a secret manager. WebSocket transport and preview deployment remain out of scope.