Skip to content

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

24.6 KB
Raw Blame
//! Tool: `generate_presentation` — build a `.pptx` deck from a
//! structured slide spec via the native-Rust [`engine`] module.
//!
//! Flow:
//! 1. Validate source-agnostic request metadata through the bus contract before
//!    touching image references, resolve readable images under host policy,
//!    then validate the resolved bus spec before artifact production.
//! 2. Start a [`Production`]: it reserves `<title>.pptx` in the files folder
//!    (the card shows "generating…") and opens the versioned artifact — or,
//!    with an `artifact_id` arg or a regenerate in scope, a new version of
//!    that artifact under the same id and file.
//! 3. Generate the deck bytes via [`engine::generate`] — pure Rust,
//!    `ppt-rs`-backed, no Python runtime, no subprocess. Wrapped in
//!    `spawn_blocking` + `tokio::time::timeout` so the synchronous
//!    library work neither blocks the async executor nor can wedge
//!    the agent loop.
//! 4. Write the bytes and [`Production::complete`]: the file becomes the
//!    artifact's newest version and the card turns ready.
//! 5. On failure: [`Production::fail`] so the UI can surface the reason.
//!
//! Originally shipped in #2778 against a managed python-pptx venv;
//! refactored to a native-Rust engine in #2780-follow-up to drop the
//! Python runtime + first-call venv-install latency + 50 MB+ Python
//! disk footprint. Tool name / input schema / output schema / artifact
//! layout are byte-identical across the swap so #3017 ArtifactCard,
//! #3026 Files panel, and the orchestrator grounding rule in #3029
//! continue to work without change.

use crate::agent::tinyagents::host::run_context::dispatch_ctx_for_tool;
use crate::core::runtime::DispatchCtx;
use std::path::PathBuf;
use std::sync::Arc;
use std::time::Duration;

use async_trait::async_trait;
use serde_json::{json, Value};

use crate::artifacts::production::Production;
use crate::artifacts::read_artifact_bytes;
use crate::security::SecurityPolicy;
use tinytools::{PermissionLevel, Tool, ToolResult};

mod engine;
mod types;

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

use tinydocs_bus::spec::SlideImage;

use self::types::{
    to_bus_spec, validate_image_references, validate_request, GeneratePresentationInput,
    GeneratePresentationOutput, PresentationError, SlideImageRequest, SlideImageSource,
    MAX_IMAGE_BYTES,
};

/// Generation timeout. `ppt-rs` typically completes the full 64-slide
/// cap in well under a second; the 30 s ceiling is a defensive bound
/// against pathological inputs slipping past bus spec validation and
/// the worst-case `spawn_blocking` thread-acquisition latency on a
/// saturated runtime.
const GENERATION_TIMEOUT: Duration = Duration::from_secs(30);

/// Tool name surfaced to the agent. Stable; do not rename without
/// coordinating with the orchestrator agent definition list.
pub const TOOL_NAME: &str = "generate_presentation";

#[async_trait]
trait ImageInspector: Sync {
    async fn inspect(&self, bytes: &[u8]) -> Result<tinydocs_bus::ImageFacts, String>;
}

#[async_trait]
trait ImageResolver: Sync {
    async fn resolve(
        &self,
        tool: &PresentationTool,
        input: &GeneratePresentationInput,
        ctx: &DispatchCtx,
    ) -> (Vec<Vec<SlideImage>>, Vec<String>);
}

struct HostImageResolver;

#[async_trait]
impl ImageResolver for HostImageResolver {
    async fn resolve(
        &self,
        tool: &PresentationTool,
        input: &GeneratePresentationInput,
        ctx: &DispatchCtx,
    ) -> (Vec<Vec<SlideImage>>, Vec<String>) {
        tool.resolve_images(input, ctx).await
    }
}

struct ModuleImageInspector<'a> {
    config: Option<&'a crate::config::Config>,
    ctx: &'a DispatchCtx,
}

#[async_trait]
impl ImageInspector for ModuleImageInspector<'_> {
    async fn inspect(&self, bytes: &[u8]) -> Result<tinydocs_bus::ImageFacts, String> {
        let loaded;
        let config = match self.config {
            Some(config) => config,
            None => {
                loaded = self
                    .ctx
                    .load_config()
                    .await
                    .map_err(|error| format!("config unavailable: {error}"))?;
                &loaded
            }
        };
        crate::modules::documents::ensure_ready(config)
            .await
            .map_err(|error| error.to_string())?;
        tokio::time::timeout(
            GENERATION_TIMEOUT,
            crate::modules::documents::inspect_image(config, bytes),
        )
        .await
        .map_err(|_| "image inspection timed out".to_string())?
        .map_err(|error| error.to_string())
    }
}

/// One-shot `.pptx` generator. See module docs for the request flow.
pub struct PresentationTool {
    workspace_dir: PathBuf,
    /// Visible folder the generated deck is written into (#5505).
    files_dir: crate::artifacts::FileRoots,
    /// Existing host config when the caller already owns the authoritative
    /// runtime snapshot. Keeping this optional preserves the ordinary agent
    /// constructor while avoiding a process-global config reload during
    /// artifact regeneration.
    config: Option<crate::config::Config>,
    /// Security policy used to validate agent-supplied `File` image paths
    /// before any filesystem read — an image path must pass the same
    /// `validate_path` checks (allowed-location, symlink-escape, forbidden
    /// dirs) as any other file-read operation.
    security: Arc<SecurityPolicy>,
    /// The artifact id a Retry re-dispatches this generation under
    /// (`artifacts::ops::ai_regenerate`); `None` mints a fresh artifact.
    regenerate_target: Option<String>,
}

impl PresentationTool {
    /// Production constructor. The engine is stateless — no runtime
    /// resolution, venv setup, or cache directory needed. Pass the
    /// workspace directory the artifact pipeline writes into, plus the
    /// active [`SecurityPolicy`] for validating `File`-source image paths.
    pub fn new(
        workspace_dir: PathBuf,
        files_dir: impl Into<crate::artifacts::FileRoots>,
        security: Arc<SecurityPolicy>,
    ) -> Self {
        Self {
            workspace_dir,
            files_dir: files_dir.into(),
            config: None,
            security,
            regenerate_target: None,
        }
    }

    /// The agent-registry constructor: the artifact metadata goes to
    /// `config.workspace_dir`, the deck to the files folder (#5505).
    pub fn for_config(config: &crate::config::Config, security: Arc<SecurityPolicy>) -> Self {
        Self::with_config(
            config.workspace_dir.clone(),
            crate::artifacts::FileRoots::from_config(config),
            security,
            config.clone(),
        )
    }

    /// Construct the tool with an authoritative host config snapshot.
    pub(crate) fn with_config(
        workspace_dir: PathBuf,
        files_dir: impl Into<crate::artifacts::FileRoots>,
        security: Arc<SecurityPolicy>,
        config: crate::config::Config,
    ) -> Self {
        Self {
            workspace_dir,
            files_dir: files_dir.into(),
            config: Some(config),
            security,
            regenerate_target: None,
        }
    }

    /// Re-dispatch this generation under an existing artifact id, so the
    /// failed card is replaced in place (#3162).
    pub(crate) fn with_regenerate_target(mut self, artifact_id: impl Into<String>) -> Self {
        self.regenerate_target = Some(artifact_id.into());
        self
    }
}

#[async_trait]
impl Tool for PresentationTool {
    fn name(&self) -> &str {
        TOOL_NAME
    }

    fn description(&self) -> &str {
        // Router-rule format per the existing tool conventions (see
        // `current_time.rs` etc.): tell the orchestrator when to use
        // this tool and when NOT to.
        "Generate a PowerPoint (.pptx) presentation from a structured slide spec. \
         USE THIS when the user asks for slides, a deck, a presentation, or a \
         slide-by-slide breakdown of a topic. Provide `title` plus a `slides` \
         array of `{title, body?, bullets?, speaker_notes?}` objects. NOT for: \
         per-slide image generation, live editing of existing decks, or non-PPT \
         formats (PDF, Keynote, Google Slides exports). The generated file is \
         persisted as an artifact in the workspace and the tool returns the \
         artifact id + absolute path so the agent can reference it in the reply."
    }

    fn parameters_schema(&self) -> Value {
        // Built as separate `json!` bindings (rather than one deeply-nested
        // literal) to keep macro expansion within the crate's default
        // recursion limit — the per-slide `images` sub-schema adds enough
        // depth to overflow a single combined literal.
        let image_item_schema = json!({
            "type": "object",
            "additionalProperties": false,
            "required": ["source"],
            "properties": {
                "source": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["type"],
                    "description": "Image data source. Use `{type:'artifact', artifact_id}` for a prior tool's output, or `{type:'file', path}` for a readable local file.",
                    "properties": {
                        "type": { "type": "string", "enum": ["artifact", "file"] },
                        "artifact_id": { "type": "string", "description": "Required when type='artifact'." },
                        "path": { "type": "string", "description": "Required when type='file'. Absolute or action-dir-relative path." }
                    }
                },
                "caption": {
                    "type": "string",
                    "maxLength": types::MAX_TEXT_CHARS,
                    "description": "Optional caption rendered as a text bullet beneath the image."
                }
            }
        });

        let images_schema = json!({
            "type": "array",
            "maxItems": types::MAX_IMAGES_PER_SLIDE,
            "description": "Images to embed beneath the slide text, single-column. PNG or JPEG only (≤5 MB each, ≤8 per deck). Each image's bytes come from a workspace artifact or a local file path the agent can read. Only attach an image whose content you have actually inspected — do not claim an image shows something you have not verified.",
            "items": image_item_schema,
        });

        let slide_item_schema = json!({
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "title": { "type": "string", "maxLength": types::MAX_TEXT_CHARS },
                "body": { "type": "string", "maxLength": types::MAX_TEXT_CHARS },
                "bullets": {
                    "type": "array",
                    "maxItems": types::MAX_BULLETS_PER_SLIDE,
                    "items": { "type": "string", "maxLength": types::MAX_TEXT_CHARS }
                },
                "speaker_notes": { "type": "string", "maxLength": types::MAX_TEXT_CHARS },
                "images": images_schema,
            }
        });

        json!({
            "type": "object",
            "additionalProperties": false,
            "required": ["title", "slides"],
            "properties": {
                "title": {
                    "type": "string",
                    "description": "Deck title. Surfaced on the title slide and used as the artifact's human-readable name. Required, non-empty.",
                    "maxLength": types::MAX_TEXT_CHARS,
                },
                "artifact_id": {
                    "type": "string",
                    "description": "Optional artifact id to update. Pass an id from a prior generate_presentation call to save this deck as a new version of that artifact instead of creating a new one.",
                },
                "author": {
                    "type": "string",
                    "description": "Optional author byline shown on the title slide.",
                    "maxLength": types::MAX_TEXT_CHARS,
                },
                "theme": {
                    "type": "string",
                    "description": "Reserved for future template-selection work. Currently informational only.",
                    "maxLength": types::MAX_TEXT_CHARS,
                },
                "slides": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": types::MAX_SLIDES,
                    "description": "Slide specs in display order. At least one entry required; hard cap to bound generation time + output size.",
                    "items": slide_item_schema,
                }
            }
        })
    }

    fn permission_level(&self) -> PermissionLevel {
        // We write files to the workspace artifacts dir. Treat as
        // Write rather than ReadOnly. No subprocess / network reach.
        PermissionLevel::Write
    }

    fn supports_markdown(&self) -> bool {
        true
    }

    async fn execute(&self, args: Value) -> anyhow::Result<ToolResult> {
        self.run(args, None, &dispatch_ctx_for_tool(None)).await
    }

    async fn execute_with_context(
        &self,
        args: Value,
        _options: tinytools::ToolCallOptions,
        context: Option<&dyn tinytools::ToolRunContext>,
    ) -> anyhow::Result<ToolResult> {
        let approval = crate::agent::tinyagents::host::run_context::approval_for_tool(context);
        self.run(
            args,
            approval.chat.as_ref(),
            &dispatch_ctx_for_tool(context),
        )
        .await
    }
}

impl PresentationTool {
    /// Produces the deck for a turn whose chat routing is `chat` (`None`
    /// outside a chat turn).
    pub(crate) async fn run(
        &self,
        args: Value,
        chat: Option<&crate::security::approval::ApprovalChatContext>,
        ctx: &DispatchCtx,
    ) -> anyhow::Result<ToolResult> {
        self.run_with_resolver(args, chat, ctx, &HostImageResolver)
            .await
    }

    async fn run_with_resolver(
        &self,
        args: Value,
        chat: Option<&crate::security::approval::ApprovalChatContext>,
        ctx: &DispatchCtx,
        resolver: &impl ImageResolver,
    ) -> anyhow::Result<ToolResult> {
        let input: GeneratePresentationInput = match serde_json::from_value(args.clone()) {
            Ok(v) => v,
            Err(err) => {
                let msg = format!("invalid generate_presentation arguments: {err}");
                tracing::warn!(target: "presentation", err = %err, "[presentation] deserialisation failed");
                return Ok(ToolResult::error(msg));
            }
        };

        if let Err(err) = validate_request(&input).and_then(|()| validate_image_references(&input))
        {
            tracing::debug!(target: "presentation", err = %err, "[presentation] validation rejected input");
            return Ok(ToolResult::error(err.to_string()));
        }

        // Resolve + validate per-slide images at the async boundary. A
        // bad image is skipped with a warning (partial success) rather
        // than failing the whole deck — mirrors the #3076 ethos.
        let (resolved_images, image_warnings) = resolver.resolve(self, &input, ctx).await;
        if !image_warnings.is_empty() {
            tracing::info!(
                target: "presentation",
                warning_count = image_warnings.len(),
                "[presentation] some images skipped with warnings"
            );
        }

        let spec = match to_bus_spec(&input, resolved_images) {
            Ok(spec) => spec,
            Err(err) => return Ok(ToolResult::error(err.to_string())),
        };
        if let Err(err) = spec.validate().map_err(PresentationError::from) {
            tracing::debug!(target: "presentation", err = %err, "[presentation] validation rejected input");
            return Ok(ToolResult::error(err.to_string()));
        }

        tracing::info!(
            target: "presentation",
            title_chars = input.title.chars().count(),
            has_author = input.author.is_some(),
            slide_count = input.slides.len(),
            "[presentation] generation request accepted"
        );

        // Reserve the file and open the artifact: a new one, or a new version
        // of `artifact_id` / the regenerate target (same id, same file,
        // history kept).
        let production = Production::start(
            &self.workspace_dir,
            self.files_dir.clone(),
            tiny_artifacts::ArtifactKind::File,
            &input.title,
            "pptx",
            None,
            input
                .artifact_id
                .as_deref()
                .or(self.regenerate_target.as_deref()),
            chat,
        )
        .await
        .map_err(anyhow::Error::msg)?;
        let output_path = production.path().to_path_buf();

        // Persist the verbatim args next to meta.json so a failed card's
        // Retry can re-dispatch this exact spec deterministically (#3162).
        // Best-effort: a write failure only forfeits future regeneration,
        // it must not abort an otherwise-successful generation.
        if let Err(err) =
            crate::artifacts::store::save_artifact_args(&self.workspace_dir, production.id(), &args)
                .await
        {
            tracing::warn!(
                target: "presentation",
                err = %err,
                artifact_id = %production.id(),
                "[presentation] failed to persist args.json; artifact will not be regenerable"
            );
        }

        let bytes = match engine::generate(&spec, GENERATION_TIMEOUT, self.config.as_ref()).await {
            Ok(bytes) => bytes,
            Err(err) => {
                production.fail(&err.to_string()).await;
                tracing::warn!(
                    target: "presentation",
                    err = %err,
                    "[presentation] engine generation failed"
                );
                return Ok(ToolResult::error(err.to_string()));
            }
        };

        if let Err(err) = tokio::fs::write(&output_path, &bytes).await {
            let filename = output_path
                .file_name()
                .map(|n| n.to_string_lossy().into_owned())
                .unwrap_or_default();
            let reason = format!("failed to write generated deck ({filename}): {err}");
            production.fail(&reason).await;
            tracing::warn!(
                target: "presentation",
                err = %err,
                artifact_id = %production.id(),
                filename = %filename,
                "[presentation] artifact file write failed"
            );
            return Ok(ToolResult::error(reason));
        }

        // Record the file as the artifact's newest version; the card turns
        // ready from that record.
        let size_bytes = match production.complete().await {
            Ok(size) => size,
            Err(reason) => {
                tracing::warn!(
                    target: "presentation",
                    artifact_id = %production.id(),
                    "[presentation] {reason}"
                );
                return Ok(ToolResult::error(reason));
            }
        };

        tracing::info!(
            target: "presentation",
            artifact_id = %production.id(),
            size_bytes,
            slide_count = input.slides.len(),
            "[presentation] generation complete"
        );

        let out = GeneratePresentationOutput {
            artifact_id: production.id().to_string(),
            artifact_path: output_path.display().to_string(),
            slide_count: input.slides.len(),
            size_bytes,
            image_warnings,
        };
        let payload = serde_json::to_value(&out)?;
        let mut markdown = format!(
            "Generated {}-slide presentation at `{}` (artifact `{}`, {} bytes).",
            out.slide_count, out.artifact_path, out.artifact_id, out.size_bytes
        );
        if !out.image_warnings.is_empty() {
            markdown.push_str("\n\n⚠️ Some images were skipped:");
            for warning in &out.image_warnings {
                markdown.push_str(&format!("\n- {warning}"));
            }
        }
        Ok(ToolResult::success_with_markdown(payload, markdown))
    }
}

impl PresentationTool {
    /// Resolve + validate every slide's images at the async boundary,
    /// returning a per-slide vec of embeddable images (aligned 1:1 with
    /// `input.slides`) plus a flat list of human-readable warnings for
    /// images that were skipped.
    ///
    /// A skip is never fatal: a deck with one bad image still renders,
    /// minus that image, and the agent is told why via the warning list.
    async fn resolve_images(
        &self,
        input: &GeneratePresentationInput,
        ctx: &DispatchCtx,
    ) -> (Vec<Vec<SlideImage>>, Vec<String>) {
        self.resolve_images_with_inspector(
            input,
            &ModuleImageInspector {
                config: self.config.as_ref(),
                ctx,
            },
        )
        .await
    }

    async fn resolve_images_with_inspector(
        &self,
        input: &GeneratePresentationInput,
        inspector: &impl ImageInspector,
    ) -> (Vec<Vec<SlideImage>>, Vec<String>) {
        let mut per_slide: Vec<Vec<SlideImage>> = Vec::with_capacity(input.slides.len());
        let mut warnings: Vec<String> = Vec::new();

        for (slide_idx, spec) in input.slides.iter().enumerate() {
            let mut resolved = Vec::with_capacity(spec.images.len());
            for (img_idx, image) in spec.images.iter().enumerate() {
                match self.resolve_one_image(image, inspector).await {
                    Ok(r) => resolved.push(r),
                    Err(reason) => {
                        // 1-based indices in the message (matches how the
                        // agent thinks about "slide 2, image 1").
                        warnings.push(format!(
                            "slide {} image {}: {reason}",
                            slide_idx + 1,
                            img_idx + 1
                        ));
                    }
                }
            }
            per_slide.push(resolved);
        }

        (per_slide, warnings)
    }

    /// Resolve a single [`SlideImageRequest`] to validated, embeddable bytes.
    /// Returns `Err(reason)` (a short human-readable string) when the
    /// image cannot be embedded — the caller turns that into a skip
    /// warning.
    async fn resolve_one_image(
        &self,
        image: &SlideImageRequest,
        inspector: &impl ImageInspector,
    ) -> Result<SlideImage, String> {
        let bytes = match &image.source {
            SlideImageSource::Artifact { artifact_id } => {
                read_artifact_bytes(&self.workspace_dir, &self.files_dir, artifact_id)
                    .await
                    .map_err(|e| format!("artifact {artifact_id} unreadable: {e}"))?
            }
            SlideImageSource::File { path } => {
                // Validate the agent-supplied path against the security
                // policy BEFORE touching the filesystem. This enforces the
                // same allowed-location / symlink-escape / forbidden-dir
                // checks as every other file-read tool — without it an
                // agent could embed `/etc/shadow` or `~/.ssh/id_rsa`.
                // `validate_path` returns the canonical, in-policy path.
                let resolved = self
                    .security
                    .validate_path(path)
                    .await
                    .map_err(|e| format!("file {path} not allowed: {e}"))?;
                // Stat first so a pathologically large file is rejected
                // before we pull it into memory.
                let meta = tokio::fs::metadata(&resolved)
                    .await
                    .map_err(|e| format!("file {path} unreadable: {e}"))?;
                if meta.len() as usize > MAX_IMAGE_BYTES {
                    return Err(format!(
                        "file {path} is {} bytes, exceeds {MAX_IMAGE_BYTES}-byte cap",
                        meta.len()
                    ));
                }
                tokio::fs::read(&resolved)
                    .await
                    .map_err(|e| format!("file {path} unreadable: {e}"))?
            }
        };

        if bytes.len() > MAX_IMAGE_BYTES {
            return Err(format!(
                "image is {} bytes, exceeds {MAX_IMAGE_BYTES}-byte cap",
                bytes.len()
            ));
        }

        let facts = inspector.inspect(&bytes).await?;

        Ok(SlideImage {
            bytes,
            format: facts.format,
            width_px: facts.width_px,
            height_px: facts.height_px,
            caption: image.caption.clone(),
        })
    }
}