agental-sdk 0.9.0 → 0.11.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 +27 -2
- package/dist/index.d.ts +3 -3
- package/dist/index.js +1 -1
- package/dist/openapi.d.ts +615 -5
- package/dist/sandbox.d.ts +84 -6
- package/dist/sandbox.js +105 -13
- package/dist/terminal.d.ts +30 -3
- package/dist/terminal.js +33 -2
- package/dist/types.d.ts +10 -0
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +1 -1
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
|
-
|
|
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
|
|
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/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";
|