feat(artifacts): define artifact storage types, config, and persistence layer

.claude/memory.md

@@ -210,6 +210,13 @@ Quick reference for anyone starting with Claude on this project. Updated by the
 - **Kill stuck processes** — `lsof -i :7788` then `kill <PID>`. Useful when `dev:app` reports a stale listener and you want to force a fresh boot rather than relying on the handle's auto-recovery.
 - **Skills runtime removed** — the QuickJS / `rquickjs` runtime is gone; `src/openhuman/skills/` is metadata-only ("Legacy skill metadata helpers retained after QuickJS runtime removal"). Skill execution surfaces are being rebuilt; don't assume a `.skill` can run end-to-end without checking the current code.
 
+## Artifacts Domain (Issue #2776)
+
+- **Filesystem-backed persistence, no SQLite** — `src/openhuman/artifacts/` stores JSON metadata (`meta.json`) + binary blobs under `<workspace_dir>/artifacts/<uuid>/`. Pattern mirrors `memory/ops/files.rs` but simpler.
+- **`"ai"` namespace in controller registry** — RPC methods are `openhuman.ai_list_artifacts`, `openhuman.ai_get_artifact`, `openhuman.ai_delete_artifact`. Future `ai_*` methods should use this same namespace.
+- **Two-layer path validation required** — (1) `validate_artifact_id` rejects empty strings, `/`, `\`, `..`, absolute Unix paths, Windows `C:` and UNC `\\` paths; (2) `assert_within_root` canonicalizes and checks containment. Replicate this pattern for any new filesystem-backed domain.
+- **`cargo test --lib` required for lib crate tests** — `cargo test -p openhuman -- "artifacts"` lists tests but filters to 0. Must use `cargo test -p openhuman --lib -- "artifacts"` because tests are in the lib crate, not integration test binaries.
+
 ## Rust Testing Patterns
 
 - **Memory tree tests filter** — `cargo test -p openhuman -- "memory::tree"` runs the memory tree unit tests (602 tests); full module paths are `openhuman::memory::tree::ingest::tests::*` and `openhuman::memory::tree::canonicalize::email_clean::tests::*`.

src/core/all.rs

@@ -134,6 +134,8 @@ fn build_registered_controllers() -> Vec<RegisteredController> {
     controllers.extend(crate::openhuman::security::all_security_registered_controllers());
     // Interactive approval workflow (#1339 — gate external-effect tool calls)
     controllers.extend(crate::openhuman::approval::all_approval_registered_controllers());
+    // Agent-generated artifact storage, retrieval, and lifecycle management
+    controllers.extend(crate::openhuman::artifacts::all_artifacts_registered_controllers());
     // Background heartbeat loop controls
     controllers.extend(crate::openhuman::heartbeat::all_heartbeat_registered_controllers());
     // Ad-hoc static directory HTTP hosting for local file sharing / previews
@@ -294,6 +296,7 @@ fn build_declared_controller_schemas() -> Vec<ControllerSchema> {
     schemas.extend(crate::openhuman::encryption::all_encryption_controller_schemas());
     schemas.extend(crate::openhuman::security::all_security_controller_schemas());
     schemas.extend(crate::openhuman::approval::all_approval_controller_schemas());
+    schemas.extend(crate::openhuman::artifacts::all_artifacts_controller_schemas());
     schemas.extend(crate::openhuman::heartbeat::all_heartbeat_controller_schemas());
     schemas.extend(crate::openhuman::http_host::all_http_host_controller_schemas());
     schemas.extend(crate::openhuman::cost::all_cost_controller_schemas());
@@ -389,6 +392,7 @@ pub fn rpc_method_name(schema: &ControllerSchema) -> String {
 pub fn namespace_description(namespace: &str) -> Option<&'static str> {
     match namespace {
         "about_app" => Some("Catalog the app's user-facing capabilities and where to find them."),
+        "ai" => Some("Agent-generated artifact storage, retrieval, and lifecycle management."),
         "app_state" => Some("Expose core-owned app shell state for frontend polling."),
         "auth" => Some("Manage app session and provider credentials."),
         "agent_experience" => Some("Local procedural experience capture and retrieval for agents."),

src/openhuman/artifacts/mod.rs

@@ -0,0 +1,10 @@
+pub mod ops;
+pub mod schemas;
+pub mod store;
+pub mod types;
+
+pub use schemas::{
+    all_controller_schemas as all_artifacts_controller_schemas,
+    all_registered_controllers as all_artifacts_registered_controllers,
+};
+pub use types::{ArtifactKind, ArtifactMeta, ArtifactStatus};

src/openhuman/artifacts/ops.rs

@@ -0,0 +1,114 @@
+use serde_json::{json, Value};
+
+use crate::openhuman::config::Config;
+use crate::rpc::RpcOutcome;
+
+use super::store;
+
+/// Default page size for `ai_list_artifacts`.
+const DEFAULT_LIMIT: usize = 50;
+/// Maximum page size cap for `ai_list_artifacts`.
+const MAX_LIMIT: usize = 200;
+
+/// List artifacts in the workspace with pagination.
+///
+/// Returns `{ "artifacts": [...], "total": N, "offset": M, "limit": L }`.
+pub async fn ai_list_artifacts(
+    config: &Config,
+    offset: Option<usize>,
+    limit: Option<usize>,
+) -> Result<RpcOutcome<Value>, String> {
+    let offset = offset.unwrap_or(0);
+    let limit = limit.unwrap_or(DEFAULT_LIMIT).min(MAX_LIMIT);
+    log::debug!(
+        "[artifacts] ai_list_artifacts: workspace={:?} offset={offset} limit={limit}",
+        config.workspace_dir
+    );
+
+    let (artifacts, total) = store::list_artifacts(&config.workspace_dir, offset, limit).await?;
+
+    log::debug!(
+        "[artifacts] ai_list_artifacts: returning {} of {total} total",
+        artifacts.len()
+    );
+
+    let value = json!({
+        "artifacts": artifacts,
+        "total": total,
+        "offset": offset,
+        "limit": limit,
+    });
+    Ok(RpcOutcome::new(value, vec![]))
+}
+
+/// Retrieve a single artifact by ID.
+///
+/// Returns the serialized `ArtifactMeta` plus an `absolute_path` field
+/// pointing to the full on-disk location of the artifact files.
+pub async fn ai_get_artifact(
+    config: &Config,
+    artifact_id: &str,
+) -> Result<RpcOutcome<Value>, String> {
+    log::debug!(
+        "[artifacts] ai_get_artifact: id={artifact_id} workspace={:?}",
+        config.workspace_dir
+    );
+
+    if artifact_id.is_empty() {
+        return Err("[artifacts] artifact_id must not be empty".to_string());
+    }
+
+    let meta = store::get_artifact(&config.workspace_dir, artifact_id).await?;
+
+    // Compute absolute path for the caller's convenience.
+    let absolute_path = config
+        .workspace_dir
+        .join("artifacts")
+        .join(&meta.path)
+        .to_string_lossy()
+        .into_owned();
+
+    let mut value =
+        serde_json::to_value(&meta).map_err(|e| format!("[artifacts] serialization error: {e}"))?;
+    if let Some(obj) = value.as_object_mut() {
+        obj.insert(
+            "absolute_path".to_string(),
+            Value::String(absolute_path.clone()),
+        );
+    }
+
+    log::debug!(
+        "[artifacts] ai_get_artifact: found id={artifact_id} absolute_path={absolute_path}"
+    );
+    Ok(RpcOutcome::new(value, vec![]))
+}
+
+/// Delete an artifact and all associated files.
+///
+/// Returns `{ "artifact_id": "...", "deleted": true }`.
+pub async fn ai_delete_artifact(
+    config: &Config,
+    artifact_id: &str,
+) -> Result<RpcOutcome<Value>, String> {
+    log::debug!(
+        "[artifacts] ai_delete_artifact: id={artifact_id} workspace={:?}",
+        config.workspace_dir
+    );
+
+    if artifact_id.is_empty() {
+        return Err("[artifacts] artifact_id must not be empty".to_string());
+    }
+
+    store::delete_artifact(&config.workspace_dir, artifact_id).await?;
+
+    log::debug!("[artifacts] ai_delete_artifact: deleted id={artifact_id}");
+    let value = json!({
+        "artifact_id": artifact_id,
+        "deleted": true,
+    });
+    Ok(RpcOutcome::new(value, vec![]))
+}
+
+#[cfg(test)]
+#[path = "ops_tests.rs"]
+mod tests;

src/openhuman/artifacts/ops_tests.rs

@@ -0,0 +1,46 @@
+use tempfile::TempDir;
+
+use super::*;
+use crate::openhuman::config::Config;
+
+fn test_config(tmp: &TempDir) -> Config {
+    Config {
+        workspace_dir: tmp.path().to_path_buf(),
+        config_path: tmp.path().join("config.toml"),
+        ..Config::default()
+    }
+}
+
+// ── ai_list_artifacts ──────────────────────────────────────────────────────
+
+#[tokio::test]
+async fn list_empty() {
+    let tmp = TempDir::new().unwrap();
+    let config = test_config(&tmp);
+    let outcome = ai_list_artifacts(&config, None, None).await.unwrap();
+    let value = outcome.into_cli_compatible_json().unwrap();
+    assert_eq!(value["total"], 0);
+    assert_eq!(value["artifacts"].as_array().unwrap().len(), 0);
+    assert_eq!(value["offset"], 0);
+    assert_eq!(value["limit"], DEFAULT_LIMIT as u64);
+}
+
+// ── ai_get_artifact ────────────────────────────────────────────────────────
+
+#[tokio::test]
+async fn get_missing_id_error() {
+    let tmp = TempDir::new().unwrap();
+    let config = test_config(&tmp);
+    let err = ai_get_artifact(&config, "").await.unwrap_err();
+    assert!(err.contains("must not be empty"), "unexpected error: {err}");
+}
+
+// ── ai_delete_artifact ─────────────────────────────────────────────────────
+
+#[tokio::test]
+async fn delete_missing_id_error() {
+    let tmp = TempDir::new().unwrap();
+    let config = test_config(&tmp);
+    let err = ai_delete_artifact(&config, "").await.unwrap_err();
+    assert!(err.contains("must not be empty"), "unexpected error: {err}");
+}