small gleam coding and (not yet) persistent agent daemon with a detachable cli forked from okami.mom/albedo
albedo docs http-extensions.md
10 kB · 186 lines
Markdown
at main

Extension HTTP behavior #

This reference describes caller-visible behavior for selected extension services. It is not an exhaustive extension inventory. OpenAPI defines supported routes and schemas. HTTP API behavior defines common HTTP rules.

Extension management stays under /extensions/{extension_name}. These routes are not aliases for core commands. The extension owns validation, persistence, permissions, and typed domain results. Enabled routes and action descriptors are discoverable through the server and session catalog.

HTTP bearer clients are human operators. Internal model callers use the same domain operations with trusted caller context supplied by the runtime. A JSON role, caller, or session ID cannot grant human permission. Core shutdown and global credential management cannot be delegated through a page descriptor. Disabling a service returns 404 for its HTTP routes.

Extension lists use common pagination and may include optional page and glance render hints. Each editable row includes resource, containing URL, value, and its observed etag. Work, paperclip, and schedule item reads are canonical item representations. Hook and linked-group reads include runtime observations and expose a separate view=configuration resource for edits, using the session configuration convention. Its validator covers only the complete configuration representation, not changing runtime observations.

Mutation responses contain resource and notification. Notification has state: "not_requested"|"queued"|"failed", with nullable safe code and detail. Multiple targets use notifications, one result per target. Creates return 201 with Location. Edits return 200. Deletes return 200 when reporting a deleted resource or notification outcome, otherwise 204. A committed ledger edit remains successful if notifying an agent fails. Secret-generating POSTs have no automatic retry after response loss. The caller reads the resource and explicitly rotates if the secret was lost.

Work #

Work operations are scoped by the invoking workspace's linked group. The creation workspace and parent are immutable after creation. Deletion refuses an item with children. Item edits and deletion use the observed If-Match.

The work service owns these operations. OpenAPI defines writable fields, state variants, and text bounds.

Human mutations can name notify_session_id to queue the existing user-change note. Results distinguish ledger commit from note delivery. Models retain their workspace-scoped create, read, update, and delete operations through trusted internal bindings. Work pages preserve linked-workspace labels and pending-work glances.

The CLI accepts /work add <title>, /work edit <id> <title>, /work status <id> <status>, and /work remove <id> alongside page forms. These shortcuts invoke the page's declared HTTP actions. Removal asks for confirmation. Targeted shortcuts fetch the item even when it is outside the first list page and retain its ETag through confirmation.

Paperclips #

The paperclip ledger is global. The original topic, title, message, suggestion, and origin remain immutable. Human review can acknowledge, reply to, resolve, dismiss, or delete an item under its observed validator. Paperclips and the service implementation describe the owners. OpenAPI defines the request and resource fields.

Humans PATCH status to acknowledged, resolved, or dismissed, or supply reply. A reply acknowledges the item and attempts a note to its filing session. The reply stays saved when notification fails. DELETE removes the item. PATCH with reply cannot also set resolved or dismissed. Human resolution can include a resolution note. It never changes the original message. A model's resolving session comes from trusted runtime context. DELETE requires If-Match. Models can file, list, and resolve still-open or acknowledged items with a nonempty resolution. Human terminal decisions cannot be overwritten by a model. All edits use If-Match. Listings use newest-first cursor order and global glances.

The CLI accepts /paperclips acknowledge <id>, /paperclips reply <id> <text>, /paperclips resolve <id> [note], /paperclips dismiss <id>, and /paperclips remove <id> through the same declared actions as page forms. Removal asks for confirmation. A stale ETag returns a conflict without retrying the mutation.

The global provider order controls which web-search providers the model tries. It lives in extensions.json. Items carry name, label, 1-based position, and whether the provider is tried. POST takes {"change": "up" | "down" | "toggle"}. A move past either end leaves the order unchanged. An unknown name is 404.

Schedule #

Scheduling is session-scoped. Once jobs cannot repeat. Recurring jobs and heartbeats require a repetition interval. Item patches and deletion use the observed If-Match.

A prompt-only edit preserves the next delivery time. Changing the delay resolves the next time from commit time. OpenAPI defines the fields and interval bounds. The schedule service owns validation and updates.

Once jobs disappear after durable delivery. Recurring prompts queue behind running work. Heartbeats skip busy sessions. Restart resumes the schedule without replaying every missed interval. Session deletion removes its jobs.

Linked workspaces #

GET requires workspace and returns its complete group with bounded remote presence facts, paged where necessary. Configuration view contains membership and revision without remote presence facts. POST uses that observed configuration URL and its If-Match, with other_workspace and other_etag from the other group's configuration read. It checks both groups and merges them in one owner commit. Stale membership on either side returns 412. DELETE uses the configuration URL plus member and checks that member belongs to the observed group at commit. The member becomes its own group. Neither operation deletes work or memory. Writes are human-only. Notifications to affected open sessions are reported separately from the committed group change. notification_count covers all targets. The response includes up to 200 outcomes and truncated when the list reaches its count or byte bound.

Webhooks #

A hook targets one session. Its target is immutable. Editable configuration has a separate validator from changing delivery observations. Creation and rotation return a secret only in that operation response. Stored secrets do not appear in ordinary reads, logs, or SSE. Rotation and configuration changes use the observed If-Match.

OpenAPI defines configuration fields, input bounds, and secret-generation requests. Webhooks links the signature and delivery owners.

Permission reads return false when no setting exists. PATCH accepts explicit agent_manage, with omission retaining its value. Only humans grant it. Agent management remains restricted to that agent's target session. Turning management off does not disable hooks or prevent reading that session's own accepted delivery payloads. Hook edits use the caller's observed revision, not a revision fetched just before overwriting a stale screen.

Incoming delivery POST has a 65,536-byte raw-body limit. It requires the configured HMAC-SHA256 signature and never accepts a bearer token instead. Default header is X-Albedo-Signature and prefix is sha256=. Missing or invalid signatures return 403, without a daemon bearer challenge. Optional X-Albedo-Event-Id, at most 128 bytes without newlines, deduplicates by hook, ID, and body hash. A changed body under that ID returns 409. Acceptance stores the delivery and its durable inbox entry together, then returns 202 with delivery_id. A full target inbox returns 429. Unknown or disabled hooks return 404. The pending bound is 1,000 per session.

Delivery lists accept state=pending|delivered|all, default all, and common pagination. Metadata contains ID, hook ID, target session, receipt and delivery timestamps, attempts, and latest deferral reason. Direct delivery reads add payload: { "encoding": "utf8"|"base64", "data": ... }. Both direct and by-hook historical reads remain available after hook deletion. Payloads are external data and carry no instruction authority. Deleting a hook retains accepted deliveries. Deleting the target session removes its hooks and inbox. An operator exposing intake through a reverse proxy allows only the signed POST method, not management GET on the same path.

OpenAI proxy #

The optional proxy uses an OpenAI-compatible envelope, including JSON and streaming responses. It is stateless with respect to agent sessions: the caller supplies history. Its format and body bounds override platform conventions for those routes.

The supported request subset and provider translation belong to the proxy contract and the proxy implementation. User images must be base64 data URLs. Remote image URLs are not fetched. Unsupported fields return a proxy-format error.

Text and reasoning stream as delta.content and delta.reasoning_content. Complete tool calls publish when the turn ends. Provider failure sends an error chunk before termination, or a JSON error for a nonstreaming request. The proxy uses daemon bearer authentication. An operator may explicitly enable anonymous loopback access. That policy never grants access to core or other extension routes.