Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

9.3 KB
Raw Blame
//! Artifact rows in a thread's message log.
//!
//! When an artifact becomes ready in a chat, a row is appended to the thread's
//! message log recording which turn made it: `type: "artifact"` with
//! `extraMetadata: { artifactId, requestId }`. The UI reads the row to render
//! the artifact's card inside that turn's reply, so a card stays with its
//! message across refreshes, cleared client storage and other devices. The row
//! is the only record of that placement; the UI's own artifact state is a
//! cache.
//!
//! The rows are for the UI only. Every core reader of the message log goes
//! through [`crate::threads::store::get_messages`] or its blocking twin, which
//! drop them, so they never reach a model (title generation, memory backfill,
//! voice context, channel adapters, edit/regenerate). Only the UI's
//! `threads.messages_list` reads the log with them.
//!
//! Artifacts made before these rows existed get one on demand
//! ([`backfill_artifact_rows`]): the turn is the first agent reply saved at or
//! after the artifact, since a turn makes its artifacts before its reply is
//! saved.

use std::path::{Path, PathBuf};
use std::sync::{Arc, OnceLock};

use async_trait::async_trait;
use chrono::{DateTime, Utc};
use serde_json::json;
use tinybus::{EventHandler, SubscriptionHandle};

use crate::artifacts::types::{ArtifactMeta, ArtifactStatus};
use crate::core::events::DomainEvent;
use crate::core::runtime::DispatchCtx;
use crate::threads::store::{self as conversations, ConversationMessage};

/// `type` of an artifact row.
pub const ARTIFACT_MESSAGE_TYPE: &str = "artifact";

const LOG_PREFIX: &str = "[threads:artifact-rows]";

/// Artifacts read per page when a thread is backfilled.
const BACKFILL_PAGE: usize = 1_000;

/// The row id for an artifact. One row per artifact: a new version, a retry or
/// a re-delivered ready event finds the row already there.
pub fn artifact_row_id(artifact_id: &str) -> String {
    format!("{ARTIFACT_ROW_ID_PREFIX}{artifact_id}")
}

/// Prefix of every artifact row's id ([`artifact_row_id`]).
const ARTIFACT_ROW_ID_PREFIX: &str = "artifact:";

/// Whether `message_id` names an artifact row: for readers that see ids but not
/// message types, such as search hits.
pub fn is_artifact_row_id(message_id: &str) -> bool {
    message_id.starts_with(ARTIFACT_ROW_ID_PREFIX)
}

/// Whether `message` is an artifact row.
pub fn is_artifact_row(message: &ConversationMessage) -> bool {
    message.message_type == ARTIFACT_MESSAGE_TYPE
}

/// `messages` without artifact rows: what every non-UI reader sees.
pub fn without_artifact_rows(messages: Vec<ConversationMessage>) -> Vec<ConversationMessage> {
    messages
        .into_iter()
        .filter(|message| !is_artifact_row(message))
        .collect()
}

fn artifact_row(
    artifact_id: &str,
    title: &str,
    request_id: Option<&str>,
    created_at: String,
) -> ConversationMessage {
    let mut extra_metadata = json!({ "artifactId": artifact_id });
    if let Some(request_id) = request_id {
        extra_metadata["requestId"] = json!(request_id);
    }
    ConversationMessage {
        id: artifact_row_id(artifact_id),
        content: title.to_string(),
        message_type: ARTIFACT_MESSAGE_TYPE.to_string(),
        extra_metadata,
        sender: "agent".to_string(),
        created_at,
    }
}

/// Append the row for `artifact_id` unless the thread already has it. Returns
/// whether a row was written.
pub async fn record_artifact_row(
    ctx: &DispatchCtx,
    workspace_dir: PathBuf,
    thread_id: &str,
    artifact_id: &str,
    title: &str,
    request_id: Option<&str>,
) -> Result<bool, String> {
    let messages = conversations::blocking::get_messages_with_artifact_rows(
        ctx.clone(),
        workspace_dir.clone(),
        thread_id,
    )
    .await?;
    let row_id = artifact_row_id(artifact_id);
    if messages.iter().any(|message| message.id == row_id) {
        return Ok(false);
    }
    let row = artifact_row(artifact_id, title, request_id, Utc::now().to_rfc3339());
    conversations::blocking::append_message(ctx.clone(), workspace_dir, thread_id.to_string(), row)
        .await?;
    log::debug!(
        "{LOG_PREFIX} recorded artifact_id={artifact_id} thread_id={thread_id} request_id={request_id:?}"
    );
    Ok(true)
}

fn parse_time(raw: &str) -> Option<DateTime<Utc>> {
    DateTime::parse_from_rfc3339(raw)
        .ok()
        .map(|time| time.with_timezone(&Utc))
}

/// The turn that made an artifact created at `created_at`: the first agent
/// reply saved at or after it. `None` when the artifact is newer than every
/// reply (its turn has not saved one).
fn owning_request_id(
    messages: &[ConversationMessage],
    created_at: DateTime<Utc>,
) -> Option<String> {
    messages
        .iter()
        .filter(|message| message.sender == "agent" && !is_artifact_row(message))
        .filter_map(|message| {
            let request_id = message.extra_metadata.get("requestId")?.as_str()?;
            Some((parse_time(&message.created_at)?, request_id))
        })
        .filter(|(saved_at, _)| *saved_at >= created_at)
        .min_by_key(|(saved_at, _)| *saved_at)
        .map(|(_, request_id)| request_id.to_string())
}

/// Rows for `artifacts` the thread has none for, in creation order. Only ready
/// artifacts without a tool call get one: a tool call's artifact renders with
/// its tool call.
pub(crate) fn missing_rows(
    messages: &[ConversationMessage],
    artifacts: &[ArtifactMeta],
) -> Vec<ConversationMessage> {
    let mut missing: Vec<&ArtifactMeta> = artifacts
        .iter()
        .filter(|artifact| artifact.status == ArtifactStatus::Ready)
        .filter(|artifact| artifact.tool_call_id.is_none())
        .filter(|artifact| {
            let row_id = artifact_row_id(&artifact.id);
            !messages.iter().any(|message| message.id == row_id)
        })
        .collect();
    missing.sort_by_key(|artifact| artifact.created_at);
    missing
        .into_iter()
        .map(|artifact| {
            let request_id = owning_request_id(messages, artifact.created_at);
            artifact_row(
                &artifact.id,
                &artifact.title,
                request_id.as_deref(),
                artifact.created_at.to_rfc3339(),
            )
        })
        .collect()
}

/// Write rows for the thread's artifacts that have none (made before these
/// rows existed, or whose row write failed), given the thread's full message
/// log. Returns the rows written.
pub async fn backfill_artifact_rows(
    ctx: &DispatchCtx,
    workspace_dir: &Path,
    thread_id: &str,
    messages: &[ConversationMessage],
) -> Result<Vec<ConversationMessage>, String> {
    let mut artifacts = Vec::new();
    loop {
        let (page, total) = crate::artifacts::store::list_artifacts(
            workspace_dir,
            artifacts.len(),
            BACKFILL_PAGE,
            Some(thread_id),
        )
        .await?;
        let empty = page.is_empty();
        artifacts.extend(page);
        if empty || artifacts.len() >= total {
            break;
        }
    }
    let mut written = Vec::new();
    for row in missing_rows(messages, &artifacts) {
        let stored = conversations::blocking::append_message(
            ctx.clone(),
            workspace_dir.to_path_buf(),
            thread_id.to_string(),
            row,
        )
        .await?;
        written.push(stored);
    }
    if !written.is_empty() {
        log::info!(
            "{LOG_PREFIX} backfilled {} artifact row(s) thread_id={thread_id}",
            written.len()
        );
    }
    Ok(written)
}

/// Writes an artifact's row when it becomes ready in a chat.
struct ArtifactRowSubscriber;

#[async_trait]
impl EventHandler<DomainEvent> for ArtifactRowSubscriber {
    fn name(&self) -> &str {
        "threads::artifact_rows"
    }

    fn domains(&self) -> Option<&[&str]> {
        Some(&["artifact"])
    }

    async fn handle(&self, event: &DomainEvent) {
        let DomainEvent::ArtifactReady {
            artifact_id,
            title,
            workspace_dir,
            thread_id: Some(thread_id),
            tool_call_id: None,
            request_id,
            ..
        } = event
        else {
            return;
        };
        // A bus event carries no context of its own (see
        // `DispatchCtx::host_default`).
        if let Err(error) = record_artifact_row(
            &DispatchCtx::host_default(),
            PathBuf::from(workspace_dir),
            thread_id,
            artifact_id,
            title,
            request_id.as_deref(),
        )
        .await
        {
            log::warn!(
                "{LOG_PREFIX} row write failed artifact_id={artifact_id} thread_id={thread_id}: {error}"
            );
        }
    }
}

static ARTIFACT_ROW_HANDLE: OnceLock<SubscriptionHandle> = OnceLock::new();

/// Register the subscriber that writes artifact rows. Idempotent.
pub fn register_artifact_row_subscriber() {
    if ARTIFACT_ROW_HANDLE.get().is_some() {
        return;
    }
    match crate::core::bus::BUS.subscribe(Arc::new(ArtifactRowSubscriber)) {
        Some(handle) => {
            let _ = ARTIFACT_ROW_HANDLE.set(handle);
            log::info!("{LOG_PREFIX} subscriber registered (domain=artifact)");
        }
        None => log::warn!("{LOG_PREFIX} failed to register subscriber — bus not initialized"),
    }
}

#[cfg(test)]
#[path = "artifact_rows_tests.rs"]
mod tests;