albedo docs

Use the daemon HTTP API

Use the bearer token and address from local discovery. The canonical OpenAPI document defines requests, responses, and bounds. Generated references group operations for clients, extensions, and daemon transfers. These groups do not change access control. Regenerate them with go -C cli generate ./internal/daemon.

On this page: Create, submit, and watch, Edit observed configuration, and Recover an uncertain input or action.

Create, submit, and watch

  1. Generate a current UUIDv7 for the session. Send PUT /sessions/{session_id} with If-None-Match: * and a kind: "new" request. Retain that identity and intent until creation is resolved.
  2. Generate a separate UUIDv7 for the input. Send PUT /sessions/{session_id}/inputs/{input_id} with kind: "message" and text. Acceptance does not mean the turn finished.
  3. Read GET /sessions/{session_id}/events with Accept: text/event-stream. Apply a complete reset snapshot before later events. On reconnect, send the last delivered generation and sequence as after_generation and after_seq. A reset replaces the old cursor. Never advance a cursor past a rejected batch.

The ordinary HTTP scenario in http_consumer_test.py exercises creation, identified input recovery, stream reconnection, and history reconciliation.

Edit observed configuration

  1. Read GET /sessions/{session_id}/configuration, retaining its ETag alongside the values shown to the user.
  2. Send PATCH to that URL with Content-Type: application/merge-patch+json and If-Match set to the observed ETag. Omit unchanged fields. Send null only for nullable fields that the edit clears.
  3. Consume the returned resource.value and resource.etag. Read application to determine whether the desired composition differs from the loaded one. Editing does not reload the session.
  4. On 412, show that the observation changed and refresh it. Do not silently reapply the edit with a newer validator.

Move a workspace separately with POST /sessions/{session_id}/workspace, the observed configuration validator, and the observed family revision.

Recover an uncertain input or action

Retain the original ID and immutable intent when a connection fails. Read the identified resource before creating another operation. If no receipt is found and the identity remains admissible, repeat the identical PUT with the same ID. A conflict means that ID belongs to a different intent. An expired identity must not be silently replaced to replay uncertain work.

Inputs use GET /sessions/{session_id}/inputs/{input_id}. Compactions use GET /sessions/{session_id}/compactions/{action_id}. A running compaction needs another receipt read. A completed receipt carries the domain result, which may be failed even though HTTP admission succeeded. An interrupted compaction has uncertain effects and is never automatically replayed. Inspect configuration and context before explicitly requesting new work.

The compaction receipt scenarios cover identity conflicts, retained selection on failure, and restart interruption. HTTP API behavior defines retention and the limits of recovery. Reload and kernel operations have no durable action receipt and must not be automatically replayed.

Previous client api Next http api design