agentos_client/
lib.rs

1#![forbid(unsafe_code)]
2
3//! # agentos-client
4//!
5//! High-level Rust client SDK for the Agent OS native sidecar. This is a 1:1 port of the TypeScript
6//! `AgentOs` client (`packages/core/src/agent-os.ts`): every public method, option type, return
7//! type, event, and error maps across with identical semantics.
8//!
9//! The client spawns the native `agentos-sidecar` binary and speaks the existing framed BARE
10//! protocol over its stdio (see [`transport`]). It does NOT embed the kernel in-process and does NOT
11//! define a new sidecar wire protocol. The generated Secure Exec schema surface comes from
12//! `agentos_sidecar_client::wire`; Agent OS layers ACP/session semantics on top of those generated wire
13//! frames through the wrapper client.
14//!
15//! See the companion design docs in `~/.agents/specs/rust-client-sdk/` (ADR-001, spec, reference,
16//! checklist) for the architecture, type-mapping, error taxonomy, and streaming model.
17
18pub mod agent_os;
19pub(crate) mod command_line;
20pub mod config;
21pub mod cron;
22pub mod error;
23pub mod fs;
24pub mod json_rpc;
25pub mod net;
26pub mod process;
27pub mod session;
28pub mod sidecar;
29pub mod stream;
30pub mod transport;
31
32// ---------------------------------------------------------------------------
33// Centralized constants (ADR-001 §6 / spec.md §7)
34// ---------------------------------------------------------------------------
35
36/// ACP protocol version negotiated on session creation.
37pub const ACP_PROTOCOL_VERSION: u64 = 1;
38
39/// Per-request permission timeout (milliseconds).
40pub const PERMISSION_TIMEOUT_MS: u64 = 120_000;
41
42/// Bounded closed-session-id set capacity (for `close_session` idempotence).
43pub const CLOSED_SESSION_ID_RETENTION_LIMIT: usize = 2048;
44
45/// Bounded exited-shell exit-code retention (for `wait_shell` after exit).
46pub const CLOSED_SHELL_EXIT_CODE_RETENTION_LIMIT: usize = 2048;
47
48/// Two-phase shell-drain timeout during dispose (milliseconds).
49pub const SHELL_DISPOSE_TIMEOUT_MS: u64 = 5_000;
50
51/// VM lifecycle ready timeout during `create` (milliseconds).
52pub const VM_READY_TIMEOUT_MS: u64 = 10_000;
53
54/// Maximum scheduled cron jobs per VM.
55pub const CRON_JOB_LIMIT: usize = 1024;
56
57// ---------------------------------------------------------------------------
58// Public re-exports
59// ---------------------------------------------------------------------------
60
61pub use agent_os::{AgentOs, PackageDescriptor, ProjectedAgent};
62pub use error::{ClientError, ClientResult};
63pub use sidecar::{
64    AgentOsSidecar, AgentOsSidecarDescription, AgentOsSidecarPlacement, SidecarState,
65};
66pub use stream::{ByteStream, Subscription};
67
68pub use config::{
69    node_modules_mount, AcpLimits, AgentOsConfig, AgentOsConfigBuilder, AgentOsLimits,
70    AgentOsSidecarConfig, FsPermissionRule, FsPermissions, HostTool, HttpLimits, JsRuntimeLimits,
71    MountConfig, MountPlugin, OverlayMountConfig, PackageRef, PatternPermissionRule,
72    PatternPermissions, PermissionMode, Permissions, PluginLimits, PythonLimits, ResourceLimits,
73    RootFilesystemConfig, RootFilesystemKind, RootFilesystemMode, RootLowerInput, RulePermissions,
74    ScheduleCallback, ScheduleDriver, ScheduleEntry, ScheduleHandle, SidecarJsBridgeCall,
75    SidecarJsBridgeCallback, SoftwareInput, SoftwareKind, TimerScheduleDriver, ToolCallback,
76    ToolKit, ToolLimits, WasmLimits,
77};
78
79pub use process::{
80    ExecOptions, ExecResult, ProcessInfo, ProcessStatus, ProcessTreeNode, SpawnHandle,
81    SpawnOptions, SpawnStdio, SpawnedProcessInfo, StdinInput, TimingMitigation,
82};
83
84pub use fs::{
85    BatchReadResult, BatchWriteEntry, BatchWriteResult, DeleteOptions, DirEntry, DirEntryType,
86    FileContent, FilesystemEntry, FilesystemEntryEncoding, FilesystemSnapshotEntries,
87    FilesystemSnapshotExport, MkdirOptions, MountFsOptions, ReaddirRecursiveOptions,
88    RootSnapshotExport, SnapshotExportKind, VirtualDirEntry, VirtualFileSystem, VirtualStat,
89};
90
91pub use shell::{ConnectTerminalOptions, OpenShellOptions, ShellHandle};
92
93pub use session::{
94    AgentCapabilities, AgentExitEvent, AgentExitStream, AgentExitSubscription, AgentInfo,
95    AgentRegistryEntry, ConfigAllowedValue, CreateSessionOptions, McpServerConfig, PermissionReply,
96    PermissionRequest, PromptCapabilities, PromptResult, ResumeSessionOptions, ResumeSessionResult,
97    SessionConfigOption, SessionId, SessionInfo, SessionInitData, SessionMode, SessionModeState,
98};
99
100pub use json_rpc::{
101    is_unknown_session, AcpTimeoutErrorData, JsonRpcError, JsonRpcId, JsonRpcNotification,
102    JsonRpcResponse, UnknownSessionErrorData,
103};
104
105pub use cron::{
106    CronAction, CronEvent, CronJobHandle, CronJobInfo, CronJobOptions, CronManager, CronOverlap,
107};
108
109// `shell` is declared here because its methods live in a sibling module to keep `lib.rs` re-exports
110// flat; the module file itself is `shell.rs`.
111pub mod shell;
agentos_client/lib.rs

agentos_client/
lib.rs
