Python
//! Development Rust API for the same engine embedded or over managed private stdio.
//! No request is automatically resubmitted after transport failure.
pub mod agents;
#[cfg(feature = "evaluation-export")]
mod evaluation_export;
mod instrumentation;
pub mod recording;
pub use recording::{RecordingConfig, RecordingDatabase, TraceQuery};
mod application_tools;
mod callbacks;
mod provider_callbacks;
mod safety_callbacks;
pub use application_tools::{Tool, ToolContext};
pub use openworker_runtime::safety as guardrails;
pub mod cli;
mod desktop;
mod mcp;
pub use agents::Approvals;
pub use mcp::McpServer;
mod driver;
pub mod host;
mod providers;
pub use agents::{
Agent, AgentHandle, AgentTeam, AgentTeamRef, Harness, HarnessBuilder, TeamOptions, TeamPolicy,
};
pub use agents::{Run, Session, SessionInput, TurnLimits};
pub use desktop::{DesktopOptions, SessionOptions, TurnOptions};
pub use openworker_runtime::compaction::Instructions as CompactionOptions;
pub use openworker_runtime::history_import::HistoryItem;
pub use openworker_runtime::package::BuiltinTools;
pub use openworker_runtime::turn_options::OutputOptions;
mod transport;
pub use host::{CoworkerConfig, HostConfig, HostProcessConfig, Storage};
pub use openworker_runtime::anthropic::Thinking as AnthropicThinking;
pub use openworker_runtime::provider::{
Diagnostic as ProviderDiagnostic, Failure as ProviderFailure, ReasoningKind,
};
pub use openworker_runtime::provider_auth::{AccessToken, Reason as TokenRefreshReason};
pub use openworker_runtime::team_service::{Command as TeamCommand, Create as TeamCreate};
pub use openworker_runtime::teams::{Member as TeamMember, Role as TeamRole};
/// OTLP/HTTP export settings: `endpoint` (collector origin, HTTPS or loopback
/// HTTP) and `deployment` (label, default `"default"`).
pub use openworker_telemetry::config::{
Acknowledgement as TelemetryAcknowledgement, Config as TelemetryConfig,
Header as TelemetryHeader, Signal as TelemetrySignal,
};
/// Opt-in prompt/tool content in telemetry (off by default).
pub use openworker_telemetry::{Capture, ContentPolicy};
pub use providers::{Credentials, Model, ModelApi, ModelProvider};
pub enum EmbeddedConfig {
Local(RuntimeConfig),
Host(Box<HostConfig>),
}
impl From<RuntimeConfig> for EmbeddedConfig {
fn from(c: RuntimeConfig) -> Self {
Self::Local(c)
}
}
impl From<HostConfig> for EmbeddedConfig {
fn from(c: HostConfig) -> Self {
Self::Host(Box::new(c))
}
}
pub enum StdioConfig {
Local(Box<ProcessConfig>),
Host(Box<HostProcessConfig>),
}
impl From<ProcessConfig> for StdioConfig {
fn from(c: ProcessConfig) -> Self {
Self::Local(Box::new(c))
}
}
impl From<HostProcessConfig> for StdioConfig {
fn from(c: HostProcessConfig) -> Self {
Self::Host(Box::new(c))
}
}
pub use openworker_runtime::connections::Choice as ModelChoice;
pub use openworker_runtime::provider::Kind as ProviderKind;
pub use openworker_runtime::{execution::Backend as Sandbox, store::Event};
pub use openworker_tools::ToolRegistry;
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};
use std::{path::PathBuf, sync::Arc, time::Duration};
use tokio::sync::{broadcast, mpsc, oneshot, watch};
use tokio_util::sync::CancellationToken;
pub type Result<T> = std::result::Result<T, Error>;
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Error {
InvalidInput(String),
Remote(String),
Provider(openworker_runtime::provider::Diagnostic),
Setup(String),
Unavailable,
/// May have committed or started. Reconcile durable IDs; do not blindly retry.
OutcomeUnknown,
Closed,
}
impl std::fmt::Display for Error {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::InvalidInput(s) | Self::Remote(s) | Self::Setup(s) => f.write_str(s),
Self::Provider(diagnostic) => std::fmt::Display::fmt(diagnostic, f),
Self::Unavailable => f.write_str("Harness unavailable or recovering; request not sent"),
Self::OutcomeUnknown => f.write_str("Harness response lost; execution outcome unknown. Reconcile saved session before retrying."),
Self::Closed => f.write_str("Harness client closed"),
}
}
}
impl std::error::Error for Error {}
/// Explicit configuration shared by both backends. Use stable absolute paths.
#[derive(Clone)]
pub struct RuntimeConfig {
pub state_dir: PathBuf,
pub bundle: PathBuf,
/// Existing OpenWorker/partner executable supporting runner/supervisor commands.
/// Embedded mode still needs this helper for out-of-process tool execution.
pub runner: PathBuf,
pub model: String,
pub provider: ProviderKind,
pub sandbox: Sandbox,
pub servers: Option<PathBuf>,
pub tool_policy: Option<PathBuf>,
pub runtime_policy: Option<PathBuf>,
pub scripted: bool,
}
impl RuntimeConfig {
pub fn new(state_dir: PathBuf, bundle: PathBuf, runner: PathBuf) -> Self {
Self {
state_dir,
bundle,
runner,
model: "gpt-6-sol".into(),
provider: ProviderKind::Openai,
sandbox: Sandbox::Openshell,
servers: None,
tool_policy: None,
runtime_policy: None,
scripted: false,
}
}
fn validate(&self) -> Result<()> {
for path in [&self.state_dir, &self.bundle, &self.runner]
.into_iter()
.chain(self.servers.iter())
.chain(self.tool_policy.iter())
.chain(self.runtime_policy.iter())
{
if !path.is_absolute() {
return Err(Error::InvalidInput(
"SDK configuration paths must be absolute".into(),
));
}
}
Ok(())
}
}
#[derive(Clone)]
pub struct RestartPolicy {
/// Total retries for the client's lifetime; successful reconnects do not reset it.
pub max_restarts: u32,
pub initial_delay: Duration,
pub max_delay: Duration,
}
impl Default for RestartPolicy {
fn default() -> Self {
Self {
max_restarts: 3,
initial_delay: Duration::from_millis(250),
max_delay: Duration::from_secs(5),
}
}
}
#[derive(Clone)]
pub struct ProcessConfig {
pub program: PathBuf,
pub runtime: RuntimeConfig,
pub restart: RestartPolicy,
}
#[derive(Clone)]
pub struct ClientOptions {
pub request_timeout: Duration,
pub shutdown_timeout: Duration,
}
impl Default for ClientOptions {
fn default() -> Self {
Self {
request_timeout: Duration::from_secs(60),
shutdown_timeout: Duration::from_secs(310),
}
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum ConnectionState {
Starting,
Ready {
generation: u64,
process_id: Option<u32>,
},
Recovering {
attempt: u32,
},
Failed,
Closed,
}
#[derive(Clone, Debug)]
pub enum Notification {
/// Private callback control channel; not a journal record or model instruction.
Application(Value),
Event(Event),
Recovered {
session_id: String,
snapshot: Value,
},
RecoveryFailed {
session_id: String,
message: String,
},
/// Consumer must attach/read events from its last processed cursor.
Gap,
}
#[derive(Clone, Debug, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ApprovalDecision {
Once,
Session,
Deny,
}
#[derive(Clone, Debug, Serialize)]
pub struct RuntimeSessionOptions {
pub name: String,
pub coworker: String,
pub workspace: PathBuf,
#[serde(skip_serializing_if = "Option::is_none")]
pub model: Option<ModelChoice>,
#[serde(skip_serializing_if = "Option::is_none")]
pub permissions: Option<openworker_runtime::permissions::Config>,
}
pub(crate) enum Command {
Request(String, Value, oneshot::Sender<Result<Value>>),
Attach(String, i64, oneshot::Sender<Result<Value>>),
Ack(String, i64, oneshot::Sender<Result<()>>),
}
struct Handle {
callback_transport: Arc<std::sync::Mutex<Option<transport::CallbackTransport>>>,
registrations: Arc<std::sync::Mutex<Vec<Value>>>,
tx: mpsc::Sender<(u64, Command)>,
stop: CancellationToken,
state: watch::Receiver<ConnectionState>,
events: broadcast::Sender<Notification>,
done: watch::Receiver<Option<Result<()>>>,
info: std::sync::OnceLock<Value>,
}
impl Drop for Handle {
fn drop(&mut self) {
self.stop.cancel();
}
}
#[derive(Clone)]
pub struct HarnessClient {
inner: Arc<Handle>,
}
impl HarnessClient {
pub(crate) async fn callback_message(&self, method: &str, params: Value) -> Result<()> {
if self.inner.stop.is_cancelled() {
return Err(Error::Closed);
}
let transport = self
.inner
.callback_transport
.lock()
.unwrap()
.clone()
.ok_or(Error::Unavailable)?;
transport.send(method, params).await
}
pub async fn embedded_host(
config: HostConfig,
registry: ToolRegistry,
options: ClientOptions,
) -> Result<Self> {
config
.validate()
.map_err(|e| Error::InvalidInput(e.to_string()))?;
driver::start(driver::Source::Host(config, registry), options).await
}
pub async fn managed_host(config: HostProcessConfig, options: ClientOptions) -> Result<Self> {
config
.host
.validate()
.map_err(|e| Error::InvalidInput(e.to_string()))?;
if !config.program.is_absolute()
|| config.restart.max_restarts > 100
|| config.restart.initial_delay > config.restart.max_delay
|| config.restart.max_delay > Duration::from_secs(60)
{
return Err(Error::InvalidInput(
"Invalid executable path or restart policy".into(),
));
}
driver::start(driver::Source::HostProcess(config), options).await
}
pub async fn create_team(
&self,
request: openworker_runtime::team_service::Create,
) -> Result<Value> {
self.request("team/create", json!(request)).await
}
pub async fn team_snapshot(&self, id: &str) -> Result<Value> {
self.request("team/snapshot", json!({"team_id":id})).await
}
pub async fn team_command(
&self,
id: &str,
command: openworker_runtime::team_service::Command,
) -> Result<Value> {
self.request("team/command", json!({"team_id":id,"command":command}))
.await
}
pub async fn team_events(&self, id: &str, after: i64) -> Result<Value> {
self.request("team/events", json!({"team_id":id,"after":after}))
.await
}
pub async fn embedded(
config: impl Into<EmbeddedConfig>,
registry: ToolRegistry,
options: ClientOptions,
) -> Result<Self> {
match config.into() {
EmbeddedConfig::Local(config) => {
config.validate()?;
driver::start(driver::Source::Embedded(config, registry), options).await
}
EmbeddedConfig::Host(config) => Self::embedded_host(*config, registry, options).await,
}
}
pub async fn managed_stdio(
config: impl Into<StdioConfig>,
options: ClientOptions,
) -> Result<Self> {
let config = match config.into() {
StdioConfig::Local(c) => *c,
StdioConfig::Host(c) => return Self::managed_host(*c, options).await,
};
config.runtime.validate()?;
if !config.program.is_absolute()
|| config.restart.max_restarts > 100
|| config.restart.initial_delay > config.restart.max_delay
|| config.restart.max_delay > Duration::from_secs(60)
{
return Err(Error::InvalidInput(
"Invalid executable path or restart policy".into(),
));
}
driver::start(driver::Source::Process(config), options).await
}
pub fn connection(&self) -> watch::Receiver<ConnectionState> {
self.inner.state.clone()
}
/// Initial handshake capabilities. Gate evolving API usage on these flags.
pub fn info(&self) -> &Value {
self.inner.info.get().expect("initialized client")
}
/// Subscribe before starting work. On RecvError::Lagged, replay from your
/// persisted processed cursor. Notifications are not an exactly-once queue.
pub fn subscribe(&self) -> broadcast::Receiver<Notification> {
self.inner.events.subscribe()
}
fn ready(&self) -> Result<()> {
if self.inner.stop.is_cancelled() {
return Err(Error::Closed);
}
if !matches!(*self.inner.state.borrow(), ConnectionState::Ready { .. }) {
return Err(Error::Unavailable);
}
Ok(())
}
fn enqueue(&self, command: Command) -> Result<()> {
self.ready()?;
let ConnectionState::Ready { generation, .. } = *self.inner.state.borrow() else {
return Err(Error::Unavailable);
};
self.inner
.tx
.try_send((generation, command))
.map_err(|e| match e {
mpsc::error::TrySendError::Full(_) => Error::Unavailable,
mpsc::error::TrySendError::Closed(_) => Error::Closed,
})
}
/// Escape hatch for evolving protocol methods. Secrets must use payloads,
/// never executable arguments; do not log requests. initialize is SDK-owned.
pub async fn request(&self, method: &str, params: Value) -> Result<Value> {
self.ready()?;
if matches!(method, "initialize" | "session/attach")
|| method.is_empty()
|| method.len() > 100
|| !params.is_object()
|| params.to_string().len() + method.len() + 128 > openworker_runtime::MAX_FRAME
{
return Err(Error::InvalidInput(
"Invalid SDK request; use attach for session subscriptions".into(),
));
}
let (tx, rx) = oneshot::channel();
self.enqueue(Command::Request(method.into(), params, tx))?;
rx.await.unwrap_or(Err(Error::OutcomeUnknown))
}
pub async fn create_session(&self, options: RuntimeSessionOptions) -> Result<String> {
let v = self
.request(
"session/create",
serde_json::to_value(options)
.map_err(|_| Error::InvalidInput("Invalid session options".into()))?,
)
.await?;
v["session"]["id"]
.as_str()
.map(str::to_owned)
.ok_or_else(|| Error::Remote("Missing session ID".into()))
}
/// Attach and replay from a caller-persisted processed cursor. The snapshot
/// and replay can overlap live notifications; deduplicate by event_id.
pub async fn attach(&self, session_id: &str, after: i64) -> Result<Value> {
self.ready()?;
if session_id.len() > 80 || after < 0 {
return Err(Error::InvalidInput("Invalid session/cursor".into()));
}
let (tx, rx) = oneshot::channel();
self.enqueue(Command::Attach(session_id.into(), after, tx))?;
rx.await.unwrap_or(Err(Error::OutcomeUnknown))
}
/// Acknowledge only processed events. Persist your cursor in the application
/// too if recovery must survive an application (not just child) restart.
pub async fn acknowledge(&self, session_id: &str, cursor: i64) -> Result<()> {
self.ready()?;
if session_id.len() > 80 || cursor < 0 {
return Err(Error::InvalidInput("Invalid session/cursor".into()));
}
let (tx, rx) = oneshot::channel();
self.enqueue(Command::Ack(session_id.into(), cursor, tx))?;
rx.await.unwrap_or(Err(Error::Closed))
}
/// Read current state without replaying or advancing the processed cursor.
/// Use attach first if automatic child-restart recovery is wanted.
pub async fn snapshot(&self, session_id: &str) -> Result<Value> {
if session_id.len() > 80 {
return Err(Error::InvalidInput("Invalid session ID".into()));
}
let (tx, rx) = oneshot::channel();
self.enqueue(Command::Request(
"session/attach".into(),
json!({"session_id":session_id}),
tx,
))?;
rx.await.unwrap_or(Err(Error::OutcomeUnknown))
}
pub async fn start_turn(
&self,
session_id: &str,
submission_id: &str,
text: &str,
) -> Result<Value> {
self.request(
"turn/start",
json!({"session_id":session_id,"submission_id":submission_id,"text":text}),
)
.await
}
pub async fn cancel_turn(&self, session_id: &str, turn_id: &str) -> Result<Value> {
self.request(
"turn/cancel",
json!({"session_id":session_id,"turn_id":turn_id}),
)
.await
}
pub async fn approve(
&self,
session_id: &str,
interaction_id: &str,
decision: ApprovalDecision,
) -> Result<Value> {
self.request(
"interaction/respond",
json!({"session_id":session_id,"interaction_id":interaction_id,"decision":decision}),
)
.await
}
pub async fn answer(
&self,
session_id: &str,
interaction_id: &str,
answer: &str,
) -> Result<Value> {
self.request(
"interaction/respond",
json!({"session_id":session_id,"interaction_id":interaction_id,"answer":answer}),
)
.await
}
/// Closes all clones. Keep the host Tokio runtime alive until this completes.
pub async fn shutdown(&self) -> Result<()> {
self.inner.stop.cancel();
let mut done = self.inner.done.clone();
loop {
if let Some(result) = done.borrow().clone() {
return result;
}
done.changed().await.map_err(|_| Error::Closed)?;
}
}
}
/// Authenticated REST/SSE service transport; independent of managed child lifecycle.
pub mod service;
pub use openworker_runtime::compliance;
#[cfg(feature = "security-adapters")]
pub use openworker_security_adapters as security_adapters;
pub use openworker_runtime::compliance_export::Sink as ComplianceSink;
#[cfg(feature = "evaluations")]
pub use openworker_observability::evaluations;
mod attachments;
pub use attachments::{Attachment, InputContent, UserInput};