Skip to content
Python
17.9 KB
Raw Blame
//! Friendly agent API: agents are values, runs return results.
//!
//! Shape follows the OpenAI Agents SDK (`Agent` + run + typed results and
//! interruptions); built-ins follow LangChain Deep Agents (declarative
//! subagents, a todo/plan tool, a per-tool `interrupt_on` approval map).
//! Everything is a thin layer over [`crate::HarnessClient`], so durability,
//! recovery and permission checks are unchanged.
//!
//! ```rust,no_run
//! use openworker_sdk::agents::*;
//! # async fn example(state_dir: std::path::PathBuf, runner: std::path::PathBuf,
//! # registry: ToolRegistry, workspace: std::path::PathBuf) -> Result<(), Box<dyn std::error::Error>> {
//!
//! let researcher = Agent::new("researcher")
//!     .description("Finds and verifies facts")
//!     .instructions("Research the assigned item and report evidence.")
//!     .tool("web.search");
//!
//! let assistant = Agent::new("assistant")
//!     .instructions("Help the user with their workspace.")
//!     .tools(["files.read", "files.write"])
//!     .planning(true)                  // built-in todo list (update_plan)
//!     .interrupt_on(["files.write"])   // only writes wait for a human
//!     .subagent(researcher);           // lead/worker team, created per session
//!
//! let harness = Harness::builder().state_dir(state_dir).executable(runner)
//!     .agent(assistant)
//!     .tools(registry)
//!     .embedded()
//!     .await?;
//!
//! let session = harness.session("assistant", workspace).await?;
//! let mut result = session.run("Tidy the docs folder").await?;
//! while let RunStatus::Interrupted = result.status {
//!     for i in &result.interruptions {
//!         session.respond(i, Response::Approve(ApprovalDecision::Once)).await?;
//!     }
//!     result = session.resume().await?;
//! }
//! println!("{}", result.final_output.unwrap_or_default());
//! # Ok(())
//! # }
//! ```
mod agent_team;
mod bundle;
pub mod coding;
pub(crate) mod compile;
mod harness;
mod session;
mod team;

pub use crate::{
    AccessToken, ApprovalDecision, Capture, ContentPolicy, Credentials, Model, ModelChoice,
    ModelProvider, ProviderKind, Sandbox, Storage, TelemetryAcknowledgement, TelemetryConfig,
    TelemetryHeader, TelemetrySignal, TokenRefreshReason, ToolRegistry,
};
pub use agent_team::{
    AgentTeam, AgentTeamRef, ChildContext, ChildOptions, ChildWorkspace, Communication,
    HistoryPage, HistoryQuery, Instance, RetirementMode, TeamDelegation, TeamOptions, TeamPolicy,
};
pub use harness::{AgentHandle, Harness, HarnessBuilder};
pub use session::{
    Interruption, InterruptionKind, Response, Run, RunEvent, RunResult, RunStatus, RunStream,
    Session, SessionInput, SessionRef, TeamRef, WorkerRef,
};
pub use team::{ItemSpec, ItemStatus, Team};

use crate::{Error, Result};
pub use openworker_runtime::budget::Limits as TurnLimits;
use serde::{Deserialize, Serialize};
use std::{collections::BTreeSet, path::PathBuf};

/// Who decides whether a tool call may run.
///
/// Engine hard checks (path containment, pinned identities) always apply first;
/// none of these modes can relax them.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "mode", content = "tools", rename_all = "snake_case")]
pub enum Approvals {
    /// Every tool call waits for your decision (engine `ask` mode). Default.
    #[default]
    Always,
    /// Deep Agents-style `interrupt_on`: only the listed qualified tools wait
    /// for a human. The SDK approves all other calls once, on the application's
    /// behalf, through the normal durable interaction record.
    Only(BTreeSet<String>),
    /// The engine's reviewer model decides; unsure verdicts come back to you.
    Reviewer,
    Auto(ModelChoice),
    /// No approvals (engine `bypass`). Use only for trusted, sandboxed work.
    Never,
}
impl Approvals {
    pub fn auto(model: ModelChoice) -> Self {
        Self::Auto(model)
    }
    pub(crate) fn mode(&self) -> openworker_runtime::permissions::Mode {
        use openworker_runtime::permissions::Mode;
        match self {
            Self::Always | Self::Only(_) => Mode::Ask,
            Self::Reviewer | Self::Auto(_) => Mode::AutoApprove,
            Self::Never => Mode::Bypass,
        }
    }
    /// True when the SDK may approve this call without asking. `alias` is the
    /// model-facing name in an interaction (`provider__tool`).
    pub(crate) fn auto_approves(&self, alias: &str) -> bool {
        // A reusable custom type needs its own exact-definition decision. An
        // interrupt_on exclusion must not silently approve arbitrary new roles.
        if alias == openworker_runtime::team_type_catalog::TOOL
            || alias == openworker_runtime::subagents::CREATE
        {
            return false;
        }
        match self {
            Self::Only(ask) => !ask
                .iter()
                .any(|t| t == alias || openworker_tools::model_alias(t).is_ok_and(|a| a == alias)),
            _ => false,
        }
    }
}

/// An agent definition. Cheap to clone; nothing runs until a [`Harness`] loads it.
///
/// Also the wire format of `HostConfig.agents`: other-language SDKs send the
/// same JSON representation defined by the SDK protocol types.
#[derive(Clone, Debug, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Agent {
    pub(crate) id: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub(crate) name: Option<String>,
    #[serde(default)]
    pub(crate) description: String,
    pub(crate) instructions: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub(crate) limits: Option<TurnLimits>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub(crate) builtin_tools: Option<openworker_runtime::package::BuiltinTools>,
    #[serde(default)]
    pub(crate) tools: Vec<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub(crate) model: Option<ModelChoice>,
    #[serde(default)]
    pub(crate) provider: ProviderKind,
    #[serde(default = "default_fallback_model")]
    pub(crate) fallback_model: String,
    #[serde(default)]
    pub(crate) planning: bool,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub(crate) memory: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub(crate) memory_scope: Option<String>,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub(crate) scheduling: bool,
    #[serde(default)]
    pub(crate) approvals: Approvals,
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub(crate) auto_skip_questions: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub(crate) auto_approver_context: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub(crate) compaction: Option<crate::CompactionOptions>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub(crate) subagents: Vec<Agent>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub(crate) standalone_subagents: Option<openworker_runtime::subagents::Config>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub(crate) servers: Option<PathBuf>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub(crate) tool_policy: Option<PathBuf>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub(crate) runtime_policy: Option<PathBuf>,
}
fn default_fallback_model() -> String {
    "gpt-6-sol".into()
}

impl Agent {
    /// `id` is the stable identifier sessions are pinned to: ASCII letters,
    /// digits, `-` or `_`, at most 64 characters.
    pub fn new(id: impl Into<String>) -> Self {
        Self {
            id: id.into(),
            name: None,
            description: String::new(),
            instructions: String::new(),
            limits: None,
            builtin_tools: None,
            tools: vec![],
            model: None,
            provider: ProviderKind::Openai,
            fallback_model: default_fallback_model(),
            planning: false,
            memory: false,
            memory_scope: None,
            scheduling: false,
            approvals: Approvals::default(),
            auto_skip_questions: false,
            auto_approver_context: None,
            compaction: None,
            subagents: vec![],
            standalone_subagents: None,
            servers: None,
            tool_policy: None,
            runtime_policy: None,
        }
    }
    pub fn limits(mut self, limits: TurnLimits) -> Self {
        self.limits = Some(limits);
        self
    }
    /// Select implicit session tools independently of application tools.
    pub fn builtin_tools(mut self, tools: openworker_runtime::package::BuiltinTools) -> Self {
        self.builtin_tools = Some(tools);
        self
    }
    pub fn id(&self) -> &str {
        &self.id
    }
    /// Display name. Defaults to the ID.
    pub fn name(mut self, name: impl Into<String>) -> Self {
        self.name = Some(name.into());
        self
    }
    /// When to use this agent. Shown to a lead agent when this is a subagent.
    pub fn description(mut self, description: impl Into<String>) -> Self {
        self.description = description.into();
        self
    }
    /// System prompt. Required.
    pub fn instructions(mut self, instructions: impl Into<String>) -> Self {
        self.instructions = instructions.into();
        self
    }
    /// Add one qualified tool (`provider.tool`) from the harness tool registry.
    /// With no selected tools or enabled tool-bearing capabilities, the agent
    /// is text-only and receives no implicit question/history tools.
    pub fn tool(mut self, name: impl Into<String>) -> Self {
        self.tools.push(name.into());
        self
    }
    pub fn tools<I, S>(mut self, names: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        self.tools.extend(names.into_iter().map(Into::into));
        self
    }
    /// Default model through a named model connection (see `connection/set`).
    pub fn model(mut self, connection: impl Into<String>, model: impl Into<String>) -> Self {
        self.model = Some(ModelChoice {
            connection: connection.into(),
            model: model.into(),
        });
        self
    }
    /// Default model, overridable when creating an independent session.
    pub fn default_model(mut self, model: ModelChoice) -> Self {
        self.model = Some(model);
        self
    }
    /// Engine fallback provider/model used when no named connection is selected.
    pub fn fallback_model(mut self, provider: ProviderKind, model: impl Into<String>) -> Self {
        self.provider = provider;
        self.fallback_model = model.into();
        self
    }
    /// Built-in durable todo list (`update_plan`). Bookkeeping only; it never
    /// grants permission.
    pub fn planning(mut self, enabled: bool) -> Self {
        self.planning = enabled;
        self
    }
    /// Only these qualified tools wait for a human; others are approved by the
    /// SDK. Shorthand for `.approvals(Approvals::Only(..))`.
    pub fn interrupt_on<I, S>(mut self, tools: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        self.approvals = Approvals::Only(tools.into_iter().map(Into::into).collect());
        self
    }
    pub fn auto_approver_context(mut self, text: impl Into<String>) -> Self {
        self.auto_approver_context = Some(text.into());
        self
    }
    pub fn compaction(mut self, options: crate::CompactionOptions) -> Self {
        self.compaction = Some(options);
        self
    }
    pub fn approvals(mut self, approvals: Approvals) -> Self {
        self.approvals = approvals;
        self
    }
    /// Enable durable memory tools; shared scope IDs are assigned by the app.
    pub fn memory(mut self, enabled: bool) -> Self {
        self.memory = enabled;
        self
    }
    pub fn memory_scope(mut self, scope: impl Into<String>) -> Self {
        self.memory = true;
        self.memory_scope = Some(scope.into());
        self
    }
    /// Enable bounded schedules driven by the SDK host while it runs.
    pub fn scheduling(mut self, enabled: bool) -> Self {
        self.scheduling = enabled;
        self
    }
    /// Return a recorded "no human answer available" result instead of parking
    /// ask_user. This does not approve tools or invent an answer.
    pub fn auto_skip_questions(mut self, enabled: bool) -> Self {
        self.auto_skip_questions = enabled;
        self
    }
    /// Allow model-created children with fresh context and delegated tools.
    pub fn allow_subagents(mut self, enabled: bool) -> Self {
        self.standalone_subagents = Some(openworker_runtime::subagents::Config {
            enabled,
            ..Default::default()
        });
        self
    }
    pub fn subagent_options(mut self, options: openworker_runtime::subagents::Config) -> Self {
        self.standalone_subagents = Some(options);
        self
    }
    /// Add a subagent. A session of this agent becomes a team lead with one
    /// worker session per subagent; delegation runs over the durable team board.
    pub fn subagent(mut self, agent: Agent) -> Self {
        self.subagents.push(agent);
        self
    }
    /// App-owned `servers.json` for this agent's MCP providers.
    pub fn servers(mut self, path: impl Into<PathBuf>) -> Self {
        self.servers = Some(path.into());
        self
    }
    /// Operator tool-classification policy file.
    pub fn tool_policy(mut self, path: impl Into<PathBuf>) -> Self {
        self.tool_policy = Some(path.into());
        self
    }
    /// Operator runtime policy file.
    pub fn runtime_policy(mut self, path: impl Into<PathBuf>) -> Self {
        self.runtime_policy = Some(path.into());
        self
    }

    pub(crate) fn display_name(&self) -> &str {
        self.name.as_deref().unwrap_or(&self.id)
    }

    pub(crate) fn validate(&self, nested: bool) -> Result<()> {
        let bad = |m: String| Err(Error::InvalidInput(m));
        if !openworker_runtime::bundle::safe_name(&self.id) || self.id.len() > 64 {
            return bad(format!(
                "Agent ID {:?} must be 1–64 ASCII letters, digits, '-' or '_'",
                self.id
            ));
        }
        if self.instructions.trim().is_empty() {
            return bad(format!("Agent {} needs instructions", self.id));
        }
        if self.tools.len() > 64 {
            return bad(format!("Agent {} supports at most 64 tools", self.id));
        }
        openworker_runtime::turn_options::validate_guidance(
            "autoApproverContext",
            self.auto_approver_context.as_deref(),
        )
        .map_err(|e| Error::InvalidInput(e.to_string()))?;
        if let Some(options) = &self.compaction {
            options
                .validate()
                .map_err(|e| Error::InvalidInput(e.to_string()))?;
        }
        let mut seen = BTreeSet::new();
        for tool in &self.tools {
            openworker_tools::qualified_parts(tool)
                .map_err(|e| Error::InvalidInput(format!("Agent {}: {tool}: {e}", self.id)))?;
            if !seen.insert(tool) {
                return bad(format!("Agent {} lists tool {tool} twice", self.id));
            }
        }
        if let Approvals::Only(ask) = &self.approvals {
            if let Some(t) = ask.iter().find(|t| !seen.contains(t)) {
                return bad(format!(
                    "Agent {}: interrupt_on names {t}, which is not one of its tools",
                    self.id
                ));
            }
        }
        if let Some(m) = &self.model {
            m.validate()
                .map_err(|e| Error::InvalidInput(format!("Agent {}: {e}", self.id)))?;
        }
        for path in [&self.servers, &self.tool_policy, &self.runtime_policy]
            .into_iter()
            .flatten()
        {
            if !path.is_absolute() {
                return bad(format!("Agent {}: policy paths must be absolute", self.id));
            }
        }
        if let Some(config) = &self.standalone_subagents {
            config
                .validate()
                .map_err(|e| Error::InvalidInput(e.to_string()))?;
            if config.enabled && (nested || !self.subagents.is_empty()) {
                return bad(
                    "Standalone delegation cannot be combined with legacy board subagents".into(),
                );
            }
        }
        if nested && !self.subagents.is_empty() {
            return bad(format!(
                "Subagent {} cannot have its own subagents (one team level)",
                self.id
            ));
        }
        if self.subagents.len() > 15 {
            return bad(format!("Agent {} has more than 15 subagents", self.id));
        }
        if !self.subagents.is_empty() {
            // Team member display names must be unique (case-insensitive) and short.
            let mut names = BTreeSet::new();
            for a in std::iter::once(self).chain(&self.subagents) {
                let name = a.display_name().trim().to_lowercase();
                if name.is_empty() || a.display_name().len() > 100 || !names.insert(name) {
                    return bad(format!(
                        "Agent {}: team display names must be unique and at most 100 bytes",
                        self.id
                    ));
                }
            }
        }
        let mut ids = BTreeSet::new();
        for sub in &self.subagents {
            sub.validate(true)?;
            if sub.id == self.id || !ids.insert(&sub.id) {
                return bad(format!("Agent {}: duplicate subagent {}", self.id, sub.id));
            }
        }
        Ok(())
    }
}

/// Configuration for model-created standalone children.
pub use openworker_runtime::subagents::Config as SubagentOptions;

#[cfg(test)]
mod tool_free_tests {
    use super::*;
    #[test]
    fn tool_free_agent_validates_without_enabling_capabilities() {
        let agent = Agent::new("guide").instructions("Answer from supplied context only.");
        agent.validate(false).unwrap();
        assert!(agent.tools.is_empty());
        assert!(!agent.memory && !agent.planning && !agent.scheduling);
    }
}