everruns_core/
background.rs

1// Background tool execution contracts.
2//
3// Decision: foreground tool execution remains the default. Tools opt into
4// detached execution with the `supports_background` hint plus a native
5// `BackgroundExecutableTool` implementation.
6
7use crate::error::Result;
8use crate::tools::ToolExecutionResult;
9use crate::traits::ToolContext;
10use async_trait::async_trait;
11use serde::{Deserialize, Serialize};
12use serde_json::Value;
13use std::sync::Arc;
14
15/// Structured progress reported by background tools.
16#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
17pub struct BackgroundProgress {
18    pub current: Option<u64>,
19    pub total: Option<u64>,
20    pub unit: Option<String>,
21    pub label: Option<String>,
22}
23
24/// Final result from a completed background tool.
25#[derive(Debug, Clone, Serialize, Deserialize)]
26pub struct BackgroundOutcome {
27    pub summary: String,
28    pub result: Value,
29    #[serde(default, skip_serializing_if = "Option::is_none")]
30    pub raw_output: Option<String>,
31}
32
33/// Sink for background status, output, and progress updates.
34#[async_trait]
35pub trait BackgroundEventSink: Send + Sync {
36    async fn status(&self, message: &str) -> Result<()>;
37
38    async fn output(&self, stream: &str, delta: &str) -> Result<()>;
39
40    async fn progress(&self, progress: BackgroundProgress) -> Result<()>;
41}
42
43/// Trait implemented by tools that natively support detached execution.
44#[async_trait]
45pub trait BackgroundExecutableTool: Send + Sync {
46    async fn execute_background(
47        &self,
48        arguments: Value,
49        context: ToolContext,
50        sink: Arc<dyn BackgroundEventSink>,
51    ) -> std::result::Result<BackgroundOutcome, ToolExecutionResult>;
52}
everruns_core/background.rs

everruns_core/
background.rs
