@rivet-dev/agentos-core 0.0.0-integrate-dylib-into-main.815fcda → 0.0.0-main.29b0797

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/README.md +43 -43
  2. package/dist/agent-os.d.ts +313 -226
  3. package/dist/agent-os.js +1418 -1545
  4. package/dist/agentos-package.d.ts +31 -0
  5. package/dist/agentos-package.js +91 -0
  6. package/dist/base-filesystem.d.ts +2 -15
  7. package/dist/base-filesystem.js +23 -171
  8. package/dist/{host-tools-zod.d.ts → bindings-zod.d.ts} +1 -1
  9. package/dist/{host-tools-zod.js → bindings-zod.js} +52 -25
  10. package/dist/bindings.d.ts +43 -0
  11. package/dist/bindings.js +34 -0
  12. package/dist/cron/cron-manager.js +43 -10
  13. package/dist/cron/index.d.ts +1 -1
  14. package/dist/cron/types.d.ts +26 -10
  15. package/dist/default-software.d.ts +8 -0
  16. package/dist/default-software.js +10 -0
  17. package/dist/filesystem-snapshot.d.ts +1 -2
  18. package/dist/filesystem-snapshot.js +0 -43
  19. package/dist/generated/AcpLimitsConfig.d.ts +20 -0
  20. package/dist/generated/AcpLimitsConfig.js +2 -0
  21. package/dist/generated/BindingLimitsConfig.d.ts +10 -0
  22. package/dist/generated/BindingLimitsConfig.js +2 -0
  23. package/dist/generated/CreateVmConfig.d.ts +28 -0
  24. package/dist/generated/FsPermissionRule.d.ts +6 -0
  25. package/dist/generated/FsPermissionRule.js +1 -0
  26. package/dist/generated/FsPermissionRuleSet.d.ts +6 -0
  27. package/dist/generated/FsPermissionRuleSet.js +1 -0
  28. package/dist/generated/FsPermissionScope.d.ts +3 -0
  29. package/dist/generated/FsPermissionScope.js +1 -0
  30. package/dist/generated/HttpLimitsConfig.d.ts +3 -0
  31. package/dist/generated/HttpLimitsConfig.js +2 -0
  32. package/dist/generated/JsModuleResolution.d.ts +1 -0
  33. package/dist/generated/JsModuleResolution.js +2 -0
  34. package/dist/generated/JsRuntimeConfig.d.ts +31 -0
  35. package/dist/generated/JsRuntimeConfig.js +1 -0
  36. package/dist/generated/JsRuntimeLimitsConfig.d.ts +11 -0
  37. package/dist/generated/JsRuntimeLimitsConfig.js +2 -0
  38. package/dist/generated/JsRuntimePlatform.d.ts +1 -0
  39. package/dist/generated/JsRuntimePlatform.js +2 -0
  40. package/dist/generated/MountPluginDescriptor.d.ts +4 -0
  41. package/dist/generated/MountPluginDescriptor.js +2 -0
  42. package/dist/generated/NativeRootFilesystemConfig.d.ts +5 -0
  43. package/dist/generated/NativeRootFilesystemConfig.js +1 -0
  44. package/dist/generated/PatternPermissionRule.d.ts +6 -0
  45. package/dist/generated/PatternPermissionRule.js +1 -0
  46. package/dist/generated/PatternPermissionRuleSet.d.ts +6 -0
  47. package/dist/generated/PatternPermissionRuleSet.js +1 -0
  48. package/dist/generated/PatternPermissionScope.d.ts +3 -0
  49. package/dist/generated/PatternPermissionScope.js +1 -0
  50. package/dist/generated/PermissionMode.d.ts +1 -0
  51. package/dist/generated/PermissionMode.js +2 -0
  52. package/dist/generated/PermissionsPolicy.d.ts +10 -0
  53. package/dist/generated/PermissionsPolicy.js +1 -0
  54. package/dist/generated/PluginLimitsConfig.d.ts +4 -0
  55. package/dist/generated/PluginLimitsConfig.js +2 -0
  56. package/dist/generated/ProcessLimitsConfig.d.ts +7 -0
  57. package/dist/generated/ProcessLimitsConfig.js +2 -0
  58. package/dist/generated/PythonLimitsConfig.d.ts +6 -0
  59. package/dist/generated/PythonLimitsConfig.js +2 -0
  60. package/dist/generated/ResourceLimitsConfig.d.ts +24 -0
  61. package/dist/generated/ResourceLimitsConfig.js +2 -0
  62. package/dist/generated/RootFilesystemConfig.d.ts +9 -0
  63. package/dist/generated/RootFilesystemConfig.js +1 -0
  64. package/dist/generated/RootFilesystemEntry.d.ts +13 -0
  65. package/dist/generated/RootFilesystemEntry.js +1 -0
  66. package/dist/generated/RootFilesystemEntryEncoding.d.ts +1 -0
  67. package/dist/generated/RootFilesystemEntryEncoding.js +2 -0
  68. package/dist/generated/RootFilesystemEntryKind.d.ts +1 -0
  69. package/dist/generated/RootFilesystemEntryKind.js +2 -0
  70. package/dist/generated/RootFilesystemLowerDescriptor.d.ts +7 -0
  71. package/dist/generated/RootFilesystemLowerDescriptor.js +1 -0
  72. package/dist/generated/RootFilesystemMode.d.ts +1 -0
  73. package/dist/generated/RootFilesystemMode.js +2 -0
  74. package/dist/generated/VmDnsConfig.d.ts +6 -0
  75. package/dist/generated/VmDnsConfig.js +2 -0
  76. package/dist/generated/VmGroupConfig.d.ts +5 -0
  77. package/dist/generated/VmGroupConfig.js +2 -0
  78. package/dist/generated/VmLimitsConfig.d.ts +20 -0
  79. package/dist/generated/VmLimitsConfig.js +1 -0
  80. package/dist/generated/VmListenPolicyConfig.d.ts +5 -0
  81. package/dist/generated/VmListenPolicyConfig.js +2 -0
  82. package/dist/generated/VmUserAccountConfig.d.ts +9 -0
  83. package/dist/generated/VmUserAccountConfig.js +2 -0
  84. package/dist/generated/VmUserConfig.d.ts +19 -0
  85. package/dist/generated/VmUserConfig.js +1 -0
  86. package/dist/generated/WasmLimitsConfig.d.ts +8 -0
  87. package/dist/generated/WasmLimitsConfig.js +2 -0
  88. package/dist/host-dir-mount.d.ts +1 -1
  89. package/dist/index.d.ts +6 -5
  90. package/dist/index.js +5 -5
  91. package/dist/layers.d.ts +7 -4
  92. package/dist/layers.js +0 -176
  93. package/dist/options-schema.d.ts +556 -0
  94. package/dist/options-schema.js +386 -0
  95. package/dist/packages.d.ts +17 -116
  96. package/dist/packages.js +35 -322
  97. package/dist/runtime-compat.d.ts +33 -46
  98. package/dist/runtime-compat.js +197 -511
  99. package/dist/runtime.d.ts +42 -8
  100. package/dist/sandbox.d.ts +112 -0
  101. package/dist/sandbox.js +264 -0
  102. package/dist/session-api.d.ts +180 -0
  103. package/dist/session-api.js +1 -0
  104. package/dist/sidecar/agentos-protocol.d.ts +509 -20
  105. package/dist/sidecar/agentos-protocol.js +808 -81
  106. package/dist/sidecar/native-process-client.d.ts +6 -2
  107. package/dist/sidecar/native-process-client.js +8 -1
  108. package/dist/sidecar/permissions.d.ts +1 -1
  109. package/dist/sidecar/permissions.js +4 -4
  110. package/dist/sidecar/rpc-client.d.ts +100 -9
  111. package/dist/sidecar/rpc-client.js +445 -110
  112. package/dist/test/runtime.d.ts +2 -1
  113. package/dist/test/runtime.js +2 -1
  114. package/dist/test/terminal-harness.js +0 -3
  115. package/dist/types.d.ts +13 -7
  116. package/package.json +46 -35
  117. package/dist/agent-session-types.d.ts +0 -67
  118. package/dist/agents.d.ts +0 -63
  119. package/dist/agents.js +0 -42
  120. package/dist/host-tools.d.ts +0 -45
  121. package/dist/host-tools.js +0 -26
  122. package/dist/overlay-filesystem.d.ts +0 -19
  123. package/dist/overlay-filesystem.js +0 -645
  124. package/fixtures/AGENTOS_SYSTEM_PROMPT.md +0 -21
  125. /package/dist/{agent-session-types.js → generated/CreateVmConfig.js} +0 -0
package/dist/runtime.d.ts CHANGED
@@ -10,6 +10,7 @@ export interface VirtualDirEntry {
10
10
  export interface VirtualStat {
11
11
  mode: number;
12
12
  size: number;
13
+ sizeExact?: bigint;
13
14
  blocks: number;
14
15
  dev: number;
15
16
  rdev: number;
@@ -20,7 +21,9 @@ export interface VirtualStat {
20
21
  ctimeMs: number;
21
22
  birthtimeMs: number;
22
23
  ino: number;
24
+ inoExact?: bigint;
23
25
  nlink: number;
26
+ nlinkExact?: bigint;
24
27
  uid: number;
25
28
  gid: number;
26
29
  }
@@ -45,7 +48,9 @@ export interface VirtualFileSystem {
45
48
  lstat(path: string): Promise<VirtualStat>;
46
49
  link(oldPath: string, newPath: string): Promise<void>;
47
50
  chmod(path: string, mode: number): Promise<void>;
48
- chown(path: string, uid: number, gid: number): Promise<void>;
51
+ chown(path: string, uid: number, gid: number, options?: {
52
+ followSymlinks?: boolean;
53
+ }): Promise<void>;
49
54
  utimes(path: string, atime: number, mtime: number): Promise<void>;
50
55
  truncate(path: string, length: number): Promise<void>;
51
56
  pread(path: string, offset: number, length: number): Promise<Uint8Array>;
@@ -76,7 +81,7 @@ export type NetworkPermissions = PermissionMode | RulePermissions<PatternPermiss
76
81
  export type ChildProcessPermissions = PermissionMode | RulePermissions<PatternPermissionRule>;
77
82
  export type ProcessPermissions = PermissionMode | RulePermissions<PatternPermissionRule>;
78
83
  export type EnvPermissions = PermissionMode | RulePermissions<PatternPermissionRule>;
79
- export type ToolPermissions = PermissionMode | RulePermissions<PatternPermissionRule>;
84
+ export type BindingPermissions = PermissionMode | RulePermissions<PatternPermissionRule>;
80
85
  export interface ProcessInfo {
81
86
  pid: number;
82
87
  ppid: number;
@@ -93,15 +98,16 @@ export interface ProcessInfo {
93
98
  }
94
99
  export interface ManagedProcess {
95
100
  pid: number;
96
- writeStdin(data: Uint8Array | string): void;
97
- closeStdin(): void;
101
+ writeStdin(data: Uint8Array | string): Promise<void>;
102
+ closeStdin(): Promise<void>;
98
103
  kill(signal?: number): void;
99
104
  wait(): Promise<number>;
100
105
  readonly exitCode: number | null;
101
106
  }
102
107
  export interface ShellHandle {
103
108
  pid: number;
104
- write(data: Uint8Array | string): void;
109
+ write(data: Uint8Array | string): Promise<void>;
110
+ /** Ordered PTY output containing stdout and stderr exactly once. */
105
111
  onData: ((data: Uint8Array) => void) | null;
106
112
  resize(cols: number, rows: number): void;
107
113
  kill(signal?: number): void;
@@ -114,6 +120,7 @@ export interface OpenShellOptions {
114
120
  cwd?: string;
115
121
  cols?: number;
116
122
  rows?: number;
123
+ /** Optional stderr-only diagnostic tap; do not render it alongside `onData`. */
117
124
  onStderr?: (data: Uint8Array) => void;
118
125
  }
119
126
  export interface ConnectTerminalOptions extends OpenShellOptions {
@@ -163,7 +170,7 @@ export interface Permissions {
163
170
  childProcess?: ChildProcessPermissions;
164
171
  process?: ProcessPermissions;
165
172
  env?: EnvPermissions;
166
- tool?: ToolPermissions;
173
+ binding?: BindingPermissions;
167
174
  }
168
175
  export interface ResourceBudgets {
169
176
  maxOutputBytes?: number;
@@ -224,6 +231,7 @@ export interface SystemDriver {
224
231
  network?: NetworkAdapter;
225
232
  commandExecutor?: CommandExecutor;
226
233
  permissions?: Permissions;
234
+ mounts: readonly NodeModulesMountConfig[];
227
235
  runtime: {
228
236
  process: ProcessConfig;
229
237
  os: OSConfig;
@@ -258,6 +266,13 @@ export interface NodeRuntimeDriverFactory {
258
266
  export interface KernelInterface {
259
267
  vfs: VirtualFileSystem;
260
268
  }
269
+ export interface KernelRecursiveDirEntry {
270
+ name: string;
271
+ path: string;
272
+ isDirectory: boolean;
273
+ isSymbolicLink: boolean;
274
+ size: number;
275
+ }
261
276
  export interface Kernel extends KernelInterface {
262
277
  mount(driver: KernelRuntimeDriver): Promise<void>;
263
278
  dispose(): Promise<void>;
@@ -267,17 +282,24 @@ export interface Kernel extends KernelInterface {
267
282
  connectTerminal(options?: ConnectTerminalOptions): Promise<number>;
268
283
  mountFs(path: string, fs: VirtualFileSystem, options?: {
269
284
  readOnly?: boolean;
270
- }): void;
271
- unmountFs(path: string): void;
285
+ }): void | Promise<void>;
286
+ unmountFs(path: string): void | Promise<void>;
272
287
  readFile(path: string): Promise<Uint8Array>;
273
288
  writeFile(path: string, content: string | Uint8Array): Promise<void>;
274
289
  mkdir(path: string): Promise<void>;
275
290
  readdir(path: string): Promise<string[]>;
291
+ readdirRecursive(path: string, options?: {
292
+ maxDepth?: number;
293
+ }): Promise<KernelRecursiveDirEntry[]>;
276
294
  stat(path: string): Promise<VirtualStat>;
277
295
  exists(path: string): Promise<boolean>;
278
296
  removeFile(path: string): Promise<void>;
279
297
  removeDir(path: string): Promise<void>;
298
+ removePath(path: string, options?: {
299
+ recursive?: boolean;
300
+ }): Promise<void>;
280
301
  rename(oldPath: string, newPath: string): Promise<void>;
302
+ movePath(oldPath: string, newPath: string): Promise<void>;
281
303
  readonly commands: ReadonlyMap<string, string>;
282
304
  readonly processes: ReadonlyMap<number, ProcessInfo>;
283
305
  readonly env: Record<string, string>;
@@ -299,11 +321,23 @@ export interface BindingTree {
299
321
  [key: string]: BindingFunction | BindingTree;
300
322
  }
301
323
  export type BindingFunction = (...args: unknown[]) => unknown;
324
+ export interface NodeModulesMountConfig {
325
+ path: string;
326
+ plugin: {
327
+ id: "host_dir";
328
+ config: {
329
+ hostPath: string;
330
+ readOnly: boolean;
331
+ };
332
+ };
333
+ readOnly: boolean;
334
+ }
302
335
  export interface NodeDriverOptions {
303
336
  filesystem?: VirtualFileSystem;
304
337
  networkAdapter?: NetworkAdapter;
305
338
  commandExecutor?: CommandExecutor;
306
339
  permissions?: Permissions;
340
+ mounts?: readonly NodeModulesMountConfig[];
307
341
  processConfig?: ProcessConfig;
308
342
  osConfig?: OSConfig;
309
343
  }
@@ -0,0 +1,112 @@
1
+ import type { MountConfig, MountConfigJsonObject, NativeMountPluginDescriptor } from "./agent-os.js";
2
+ import type { Bindings } from "./bindings.js";
3
+ export interface AgentOsSandboxProcessResult {
4
+ stdout?: string;
5
+ stderr?: string;
6
+ exitCode?: number | null;
7
+ timedOut?: boolean;
8
+ durationMs?: number;
9
+ }
10
+ export interface AgentOsSandboxProcessInfo {
11
+ id: string;
12
+ command?: string;
13
+ args?: string[];
14
+ status?: string;
15
+ exitCode?: number | null;
16
+ pid?: number | null;
17
+ }
18
+ export interface AgentOsSandboxProcessLogs {
19
+ entries: Array<{
20
+ data: string;
21
+ encoding?: "base64" | string;
22
+ stream?: "stdout" | "stderr" | "combined" | string;
23
+ timestampMs?: number;
24
+ }>;
25
+ }
26
+ export interface AgentOsSandboxClient {
27
+ dispose?(): Promise<void> | void;
28
+ runProcess(options: {
29
+ command: string;
30
+ args?: string[];
31
+ cwd?: string;
32
+ env?: Record<string, string>;
33
+ timeoutMs?: number;
34
+ }): Promise<AgentOsSandboxProcessResult>;
35
+ createProcess(options: {
36
+ command: string;
37
+ args?: string[];
38
+ cwd?: string;
39
+ env?: Record<string, string>;
40
+ }): Promise<AgentOsSandboxProcessInfo>;
41
+ listProcesses(): Promise<{
42
+ processes: AgentOsSandboxProcessInfo[];
43
+ }>;
44
+ stopProcess(id: string): Promise<AgentOsSandboxProcessInfo>;
45
+ killProcess(id: string): Promise<AgentOsSandboxProcessInfo>;
46
+ getProcessLogs(id: string, options?: {
47
+ stream?: "stdout" | "stderr" | "combined";
48
+ tail?: number;
49
+ }): Promise<AgentOsSandboxProcessLogs>;
50
+ sendProcessInput(id: string, input: {
51
+ data: string;
52
+ encoding: "base64";
53
+ }): Promise<unknown>;
54
+ }
55
+ export interface AgentOsSandboxProvider {
56
+ start(): Promise<AgentOsSandboxClient>;
57
+ }
58
+ export interface AgentOsSandboxCommonOptions {
59
+ /** Mount path inside the agentOS VM. Defaults to "/mnt/sandbox". */
60
+ mountPath?: string;
61
+ /** Root path inside the external sandbox provider. Defaults to "/". */
62
+ sandboxRoot?: string;
63
+ /** Per-request timeout for sandbox-agent filesystem calls. */
64
+ timeoutMs?: number;
65
+ /** Maximum file size allowed for buffered pread/truncate fallbacks. */
66
+ maxFullReadBytes?: number;
67
+ /** Marks the VM mount read-only. Defaults to false. */
68
+ readOnly?: boolean;
69
+ }
70
+ export interface AgentOsSandboxProviderOptions extends AgentOsSandboxCommonOptions {
71
+ /** Provider used to start a Sandbox Agent client for this VM. */
72
+ provider: AgentOsSandboxProvider;
73
+ }
74
+ export interface AgentOsSandboxClientOptions extends AgentOsSandboxCommonOptions {
75
+ /** Externally provisioned Sandbox Agent-compatible client instance. */
76
+ client: AgentOsSandboxClient;
77
+ /**
78
+ * Advanced lifecycle control. Set true to dispose `client` with the VM, or
79
+ * provide a custom dispose hook. Defaults to false for the object form.
80
+ */
81
+ dispose?: boolean | (() => void | Promise<void>);
82
+ }
83
+ export type AgentOsSandboxOptions = AgentOsSandboxProviderOptions | AgentOsSandboxClientOptions;
84
+ export type AgentOsSandboxInput = AgentOsSandboxOptions;
85
+ declare const sandboxDisposeHooks: unique symbol;
86
+ type SandboxDisposeHook = () => void | Promise<void>;
87
+ export type AgentOsSandboxExpandedOptions = {
88
+ mounts?: MountConfig[];
89
+ bindings?: Bindings[];
90
+ [sandboxDisposeHooks]?: SandboxDisposeHook[];
91
+ };
92
+ type ResolvedSandboxOptions = AgentOsSandboxCommonOptions & {
93
+ client: AgentOsSandboxClient;
94
+ };
95
+ export type SandboxMountPluginConfig = MountConfigJsonObject & {
96
+ baseUrl: string;
97
+ token?: string;
98
+ headers?: Record<string, string>;
99
+ basePath?: string;
100
+ timeoutMs?: number;
101
+ maxFullReadBytes?: number;
102
+ };
103
+ export declare function createSandboxFs(input: ResolvedSandboxOptions | AgentOsSandboxClientOptions): NativeMountPluginDescriptor<SandboxMountPluginConfig>;
104
+ export declare function createSandboxBindings(input: ResolvedSandboxOptions | AgentOsSandboxClientOptions): Bindings;
105
+ export declare function getSandboxDisposeHooks(options: object | undefined): SandboxDisposeHook[];
106
+ export declare function resolveSandboxOptions<T extends {
107
+ sandbox?: AgentOsSandboxInput;
108
+ }>(options: T): Promise<Omit<T, "sandbox"> & {
109
+ mounts?: MountConfig[];
110
+ bindings?: Bindings[];
111
+ }>;
112
+ export {};
@@ -0,0 +1,264 @@
1
+ import { z } from "zod";
2
+ const sandboxDisposeHooks = Symbol("agentos.sandboxDisposeHooks");
3
+ function binding(def) {
4
+ return def;
5
+ }
6
+ function normalizeHeaders(headers) {
7
+ if (!headers) {
8
+ return undefined;
9
+ }
10
+ if (headers instanceof Headers) {
11
+ return Object.fromEntries(headers.entries());
12
+ }
13
+ if (Array.isArray(headers)) {
14
+ return Object.fromEntries(headers);
15
+ }
16
+ return Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, String(value)]));
17
+ }
18
+ function getSerializableClientConfig(client) {
19
+ const serializable = client;
20
+ const baseUrl = serializable.baseUrl?.trim().replace(/\/+$/, "");
21
+ if (!baseUrl) {
22
+ throw new Error("Sandbox client does not expose a serializable baseUrl; connect with a standard SandboxAgent client instance");
23
+ }
24
+ return {
25
+ baseUrl,
26
+ ...(serializable.token ? { token: serializable.token } : {}),
27
+ ...(serializable.defaultHeaders
28
+ ? { headers: normalizeHeaders(serializable.defaultHeaders) }
29
+ : {}),
30
+ };
31
+ }
32
+ export function createSandboxFs(input) {
33
+ const options = input;
34
+ return {
35
+ id: "sandbox_agent",
36
+ config: {
37
+ ...getSerializableClientConfig(options.client),
38
+ ...(options.sandboxRoot ? { basePath: options.sandboxRoot } : {}),
39
+ ...(options.timeoutMs != null ? { timeoutMs: options.timeoutMs } : {}),
40
+ ...(options.maxFullReadBytes != null
41
+ ? { maxFullReadBytes: options.maxFullReadBytes }
42
+ : {}),
43
+ },
44
+ };
45
+ }
46
+ export function createSandboxBindings(input) {
47
+ const options = input;
48
+ const { client } = options;
49
+ return {
50
+ name: "sandbox",
51
+ description: "Execute commands and manage processes in a remote sandbox environment.",
52
+ bindings: {
53
+ "run-command": binding({
54
+ description: "Run a command synchronously in the sandbox and return its stdout, stderr, and exit code.",
55
+ inputSchema: z.object({
56
+ command: z
57
+ .string()
58
+ .describe("The command to execute (e.g. 'ls', 'python3')."),
59
+ args: z.array(z.string()).optional(),
60
+ cwd: z.string().optional(),
61
+ env: z.record(z.string(), z.string()).optional(),
62
+ timeoutMs: z.number().optional(),
63
+ }),
64
+ timeout: 120_000,
65
+ execute: async (input) => {
66
+ const result = await client.runProcess(input);
67
+ return {
68
+ stdout: result.stdout,
69
+ stderr: result.stderr,
70
+ exitCode: result.exitCode,
71
+ timedOut: result.timedOut,
72
+ durationMs: result.durationMs,
73
+ };
74
+ },
75
+ }),
76
+ "create-process": binding({
77
+ description: "Start a long-running background process in the sandbox. Returns a process ID for later management.",
78
+ inputSchema: z.object({
79
+ command: z.string(),
80
+ args: z.array(z.string()).optional(),
81
+ cwd: z.string().optional(),
82
+ env: z.record(z.string(), z.string()).optional(),
83
+ }),
84
+ execute: async (input) => {
85
+ const proc = await client.createProcess(input);
86
+ return {
87
+ id: proc.id,
88
+ command: proc.command,
89
+ args: proc.args,
90
+ status: proc.status,
91
+ pid: proc.pid,
92
+ };
93
+ },
94
+ }),
95
+ "list-processes": binding({
96
+ description: "List all processes running in the sandbox.",
97
+ inputSchema: z.object({}),
98
+ execute: async () => {
99
+ const result = await client.listProcesses();
100
+ return {
101
+ processes: result.processes.map((p) => ({
102
+ id: p.id,
103
+ command: p.command,
104
+ args: p.args,
105
+ status: p.status,
106
+ exitCode: p.exitCode,
107
+ pid: p.pid,
108
+ })),
109
+ };
110
+ },
111
+ }),
112
+ "stop-process": binding({
113
+ description: "Gracefully stop a running process in the sandbox.",
114
+ inputSchema: z.object({ id: z.string() }),
115
+ execute: async (input) => {
116
+ const proc = await client.stopProcess(input.id);
117
+ return {
118
+ id: proc.id,
119
+ status: proc.status,
120
+ exitCode: proc.exitCode,
121
+ };
122
+ },
123
+ }),
124
+ "kill-process": binding({
125
+ description: "Forcefully kill a running process in the sandbox.",
126
+ inputSchema: z.object({ id: z.string() }),
127
+ execute: async (input) => {
128
+ const proc = await client.killProcess(input.id);
129
+ return {
130
+ id: proc.id,
131
+ status: proc.status,
132
+ exitCode: proc.exitCode,
133
+ };
134
+ },
135
+ }),
136
+ "get-process-logs": binding({
137
+ description: "Get stdout/stderr logs from a sandbox process.",
138
+ inputSchema: z.object({
139
+ id: z.string(),
140
+ stream: z.enum(["stdout", "stderr", "combined"]).optional(),
141
+ tail: z.number().optional(),
142
+ }),
143
+ execute: async (input) => {
144
+ const result = await client.getProcessLogs(input.id, {
145
+ stream: input.stream,
146
+ tail: input.tail,
147
+ });
148
+ return {
149
+ logs: result.entries.map((e) => {
150
+ const data = e.encoding === "base64"
151
+ ? Buffer.from(e.data, "base64").toString("utf-8")
152
+ : e.data;
153
+ return {
154
+ data,
155
+ stream: e.stream,
156
+ timestampMs: e.timestampMs,
157
+ };
158
+ }),
159
+ };
160
+ },
161
+ }),
162
+ "send-input": binding({
163
+ description: "Send text input to an interactive sandbox process via stdin.",
164
+ inputSchema: z.object({
165
+ id: z.string(),
166
+ data: z.string(),
167
+ }),
168
+ execute: async (input) => {
169
+ await client.sendProcessInput(input.id, {
170
+ data: Buffer.from(input.data, "utf-8").toString("base64"),
171
+ encoding: "base64",
172
+ });
173
+ return { sent: true };
174
+ },
175
+ }),
176
+ },
177
+ };
178
+ }
179
+ function isProviderOptions(input) {
180
+ return "provider" in input;
181
+ }
182
+ function isClientOptions(input) {
183
+ return "client" in input;
184
+ }
185
+ function assertNoLegacySandboxOptions(input) {
186
+ const legacyKeys = ["mount", "bindings", "path", "basePath"];
187
+ for (const key of legacyKeys) {
188
+ if (key in input) {
189
+ const replacement = key === "path" || key === "basePath" ? "sandboxRoot" : undefined;
190
+ throw new Error(replacement
191
+ ? `sandbox.${key} has been removed; use sandbox.${replacement} instead.`
192
+ : `sandbox.${key} has been removed; sandbox mounts and bindings are always enabled.`);
193
+ }
194
+ }
195
+ }
196
+ async function normalizeSandboxInput(input) {
197
+ assertNoLegacySandboxOptions(input);
198
+ if (isProviderOptions(input)) {
199
+ if (typeof input.provider?.start !== "function") {
200
+ throw new Error("sandbox.provider must expose a start() function.");
201
+ }
202
+ const client = await input.provider.start();
203
+ return {
204
+ options: { ...input, client },
205
+ dispose: () => client.dispose?.(),
206
+ };
207
+ }
208
+ if (!isClientOptions(input)) {
209
+ throw new Error("sandbox must be configured with either { provider } or { client }.");
210
+ }
211
+ const dispose = typeof input.dispose === "function"
212
+ ? input.dispose
213
+ : input.dispose === true
214
+ ? () => input.client.dispose?.()
215
+ : undefined;
216
+ return {
217
+ options: input,
218
+ dispose,
219
+ };
220
+ }
221
+ function attachSandboxDisposeHooks(options, hooks) {
222
+ if (hooks.length === 0) {
223
+ return options;
224
+ }
225
+ Object.defineProperty(options, sandboxDisposeHooks, {
226
+ value: hooks,
227
+ enumerable: false,
228
+ configurable: false,
229
+ writable: false,
230
+ });
231
+ return options;
232
+ }
233
+ export function getSandboxDisposeHooks(options) {
234
+ return options
235
+ ? (options[sandboxDisposeHooks] ?? [])
236
+ : [];
237
+ }
238
+ export async function resolveSandboxOptions(options) {
239
+ const { sandbox, ...rest } = options;
240
+ if (!sandbox) {
241
+ return rest;
242
+ }
243
+ const normalizedSandbox = await normalizeSandboxInput(sandbox);
244
+ const sandboxOptions = normalizedSandbox.options;
245
+ const expanded = rest;
246
+ const mountPath = sandboxOptions.mountPath ?? "/mnt/sandbox";
247
+ const mounts = [
248
+ ...(expanded.mounts ?? []),
249
+ {
250
+ path: mountPath,
251
+ plugin: createSandboxFs(sandboxOptions),
252
+ readOnly: sandboxOptions.readOnly,
253
+ },
254
+ ];
255
+ const bindings = [
256
+ ...(expanded.bindings ?? []),
257
+ createSandboxBindings(sandboxOptions),
258
+ ];
259
+ return attachSandboxDisposeHooks({
260
+ ...expanded,
261
+ mounts,
262
+ bindings,
263
+ }, normalizedSandbox.dispose ? [normalizedSandbox.dispose] : []);
264
+ }
@@ -0,0 +1,180 @@
1
+ import type { ContentBlock, Implementation, McpServer, RequestPermissionRequest, RequestPermissionResponse, SessionConfigOption, SessionUpdate, StopReason } from "@agentclientprotocol/sdk";
2
+ export type { ContentBlock, McpServer, SessionConfigOption, SessionUpdate, StopReason, };
3
+ export type { RequestPermissionRequest, RequestPermissionResponse };
4
+ export type JsonValue = null | boolean | number | string | JsonValue[] | {
5
+ [key: string]: JsonValue;
6
+ };
7
+ export interface SerializedError {
8
+ code: string;
9
+ message: string;
10
+ details?: JsonValue;
11
+ retryable?: boolean;
12
+ }
13
+ /** Exact upstream ACP MCP server configuration. */
14
+ export type McpServerConfig = McpServer;
15
+ export type PermissionPolicy = "reject_all" | "ask" | "allow_all";
16
+ export interface OpenSessionInput {
17
+ sessionId?: string;
18
+ agent: string;
19
+ cwd?: string;
20
+ additionalDirectories?: string[];
21
+ env?: Record<string, string>;
22
+ mcpServers?: McpServerConfig[];
23
+ /**
24
+ * Immutable AgentOS strategy for native ACP permission requests. Defaults to
25
+ * `allow_all`. This does not configure VM permissions or adapter tool access.
26
+ */
27
+ permissionPolicy?: PermissionPolicy;
28
+ skipOsInstructions?: boolean;
29
+ additionalInstructions?: string;
30
+ }
31
+ export interface SessionTarget {
32
+ sessionId?: string;
33
+ }
34
+ export type DeleteSessionInput = SessionTarget;
35
+ export type SessionState = {
36
+ status: "idle";
37
+ } | {
38
+ status: "running";
39
+ startedAt: string;
40
+ } | {
41
+ status: "waiting";
42
+ waitingSince: string;
43
+ requests: PendingPermissionRequest[];
44
+ } | {
45
+ status: "failed";
46
+ error: SerializedError;
47
+ };
48
+ export interface SessionInfo {
49
+ sessionId: string;
50
+ agent: string;
51
+ cwd: string;
52
+ additionalDirectories: string[];
53
+ state: SessionState;
54
+ latestSequence: number;
55
+ title?: string;
56
+ metadata?: Record<string, JsonValue> | null;
57
+ createdAt: string;
58
+ updatedAt: string;
59
+ }
60
+ export interface ListSessionsInput {
61
+ cursor?: string;
62
+ limit?: number;
63
+ }
64
+ export interface SessionPage {
65
+ sessions: SessionInfo[];
66
+ nextCursor: string | null;
67
+ }
68
+ export interface PromptInput {
69
+ sessionId?: string;
70
+ idempotencyKey?: string;
71
+ content: ContentBlock[];
72
+ }
73
+ export interface UserMessage {
74
+ id: string;
75
+ role: "user";
76
+ content: ContentBlock[];
77
+ }
78
+ export interface AgentMessage {
79
+ id: string;
80
+ role: "agent";
81
+ content: ContentBlock[];
82
+ }
83
+ export interface PromptResult {
84
+ sessionId: string;
85
+ message: AgentMessage | null;
86
+ stopReason: StopReason;
87
+ }
88
+ export interface CancelPromptResult {
89
+ status: "cancelled" | "no_active_prompt";
90
+ }
91
+ export interface DurableSessionEventEnvelope {
92
+ durability: "durable";
93
+ sessionId: string;
94
+ sequence: number;
95
+ timestamp: string;
96
+ }
97
+ export interface EphemeralSessionEventEnvelope {
98
+ durability: "ephemeral";
99
+ sessionId: string;
100
+ afterSequence: number;
101
+ }
102
+ type FlatAcpSessionUpdate<Update extends SessionUpdate = SessionUpdate> = Update extends SessionUpdate ? Omit<Update, "sessionUpdate"> & {
103
+ type: Update["sessionUpdate"];
104
+ } : never;
105
+ /** Exact ACP session-update payloads with the ACP discriminator promoted to `type`. */
106
+ export type AcpSessionEvent = FlatAcpSessionUpdate;
107
+ export type DurableSessionUpdateEntry = DurableSessionEventEnvelope & AcpSessionEvent;
108
+ export type DurablePermissionRequestEntry = DurableSessionEventEnvelope & {
109
+ type: "permission_request";
110
+ requestId: string;
111
+ } & Omit<RequestPermissionRequest, "sessionId">;
112
+ export type DurablePermissionResponseEntry = DurableSessionEventEnvelope & {
113
+ type: "permission_response";
114
+ requestId: string;
115
+ status: "accepted" | "not_pending";
116
+ reason?: PermissionTerminalReason;
117
+ } & RequestPermissionResponse;
118
+ export type DurableSessionEventEntry = DurableSessionUpdateEntry | DurablePermissionRequestEntry | DurablePermissionResponseEntry;
119
+ export type EphemeralSessionEventEntry = EphemeralSessionEventEnvelope & FlatAcpSessionUpdate<Extract<SessionUpdate, {
120
+ sessionUpdate: "agent_message_chunk" | "agent_thought_chunk";
121
+ }>>;
122
+ export type SessionStreamEntry = DurableSessionEventEntry | EphemeralSessionEventEntry;
123
+ export interface ReadHistoryInput extends SessionTarget {
124
+ before?: number;
125
+ after?: number;
126
+ limit?: number;
127
+ }
128
+ export interface HistoryPage {
129
+ events: DurableSessionEventEntry[];
130
+ hasMoreBefore: boolean;
131
+ hasMoreAfter: boolean;
132
+ }
133
+ export interface SessionConfig {
134
+ revision: number;
135
+ options: SessionConfigOption[];
136
+ }
137
+ export interface SetSessionConfigOptionInput extends SessionTarget {
138
+ configId: string;
139
+ value: string | boolean;
140
+ }
141
+ export interface SessionCapabilities {
142
+ protocolVersion: number;
143
+ loadSession: boolean;
144
+ prompt?: {
145
+ audio?: boolean;
146
+ embeddedContext?: boolean;
147
+ image?: boolean;
148
+ };
149
+ mcp?: {
150
+ http?: boolean;
151
+ sse?: boolean;
152
+ };
153
+ session?: {
154
+ list?: boolean;
155
+ resume?: boolean;
156
+ close?: boolean;
157
+ delete?: boolean;
158
+ additionalDirectories?: boolean;
159
+ };
160
+ extensions?: Record<string, JsonValue>;
161
+ }
162
+ export type SessionAgentInfo = Implementation;
163
+ export interface PendingPermissionRequest {
164
+ requestId: string;
165
+ options: RequestPermissionRequest["options"];
166
+ toolCall: RequestPermissionRequest["toolCall"];
167
+ _meta?: RequestPermissionRequest["_meta"];
168
+ }
169
+ export interface PermissionResponse {
170
+ sessionId: string;
171
+ requestId: string;
172
+ optionId: string;
173
+ }
174
+ export type PermissionTerminalReason = "already_resolved" | "prompt_cancelled" | "adapter_exited" | "session_deleted" | "vm_shutdown" | "request_not_found";
175
+ export type PermissionResponseResult = {
176
+ status: "accepted";
177
+ } | {
178
+ status: "not_pending";
179
+ reason: PermissionTerminalReason;
180
+ };