run
Runs the agent once and folds its events into transcript, suspending until the run ends.
Returns the state the run ended in, which is also what transcript now reports: a RunState.Finished when the agent said so, a RunState.Failed when it sent RUN_ERROR or when the stream threw -- a protocol violation caught by upstream's verifier, say. A throw is folded into the transcript as a RUN_ERROR with code CLIENT_ERROR_CODE and is not rethrown: the transcript is the report, and a UI that launched this from a button does not want an unhandled exception for a run that failed in an ordinary way. Cancellation is the exception -- it is recorded the same way, with CANCELLED_CODE, and then propagates, because the caller asked for it and a cancelled coroutine has to stay cancelled. A stream that ends without RUN_FINISHED or RUN_ERROR -- a connection the server closed cleanly mid-run -- is a failure too, recorded under CLIENT_ERROR_CODE: upstream's verifier checks each event against the last but has no opinion about the end of the stream, so this is where that check lives.
Recording a cancellation at all is deliberate. Without it the transcript keeps the caret blinking under text that will never grow and a tool call waiting on arguments that will never arrive, until the next run happens to settle them. The reducer has no state for "stopped on request", so the run is marked failed and the code says why. The message is a fixed one rather than the exception's: a Job.cancel() with no cause carries the coroutine class name as its message, which is not something to draw.
Once the agent has ended the run itself -- RUN_FINISHED or RUN_ERROR seen -- nothing that happens afterwards rewrites that verdict: a verifier throw on a trailing event, a cancellation while upstream's transport waits for the server to close the connection, or the RUN_ERROR upstream's HttpAgent sends when that wait ends in a transport failure, all leave the agent's own message and code in place. A cancellation that arrives while this call is still waiting for an earlier run to release the mutex records nothing, because nothing of this run had started.
Only the coroutine that called this can stop the run. AbstractAgent.abortRun cancels a job that upstream's runAgent starts, and runAgentObservable starts none, so through this class it is inert.
With a tools registry, a run that calls one of its tools is answered by another run, and this returns the state the last of those ended in; see the class note. A tool result an earlier run failed to carry goes out with this one, placed after the call it answers.
A thread that is interrupted -- the last run stopped to ask, and pendingInterrupts is not empty -- may not run this way, and this throws before anything is sent: the protocol lets no run start past an unanswered interrupt, so the run would be refused by the server or, worse, accepted and continued past the question. resume is the call that continues such a thread. The one exception is a retry: a resume whose run failed left its answers owed, and this carries them again.
Parameters
the run's id, tools, context and forwarded properties. The id is generated here when absent rather than by the agent, because a tool executed during the run is told which run called it; the rest are defaulted the way the agent defaults them, with the registry's tools declared after the caller's. The messages sent are the agent's own -- what it was constructed with, plus what earlier runs through it produced.
Throws
when the thread is interrupted and no failed resume is owed.