openagents_sdk::computers
Account-bound cloud computers over the generated public contract. Save mutation requests before sending them; reuse the same request after response loss. Local cancellation never stops a remote computer or command.
| Item | What it does |
|---|---|
Command struct | A command as the service last reported it. |
CommandOutcome enum | How a finished command ended. |
CommandRef struct | Identifies one command on one cloud computer. |
CommandRequest struct | A saved request to run a command, safe to resend after a lost response. |
Computer struct | A cloud computer as the service last reported it. |
ComputerPage struct | One page of cloud computers from a list call. |
ComputerRef struct | Identifies one cloud computer on one account and deployment. |
Computers struct | A borrowed client bound to one authenticated account. |
CreateRequest struct | A saved request to create a cloud computer, safe to resend after a lost response. |
Credential struct | A prepared credential as the service last reported it. |
CredentialRef struct | Identifies one prepared credential on a cloud computer. |
CredentialRequest struct | A saved request to prepare a credential for a command. |
Error enum | An error from a cloud computer call. |
File struct | A file read from a cloud computer. |
Output struct | One page of a command's output. |
OutputReader struct | Reads a command's output page by page; save it to continue reading later. |
Refusal enum | A stable refusal category; `Error::code` preserves future server codes. |
RequestKey struct | A key that lets the service recognize a resent request as the same request. |
RetryPolicy struct | How many times, and how long apart, to retry a failed request. |
WaitFor enum | The computer state that `wait` waits for. |
WriteIntent struct | A recovery record contains the expected hash, not the file's private bytes. |
WriteReceipt struct | Confirms that a file on the computer has the expected bytes. |
Command
pub struct Command {}
A command as the service last reported it.
Command::reference
pub fn reference(&self) -> &CommandRef
Returns the reference to this command.
Command::data
pub fn data(&self) -> &generated::AppCommand
Returns the command's details as the service sent them.
Command::outcome
pub fn outcome(&self) -> Option<CommandOutcome>
Returns how the command ended, or None while it still runs.
CommandOutcome
pub enum CommandOutcome {
Succeeded,
Failed,
Cancelled,
TimedOut,
Unknown,
}
How a finished command ended.
CommandRef
pub struct CommandRef {}
Identifies one command on one cloud computer.
CommandRef::id
pub fn id(&self) -> &str
Returns the command's ID.
CommandRef::computer
pub fn computer(&self) -> &ComputerRef
Returns the computer the command runs on.
CommandRequest
pub struct CommandRequest {}
A saved request to run a command, safe to resend after a lost response.
CommandRequest::options
pub fn options(&self) -> &CommandOptions
The exact saved command settings, including credential references.
CommandRequest::key
pub fn key(&self) -> &RequestKey
Returns the key that identifies this request.
CommandRequest::computer
pub fn computer(&self) -> &ComputerRef
Returns the computer the command runs on.
Computer
pub struct Computer {}
A cloud computer as the service last reported it.
Computer::reference
pub fn reference(&self) -> &ComputerRef
Returns the reference to this computer.
Computer::data
pub fn data(&self) -> &generated::AppComputer
Returns the computer's details as the service sent them.
Computer::awake
pub fn awake(&self) -> bool
Returns whether the computer is running and online.
Computer::stopped
pub fn stopped(&self) -> bool
Returns whether the computer is stopped and offline.
ComputerPage
pub struct ComputerPage {
pub computers: Vec<Computer>,
pub next_cursor: Option<String>,
}
One page of cloud computers from a list call.
ComputerRef
pub struct ComputerRef {}
Identifies one cloud computer on one account and deployment.
ComputerRef::id
pub fn id(&self) -> &str
Returns the computer's ID.
ComputerRef::account
pub fn account(&self) -> &str
Returns the ID of the account that owns the computer.
ComputerRef::deployment
pub fn deployment(&self) -> &Deployment
Returns the deployment the computer belongs to.
Computers
pub struct Computers<'a> {}
A borrowed client bound to one authenticated account. Auth and history retain their existing retry behavior; only eligible Computers operations retry.
Computers::command_request
pub fn command_request(
&self,
computer: &ComputerRef,
mut options: CommandOptions,
) -> Result<CommandRequest, Error>
Builds a request to run a command; save it before you send it.
Computers::execute
pub async fn execute(
&self,
request: &CommandRequest,
cancel: &CancellationToken,
) -> Result<Command, Error>
Runs a saved command request on its computer.
Computers::get_command
pub async fn get_command(
&self,
reference: &CommandRef,
cancel: &CancellationToken,
) -> Result<Command, Error>
Gets the current state of a command.
Computers::cancel_command
pub async fn cancel_command(
&self,
reference: &CommandRef,
cancel: &CancellationToken,
) -> Result<Command, Error>
Asks the computer to cancel a command.
Computers::output
pub fn output(&self, reference: &CommandRef) -> Result<OutputReader, Error>
Returns a reader for a command's output from the start.
Computers::output_at
pub fn output_at(
&self,
reference: &CommandRef,
stdout: u64,
stderr: u64,
) -> Result<OutputReader, Error>
Read from previously delivered byte positions without replaying a command.
Computers::wait_command
pub async fn wait_command(
&self,
reference: &CommandRef,
timeout: Duration,
cancel: &CancellationToken,
) -> Result<Command, Error>
Waits until a command finishes, the timeout ends, or the call is canceled.
Computers::credential_request
pub fn credential_request(
&self,
command: &CommandRequest,
source: &str,
rule: &str,
ttl_seconds: u64,
) -> Result<CredentialRequest, Error>
Save this request, prepare every required source, then send the command. A wake or expired/revoked reference requires a new preparation request.
Computers::credential_reference
pub fn credential_reference(
&self,
computer: &ComputerRef,
id: &str,
) -> Result<CredentialRef, Error>
Returns a reference to the credential with this ID on a computer.
Computers::command_with_credential
pub fn command_with_credential(
&self,
command: &CommandRequest,
credential: &Credential,
env_name: &str,
) -> Result<CommandRequest, Error>
Add the non-secret marker before saving and dispatching the final command. A changed command body cannot reuse a key that was already submitted.
Computers::prepare_credential
pub async fn prepare_credential(
&self,
request: &CredentialRequest,
cancel: &CancellationToken,
) -> Result<Credential, Error>
Sends a saved request to prepare a credential.
Computers::get_credential
pub async fn get_credential(
&self,
reference: &CredentialRef,
cancel: &CancellationToken,
) -> Result<Credential, Error>
Gets the current state of a prepared credential.
Computers::revoke_credential
pub async fn revoke_credential(
&self,
reference: &CredentialRef,
cancel: &CancellationToken,
) -> Result<(), Error>
Revokes a prepared credential so no command can use it.
Computers::write_intent
pub fn write_intent(
&self,
computer: &ComputerRef,
path: &str,
bytes: &[u8],
) -> Result<WriteIntent, Error>
Builds a write request for a file of up to 4 MiB; save it before you send it.
Computers::read_file
pub async fn read_file(
&self,
computer: &ComputerRef,
path: &str,
cancel: &CancellationToken,
) -> Result<File, Error>
Reads a file from a cloud computer and checks its hash.
Computers::write_file
pub async fn write_file(
&self,
intent: &WriteIntent,
bytes: &[u8],
cancel: &CancellationToken,
) -> Result<WriteReceipt, Error>
Send once. A lost write response requires read/hash reconciliation; it never triggers another upload, including on a 429 or 503.
Computers::reconcile_write
pub async fn reconcile_write(
&self,
intent: &WriteIntent,
cancel: &CancellationToken,
) -> Result<Option<WriteReceipt>, Error>
Observe matching bytes after an uncertain upload. This does not claim which writer produced them or submit another write.
Computers::create_request
pub fn create_request(
&self,
mut options: CreateOptions,
) -> Result<CreateRequest, Error>
Create and retain this request before sending it. Serialization is explicit and contains private settings, but never a session credential.
Computers::create
pub async fn create(
&self,
request: &CreateRequest,
cancel: &CancellationToken,
) -> Result<Computer, Error>
Creates a cloud computer from a saved request.
Computers::get
pub async fn get(
&self,
reference: &ComputerRef,
cancel: &CancellationToken,
) -> Result<Computer, Error>
Gets the current state of a cloud computer.
Computers::list
pub async fn list(
&self,
limit: u16,
after: Option<&str>,
cancel: &CancellationToken,
) -> Result<ComputerPage, Error>
Lists up to limit cloud computers, starting after a cursor.
Computers::capabilities
pub async fn capabilities(
&self,
cancel: &CancellationToken,
) -> Result<Capabilities, Error>
Returns what cloud computers on this deployment support.
Computers::stop
pub async fn stop(
&self,
reference: &ComputerRef,
cancel: &CancellationToken,
) -> Result<Computer, Error>
An explicit intent; an uncertain stop is observed, never automatically replayed.
Computers::wake
pub async fn wake(
&self,
reference: &ComputerRef,
cancel: &CancellationToken,
) -> Result<Computer, Error>
Starts a stopped cloud computer.
Computers::delete
pub async fn delete(
&self,
reference: &ComputerRef,
cancel: &CancellationToken,
) -> Result<(), Error>
Delete only a cloud computer. Never reinterpret its ID as an enrolled name.
Computers::wait
pub async fn wait(
&self,
reference: &ComputerRef,
target: WaitFor,
timeout: Duration,
cancel: &CancellationToken,
) -> Result<Computer, Error>
Wait for an observed state; timeout and cancellation send no remote intent.
Computers::with_retries
pub fn with_retries(mut self, policy: RetryPolicy) -> Result<Self, Error>
Sets how failed requests are retried.
Computers::with_operation_timeout
pub fn with_operation_timeout(mut self, timeout: Duration) -> Result<Self, Error>
Sets how long one call may take, up to 10 minutes.
Computers::reference
pub fn reference(&self, id: &str) -> Result<ComputerRef, Error>
Returns a reference to the computer with this ID on the session's account.
Computers::command_reference
pub fn command_reference(
&self,
computer: &ComputerRef,
id: &str,
) -> Result<CommandRef, Error>
Returns a reference to the command with this ID on a computer.
CreateRequest
pub struct CreateRequest {}
A saved request to create a cloud computer, safe to resend after a lost response.
CreateRequest::key
pub fn key(&self) -> &RequestKey
Returns the key that identifies this request.
Credential
pub struct Credential {}
A prepared credential as the service last reported it.
Credential::reference
pub fn reference(&self) -> &CredentialRef
Returns the reference to this credential.
Credential::data
pub fn data(&self) -> &generated::AppComputerCredentialReference
Returns the credential's details as the service sent them.
CredentialRef
pub struct CredentialRef {}
Identifies one prepared credential on a cloud computer.
CredentialRef::id
pub fn id(&self) -> &str
Returns the credential's ID.
CredentialRef::computer
pub fn computer(&self) -> &ComputerRef
Returns the computer the credential is for.
CredentialRef::placeholder
pub fn placeholder(&self) -> String
The non-secret marker to give the model or Git client in the guest.
CredentialRequest
pub struct CredentialRequest {}
A saved request to prepare a credential for a command.
CredentialRequest::key
pub fn key(&self) -> &RequestKey
Returns the key that identifies this request.
CredentialRequest::computer
pub fn computer(&self) -> &ComputerRef
Returns the computer the credential is for.
Error
pub enum Error {
Session(crate::Error),
InvalidInput,
InvalidResponse,
TooLarge,
Redirect,
PaymentRequired(crate::PaymentRequired),
Cancelled,
WaitTimedOut,
Unsupported,
RandomUnavailable,
Network { timeout: bool },
Api { status: u16, code: Option<String>, retry_after: Option<Duration> },
Uncertain { operation: &'static str, key: Option<String>, cause: Box<Error> },
}
An error from a cloud computer call.
Error::refusal
pub fn refusal(&self) -> Option<Refusal>
Returns the kind of refusal, when the service refused the request.
Error::status
pub fn status(&self) -> Option<u16>
Returns the HTTP status code, when the service sent one.
Error::code
pub fn code(&self) -> Option<&str>
Returns the service's error code, when it sent one.
Error::retry_after
pub fn retry_after(&self) -> Option<Duration>
Returns how long the service asked you to wait before trying again.
Error::payment_required
pub fn payment_required(&self) -> Option<&crate::PaymentRequired>
Returns the payment request, when the call needs payment.
File
pub struct File {
pub bytes: Vec<u8>,
pub sha256: String,
pub etag: String,
}
A file read from a cloud computer.
Output
pub struct Output {
pub command: Command,
pub stdout: Vec<u8>,
pub stderr: Vec<u8>,
pub stdout_gap: bool,
pub stderr_gap: bool,
pub terminal: bool,
pub has_more: bool,
}
One page of a command's output.
OutputReader
pub struct OutputReader {}
Reads a command's output page by page; save it to continue reading later.
OutputReader::command
pub fn command(&self) -> &CommandRef
Returns the command whose output this reads.
OutputReader::next_page
pub async fn next_page(
&mut self,
computers: &Computers<'_>,
cancel: &CancellationToken,
) -> Result<Option<Output>, Error>
Reads the next page of output, or returns None after the last page.
Refusal
pub enum Refusal {
Authentication,
AccessDenied,
PaymentRequired,
Missing,
Quota,
RateLimited,
Conflict,
Unsupported,
Unavailable,
Other,
}
A stable refusal category; Error::code preserves future server codes.
RequestKey
pub struct RequestKey(String);
A key that lets the service recognize a resent request as the same request.
RequestKey::generate
pub fn generate() -> Result<Self, Error>
Creates a new random key.
RequestKey::as_str
pub fn as_str(&self) -> &str
Returns the key as text.
RetryPolicy
pub struct RetryPolicy {
pub max_retries: u8,
pub initial_delay: Duration,
pub max_delay: Duration,
}
How many times, and how long apart, to retry a failed request.
RetryPolicy::none
pub fn none() -> Self
Returns a policy that never retries.
WaitFor
pub enum WaitFor {
Awake,
Stopped,
Deleted,
}
The computer state that wait waits for.
WriteIntent
pub struct WriteIntent {}
A recovery record contains the expected hash, not the file's private bytes.
WriteIntent::allow_overwrite
pub fn allow_overwrite(mut self) -> Self
Choose this before sending; never change a write being recovered.
WriteIntent::overwrites
pub fn overwrites(&self) -> bool
Returns whether the write may replace an existing file.
WriteIntent::computer
pub fn computer(&self) -> &ComputerRef
Returns the computer the file is written to.
WriteIntent::path
pub fn path(&self) -> &str
Returns the file's path on the computer.
WriteIntent::size
pub fn size(&self) -> u64
Returns the file's size in bytes.
WriteIntent::sha256
pub fn sha256(&self) -> &str
Returns the file's SHA-256 hash as hexadecimal text.
WriteReceipt
pub struct WriteReceipt {
pub intent: WriteIntent,
pub observed_matching: bool,
}
Confirms that a file on the computer has the expected bytes.