Python
//! Sessions and runs: a typed wrapper over the host's `agent/*` and `run/*`
//! methods. Run completion, team handling, `interrupt_on` auto-approval,
//! busy retries and journal streaming all happen in the host, so this file is
//! what every language SDK needs to reproduce, and no more.
use super::team::Team;
use crate::{ApprovalDecision, Error, Event, HarnessClient, Result};
use serde::{Deserialize, Serialize};
use serde_json::{json, Map, Value};
use std::{collections::HashSet, path::Path};
use tokio::sync::mpsc;
/// Per-call long-poll bound. Well under the client request timeout.
const WAIT_MS: u64 = 2000;
/// Everything needed to reattach after an application restart. Persist it
/// (it is `Serialize`); only `session_id` is strictly required.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct SessionRef {
pub session_id: String,
pub agent: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub team: Option<TeamRef>,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct TeamRef {
pub team_id: String,
pub workers: Vec<WorkerRef>,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct WorkerRef {
pub session_id: String,
pub agent: String,
}
/// A run stopped because a human must decide something.
#[derive(Clone, Debug, PartialEq)]
pub struct Interruption {
pub id: String,
pub session_id: String,
/// Which agent asked (the lead or one of its subagents).
pub agent: String,
pub kind: InterruptionKind,
}
#[derive(Clone, Debug, PartialEq)]
pub enum InterruptionKind {
/// Required check unavailable. Restore its handler/service, then resume_safety.
Safety { code: String },
/// A tool call awaiting approval. `tool` is the model-facing alias
/// (`provider__tool`); `category` is the engine's effect classification.
Approval {
tool: String,
arguments: Value,
category: Option<String>,
},
/// `ask_user`, a compaction choice, or any other non-tool interaction.
Question {
question: String,
options: Vec<String>,
},
}
impl Interruption {
fn from_wire(v: &Value) -> Option<Self> {
let s = |k: &str| v[k].as_str().map(str::to_owned);
let kind = if v["kind"] == "safety" {
InterruptionKind::Safety {
code: s("code").unwrap_or_else(|| "GUARDRAIL_UNAVAILABLE".into()),
}
} else if v["kind"] == "approval" {
InterruptionKind::Approval {
tool: s("tool").unwrap_or_default(),
arguments: v["arguments"].clone(),
category: s("category"),
}
} else {
InterruptionKind::Question {
question: s("question").unwrap_or_default(),
options: v["options"]
.as_array()
.into_iter()
.flatten()
.filter_map(|o| o.as_str().map(str::to_owned))
.collect(),
}
};
Some(Self {
id: s("id")?,
session_id: s("session_id")?,
agent: s("agent").unwrap_or_default(),
kind,
})
}
}
/// Your reply to an [`Interruption`].
#[derive(Clone, Debug)]
pub enum Response {
Approve(ApprovalDecision),
Deny,
Answer(String),
/// Leave it pending; the run returns `Interrupted`.
Defer,
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum RunStatus {
Completed,
/// Waiting on `interruptions`; respond, then call [`Session::resume`].
Interrupted,
Cancelled,
/// Engine turn status: `failed`, `interrupted` or `truncated`.
Failed(String),
}
#[derive(Clone, Debug)]
pub struct RunResult {
pub status: RunStatus,
/// Lead agent's last assistant message for this run, if any.
pub final_output: Option<String>,
pub interruptions: Vec<Interruption>,
/// Stable ID of the submitted input; reuse it to retry after `OutcomeUnknown`.
pub submission_id: Option<String>,
/// Lead session's journal cursor when the run returned.
pub cursor: i64,
/// Team board at the end of the run, for sessions with subagents.
pub board: Option<Value>,
pub provider_error: Option<openworker_runtime::provider::Diagnostic>,
}
impl RunResult {
fn from_wire(v: &Value) -> Self {
let status = match v["status"].as_str().unwrap_or("") {
"completed" => RunStatus::Completed,
"interrupted" => RunStatus::Interrupted,
"cancelled" => RunStatus::Cancelled,
_ => RunStatus::Failed(v["failure"].as_str().unwrap_or("failed").to_owned()),
};
Self {
status,
final_output: v["final_output"].as_str().map(str::to_owned),
interruptions: v["interruptions"]
.as_array()
.into_iter()
.flatten()
.filter_map(Interruption::from_wire)
.collect(),
submission_id: v["submission_id"].as_str().map(str::to_owned),
cursor: v["cursor"].as_i64().unwrap_or(0),
board: v.get("board").filter(|b| !b.is_null()).cloned(),
provider_error: serde_json::from_value(v["provider_error"].clone()).ok(),
}
}
}
/// Progress while a run is streaming.
#[derive(Clone, Debug)]
pub enum RunEvent {
AttemptStarted {
session_id: String,
turn_id: Option<String>,
attempt_id: String,
attempt: u32,
},
AttemptFinished {
session_id: String,
turn_id: Option<String>,
attempt_id: String,
status: String,
failure: Option<openworker_runtime::provider::Failure>,
},
TextDelta {
session_id: String,
turn_id: Option<String>,
attempt_id: String,
text: String,
},
ReasoningDelta {
session_id: String,
turn_id: Option<String>,
attempt_id: String,
kind: openworker_runtime::provider::ReasoningKind,
text: String,
block_index: u64,
},
ModelActivity {
session_id: String,
turn_id: Option<String>,
attempt_id: String,
elapsed_ms: u64,
},
ProviderError {
session_id: String,
turn_id: Option<String>,
attempt_id: String,
diagnostic: openworker_runtime::provider::Diagnostic,
},
/// Child events keep their original journal identity; do not add their usage twice.
SubagentActivity {
agent_id: String,
parent_session_id: String,
event: Event,
summary: Value,
},
/// Named-team events retain both instance and definition identities.
TeamActivity {
agent_id: String,
agent_type: String,
team_id: String,
event: Event,
summary: Value,
},
Message {
agent: String,
text: String,
},
ToolStarted {
agent: String,
tool: String,
/// Correlates with application ToolContext::call_id and the raw journal.
call_id: String,
/// Scope call IDs to their turn; providers may reuse IDs in later turns.
turn_id: Option<String>,
},
ToolFinished {
agent: String,
tool: String,
call_id: String,
turn_id: Option<String>,
},
/// The host approved a call because the agent's `interrupt_on` excludes it.
AutoApproved {
agent: String,
tool: String,
},
PlanUpdated {
agent: String,
plan: Value,
},
Interrupted(Interruption),
/// Any other engine event (team updates, attempts, sandbox lifecycle...).
Other(Event),
}
impl RunEvent {
fn from_wire(item: &Value) -> Option<Self> {
if let (Some(agent_id), Some(parent_session_id)) = (
item["agent_id"].as_str(),
item["parent_session_id"].as_str(),
) {
return Some(Self::SubagentActivity {
agent_id: agent_id.into(),
parent_session_id: parent_session_id.into(),
event: serde_json::from_value(item["event"].clone()).ok()?,
summary: item["summary"].clone(),
});
}
if let (Some(agent_id), Some(team_id)) =
(item["agent_id"].as_str(), item["team_id"].as_str())
{
return Some(Self::TeamActivity {
agent_id: agent_id.into(),
agent_type: item["agent"].as_str()?.into(),
team_id: team_id.into(),
event: serde_json::from_value(item["event"].clone()).ok()?,
summary: item["summary"].clone(),
});
}
let agent = item["agent"].as_str().unwrap_or_default().to_owned();
let summary = &item["summary"];
let session_id = item["event"]["session_id"]
.as_str()
.unwrap_or_default()
.to_owned();
let turn_id = item["event"]["turn_id"].as_str().map(str::to_owned);
let attempt_id = || {
summary["attempt_id"]
.as_str()
.unwrap_or_default()
.to_owned()
};
let tool = || summary["tool"].as_str().unwrap_or_default().to_owned();
// Older hosts omit this from summaries, but retain it in the journal.
let call_id = || {
summary["call_id"]
.as_str()
.or_else(|| item["event"]["data"]["call_id"].as_str())
.unwrap_or_default()
.to_owned()
};
Some(match summary["type"].as_str() {
Some("model_attempt_started") => RunEvent::AttemptStarted {
session_id,
turn_id,
attempt_id: attempt_id(),
attempt: summary["attempt"].as_u64()? as u32,
},
Some("model_attempt_finished") => RunEvent::AttemptFinished {
session_id,
turn_id,
attempt_id: attempt_id(),
status: summary["status"].as_str()?.into(),
failure: serde_json::from_value(summary["kind"].clone()).ok(),
},
Some("assistant_delta") => RunEvent::TextDelta {
session_id,
turn_id,
attempt_id: attempt_id(),
text: summary["text"].as_str()?.into(),
},
Some("reasoning_delta") => RunEvent::ReasoningDelta {
session_id,
turn_id,
attempt_id: attempt_id(),
kind: serde_json::from_value(summary["kind"].clone()).ok()?,
text: summary["text"].as_str()?.into(),
block_index: summary["block_index"].as_u64()?,
},
Some("model_activity") => RunEvent::ModelActivity {
session_id,
turn_id,
attempt_id: attempt_id(),
elapsed_ms: summary["elapsed_ms"].as_u64()?,
},
Some("provider_error") => RunEvent::ProviderError {
session_id,
turn_id,
attempt_id: attempt_id(),
diagnostic: serde_json::from_value(summary["diagnostic"].clone()).ok()?,
},
Some("message") => RunEvent::Message {
agent,
text: summary["text"].as_str().unwrap_or_default().to_owned(),
},
Some("tool_started") => RunEvent::ToolStarted {
agent,
tool: tool(),
call_id: call_id(),
turn_id: item["event"]["turn_id"].as_str().map(str::to_owned),
},
Some("tool_finished") => RunEvent::ToolFinished {
agent,
tool: tool(),
call_id: call_id(),
turn_id: item["event"]["turn_id"].as_str().map(str::to_owned),
},
Some("auto_approved") => RunEvent::AutoApproved {
agent,
tool: tool(),
},
Some("plan_updated") => RunEvent::PlanUpdated {
agent,
plan: summary["plan"].clone(),
},
_ => RunEvent::Other(serde_json::from_value(item["event"].clone()).ok()?),
})
}
}
/// A run in progress. `next()` yields events; `finish()` returns the result.
pub struct RunStream {
rx: mpsc::UnboundedReceiver<RunEvent>,
task: tokio::task::JoinHandle<Result<RunResult>>,
}
impl RunStream {
pub async fn next(&mut self) -> Option<RunEvent> {
self.rx.recv().await
}
/// Drain remaining events and return the outcome.
pub async fn finish(mut self) -> Result<RunResult> {
while self.rx.recv().await.is_some() {}
self.task.await.unwrap_or(Err(Error::Closed))
}
}
#[derive(Clone)]
pub struct Session {
client: HarnessClient,
reference: SessionRef,
}
#[derive(Clone, Debug, Serialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum SessionInput {
Message {
text: String,
},
Approval {
interaction_id: String,
#[serde(skip_serializing_if = "Option::is_none")]
target_session_id: Option<String>,
decision: ApprovalDecision,
},
Answer {
interaction_id: String,
#[serde(skip_serializing_if = "Option::is_none")]
target_session_id: Option<String>,
text: String,
},
}
impl From<&str> for SessionInput {
fn from(text: &str) -> Self {
Self::Message { text: text.into() }
}
}
impl From<&String> for SessionInput {
fn from(text: &String) -> Self {
Self::Message { text: text.clone() }
}
}
impl From<String> for SessionInput {
fn from(text: String) -> Self {
Self::Message { text }
}
}
/// Lightweight durable run reference. Readers page the journal independently;
/// not reading events never queues unbounded data or pauses execution.
#[derive(Clone)]
pub struct Run {
session: Session,
submission: String,
cursors: Map<String, Value>,
}
impl Run {
pub fn id(&self) -> &str {
&self.submission
}
pub async fn result(&self) -> Result<RunResult> {
self.session.wait(Some(&self.submission)).await
}
pub fn events(
&self,
) -> std::pin::Pin<Box<dyn futures_util::Stream<Item = Result<RunEvent>> + Send>> {
let me = self.clone();
Box::pin(async_stream::try_stream! {
let mut cursors=me.cursors.clone();
loop {
let value=me.session.client.request("run/wait",json!({"session_id":me.session.id(),"submission_id":me.submission,"wait_ms":WAIT_MS,"max_events":128,"cursors":cursors})).await?;
for item in value["events"].as_array().into_iter().flatten() {
if let Some(event)=RunEvent::from_wire(item) { yield event; }
}
cursors=value["cursors"].as_object().cloned().ok_or_else(||Error::Remote("Missing event cursors".into()))?;
if value["status"]!="running" && value["more_events"]!=true { break; }
}
})
}
}
impl Session {
/// Metadata only: text, tool arguments/results and credentials are omitted.
pub async fn compliance_delivery_health(&self) -> Result<serde_json::Value> {
self.client
.request(
"compliance/delivery-health",
json!({"session_id":self.id()}),
)
.await
}
pub async fn compliance_activity(
&self,
query: crate::compliance::Query,
) -> Result<serde_json::Value> {
let mut p =
serde_json::to_value(query).map_err(|e| crate::Error::InvalidInput(e.to_string()))?;
p["session_id"] = json!(self.id());
self.client.request("compliance/read", p).await
}
pub async fn resume_safety(&self) -> Result<()> {
self.client
.request("safety/resume", json!({"session_id":self.id()}))
.await?;
Ok(())
}
pub async fn send_with_options(&self, text: &str, options: crate::TurnOptions) -> Result<Run> {
if options
.limits
.as_ref()
.is_some_and(|l| l.max_output_tokens_per_call != 8192)
&& self.client.info()["capabilities"]["per_call_output_limit"] != true
{
return Err(Error::Setup(
"Update the host to configure per-call output limits".into(),
));
}
if (options.auto_approver_context.is_some() || options.compaction.is_some())
&& self.client.info()["capabilities"]["application_guidance"] != true
{
return Err(Error::Setup(
"Update the host to configure application guidance".into(),
));
}
if (options.instruction_addendum.is_some() || options.output.is_some())
&& self.client.info()["capabilities"]["turn_context"] != true
{
return Err(Error::Setup(
"Host does not support turn context; update the runtime".into(),
));
}
let id = options
.submission_id
.unwrap_or_else(|| openworker_runtime::id("sub"));
if options.safety.is_some() && self.client.info()["capabilities"]["guardrails"] != true {
return Err(Error::Setup(
"This harness build does not support guardrails".into(),
));
}
let mut parameters = json!({"session_id":self.id(),"submission_id":id,"input":{"text":text},"limits":options.limits,"safety":options.safety});
if let Some(context) = options.auto_approver_context {
parameters["auto_approver_context"] = json!(context);
}
if let Some(compaction) = options.compaction {
parameters["compaction"] = json!(compaction);
}
if let Some(addendum) = options.instruction_addendum {
parameters["instruction_addendum"] = json!(addendum);
}
if let Some(output) = options.output {
parameters["output"] = json!(output);
}
let started = self.client.request("session/send", parameters).await?;
Ok(Run {
session: self.clone(),
submission: id,
cursors: started["cursors"].as_object().cloned().unwrap_or_default(),
})
}
pub async fn send(&self, input: impl Into<SessionInput>) -> Result<Run> {
let input = input.into();
if let SessionInput::Message { text } = &input {
return self
.send_with_id(&openworker_runtime::id("sub"), text)
.await;
}
let mut cursors = Map::new();
for sid in self.member_ids() {
cursors.insert(
sid.clone(),
self.client.snapshot(&sid).await?["cursor"].clone(),
);
}
let receipt = self
.client
.request(
"session/send",
json!({"session_id":self.id(),"input":input}),
)
.await?;
let submission = receipt["run_id"]
.as_str()
.ok_or_else(|| Error::Remote("Control accepted without an SDK run reference".into()))?
.to_owned();
Ok(Run {
session: self.clone(),
submission,
cursors,
})
}
pub async fn send_with_limits(&self, text: &str, limits: super::TurnLimits) -> Result<Run> {
self.send_with_id_and_limits(&openworker_runtime::id("sub"), text, Some(limits))
.await
}
pub async fn send_with_id(&self, id: &str, text: &str) -> Result<Run> {
self.send_with_id_and_limits(id, text, None).await
}
pub async fn send_with_id_and_limits(
&self,
id: &str,
text: &str,
limits: Option<super::TurnLimits>,
) -> Result<Run> {
if limits
.as_ref()
.is_some_and(|l| l.max_output_tokens_per_call != 8192)
&& self.client.info()["capabilities"]["per_call_output_limit"] != true
{
return Err(Error::Setup(
"Update the host to configure per-call output limits".into(),
));
}
if limits.is_some() && self.client.info()["capabilities"]["turn_limits"] != true {
return Err(crate::Error::Setup(
"Host does not support turn limits".into(),
));
}
let mut parameters =
json!({"session_id":self.id(),"submission_id":id,"input":{"text":text}});
if let Some(limits) = limits {
parameters["limits"] = json!(limits);
}
let started = self.client.request("session/send", parameters).await?;
Ok(Run {
session: self.clone(),
submission: id.into(),
cursors: started["cursors"].as_object().cloned().unwrap_or_default(),
})
}
/// Authoritative read only; no scheduling or automatic approval side effects.
pub async fn state(&self) -> Result<Value> {
self.client
.request("session/state", json!({"session_id":self.id()}))
.await
}
pub(crate) async fn create(
client: HarnessClient,
agent: &str,
workspace: &Path,
) -> Result<Self> {
Self::create_with_model(client, agent, workspace, None).await
}
pub(crate) async fn create_with_model(
client: HarnessClient,
agent: &str,
workspace: &Path,
model: Option<crate::ModelChoice>,
) -> Result<Self> {
let mut options = json!({"agent":agent,"workspace":workspace});
if let Some(model) = model {
options["model"] = json!(model);
}
Self::create_options(client, options).await
}
pub(crate) async fn create_options(client: HarnessClient, options: Value) -> Result<Self> {
if (options.get("auto_approver_context").is_some() || options.get("compaction").is_some())
&& client.info()["capabilities"]["application_guidance"] != true
{
return Err(Error::Setup(
"Update the host to configure application guidance".into(),
));
}
if options.get("initial_history").is_some()
&& client.info()["capabilities"]["initial_history"] != true
{
return Err(Error::Setup(
"Update the host to import conversation history".into(),
));
}
if options.get("auto_skip_questions").is_some()
&& client.info()["capabilities"]["sdk_question_policy"] != true
{
return Err(Error::Setup(
"Update the host to configure SDK question policy".into(),
));
}
let created = client.request("agent/session", options).await?;
let reference: SessionRef = serde_json::from_value(created["session"].clone())
.map_err(|_| Error::Remote("Malformed agent/session result".into()))?;
Self::open(client, reference).await
}
pub(crate) async fn open(client: HarnessClient, reference: SessionRef) -> Result<Self> {
let session = Self { client, reference };
// Attach every member at its current cursor so child-restart recovery
// covers them without replaying history.
for sid in session.member_ids() {
let cursor = session.client.snapshot(&sid).await?["cursor"]
.as_i64()
.unwrap_or(0);
session.client.attach(&sid, cursor).await?;
}
Ok(session)
}
pub fn id(&self) -> &str {
&self.reference.session_id
}
pub fn agent(&self) -> &str {
&self.reference.agent
}
/// Persist this to resume after an application restart.
pub fn reference(&self) -> &SessionRef {
&self.reference
}
/// Typed team board access, for sessions whose agent has subagents.
pub fn team(&self) -> Option<Team> {
self.reference
.team
.as_ref()
.map(|t| Team::new(self.client.clone(), t.team_id.clone()))
}
/// Current durable state of the lead session.
pub async fn snapshot(&self) -> Result<Value> {
self.client.snapshot(self.id()).await
}
fn member_ids(&self) -> Vec<String> {
let mut ids = vec![self.reference.session_id.clone()];
if let Some(t) = &self.reference.team {
ids.extend(t.workers.iter().map(|w| w.session_id.clone()));
}
ids
}
/// Send input and wait until the run completes or needs you.
pub async fn run(&self, input: &str) -> Result<RunResult> {
self.run_with_submission(&openworker_runtime::id("sub"), input)
.await
}
/// Like [`Self::run`] with your own stable submission ID. Resending the same
/// ID after `Error::OutcomeUnknown` never starts a second turn.
pub async fn run_with_submission(&self, submission_id: &str, input: &str) -> Result<RunResult> {
self.start(submission_id, input).await?;
self.wait(Some(submission_id)).await
}
/// Run and answer interruptions inline with `handler`. Returning
/// [`Response::Defer`] stops and returns the run as `Interrupted`.
pub async fn run_with<F>(&self, input: &str, mut handler: F) -> Result<RunResult>
where
F: FnMut(&Interruption) -> Response,
{
let mut result = self.run(input).await?;
loop {
if result.status != RunStatus::Interrupted {
return Ok(result);
}
let mut deferred = false;
for i in &result.interruptions {
let response = handler(i);
deferred |= matches!(response, Response::Defer);
self.respond(i, response).await?;
}
if deferred {
return Ok(result);
}
let submission = result.submission_id.clone();
result = self.resume().await?;
result.submission_id = submission;
}
}
/// Send input and stream progress events (read from the durable journal
/// by the host, so nothing is lost to timing or a child restart).
pub async fn run_streamed(&self, input: &str) -> Result<RunStream> {
let submission = openworker_runtime::id("sub");
let started = self.start(&submission, input).await?;
let cursors = started["cursors"].as_object().cloned().unwrap_or_default();
Ok(self.spawn(Some(submission), cursors))
}
/// Submit an ordered user message, staging immutable attachments first.
pub async fn send_input(
&self,
input: crate::UserInput,
options: crate::TurnOptions,
) -> Result<Run> {
if (options.auto_approver_context.is_some() || options.compaction.is_some())
&& self.client.info()["capabilities"]["application_guidance"] != true
{
return Err(Error::Setup(
"Update the host to configure application guidance".into(),
));
}
let parts = input.upload(&self.client, self.id()).await?;
let id = options
.submission_id
.unwrap_or_else(|| openworker_runtime::id("sub"));
let value=self.client.request("session/send",json!({"session_id":self.id(),"submission_id":id,"input":{"content":parts},"limits":options.limits,"safety":options.safety,"instruction_addendum":options.instruction_addendum,"auto_approver_context":options.auto_approver_context,"compaction":options.compaction,"output":options.output})).await?;
Ok(Run {
session: self.clone(),
submission: id,
cursors: value["cursors"].as_object().cloned().unwrap_or_default(),
})
}
pub async fn run_input(&self, input: crate::UserInput) -> Result<RunResult> {
let parts = input.upload(&self.client, self.id()).await?;
let id = openworker_runtime::id("sub");
self.client
.request(
"run/start",
json!({"session_id":self.id(),"submission_id":id,"content":parts}),
)
.await?;
self.wait(Some(&id)).await
}
pub async fn run_with_attachments(
&self,
text: &str,
attachments: Vec<crate::Attachment>,
) -> Result<RunResult> {
let mut content = vec![crate::InputContent::text(text)];
content.extend(attachments.into_iter().map(crate::InputContent::from));
self.run_input(crate::UserInput::new(content)).await
}
pub async fn run_input_streamed(&self, input: crate::UserInput) -> Result<RunStream> {
let parts = input.upload(&self.client, self.id()).await?;
let id = openworker_runtime::id("sub");
let started = self
.client
.request(
"run/start",
json!({"session_id":self.id(),"submission_id":id,"content":parts}),
)
.await?;
Ok(self.spawn(
Some(id),
started["cursors"].as_object().cloned().unwrap_or_default(),
))
}
/// Keep waiting after responding to interruptions (or after reattaching).
pub async fn resume(&self) -> Result<RunResult> {
self.wait(None).await
}
/// Streaming form of [`Self::resume`], from the current journal position.
pub async fn resume_streamed(&self) -> Result<RunStream> {
let mut cursors = Map::new();
for sid in self.member_ids() {
let c = self.client.snapshot(&sid).await?["cursor"].clone();
cursors.insert(sid, c);
}
Ok(self.spawn(None, cursors))
}
async fn start(&self, submission_id: &str, input: &str) -> Result<Value> {
self.client
.request(
"run/start",
json!({"session_id": self.id(), "submission_id": submission_id, "text": input}),
)
.await
}
async fn wait(&self, submission: Option<&str>) -> Result<RunResult> {
loop {
let v = self
.client
.request(
"run/wait",
json!({"session_id": self.id(), "submission_id": submission,
"wait_ms": WAIT_MS}),
)
.await?;
if v["status"] != "running" {
return Ok(RunResult::from_wire(&v));
}
}
}
fn spawn(&self, submission: Option<String>, mut cursors: Map<String, Value>) -> RunStream {
// Unbounded so an unread stream never stalls the run.
let (tx, rx) = mpsc::unbounded_channel();
let me = self.clone();
let task = tokio::spawn(async move {
let mut announced = HashSet::new();
loop {
let v = me
.client
.request(
"run/wait",
json!({"session_id": me.id(), "submission_id": submission,
"wait_ms": WAIT_MS, "cursors": cursors}),
)
.await?;
for item in v["events"].as_array().into_iter().flatten() {
if let Some(e) = RunEvent::from_wire(item) {
let _ = tx.send(e);
}
}
if let Some(c) = v["cursors"].as_object() {
cursors = c.clone();
}
let result = RunResult::from_wire(&v);
for i in &result.interruptions {
if announced.insert(i.id.clone()) {
let _ = tx.send(RunEvent::Interrupted(i.clone()));
}
}
if v["status"] != "running" && v["more_events"] != true {
return Ok(result);
}
}
});
RunStream { rx, task }
}
/// Reply to an interruption. The host checks the reply matches the
/// interruption kind and retries while the engine is briefly busy.
pub async fn respond(&self, interruption: &Interruption, response: Response) -> Result<()> {
let mut p = json!({"session_id": interruption.session_id,
"interaction_id": interruption.id});
match (&interruption.kind, response) {
(_, Response::Defer) => return Ok(()),
(InterruptionKind::Approval { .. }, Response::Approve(d)) => p["decision"] = json!(d),
(InterruptionKind::Approval { .. }, Response::Deny) => {
p["decision"] = json!(ApprovalDecision::Deny)
}
(InterruptionKind::Question { .. }, Response::Answer(a)) => p["answer"] = json!(a),
_ => {
return Err(Error::InvalidInput(
"Approve/Deny approvals; Answer questions".into(),
))
}
}
let mut input = json!({"type":if p.get("decision").is_some(){"approval"}else{"answer"},"interaction_id":interruption.id,"target_session_id":interruption.session_id});
if let Some(d) = p.get("decision") {
input["decision"] = d.clone();
} else {
input["text"] = p["answer"].clone();
}
self.client.request("session/send",json!({"session_id":self.id(),"submission_id":openworker_runtime::id("response"),"input":input})).await.map(drop)
}
/// Cancel every active turn in this session and its workers. The team
/// board stays usable; use [`Team::cancel`] to end the team for good.
pub async fn cancel(&self) -> Result<()> {
self.client
.request("run/cancel", json!({"session_id": self.id()}))
.await
.and_then(check_member_errors)
}
/// Close the session and its workers. Cancel active turns first.
pub async fn close(&self) -> Result<()> {
self.client
.request("agent/close", json!({"session_id": self.id()}))
.await
.and_then(check_member_errors)
}
}
fn check_member_errors(result: Value) -> Result<()> {
if let Some(errors) = result
.get("errors")
.and_then(Value::as_object)
.filter(|e| !e.is_empty())
{
return Err(Error::Remote(format!(
"Some session operations failed: {}",
json!(errors)
)));
}
Ok(())
}
impl super::Approvals {
/// Convenience for building an [`super::Approvals::Only`] set.
pub fn only<I, S>(tools: I) -> Self
where
I: IntoIterator<Item = S>,
S: Into<String>,
{
Self::Only(tools.into_iter().map(Into::into).collect())
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn partial_member_failure_is_not_success() {
assert!(check_member_errors(
json!({"closed":1,"errors":{"worker":"Cancel active turn before closing"}})
)
.is_err());
assert!(
check_member_errors(json!({"cancelled":1,"errors":{"worker":"Unavailable"}})).is_err()
);
assert!(check_member_errors(json!({"closed":2,"errors":{}})).is_ok());
}
#[test]
fn wire_results_map_to_types() {
let r = RunResult::from_wire(&json!({
"status": "interrupted", "final_output": null, "cursor": 7, "submission_id": "s",
"interruptions": [
{"id":"i","session_id":"w","agent":"worker","kind":"approval",
"tool":"files__write","arguments":{"path":"x"},"category":"write_local"},
{"id":"q","session_id":"l","agent":"lead","kind":"question",
"question":"Go?","options":["Yes"]}
],
"board": null
}));
assert_eq!(r.status, RunStatus::Interrupted);
assert_eq!(r.cursor, 7);
assert!(r.board.is_none());
assert!(matches!(&r.interruptions[0].kind,
InterruptionKind::Approval { tool, category: Some(c), .. } if tool == "files__write" && c == "write_local"));
assert!(matches!(&r.interruptions[1].kind,
InterruptionKind::Question { options, .. } if options == &["Yes"]));
let f = RunResult::from_wire(&json!({"status":"failed","failure":"truncated"}));
assert_eq!(f.status, RunStatus::Failed("truncated".into()));
}
#[test]
fn stream_items_map_to_events() {
let m = RunEvent::from_wire(&json!({"agent":"a","summary":{"type":"message","text":"hi"}}));
assert!(matches!(m, Some(RunEvent::Message { text, .. }) if text == "hi"));
let a = RunEvent::from_wire(
&json!({"agent":"a","summary":{"type":"auto_approved","tool":"x__y"}}),
);
assert!(matches!(a, Some(RunEvent::AutoApproved { tool, .. }) if tool == "x__y"));
let o = RunEvent::from_wire(&json!({"agent":"a","summary":null,
"event":{"event_id":3,"session_id":"s","turn_id":null,"type":"compacted","data":{}}}));
assert!(matches!(o, Some(RunEvent::Other(e)) if e.event_id == 3));
}
#[test]
fn tool_events_preserve_call_identity_from_current_and_older_hosts() {
for from_summary in [false, true] {
for kind in ["tool_started", "tool_finished"] {
let mut item = json!({"agent":"builder",
"summary":{"type":kind,"tool":"app__preview"},
"event":{"data":{"call_id":"call-preview"}}});
if from_summary {
item["summary"]["call_id"] = json!("call-preview");
}
let mapped = RunEvent::from_wire(&item).unwrap();
match mapped {
RunEvent::ToolStarted { call_id, tool, .. }
| RunEvent::ToolFinished { call_id, tool, .. } => {
assert_eq!(call_id, "call-preview");
assert_eq!(tool, "app__preview");
}
other => panic!("unexpected tool event: {other:?}"),
}
}
}
}
#[test]
fn repeated_call_ids_keep_distinct_turns() {
for kind in ["tool_started", "tool_finished"] {
let mut keys = Vec::new();
for turn in [Some("turn-one"), Some("turn-two"), None] {
let item = json!({"agent":"builder",
"summary":{"type":kind,"tool":"app__preview","call_id":"call-preview"},
"event":{"turn_id":turn,"data":{"call_id":"call-preview"}}});
match RunEvent::from_wire(&item).unwrap() {
RunEvent::ToolStarted {
call_id, turn_id, ..
}
| RunEvent::ToolFinished {
call_id, turn_id, ..
} => {
assert_eq!(turn_id.as_deref(), turn);
keys.push((turn_id, call_id));
}
other => panic!("unexpected tool event: {other:?}"),
}
}
assert_ne!(keys[0], keys[1]);
assert_eq!(keys[0].1, keys[1].1);
assert!(keys[2].0.is_none());
}
}
#[test]
fn attempt_reasoning_and_provider_diagnostics_are_typed() {
let event = json!({"session_id":"s","turn_id":"t","data":{}});
let item = |summary: Value| json!({"agent":"a","event":event,"summary":summary});
assert!(
matches!(RunEvent::from_wire(&item(json!({"type":"model_attempt_started","attempt_id":"a1","attempt":1}))),Some(RunEvent::AttemptStarted{attempt:1,attempt_id,..}) if attempt_id=="a1")
);
assert!(matches!(
RunEvent::from_wire(&item(
json!({"type":"model_attempt_finished","attempt_id":"a1","status":"failed","kind":"incomplete_stream"})
)),
Some(RunEvent::AttemptFinished {
failure: Some(openworker_runtime::provider::Failure::IncompleteStream),
..
})
));
assert!(
matches!(RunEvent::from_wire(&item(json!({"type":"reasoning_delta","attempt_id":"a1","kind":"summary","text":"display","block_index":0}))),Some(RunEvent::ReasoningDelta{kind:openworker_runtime::provider::ReasoningKind::Summary,text,..}) if text=="display")
);
let diagnostic = json!({"category":"authentication","retryable":false,"http_status":401,"request_id":"req_fixture","api":"responses","code":"invalid_api_key"});
assert!(
matches!(RunEvent::from_wire(&item(json!({"type":"provider_error","attempt_id":"a1","diagnostic":diagnostic}))),Some(RunEvent::ProviderError{diagnostic,..}) if diagnostic.http_status==Some(401))
);
let result = RunResult::from_wire(&json!({"status":"failed","provider_error":diagnostic}));
assert_eq!(
result.provider_error.unwrap().request_id.as_deref(),
Some("req_fixture")
);
}
}