Struct AgentOs 

pub struct AgentOs { /* private fields */ }

The high-level client. Cheaply cloneable via Arc.

Implementations

impl AgentOs

pub async fn create(options: AgentOsConfig) -> Result<AgentOs, ClientError>

The sole public VM entry point. Processes software, spawns/authenticates the sidecar, creates the VM, waits for ready (10s), configures it, takes a lease, and constructs the cron manager (default crate::config::TimerScheduleDriver).

pub async fn link_software( &self, descriptor: PackageDescriptor, ) -> Result<(), ClientError>

Dispose the VM (= TS dispose). Teardown order:

1. cron dispose
2. kill all shells + snapshot pending exits
3. kill all connected terminals
4. drain tracked shell-exit tasks (two-phase, bounded by crate::SHELL_DISPOSE_TIMEOUT_MS)
5. release the lease (or tear down the transport)

Idempotent (guarded by disposed). Dynamically link a software package into the RUNNING VM (parity with the TS client’s linkSoftware). Forwarded to the sidecar, which owns the /opt/agentos projection and appends the package to its live staging dir, so the package’s commands appear under /opt/agentos/bin (on $PATH) immediately with no reboot. Errors if a command name is already linked.

pub async fn install_software( &self, source: impl Into<SoftwareSource>, ) -> Result<InstalledSoftware, ClientError>

Resolve, verify, pin, and project one exact software artifact inside the sidecar. The client sends only the source, never a resolved host path.

A crate::SoftwareSource::Registry source resolves on this host to the release manifest’s URL and digest, so the sidecar verifies the bytes exactly as for an explicit URL source.

pub async fn uninstall_software( &self, package_id: &str, ) -> Result<InstalledSoftware, ClientError>

Remove one exact package identity from the live VM. Missing ids are a typed error so actor desired state cannot silently drift from Core.

pub fn installed_software(&self) -> Vec<InstalledSoftware>

Content-addressed packages installed through Self::install_software. The legacy package-name view remains available through Self::list_software for trusted path configuration.

pub async fn list_software(&self) -> Result<Vec<SoftwareInfo>, ClientError>

pub async fn shutdown(&self) -> Result<(), ClientError>

pub fn sidecar(&self) -> Arc<AgentOsSidecar>

The (possibly shared) sidecar handle backing this VM. Public for parity with TS AgentOs.sidecar (e.g. describe() reports active_vm_count across VMs sharing a pool).

impl AgentOs

pub fn schedule_cron( &self, options: CronJobOptions, ) -> Result<CronJobHandle, ClientError>

Schedule a cron job. SYNC. Validates the schedule (errors InvalidSchedule / PastSchedule). id defaults to a UUID; overlap defaults to allow.

Mirrors TS AgentOs.scheduleCron / CronManager.schedule: validation happens up front, the driver is asked to arm the timer (this.driver.schedule({ id, schedule, callback })), and the job is registered. The driver owns all timing: it parses the schedule, fires the callback, reschedules cron after each fire, and is cancelled on CronJobHandle::cancel / CronManager::dispose. The returned CronJobHandle cancels the job.

pub fn list_cron_jobs(&self) -> Vec<CronJobInfo>

Snapshot all cron jobs. Mirrors TS CronManager.list.

pub fn cancel_cron_job(&self, id: &str)

Cancel a cron job. No-op if unknown; never errors. Mirrors TS CronManager.cancel.

pub fn cron_events(&self) -> Receiver<CronEvent>

Subscribe to cron events. The TS API returns no unsubscribe; dropping the receiver is the equivalent. Each run emits Fire then Complete|Error. Mirrors TS AgentOs.onCronEvent.

impl AgentOs

pub async fn read_file(&self, path: &str) -> Result<Vec<u8>>

Read a file’s raw bytes (no decode).

pub async fn write_file( &self, path: &str, content: impl Into<FileContent>, ) -> Result<()>

Write a file. Writable-path guard; does NOT auto-create parents; Text -> UTF-8.

pub async fn write_files( &self, entries: Vec<BatchWriteEntry>, ) -> Vec<BatchWriteResult>

Batch write. Sequential; never rejects (per-entry error); auto-creates parent dirs.

pub async fn read_files(&self, paths: Vec<String>) -> Vec<BatchReadResult>

Batch read. Sequential; never rejects; content None on failure.

pub async fn mkdir(&self, path: &str, options: MkdirOptions) -> Result<()>

Make a directory. Recursive -> writable guard + mkdirp; non-recursive -> safe guard + single level. The guard asymmetry is load-bearing.

pub async fn readdir(&self, path: &str) -> Result<Vec<String>>

List basenames (may include ./..).

pub async fn read_dir_with_types( &self, path: &str, ) -> Result<Vec<VirtualDirEntry>>

List directory entries with their resolved type, mirroring the TS readDirWithTypes used by a typed fs/readDir host request. ./.. are filtered by the caller. A symlink is reported as a symlink (lstat-style, not followed); other entries are stat’d as directory vs file.

pub async fn readdir_recursive( &self, path: &str, options: ReaddirRecursiveOptions, ) -> Result<Vec<DirEntry>>

Recursive BFS listing; symlinks recorded but NOT descended; a stat failure aborts the call.

pub async fn readdir_entries(&self, path: &str) -> Result<Vec<VirtualDirEntry>>

Return typed immediate children using one sidecar filesystem operation.

pub async fn stat(&self, path: &str) -> Result<VirtualStat>

Stat (follows symlinks).

pub async fn exists(&self, path: &str) -> Result<bool>

Existence check. Safe-path guard still errors; missing path -> false.

pub async fn export_root_filesystem( &self, max_bytes: usize, ) -> Result<RootSnapshotExport>

Export the root filesystem snapshot. Octal-string mode + utf8/base64 content verbatim.

pub async fn mount_fs(&self, descriptor: DynamicMountDescriptor) -> Result<()>

Mount a portable sidecar-owned filesystem descriptor.

pub async fn unmount_fs(&self, path: &str) -> Result<()>

pub async fn list_mounts(&self) -> Result<Vec<MountInfo>>

pub async fn move_path(&self, from: &str, to: &str) -> Result<()>

Move a path through the sidecar primitive. The kernel attempts rename first, then falls back to recursive copy+remove on EXDEV.

pub async fn remove(&self, path: &str, options: RemoveOptions) -> Result<()>

Delete a path through the sidecar primitive. Non-recursive directory deletes preserve ENOTEMPTY semantics.

impl AgentOs

pub async fn exec( &self, command: impl Into<String>, options: LanguageExecutionOptions, ) -> ClientResult<CodeExecutionResult>

pub async fn exec_argv( &self, command: impl Into<String>, args: Vec<String>, options: LanguageExecutionOptions, ) -> ClientResult<CodeExecutionResult>

pub async fn execute_javascript( &self, source: impl Into<String>, options: JavaScriptExecutionOptions, ) -> ClientResult<CodeExecutionResult>

pub async fn evaluate_javascript( &self, expression: impl Into<String>, options: JavaScriptExecutionOptions, ) -> ClientResult<CodeEvaluationResult>

pub async fn execute_javascript_file( &self, path: impl Into<String>, options: LanguageExecutionOptions, ) -> ClientResult<CodeExecutionResult>

pub async fn spawn_javascript( &self, source: impl Into<String>, options: LanguageSpawnOptions, ) -> ClientResult<ProcessDescriptor>

pub async fn spawn_javascript_file( &self, path: impl Into<String>, options: LanguageSpawnOptions, ) -> ClientResult<ProcessDescriptor>

pub async fn execute_typescript( &self, source: impl Into<String>, options: TypeScriptExecutionOptions, ) -> ClientResult<CodeExecutionResult>

pub async fn evaluate_typescript( &self, expression: impl Into<String>, options: TypeScriptExecutionOptions, ) -> ClientResult<CodeEvaluationResult>

pub async fn execute_typescript_file( &self, path: impl Into<String>, options: TypeScriptExecutionOptions, ) -> ClientResult<CodeExecutionResult>

pub async fn spawn_typescript( &self, source: impl Into<String>, options: LanguageSpawnOptions, ) -> ClientResult<ProcessDescriptor>

pub async fn spawn_typescript_file( &self, path: impl Into<String>, options: LanguageSpawnOptions, ) -> ClientResult<ProcessDescriptor>

pub async fn check_typescript( &self, source: impl Into<String>, options: TypeScriptCheckOptions, ) -> ClientResult<TypeScriptCheckResult>

pub async fn check_typescript_project( &self, options: TypeScriptCheckOptions, ) -> ClientResult<TypeScriptCheckResult>

pub async fn install_npm_project( &self, options: NpmProjectInstallOptions, ) -> ClientResult<CodeExecutionResult>

pub async fn install_npm_packages( &self, packages: Vec<String>, options: NpmPackageInstallOptions, ) -> ClientResult<CodeExecutionResult>

pub async fn execute_npm_script( &self, script: impl Into<String>, options: LanguageExecutionOptions, ) -> ClientResult<CodeExecutionResult>

pub async fn execute_npm_package( &self, package_spec: impl Into<String>, binary: Option<String>, options: LanguageExecutionOptions, ) -> ClientResult<CodeExecutionResult>

pub async fn execute_python( &self, source: impl Into<String>, options: InlineExecutionOptions, ) -> ClientResult<CodeExecutionResult>

pub async fn evaluate_python( &self, expression: impl Into<String>, options: InlineExecutionOptions, ) -> ClientResult<CodeEvaluationResult>

pub async fn execute_python_file( &self, path: impl Into<String>, options: LanguageExecutionOptions, ) -> ClientResult<CodeExecutionResult>

pub async fn execute_python_module( &self, module: impl Into<String>, options: LanguageExecutionOptions, ) -> ClientResult<CodeExecutionResult>

pub async fn spawn_python( &self, source: impl Into<String>, options: LanguageSpawnOptions, ) -> ClientResult<ProcessDescriptor>

pub async fn spawn_python_file( &self, path: impl Into<String>, options: LanguageSpawnOptions, ) -> ClientResult<ProcessDescriptor>

pub async fn spawn_python_module( &self, module: impl Into<String>, options: LanguageSpawnOptions, ) -> ClientResult<ProcessDescriptor>

pub async fn install_python_packages( &self, packages: Vec<String>, options: PythonInstallOptions, ) -> ClientResult<CodeExecutionResult>

pub async fn create_context( &self, context_id: &str, ) -> ClientResult<ContextDescriptor>

pub async fn get_context( &self, context_id: &str, ) -> ClientResult<ContextDescriptor>

pub async fn list_contexts(&self) -> ClientResult<Vec<ContextDescriptor>>

pub async fn reset_context(&self, context_id: &str) -> ClientResult<()>

pub async fn delete_context(&self, context_id: &str) -> ClientResult<()>

impl AgentOs

pub async fn http_request(&self, request: HttpRequest) -> Result<HttpResponse>

Fetch from a guest server listening on port inside the VM.

path is derived from the request URI’s pathname+search; the host is ignored. The body is only sent for methods other than GET/HEAD. The response body is base64-decoded.

pub async fn http_request_stream_start( &self, request: HttpRequest, ) -> Result<HttpStreamHead>

Starts a bounded streaming request to a guest HTTP listener.

pub async fn http_request_stream_read( &self, stream_id: &str, max_bytes: u32, ) -> Result<HttpStreamChunk>

Reads at most max_bytes from an existing guest HTTP response stream.

pub async fn http_request_stream_cancel(&self, stream_id: &str) -> Result<()>

Cancels an existing guest HTTP response stream.

impl AgentOs

pub async fn exec_process( &self, command: &str, options: ExecOptions, ) -> Result<ExecResult>

Run a command to completion. The wire Execute request starts the process and returns a process id immediately; stdout/stderr are accumulated and the call resolves once the matching ProcessExited event arrives. This mirrors the TS pass-through to kernel.exec semantically: the result is the full captured stdout/stderr plus exit code.

pub async fn exec_argv_process( &self, command: &str, args: &[String], options: ExecOptions, ) -> Result<ExecResult>

Run a command to completion from an already-structured (command, args) argv, bypassing the exec command-line parser. Each args element is sent verbatim as a distinct argv element — no whitespace re-splitting, no shell metacharacter detection, and no routing through sh -c. Callers that already hold a structured argv (for example the cron Exec action) must use this so the structured-argv contract is preserved end to end.

pub fn spawn_process( &self, command: &str, args: Vec<String>, options: SpawnOptions, ) -> Result<SpawnHandle>

Spawn a process. SYNC; returns { pid } only. Installs stdout/stderr fan-out over broadcast channels and wires exit via a background event-pump task. The user-facing pid is the SDK-allocated map key (the wire process_id is held inside the [ProcessEntry]).

pub fn write_process_stdin( &self, pid: u32, data: StdinInput, ) -> Result<(), ClientError>

Write to a spawned process’s stdin. SYNC. Errors with ProcessNotFound.

pub async fn write_process_stdin_awaited( &self, pid: u32, data: StdinInput, ) -> Result<(), ClientError>

Write stdin and wait for the sidecar acknowledgement.

pub fn close_process_stdin(&self, pid: u32) -> Result<(), ClientError>

Close a spawned process’s stdin. SYNC. Errors with ProcessNotFound.

pub async fn close_process_stdin_awaited( &self, pid: u32, ) -> Result<(), ClientError>

Close stdin and wait for the sidecar acknowledgement.

pub fn on_process_output( &self, pid: u32, handler: impl FnMut(ProcessOutput) + Send + 'static, ) -> Result<Subscription, ClientError>

Subscribe to the unified stdout/stderr event stream for a process.

pub fn on_process_exit( &self, pid: u32, handler: impl FnOnce(ProcessExit) + Send + 'static, ) -> Result<Subscription, ClientError>

Register a once-only exit handler. If the process has already exited, the handler fires immediately and synchronously and a no-op unsubscribe is returned (the watch already holds a confirmed exit). Otherwise the handler fires once when the exit code lands. The exit code is i32, never null.

pub async fn wait_process(&self, pid: u32) -> Result<i32, ClientError>

Await a spawned process’s exit code. Unknown-pid lookup errors (synchronously in TS; here the lookup error is returned before any awaiting begins).

pub async fn read_process_output( &self, pid: u32, after: Option<u64>, max_events: Option<usize>, max_bytes: Option<usize>, ) -> Result<ProcessOutputReplay, ClientError>

Read bounded sequenced output retained for a spawned process.

pub fn list_processes(&self) -> Vec<SpawnedProcessInfo>

List SDK-spawned processes only. running = exit_code.is_none().

pub async fn all_processes(&self) -> Result<Vec<ProcessInfo>>

List ALL kernel processes (native sidecar process snapshot).

The kernel snapshot keys processes by their raw kernel pid. SDK-spawned root processes carry a synthetic display pid (the spawn return value); this remaps each snapshot entry’s pid/ppid/pgid/sid back to that display pid via the per-process kernel_pid watch, so a caller can correlate spawn() with all_processes()/process_tree(). Results are sorted ascending by display pid (TS snapshotProcesses .sort((l,r) => l.pid - r.pid)).

pub async fn process_tree(&self) -> Result<Vec<ProcessTreeNode>>

Build the process forest from all_processes, linked by ppid.

pub fn get_process(&self, pid: u32) -> Result<SpawnedProcessInfo, ClientError>

Get a single SDK-spawned process’s info. Errors (not None) when not found.

pub fn stop_process(&self, pid: u32) -> Result<(), ClientError>

SIGTERM a spawned process. No-op if already exited; errors if unknown.

pub fn kill_process(&self, pid: u32) -> Result<(), ClientError>

SIGKILL a spawned process. No-op if already exited; errors if unknown.

pub async fn signal_process_awaited( &self, pid: u32, signal: &str, ) -> Result<(), ClientError>

Deliver a signal and wait for the sidecar acknowledgement.

pub async fn resize_process_pty_awaited( &self, pid: u32, cols: u16, rows: u16, ) -> Result<(), ClientError>

Resize a spawned process PTY and wait for the sidecar acknowledgement.

impl AgentOs

pub async fn create_sidecar( sidecar_id: Option<String>, ) -> Result<Arc<AgentOsSidecar>, ClientError>

Create an explicit sidecar handle. sidecar_id defaults to agentos-native-sidecar-<uuid>.

Parity with TypeScript createAgentOsSidecarInternal: the explicit handle carries an Explicit placement whose sidecar_id echoes the resolved id and has no shared pool.

pub async fn get_shared_sidecar( pool: Option<String>, sidecar_binary_path: Option<String>, ) -> Result<Arc<AgentOsSidecar>, ClientError>

Get (or create) a pooled shared sidecar. Pool defaults to "default". Uses the process-global cache.

Parity with TypeScript getSharedAgentOsSidecarInternal: return the cached sidecar for the pool when it exists and is not disposed; otherwise build a fresh handle (agentos-shared-sidecar:<pool>, Shared placement) and cache it. Because the cache is a process-global concurrent map rather than a synchronously-checked Map, the insert is done atomically with entry/insert so two racing callers converge on a single live handle.

impl AgentOs

pub fn open_shell(&self, options: OpenShellOptions) -> Result<ShellHandle>

Open a PTY-backed shell. SYNC. Returns a synthetic shell-N id (NOT a pid).

The shell id and its registry entry are allocated synchronously (matching the TS sync contract); the actual guest-process spawn, output fan-out, and exit-task registration happen on a background task because the wire spawn is async. The exit task is tracked in the pending-shell-exit set so dispose can drain it (two-phase teardown).

Stdout and stderr are fanned into the shell’s ordered data broadcast (on_shell_data). Stderr is also fanned into a dedicated diagnostic broadcast (on_shell_stderr and the [OpenShellOptions::on_stderr] callback); terminal renderers should consume only data.

pub async fn connect_terminal( &self, options: ConnectTerminalOptions, ) -> Result<u32>

Connect a terminal bound to host stdio. Returns a PID. NOT tracked in the shells map; cannot be addressed by other shell methods. Killed during dispose via the terminal registry.

Mirrors the TS connectTerminal, which routes its onData/onStderr callbacks through openShell. The Rust port opens a shell, wires the caller’s on_data to ordered terminal data and on_stderr to the optional diagnostic tap, then returns the shell’s pid. Host stdin binding, terminal raw-mode, and SIGWINCH/resize forwarding are host-process concerns that have no native wire op and are intentionally not bound here.

pub fn write_shell( &self, shell_id: &str, data: StdinInput, ) -> Result<(), ClientError>

Write to a shell. SYNC fire-and-forget. Errors with ClientError::ShellNotFound.

pub fn list_shells(&self) -> Vec<TerminalInfo>

List actor-addressable shells currently retained by Core.

pub async fn snapshot_shell( &self, shell_id: &str, after: Option<u64>, max_bytes: Option<usize>, ) -> Result<TerminalSnapshot, ClientError>

Read a bounded raw-byte terminal replay. Screen rendering is a client concern.

pub async fn snapshot_shell_page( &self, shell_id: &str, after: Option<u64>, max_events: Option<usize>, max_bytes: Option<usize>, ) -> Result<TerminalSnapshot, ClientError>

Read a terminal replay page with the same event and byte bounds as process output replay.

pub async fn write_shell_awaited( &self, shell_id: &str, data: StdinInput, ) -> Result<(), ClientError>

Write to a shell and AWAIT the wire write. Same routing as Self::write_shell, but the caller observes wire failures instead of a fire-and-forget warn — used by the actor plugin’s writeShell action so a failed write rejects the action.

pub fn on_shell_data( &self, shell_id: &str, handler: impl FnMut(ShellData) + Send + 'static, ) -> Result<Subscription, ClientError>

Subscribe to a shell’s ordered terminal data. SYNC register; multi-handler; dropping the returned stream is the unsubscribe. Carries stdout and stderr exactly once in wire order. Use Self::on_shell_stderr only as a channel-specific diagnostic tap, not as a second terminal-rendering stream. Errors with ClientError::ShellNotFound.

pub fn on_shell_output( &self, shell_id: &str, handler: impl FnMut(TerminalOutputEvent) + Send + 'static, ) -> Result<Subscription, ClientError>

Subscribe to sequenced terminal output retained by Core.

pub fn on_shell_stderr( &self, shell_id: &str, handler: impl FnMut(ShellData) + Send + 'static, ) -> Result<Subscription, ClientError>

Subscribe to a shell’s stderr. SYNC register; multi-handler; dropping the returned stream is the unsubscribe. This is the optional diagnostic channel backing the TS onStderr option; stderr is also present once in ordered on_shell_data. Errors with ClientError::ShellNotFound.

pub fn on_shell_exit( &self, shell_id: &str, handler: impl FnOnce(ShellExit) + Send + 'static, ) -> Result<Subscription, ClientError>

pub fn resize_shell( &self, shell_id: &str, cols: u16, rows: u16, ) -> Result<(), ClientError>

Resize a shell’s PTY winsize. SYNC fire-and-forget, mirroring the TS ShellHandle.resize (which dispatches resizePty in the background after the spawn lands). Errors with ClientError::ShellNotFound.

pub async fn resize_shell_awaited( &self, shell_id: &str, cols: u16, rows: u16, ) -> Result<(), ClientError>

Resize a shell and wait for the sidecar acknowledgement.

pub async fn wait_shell(&self, shell_id: &str) -> Result<i32, ClientError>

Wait for a shell to exit and return its process exit code (TS waitShell). Resolves immediately for a shell that already exited within the bounded retention window. Errors with ClientError::ShellNotFound for an unknown id.

pub fn close_shell(&self, shell_id: &str) -> Result<(), ClientError>

Close a shell. SYNC. kill() + immediate map delete; the exit task is still drained by dispose. Errors with ClientError::ShellNotFound.

pub async fn close_shell_awaited( &self, shell_id: &str, ) -> Result<(), ClientError>

Close a shell and wait for signal delivery to be acknowledged.

Trait Implementations

impl Clone for AgentOs

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.