pub struct Run { /* private fields */ }Expand description
A run in progress.
Yields events through Run::recv and settles into an Outcome through
Run::finish.
Dropping a Run kills the agent. That is the safe default for the hosts
this crate targets: closing a window or cancelling a request should stop the
work, not leave an agent running invisibly, spending quota and touching
files with nobody watching. Call Run::detach when background execution is
genuinely what you want.
On Unix, dropping synchronously signals the run’s process group and then
aborts the driver task. What it cannot do is wait: Drop cannot await, so
it does not block until the child has exited or its readers have been
joined. Use Run::cancel when you need to know the tree has actually gone
before continuing, such as before touching the files it was working on. On
Windows only the direct child is signalled.
Implementations§
Source§impl Run
impl Run
Sourcepub async fn recv(&mut self) -> Option<Event>
pub async fn recv(&mut self) -> Option<Event>
The next event, or None once the agent has finished producing them.
Sourcepub async fn send(&self, message: &str) -> Result<()>
pub async fn send(&self, message: &str) -> Result<()>
Send another message while the agent is still working.
The whole point of crate::Request::interactive: a user who types a
correction mid-turn should not have to wait for the turn to finish.
The agent takes it at its next step boundary, not mid-token, so an answer already being written finishes first and a long tool-using task changes course at its next step. Verified against claude 2.1.212 and codex-cli 0.145.0.
§Ordering, and why there is no acknowledgement
The caller already knows what it sent, so the intended pattern is to append the message to the transcript immediately, below the user’s previous one, and carry on. This deliberately does not ask the agent to echo the message back for sequencing: an echo would only tell a UI something it already knew, and waiting for one would delay the very thing this exists to make immediate.
§Errors
Error::Unsupported on a run that did not open the channel with
crate::Request::interactive. Error::Cancelled once the channel
has closed, which happens when the turn settles or the run is torn down:
a message sent after the turn ends is too late and belongs in a new
run resuming the session, so this reports it rather than dropping it.
Sourcepub async fn respond(&self, id: &str, decision: &Decision) -> Result<()>
pub async fn respond(&self, id: &str, decision: &Decision) -> Result<()>
Answer an Event::ApprovalRequest.
The agent is blocked until this is called, so a consumer that receives an approval request and never responds stalls the run until its timeout.
The id must be the one from the request. The agent ignores an answer carrying any other id and keeps waiting, so a mismatch presents as a hang rather than an error; this passes the id straight through and does not invent one.
§Errors
Error::Unsupported on a run that did not ask for approvals, since
there is no channel to answer on. Error::Cancelled if the run has
already finished or been torn down, which is the same reason a decision
can no longer be delivered.
Sourcepub fn argv(&self) -> &[String]
pub fn argv(&self) -> &[String]
The exact command line that was spawned.
This contains the prompt and any session id. Treat it as sensitive:
logging it verbatim puts user content into your logs. Use
Run::redacted_argv for diagnostics.
Sourcepub fn redacted_argv(&self) -> Vec<String>
pub fn redacted_argv(&self) -> Vec<String>
The command line with every non-public value replaced by a placeholder.
Prompts, system prompts, session ids and anything from
crate::Request::unchecked_args are removed; flag names are kept so
the command stays recognisable. Sensitivity is recorded where each
argument is built rather than inferred from the finished line, so a
bare positional prompt or an opaque raw argument is covered too.
Sourcepub async fn cancel(self) -> Result<Outcome>
pub async fn cancel(self) -> Result<Outcome>
Stop the run and wait until the agent is actually gone.
Cooperative rather than an abort: the driver is asked to stop, signals the process group, reaps the child and joins its readers, and only then does this return. So when it returns the tree really has exited, which matters if the next thing you do touches the files it was working on.
Returns the partial Outcome if the run happened to finish first,
otherwise Error::Cancelled.
§Errors
Error::Cancelled in the normal case, or whatever the run failed with
if it failed before the request arrived.