The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
artifacts
Metadata store and lifecycle for agent-generated files (presentations,
documents, images, video). Metadata lives in the hidden, per-account
<workspace_dir>/artifacts/; the files themselves are written to a visible
files folder, ~/OpenHuman/projects/Files by default
(config::default_files_dir, #5505). Producer tools
(tools/impl/presentation, tools/impl/document, media::generation) call
this module to reserve an artifact and its file, write their bytes, and flip the record to
Ready or Failed; the module publishes the matching bus events, persists
meta.json / args.json, and exposes ai.* RPC controllers plus three
agent tools for listing, fetching, deleting, and regenerating. It never
renders artifact content itself.
Key files
| File | Role |
|---|---|
mod.rs |
mod decls and re-exports: ArtifactKind / ArtifactMeta / ArtifactStatus, the producer API (create_artifact, finalize_artifact, fail_artifact, read_artifact_bytes), and all_artifacts_controller_schemas / all_artifacts_registered_controllers. |
types.rs |
ArtifactKind (presentation/document/image/other), ArtifactStatus (pending/ready/failed), ArtifactMeta. Enums serialize lowercase; parse is case-insensitive and never errors (unknown kind → Other, unknown status → Pending). ArtifactMeta.error and .thread_id are optional, skip_serializing_if none. |
files.rs |
Where the bytes live: reserve_file (claims <stem>.<ext>, then <stem> (2).<ext>, with create_new in the shared files folder), resolve_file + the escape guard, resolve_ready_file (pub: the one id → existing-file lookup for readers and the desktop Download command), remove_empty_placeholder, the "file missing" error. |
migrate.rs |
migrate_legacy_artifacts: the idempotent, crash-safe boot move of pre-#5505 files into the files folder (copy to .<id>.partial → claim a name and rename → atomic meta write → delete legacy bytes). Run per account from config::ensure_agent_dirs. |
store.rs |
All filesystem I/O over tokio::fs: artifacts_root, create_artifact, finalize_artifact, fail_artifact, read_artifact_bytes (pub); save_artifact_meta, save_artifact_args, read_artifact_args, list_artifacts, get_artifact, delete_artifact (pub(crate)); validate_artifact_id / assert_within_root sandboxing; create_artifact_regenerating (explicit regenerate target); sanitize_filename_stem. |
ops.rs |
RPC business logic returning Outcome<Value>: ai_list_artifacts, ai_get_artifact, ai_delete_artifact, ai_regenerate. DEFAULT_LIMIT = 50, MAX_LIMIT = 200. The regenerate path that re-runs PresentationTool is #[cfg(feature = "documents")]; without the feature ai_regenerate returns an error. |
schemas.rs |
ControllerSchemas and handle_* fns for the four ai.* controllers; param helpers read_required, read_optional_u64, read_optional_string (whitespace-only → absent), type_name. |
tiny_store.rs |
OpenHuman's side of the versioned artifacts (tiny-artifacts): versioned_store (records in the configured storage backend: version_documents.rs; older JSON records are imported once), the acting tenant's scoped blob-backed file store, guarded migration of old path references, LegacyUiBridge (shows the newest version through the legacy row, events and visible files folder), artifacts_service, the agent tools, and save_operator_version (the preview panel's autosave). |
production.rs |
Production: how producer tools (deck, document, generated media) file their output — reserve the file and the card, open the versioned record under the same id, then complete or fail it. |
*_tests.rs |
Sibling test files for each of the above (#[path]). |
Public surface
ArtifactKind,ArtifactMeta,ArtifactStatus.- Producer API,
puband re-exported frommod.rs:create_artifact(workspace_dir, kind, title, extension) -> (ArtifactMeta, PathBuf): mints a UUID (create_artifact_regeneratingreuses an explicit regenerate target), creates<root>/<id>/, writes aPendingmeta.json, publishesArtifactPending, and returns the absolute path the producer should write to (<id>/<sanitized-title>.<ext>).finalize_artifact(workspace_dir, id, size_bytes):Pending → Ready, publishesArtifactReady; no-op if alreadyReadywith the same size.fail_artifact(workspace_dir, id, reason):→ Failed, storesmeta.error, publishesArtifactFailed. Logs onlyreason.len(), not the reason.read_artifact_bytes(workspace_dir, id): the one sanctioned id → bytes path; refuses non-Readyrecords.
store::save_artifact_argsispub(crate)and called directly by the producers right aftercreate_artifact(best-effort; failure only forfeits regeneration).all_artifacts_controller_schemas/all_artifacts_registered_controllers.
RPC / controllers
Namespace ai. Registered in core/all.rs under DomainGroup::Agent via
all_artifacts_registered_controllers(); all_artifacts_controller_schemas()
is used by schemas_tests.rs to check every function has a schema and a
handler. Handlers load config through config::rpc::load_config_with_timeout()
and trim string params.
| Method | Inputs | Output |
|---|---|---|
ai.list_artifacts |
offset?: u64 (default 0), limit?: u64 (default 50, cap 200), thread_id?: string |
{ artifacts: ArtifactMeta[], total, offset, limit }: total is the count after the thread_id filter |
ai.get_artifact |
artifact_id: string |
flat ArtifactMeta fields + absolute_path (root joined with meta.path) |
ai.delete_artifact |
artifact_id: string |
{ artifact_id, deleted: true } |
ai.regenerate |
artifact_id, thread_id, client_id (all required) |
{ artifact_id, regenerated: true, is_error } |
ai.regenerate only accepts kind == presentation, reloads args.json,
and re-runs PresentationTool::with_regenerate_target(id) with the
{thread_id, client_id} chat context passed to the tool, so the same id
is reused and the Pending/Ready/Failed events route back to the originating
chat. The RPC result is an ack; the card state comes from the socket events.
When thread_id is given to list_artifacts, legacy records with no
thread_id are excluded.
Agent tools
The agent's artifact tools are the tiny-artifacts crate's, bound to this
workspace by tiny_store::registered_tools and constructed in
tools/ops.rs. Every write goes through the crate's
Artifacts service, so a tool-made artifact is a versioned record shown
through LegacyUiBridge exactly like a producer-made one.
| Tool | Permission | Behavior |
|---|---|---|
create_artifact |
Write |
New artifact with its first version: body for text / markdown / html, path (a file in the agent's working folder or the files folder) for image / file. |
update_artifact |
Write |
Appends a version; an identical text body appends nothing. |
read_artifact |
default | One record with its full history. |
list_artifacts |
default | Every versioned record, newest first. |
delete_artifact |
Dangerous |
Deletes the record, its card and file. Default-OFF: its ToolFamily in tools/user_filter.rs keeps the old toggle id artifact_delete so saved choices still apply. |
All five classify as DomainGroup::Agent (tools/ops_tool_groups.rs), so a
harness-scoped agent keeps them. There is no regenerate tool; regeneration is
RPC-only.
Events
Published by store.rs on crate::core::bus::BUS (no bus.rs; this module
subscribes to nothing):
DomainEvent::ArtifactPending: fromcreate_artifact.DomainEvent::ArtifactReady: fromfinalize_artifacton a real transition.DomainEvent::ArtifactFailed: fromfail_artifact.
All three carry thread_id / client_id taken from the
ApprovalChatContext the producing tool receives with its run context; outside a chat turn
(CLI, cron, sub-agents) both are None and the
web_chat::artifact_surface subscriber (web_chat/event_bus.rs) drops the
event.
Persistence
- Metadata root
<workspace_dir>/artifacts/, created on demand byartifacts_root. Per account. Not inWORKSPACE_INTERNAL_DIRS: the agent reads its large tool outputs back fromartifacts/tool-results/, so a record'sfileis bounded by the escape guard instead. - With a storage backend configured (
crate::storage) the records (meta.json,args.json) areartifacts/artifact_argsdocuments under the acting agent's scope instead (store_documents.rs); the first use imports the legacy files, and the content files stay files in the files folder on every backend. <root>/<id>/meta.json: pretty-printedArtifactMeta, written atomically (temp + rename).<root>/<id>/args.json: verbatim producer-tool args, written by the producer viasave_artifact_args, read byai_regenerate. Absent for artifacts created before it existed, which makes them non-regenerable.<files_dir>/<stem>.<ext>: the artifact bytes.meta.fileis the absolute path,meta.file_rootthe files folder it was placed in, andmeta.paththe file name. The files folder is shared by every account on the OS user;create_newkeeps names from colliding, and each account lists only its own metadata. Changing the folder affects new artifacts only; existing ones keep resolving through their recordedfile.- Legacy records (
fileabsent) keepmeta.path=<id>/<filename>under the metadata root untilmigrate_legacy_artifactsmoves them. - A failed generation removes its zero-byte placeholder; deleting an
artifact removes its file and its metadata directory; a
Readyrecord whose file was moved or deleted outside OpenHuman reads as "file missing". list_artifactsscans root subdirectories, sorts bycreated_atdescending, applies thethread_idfilter before pagination, and skips entries whosemeta.jsonis missing or corrupt (warn!, not an error).- Regeneration reuses the existing directory and the file it owns, and
preserves the original
created_atso the artifact keeps its position in the sorted list.
Used by
tools/impl/presentation/mod.rsandtools/impl/document/mod.rs(documentsfeature; inscripts/ci/product-features.txt, not in Cargo defaults), andmedia/generation/artifact_tool.rs: the producers. Presentation also usesread_artifact_bytesfor its image pipeline.config/ops/agent.rs(ensure_agent_dirs): creates the files folder and runs the migration at boot.crates/openhuman-app/src/artifact_commands.rs: the desktop Download command resolves an artifact id throughresolve_ready_file.web_chat/event_bus.rs: bridges the three events to web-channelartifact_*events.core/all.rs: controller registry.
Notes / gotchas
- Path-traversal hardening is layered:
validate_artifact_idrejects empty,.,.., anything containing/or\, absolute paths, andX:drive-letter prefixes;assert_within_rootre-checks every resolved path; every reader resolves throughfiles::resolve_file, which refuses a legacymeta.pathwith..components (a lexicalstarts_withalone let<root>/../xthrough) and holds a recordedfileto the escape guard: absolute, no.., strictly inside itsfile_root(symlinks resolved), and neverSecurityPolicy::is_always_forbidden. create_artifactrejects empty titles/extensions and extensions containing/,\, or.. Filename stems are lowercased ASCII[a-z0-9_-], capped at 80 chars, fallbackartifact.- Log prefix is
[artifacts]([tiny-artifacts]intiny_store.rs).