The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
//! [`Production`]: how a producer tool (a deck, a document, a generated image
//! or video) files what it makes as a versioned artifact.
//!
//! Every artifact goes through the `tiny-artifacts` service; a producer only
//! adds the part that is OpenHuman's — reserving a file name in the visible
//! files folder, so it can write its bytes there while the user already sees
//! a "generating…" card. The flow:
//!
//! 1. [`Production::start`] reserves the file and the card, and opens the
//! versioned record under the same id. A revision (`revise`: an
//! `artifact_id` argument or a regenerate target) reuses the existing id
//! and file, and keeps the record's history.
//! 2. The producer writes its bytes to [`Production::path`].
//! 3. [`Production::complete`] appends the file as a new agent version; the UI
//! bridge marks the card ready. [`Production::fail`] fails both instead.
//!
//! The record is written before the card is marked ready, so a ready card
//! always has its versioned record.
use std::path::{Path, PathBuf};
use std::sync::Arc;
use tiny_artifacts::{ArtifactKind, Artifacts, Author, Content};
use super::files::FileRoots;
use super::tiny_store::{artifacts_service_current, legacy_kind_for_extension};
use super::types::ArtifactKind as LegacyArtifactKind;
use crate::security::approval::ApprovalChatContext;
/// Starts the card's failure reason when a version was recorded but the card
/// could not show it (its file in the files folder was not updated). The UI
/// keys on it to say so, instead of "generation failed".
pub const SAVED_NOT_SHOWN: &str = "saved-not-shown:";
/// A file being produced as an artifact.
pub struct Production {
artifacts: Artifacts,
workspace_dir: PathBuf,
files: FileRoots,
chat: Option<ApprovalChatContext>,
id: String,
path: PathBuf,
/// Whether this adds a version to an artifact that already has one: its
/// failure must leave that artifact as it was, not fail it.
revision: bool,
}
impl std::fmt::Debug for Production {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Production")
.field("id", &self.id)
.field("path", &self.path)
.finish_non_exhaustive()
}
}
impl Production {
/// Reserve the file (`<title>.<extension>` in the files folder) and open
/// the artifact. `revise` names an existing artifact to add a version to;
/// otherwise a new artifact is made. `tool_call_id` ties the card to the
/// producing call's bubble; `chat` is the turn the card is announced to
/// (`None` outside a chat turn).
///
/// # Errors
///
/// Returns an error when the file cannot be reserved or the record cannot
/// be opened; the card is failed in the second case.
pub async fn start(
workspace_dir: &Path,
files: FileRoots,
kind: ArtifactKind,
title: &str,
extension: &str,
tool_call_id: Option<&str>,
revise: Option<&str>,
chat: Option<&ApprovalChatContext>,
) -> Result<Self, String> {
let legacy_kind = if kind == ArtifactKind::Image {
LegacyArtifactKind::Image
} else {
legacy_kind_for_extension(&extension.to_ascii_lowercase())
};
let target = revise.filter(|id| !id.trim().is_empty());
let (meta, path) = super::store::create_artifact_regenerating(
workspace_dir,
files.clone(),
legacy_kind,
title,
extension,
tool_call_id,
target,
chat,
)
.await?;
let artifacts = artifacts_service_current(workspace_dir, files.clone(), None, chat);
let mut production = Self {
artifacts,
workspace_dir: workspace_dir.to_path_buf(),
files,
chat: chat.cloned(),
id: meta.id.clone(),
path,
revision: false,
};
// A revision keeps its record and history; a new artifact opens one.
let existing = production
.artifacts
.get(&meta.id)
.await
.map_err(|e| e.to_string());
let opened = match existing {
Ok(Some(record)) => {
production.revision = !record.versions.is_empty();
Ok(())
}
Ok(None) => production
.artifacts
.begin(kind, title, Some(meta.id.clone()))
.await
.map(|_| ())
.map_err(|e| e.to_string()),
Err(err) => Err(err),
};
if let Err(err) = opened {
let reason = format!("could not open the artifact record: {err}");
production.fail_card(&reason).await;
return Err(reason);
}
Ok(production)
}
/// The artifact's id.
pub fn id(&self) -> &str {
&self.id
}
/// Where the producer writes its bytes.
pub fn path(&self) -> &Path {
&self.path
}
/// File the written bytes as a new version and mark the card ready.
/// Returns the file's size.
///
/// # Errors
///
/// Returns an error when the version cannot be recorded or the card cannot
/// be marked ready; the card is failed then.
pub async fn complete(&self) -> Result<u64, String> {
let path = self.path.display().to_string();
let saved = self
.artifacts
.revise(
&self.id,
Content::File(path),
&Author::agent(super::tiny_store::AGENT_AUTHOR_ID),
None,
)
.await;
match saved {
Ok(saved) => match (
saved.notice,
saved.record.latest().and_then(|v| v.file.clone()),
) {
(None, Some(file)) => Ok(file.size_bytes),
// The version is recorded, so the production succeeded; only
// the card (and the file in the files folder) could not follow.
// The card says exactly that.
(Some(notice), Some(file)) => {
tracing::warn!(
target: "tiny-artifacts",
artifact_id = %self.id,
version = saved.version,
notice = %notice,
"[artifacts] version saved but not shown"
);
self.fail_card(&format!(
"{SAVED_NOT_SHOWN} version {} is saved, but {notice}",
saved.version
))
.await;
Ok(file.size_bytes)
}
(_, None) => {
let reason = "failed to finalize artifact: the recorded version has no file";
self.fail_card(reason).await;
Err(reason.to_string())
}
},
// Nothing was recorded: end it as any failed production ends.
Err(err) => {
let reason = format!("failed to finalize artifact: {err}");
self.fail(&reason).await;
Err(reason)
}
}
}
/// End the production with `reason`. A new artifact is failed, record and
/// card. A revision leaves the artifact as it was: the record keeps its
/// versions and the card shows the newest of them again.
pub async fn fail(&self, reason: &str) {
if self.revision {
self.restore_card(reason).await;
return;
}
let shown = match self.artifacts.fail(&self.id, reason).await {
Ok(saved) => saved.notice,
Err(err) => Some(err.to_string()),
};
// The record took the failure but the card did not follow (or the
// record could not take it): fail the card directly, so it never stays
// "generating".
if let Some(why) = shown {
tracing::warn!(
target: "tiny-artifacts",
artifact_id = %self.id,
err = %why,
"[artifacts] the failure did not reach the card; failing it directly"
);
self.fail_card(reason).await;
}
}
/// Show a revised artifact's newest recorded version again after its
/// revision failed. Failing the card is the fallback when that is not
/// possible.
async fn restore_card(&self, reason: &str) {
tracing::warn!(
target: "tiny-artifacts",
artifact_id = %self.id,
reason,
"[artifacts] revision failed; keeping the artifact's newest version"
);
let record = match self.artifacts.get(&self.id).await {
Ok(Some(record)) if record.latest().is_some() => record,
_ => return self.fail_card(reason).await,
};
let ctx = crate::core::runtime::DispatchCtx::ambient();
let scoped = crate::storage::sessions::artifact_scoped_for_in(&self.workspace_dir, &ctx);
let file_store = scoped.as_ref().map(|scoped| {
let storage = super::tiny_store::storage_bundle(scoped);
Arc::new(tiny_artifacts::BlobFileStore::new(&storage))
as Arc<dyn tiny_artifacts::FileStore>
});
let bridge = super::tiny_store::LegacyUiBridge::new(
&self.workspace_dir,
self.files.clone(),
super::tiny_store::guarded_roots(super::tiny_store::file_roots(
&self.workspace_dir,
&self.files,
None,
)),
file_store,
self.chat.as_ref(),
&ctx,
);
if let Err(err) = bridge.show_newest(&record).await {
tracing::warn!(
target: "tiny-artifacts",
artifact_id = %self.id,
err = %err,
"[artifacts] could not show the newest version again"
);
self.fail_card(reason).await;
}
}
/// Fail the card directly (when the record could not take the change).
async fn fail_card(&self, reason: &str) {
let _ = super::store::fail_artifact(
&self.workspace_dir,
self.files.clone(),
&self.id,
reason,
self.chat.as_ref(),
)
.await;
}
}
#[cfg(test)]
#[path = "production_tests.rs"]
mod tests;