# Artifacts Artifacts are versioned web pages stored by the daemon. The [artifacts extension](../src/albedo/harness/extensions/artifacts/extension.gleam) registers the service and Python host routes. The gallery is global and artifacts outlive their originating session. ## The model's side The [Python binding](../priv/python/albedo_plugins/artifacts.py) 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](../src/albedo/harness/extensions/artifacts/ledger.gleam) 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](../src/albedo/harness/extensions/artifacts/ledger.gleam) 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](../src/albedo/harness/extensions/artifacts/rpc.gleam) connects kernel calls to the ledger. ## Serving and isolation The [service](../src/albedo/harness/extensions/artifacts/service.gleam) handles artifact requests. [`frame.resolve` and `frame.inject`](../src/albedo/harness/extensions/artifacts/frame.gleam) resolve files and insert the bridge into HTML before page scripts. The [bridge](../priv/artifacts/bridge.js) supplies page integration, including persisted state. Artifact pages run in a sandbox with network access, as declared in the [extension instructions](../src/albedo/harness/extensions/artifacts/extension.gleam). Treat page content as executable code, not as trusted daemon code. ## Waiting for versions [`waiting`](../src/albedo/harness/extensions/artifacts/waiting.gleam) 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`](../src/albedo/harness/sdk/subscriptions.gleam) 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](contributing.md) when adding callers. ## Clients The [terminal client](../cli/internal/tui/artifact.go) 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](../priv/python/albedo_plugins/artifacts.py). Artifacts differ from workspace [files](files.md): 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](kernel-state.md#saved-pastes-and-uploads). ## Related pages - [All topics](README.md) - [Change guidance](contributing.md) - [Files extension](files.md) - [Web client](web.md)