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

Artifacts #

Artifacts are versioned web pages stored by the daemon. The artifacts extension registers the service and Python host routes. The gallery is global and artifacts outlive their originating session.

The model's side #

The Python binding exposes asynchronous artifacts.create and update. Creation accepts one HTML string, a mapping of files, or a directory. An update with files changes named paths and uses None to remove a path. A directory replaces the tree. The binding requires the entry file and rejects HTML with root-relative src or href paths.

A title-only update renames the artifact without creating a version. The ledger's save implementation distinguishes that path from saving new files.

Directory uploads skip .git, .DS_Store, node_modules, and __pycache__. The binding limits a file to 16 MiB and a directory version to 64 MiB. It hashes files, asks the host which hashes are missing, and uploads missing content. list, get, read, state, errors, and url inspect saved artifacts.

Storage #

The ledger owns artifact metadata, versions, file manifests, content hashes, state, and recorded failures. valid_path and valid_title validate inputs. save records a version. The RPC handler connects kernel calls to the ledger.

Serving and isolation #

The service handles artifact requests. frame.resolve and frame.inject resolve files and insert the bridge into HTML before page scripts. The bridge supplies page integration, including persisted state. Artifact pages run in a sandbox with network access, as declared in the extension instructions. Treat page content as executable code, not as trusted daemon code.

Waiting for versions #

waiting owns the artifact wait policy. Latest-version requests register before re-reading the version, wait up to 25 seconds if it has not advanced, then read storage again. Saving and deleting publish only after the ledger operation commits. Keep version and storage decisions in the artifact extension.

The typed sdk/subscriptions capability supplies one-shot wakeups in the stable artifacts namespace, keyed by artifact ID. It carries no version or event history. Multiple requests can wait on the same key. Each call admits one subscription without a global cap, so callers must bound concurrent requests. Registration returns only after the subscription is visible to publishers.

The native notifier monitors the subscribing process and removes its registry entry on owner death. wait explicitly closes on wake or timeout. close waits for notifier exit and drains its wake before returning, including when a publish races the timeout. Close immediately when the version read settles the request. Handles belong to their creating process and must not be transferred. The daemon observation bus and the invalidate callbacks do not implement this keyed wait contract. Follow the shared commit and lifetime rules when adding callers.

Clients #

The terminal client presents artifacts to the user. artifacts.url requires a running albedo web process and returns a URL for a version or the latest version. See the Python binding. Artifacts differ from workspace files: saving one uploads content into the artifact store. Files attached to a chat message are not artifacts. They are saved beside pastes and expire by age. See saved pastes and uploads.