agental-sdk 0.8.0 → 0.10.0

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.
package/README.md CHANGED
@@ -95,13 +95,22 @@ await sandbox.schedules.update(tick.id, { enabled: false }); // paused
95
95
 
96
96
  ## Files
97
97
 
98
- Paths are relative to the work folder, `/opt/agental`. A file can be up to 10 MB.
98
+ A path is relative to the work folder, `/opt/agental`, or absolute: anywhere on the machine, as root sees it. A file can be up to 10 MB.
99
99
 
100
100
  ```ts
101
101
  await sandbox.files.write("notes.txt", "hi");
102
102
  await sandbox.files.read("notes.txt"); // "hi"
103
103
  await sandbox.files.write("logo.png", bytes); // a Uint8Array
104
104
  await sandbox.files.readBytes("logo.png");
105
+ await sandbox.files.read("/etc/hostname");
106
+
107
+ const file = await sandbox.files.get("notes.txt"); // { path, bytes, modifiedAt, text }
108
+ await sandbox.files.write("notes.txt", "ho", { ifModifiedAt: file.modifiedAt }); // file_changed if it was changed since
109
+
110
+ await sandbox.files.list("/var/log"); // { path, entries: [{ name, kind, bytes, modifiedAt }], truncated }
111
+ await sandbox.files.makeFolder("out/today");
112
+ await sandbox.files.move("notes.txt", "out/today/notes.txt"); // file_exists if something is there
113
+ await sandbox.files.delete("out", { recursive: true });
105
114
  ```
106
115
 
107
116
  ## Stop, start, fork, snapshot
@@ -188,7 +197,23 @@ for await (const chunk of terminal) process.stdout.write(chunk); // Uint8Array,
188
197
  const { exitCode, closeCode } = await terminal.exited; // 3, 1000
189
198
  ```
190
199
 
191
- It needs a key with the `exec` action, and the sandbox running. It is opened with the runtime's own `WebSocket` (Node 22 and later, browsers, Deno, Bun); in Node 20 pass `new Agental({ WebSocket })` from the `ws` package. The API closes it when the shell ends (`closeCode` 1000, with `exitCode`), when the key or the sandbox no longer lets it be open (4003), after 30 minutes with nothing typed (4008), and when its sandbox stops answering (4011); `error` says why when the API did. `close()`, or leaving the `for await`, hangs the shell up, as an SSH session's end does: start what must outlive it with `nohup` or `setsid`. The command's `agental shell <sandbox-id>` opens one in your own terminal.
200
+ It needs a key with the `exec` action, and the sandbox running. It is opened with the runtime's own `WebSocket` (Node 22 and later, browsers, Deno, Bun); in Node 20 pass `new Agental({ WebSocket })` from the `ws` package. The API closes it when the shell ends (`closeCode` 1000, with `exitCode`), when the key or the sandbox no longer lets it be open (4003), after 30 minutes with nothing typed (4008), and when its sandbox stops answering (4011); `error` says why when the API did. `close()`, or leaving the `for await`, hangs the shell up, as an SSH session's end does, unless the shell is kept. The command's `agental shell <sandbox-id>` opens one in your own terminal.
201
+
202
+ A kept shell runs on when its terminal closes, until it exits, is closed, or the sandbox stops, and is opened again by its id, with the last 256 KiB it printed first:
203
+
204
+ ```ts
205
+ const first = await sandbox.terminal({ keep: true });
206
+ first.write("npm run dev\n");
207
+ await first.whenStarted();
208
+ const { id, n } = first.kept!; // "pty_…", 1; null on a sandbox whose agent is from before kept shells
209
+ first.close(); // npm run dev runs on
210
+
211
+ await sandbox.terminals(); // [{ id, n, running: "npm run dev", cwd: "/root/app", attached: false, exit: null, … }]
212
+ const again = await sandbox.terminal({ attach: id });
213
+ await sandbox.closeTerminal(id); // ends it: what runs in it is sent SIGHUP
214
+ ```
215
+
216
+ Opening a kept shell again closes the terminal that had it with 4009 (`TERMINAL_CLOSE.elsewhere`): it runs on in the new one.
192
217
 
193
218
  ## Desktop
194
219
 
package/dist/client.d.ts CHANGED
@@ -27,7 +27,7 @@ export interface SandboxFilter {
27
27
  memoryKept?: boolean;
28
28
  /** open, blocked or allowlist. */
29
29
  outbound?: string | readonly string[];
30
- /** What they are doing: low-cpu, disk-full, memory-full or not-read. Any of them. */
30
+ /** What they are doing: low-cpu, disk-full, memory-full, agent-silent or not-read. Any of them. */
31
31
  activity?: string | readonly string[];
32
32
  /** None of these. */
33
33
  notActivity?: string | readonly string[];
package/dist/index.d.ts CHANGED
@@ -4,9 +4,9 @@ export type { BurstRefusalCode } from "./errors.js";
4
4
  export type { AgentalOptions } from "./http.js";
5
5
  export { Browser, Commands, Desktop, Email, Files, Sandbox, Schedules, Ssh } from "./sandbox.js";
6
6
  export { Secrets, Template, Templates } from "./template.js";
7
- export { Terminal, TERMINAL_CLOSE, TERMINAL_PROTOCOL } from "./terminal.js";
7
+ export { KEPT_TERMINAL_ID, Terminal, TERMINAL_CLOSE, TERMINAL_PROTOCOL } from "./terminal.js";
8
8
  export type { TerminalExit, TerminalOptions, WebSocketConstructor, WebSocketLike } from "./terminal.js";
9
9
  export type { TemplateChanges } from "./template.js";
10
- export type { BurstOptions, CommandLine, CreateOptions, DesktopButton, ExecEvent, ExecOptions, SandboxChanges, ScreenshotOptions, SendEmailOptions, StartOptions, StopOptions, WaitOptions } from "./sandbox.js";
11
- export type { AccountEmail, ApiKey, ApiKeyAction, ApiKeyPreset, ApiKeyUsage, Billing, BrowserState, BurstFee, BurstQuote, Headroom, HeadroomNow, HeadroomRange, HeadroomStep, Catalog, Region, AutoReload, BillingCard, BillingDetails, BillingInvoice, BillingInvoices, Checkout, Command, CreateSchedule, CreateApiKey, CreatedApiKey, DesktopLink, DesktopScreenshot, DesktopState, Egress, EgressAccount, EgressInput, EmailMessage, EmailMessageList, EmailMessageSummary, ExecResult, HiddenVariable, HostRoute, Invite, Me, Member, Organization, MetricsAtMoment, MetricsReading, NetworkRule, Operation, PlainVariable, Plan, Policy, Prices, RunningOverTime, SandboxAutoStop, SandboxEmail, SandboxInfo, SandboxSummary, SandboxJob, SandboxJobItem, SandboxJobPreview, SandboxMetrics, SandboxNetwork, SandboxNetworkDetail, SandboxOwnNetwork, SandboxStatus, SandboxTemplate, SandboxUsage, Schedule, ScheduleRun, SecretVariable, SendEmail, SetAutoStop, Size, Snapshot, SshKey, SshState, UpdateSchedule, Team, TeamRole, Telemetry, DataRetention, AccountExport, TelemetryTest, ClaudeConnection, ClaudeSession, RunsOnRepository, RunsOnRepositories, TemplateApplied, TemplateInfo, TemplateNetwork, TemplateSandbox, TemplateStart, TemplateSsh, Usage, Webhook, WebhookDelivery, } from "./types.js";
10
+ export type { BurstOptions, CommandLine, CreateOptions, DesktopButton, ExecEvent, ExecOptions, ResizeOptions, SandboxChanges, ScreenshotOptions, SendEmailOptions, StartOptions, StopOptions, WaitOptions } from "./sandbox.js";
11
+ export type { AccountEmail, ApiKey, ApiKeyAction, ApiKeyPreset, ApiKeyUsage, Billing, BrowserState, BurstFee, BurstQuote, Headroom, HeadroomNow, HeadroomRange, HeadroomStep, Catalog, Region, AutoReload, BillingCard, BillingDetails, BillingInvoice, BillingInvoices, Checkout, Command, CreateSchedule, CreateApiKey, CreatedApiKey, DesktopLink, DesktopScreenshot, DesktopState, Egress, EgressAccount, EgressInput, EmailMessage, EmailMessageList, EmailMessageSummary, ExecResult, FileContents, FileWritten, Folder, FolderEntry, HiddenVariable, HostRoute, Invite, Me, Member, Organization, MetricsAtMoment, MetricsReading, NetworkRule, Operation, PlainVariable, Plan, Policy, Prices, RunningOverTime, SandboxAutoStop, SandboxEmail, SandboxInfo, SandboxSummary, SandboxJob, SandboxJobItem, SandboxJobPreview, SandboxMetrics, SandboxNetwork, SandboxNetworkDetail, SandboxOwnNetwork, SandboxStatus, SandboxTemplate, SandboxUsage, Schedule, ScheduleRun, SecretVariable, SendEmail, SetAutoStop, Size, Snapshot, SshKey, KeptTerminal, SshState, UpdateSchedule, Team, TeamRole, Telemetry, DataRetention, AccountExport, TelemetryTest, ClaudeConnection, ClaudeSession, RunsOnRepository, RunsOnRepositories, TemplateApplied, TemplateInfo, TemplateNetwork, TemplateSandbox, TemplateStart, TemplateSsh, Usage, Webhook, WebhookDelivery, } from "./types.js";
12
12
  export { verifyWebhook } from "./webhooks.js";
package/dist/index.js CHANGED
@@ -2,5 +2,5 @@ export { Agental } from "./client.js";
2
2
  export { AgentalError, ApiError, ConnectionError, ProxyError, TimeoutError } from "./errors.js";
3
3
  export { Browser, Commands, Desktop, Email, Files, Sandbox, Schedules, Ssh } from "./sandbox.js";
4
4
  export { Secrets, Template, Templates } from "./template.js";
5
- export { Terminal, TERMINAL_CLOSE, TERMINAL_PROTOCOL } from "./terminal.js";
5
+ export { KEPT_TERMINAL_ID, Terminal, TERMINAL_CLOSE, TERMINAL_PROTOCOL } from "./terminal.js";
6
6
  export { verifyWebhook } from "./webhooks.js";