small gleam coding and (not yet) persistent agent daemon with a detachable cli forked from okami.mom/albedo
albedo robot-docs webhooks.md
5.2 kB · 93 lines
Markdown
at main

Webhooks #

The webhooks extension accepts signed deliveries for a persistent session. Its extension registration connects the service, storage, transfer adapter, and Python binding. See also Discord, which delivers another kind of external event.

Setup #

sdk/webhook_address constructs the intake path and, given a port, a loopback delivery URL. The daemon server records the port in daemon/webhook_intake once the intake listener binds, and clears it when the intake stops for good. The host passes webhook_intake.port to the extension as intake_port, a function that reads the current port. The service reads it from extension.Daemon. Kernel routes and the /webhooks command read it from extension.Preparation, so the extension prepares its session contribution with OwnedManagedPlugin. Its transfer adapter reads addresses through intake_url in transfer.BindingsContext, which resolves a path against the live listener and answers None while there is none. Other transfer owners ignore that field. Read the port each time an address is shown, and do not keep the number, because a stopped intake must show no URL. A hook has a secret, an enabled flag, a signature header, and a prefix. ledger.gleam defaults the header to x-albedo-signature and the prefix to sha256=. The terminal client and web client provide management pages.

Delivery #

accept checks the signature and rejects bodies over 64 KiB. The ledger stores an accepted delivery and posts it to the session's inbox in one transaction, from outside, posted once under the delivery's id, read after the running turn ends. The input contains a bounded preview. webhooks.delivery(id) reads the stored payload for the session. The service returns a delivery ID for an accepted request and reports invalid signatures as an error. Delivery can fail, including when the inbox is full.

A delivery's letter holds its state: whether it was delivered, how often the inbox tried, and why it waits. accept posts it as input.Filed under the delivery's id, filed under the hook. The ledger reads letters through sdk/mail. Its service, upgrade, and import run with handles bound to no session and reach the letters of every hook's session, so webhooks declares Correspondence (extension capabilities). A delivery is pending until its letter is delivered. A dropped letter was never delivered, so its delivery stays pending, as receipts have always shown it. A delivery from before the inbox, which has no letter, is delivered when its own delivered_at says so.

A page of pending receipts reads the hook's undelivered letters (mail.undelivered_in). A page of delivered ones reads its delivered letters (mail.delivered_in) and its deliveries from before the inbox. Each read uses an index that holds only rows in that state, so a page reads about the rows it returns, whatever the hook's or its session's history holds.

ledger.settle gives older deliveries the letter accept gives a new one: a delivery stored before the inbox existed, still waiting, gets its letter, and a letter posted before letters were filed is filed under its hook. It reads a page of deliveries at a time. It runs once when a daemon upgrades, before the service takes requests, and webhook_upgrades, a table no transfer carries, remembers that it ran. It runs again for the sessions an import brings, in the transfer adapter's activate as the import goes live, so a move from an older daemon shows its receipts at once. Only moves from an older daemon to a newer one are supported; see moves between versions.

A delivery to a hook whose session moved to another daemon is refused with status 410. The service tells the session once through extension.Daemon.tell_refused and answers the sender with extension.Daemon.hook_gone. Both are bound to moves by the daemon server.

A received payload is external data, not an instruction. The extension explicitly includes that boundary in its model instructions.

Management #

webhooks.py exposes list, delivery, create, rotate, configure, enable, disable, and delete. Management requires a human to enable agent management for the session. Reading a delivery does not require that permission. Changes to existing hooks take a revision. The RPC handler enforces the session and permission checks.