small gleam coding and (not yet) persistent agent daemon with a detachable cli forked from okami.mom/albedo
albedo docs contributing-api.md
6.1 kB · 121 lines
Markdown
at main

Change the HTTP API #

Use this guide when adding an operation or changing API behavior. Read the repository instructions and shared contribution rules first.

Choose the contract owner #

Keep each kind of information in its canonical document:

Information Owner
Routes, methods, parameters, schemas, variants, and bounds OpenAPI.
Ordering, uncertain outcomes, retry rules, and caller obligations HTTP API behavior.
State owners, durable commits, and lifecycle boundaries API architecture.
Go operations, decoding, and connection recovery Client API ownership.
Local discovery, launch, and native services Daemon lifecycle.
Feature-specific implementation contracts Robot documentation.

Update the owner in the same change as the behavior. Link other pages to it instead of copying field or event inventories. Distinguish implemented behavior from a new requirement. Do not describe a proposed acceptance check as existing test coverage.

Define the operation #

Name the domain owner before adding a route. Keep HTTP parsing and response mapping in daemon adapters, session state in its actor, durable writes on the store owner, and extension tables with their extension.

Keep daemon protocol compatibility separate from OpenAPI document-format versions and storage migrations. Review the effect on existing clients when changing a wire contract.

Edit the OpenAPI operation and shared schemas. Define required, optional, and nullable fields explicitly. Declare byte limits as well as character limits where needed. For SSE, validate the JSON inside data, not just the outer string.

Specify the operation's commit point, identity, and recovery rule. Decide what a caller can establish after losing a response. Do not add automatic retries around uncertain external effects. Preserve the original intent and ID for identified retries.

Keep creation provenance separate from mutable session configuration. Do not reconstruct an old submitted request from a current name, model, or workspace. Preserve explicit unavailable provenance for older sessions.

For family operations, preserve membership validation and mutation under the existing owner. Keep workspace intent durable before kernel cleanup. Cleanup failure must not be presented as rollback of committed state.

Implement the client boundary #

Add a named operation and typed result to the Go daemon adapter. Keep path encoding, accepted statuses, capability checks, response bounds, and recovery there. Return typed results to application workflows and typed messages to UI models. Do not add public generic request helpers or forwarding-only wrappers.

Regenerate the client contracts after editing OpenAPI:

go -C cli generate ./internal/daemon
npm --prefix web run generate

The static gate also checks Go generation and the web generator. Include generated files when their output changes.

Keep discovery and launch outside the API connection. A failed authenticated request does not authorize starting or replacing a daemon. Follow terminal screen conventions or the web client contracts when integrating an operation into a screen.

Preserve failure boundaries #

Use the settings owner and home lock for grouped settings and credential changes. Keep secrets write-only. Bound replacement documents and recovery records, reject unsafe destinations or permissions, and keep recovery bytes out of logs. A committed journal completes publication after failure instead of undoing it. See settings recovery.

For login identity, keep secret comparison inside the sign-in service in oauth_flows. Use its protected keyed fingerprint rather than a public hash of low-entropy input. Do not persist callback codes or access tokens in admission records. Let the credentials owner retain resulting accounts.

For live delivery, retain bounded queues before mailboxes and release subscriptions after disconnect. Capture status, progress, pending ownership, and cursor together. Advance a client's cursor only after successful delivery. Keep large arguments and results in bounded content reads rather than per-client buffers.

Verify the change #

Use the shared real-daemon harness for observable workflows. Extend an existing scenario where possible. Validate actual responses and decoded SSE payloads against the contract. A hand-built example does not replace checking a real response.

Exercise the failure modes the operation introduces. For durable mutations, check response loss, same-ID replay, conflicting intent, and post-failure state. For settings persistence, place real interruption points around the commit decision. For streams, check reset, stale generations, callback failure, and overflow where affected.

Use controlled transport tests for malformed responses and uncertain network outcomes a healthy daemon cannot reliably produce. Keep focused parser and concurrency tests only where they catch failures the end-to-end scenario cannot reach. Do not add tests that require exact prose, Markdown headings, or source indentation.

Run the relevant tests and the repository commit gate. Report what ran and which failure boundaries remain untested. Link existing verification evidence when it helps a reviewer, but do not treat that list as proof of complete coverage.