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.