agental-sdk 0.3.0 → 0.5.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/dist/openapi.d.ts CHANGED
@@ -1335,6 +1335,24 @@ export interface paths {
1335
1335
  patch?: never;
1336
1336
  trace?: never;
1337
1337
  };
1338
+ "/v1/sandboxes/{id}/terminal": {
1339
+ parameters: {
1340
+ query?: never;
1341
+ header?: never;
1342
+ path?: never;
1343
+ cookie?: never;
1344
+ };
1345
+ /** @description Whether a terminal can be opened on the sandbox now. A WebSocket handshake to this address opens one instead, with a ticket from POST /v1/sandboxes/{id}/terminal. */
1346
+ get: operations["getSandboxTerminal"];
1347
+ put?: never;
1348
+ /** @description A ticket to open a terminal on the sandbox: a login shell in it, as root in /root, with what a command runs with. Open a WebSocket to path on this API's address within 30 seconds, with the subprotocols agental.terminal.v1 and ticket.<ticket>. Send challenge, the base64url SHA-256 (unpadded) of a verifier of 43 to 128 base64url characters that you keep, as OAuth's PKCE does with S256, and add the subprotocol verifier.<verifier>: the ticket then opens a terminal only with it, from any address. Without a challenge, it opens one only from the address it was asked from. Send what is typed as binary messages, and {"type":"resize","cols":n,"rows":n} as text. The terminal's output comes as binary messages; {"type":"started"}, {"type":"exit","code","signal","timedOut"} and {"type":"error","code","message"} come as text. It is closed when the shell ends (1000), when what let it be opened no longer does, as a key taken away, a session ended or the sandbox stopped (4003), after 30 minutes with nothing typed (4008), and when it could not be opened or its sandbox stopped answering (4011). Closing it hangs the shell up: what runs in it is sent SIGHUP, as when an SSH session ends. */
1349
+ post: operations["openSandboxTerminal"];
1350
+ delete?: never;
1351
+ options?: never;
1352
+ head?: never;
1353
+ patch?: never;
1354
+ trace?: never;
1355
+ };
1338
1356
  "/v1/sandboxes/{id}/schedules": {
1339
1357
  parameters: {
1340
1358
  query?: never;
@@ -1928,7 +1946,7 @@ export interface paths {
1928
1946
  };
1929
1947
  get?: never;
1930
1948
  put?: never;
1931
- /** @description Brings running sandboxes on the template up to date with it now: all of them, or the ones named. It is the only call that changes a running sandbox because of its template; a change to a template reaches the others when they next start. Their next command gets the template's variables as they are now, with each sandbox's own on top. Its files are written to their disks now, where that can be done, and before their next command in any case. Each is held to the template's outbound rule, with its own addresses on top, from when this answers: its server is told first, one sandbox at a time, and one whose server does not take it is named in failed and left as it was. Nothing is restarted, and connections that are already open are not cut. */
1949
+ /** @description Brings running sandboxes on the template up to date with it now: all of them, or the ones named. It is the only call that changes a running sandbox because of its template; a change to a template reaches the others when they next start. Their next command gets the template's variables as they are now, with each sandbox's own on top. Its files are written to their disks now, where that can be done, and before their next command in any case. Each is held to the template's outbound rule, with its own addresses on top, from when this answers: its server is told first, one sandbox at a time, and one whose server does not take it is named in failed and left as it was. Nothing is restarted. Every open connection the rule now forbids, from the sandbox or through its proxy, is cut by the time this answers: the program in the sandbox sees it reset, and the far end hears nothing more. Connections the rule still allows carry on untouched, as do SSH sessions into the sandbox, its public addresses and the desktop. */
1932
1950
  post: operations["applyTemplate"];
1933
1951
  delete?: never;
1934
1952
  options?: never;
@@ -1963,7 +1981,7 @@ export interface paths {
1963
1981
  };
1964
1982
  /** @description What the sandbox may reach outside itself: the rule it is held to, as network on the sandbox says it, and what it comes from: its template's rule as the sandbox has it, and its own addresses on top. It changes nothing, and is answered whatever state the sandbox is in. */
1965
1983
  get: operations["getNetwork"];
1966
- /** @description Sets the addresses the sandbox may reach on top of its template's outbound rule, in place of the ones it had. They add to what the template lets out and never take from it: on an open template they change nothing until the template is blocked or an allowlist. The sandbox is held to its template's rule with these on top from when this answers, without a restart, running or stopped, and connections that are already open are not cut. The rule itself is its template's, and is changed with PUT /v1/templates/{id}/network: sending outbound here is refused with rule_on_template. What is sent to the sandbox, commands, files, its public addresses and SSH, is not affected. Only where GET /v1/policy says networkPolicy. */
1984
+ /** @description Sets the addresses the sandbox may reach on top of its template's outbound rule, in place of the ones it had. They add to what the template lets out and never take from it: on an open template they change nothing until the template is blocked or an allowlist. The sandbox is held to its template's rule with these on top from when this answers, without a restart, running or stopped. Taking an address away cuts the open connections to it by the time this answers, those through the sandbox's proxy included: the program sees its connection reset. Connections the rule still allows carry on untouched. The rule itself is its template's, and is changed with PUT /v1/templates/{id}/network: sending outbound here is refused with rule_on_template. What is sent to the sandbox, commands, files, its public addresses and SSH, is not affected. Only where GET /v1/policy says networkPolicy. */
1967
1985
  put: operations["setNetwork"];
1968
1986
  post?: never;
1969
1987
  delete?: never;
@@ -2713,6 +2731,22 @@ export interface paths {
2713
2731
  patch?: never;
2714
2732
  trace?: never;
2715
2733
  };
2734
+ "/v1/headroom/budget": {
2735
+ parameters: {
2736
+ query?: never;
2737
+ header?: never;
2738
+ path?: never;
2739
+ cookie?: never;
2740
+ };
2741
+ get?: never;
2742
+ put: operations["setHeadroomBudget"];
2743
+ post?: never;
2744
+ delete?: never;
2745
+ options?: never;
2746
+ head?: never;
2747
+ patch?: never;
2748
+ trace?: never;
2749
+ };
2716
2750
  "/v1/burst/budget": {
2717
2751
  parameters: {
2718
2752
  query?: never;
@@ -2746,6 +2780,22 @@ export interface paths {
2746
2780
  patch?: never;
2747
2781
  trace?: never;
2748
2782
  };
2783
+ "/v1/headroom": {
2784
+ parameters: {
2785
+ query?: never;
2786
+ header?: never;
2787
+ path?: never;
2788
+ cookie?: never;
2789
+ };
2790
+ get: operations["getHeadroom"];
2791
+ put?: never;
2792
+ post?: never;
2793
+ delete?: never;
2794
+ options?: never;
2795
+ head?: never;
2796
+ patch?: never;
2797
+ trace?: never;
2798
+ };
2749
2799
  "/v1/egress": {
2750
2800
  parameters: {
2751
2801
  query?: never;
@@ -3893,6 +3943,38 @@ export interface components {
3893
3943
  kept: string;
3894
3944
  }[];
3895
3945
  };
3946
+ SandboxTerminal: {
3947
+ /** @description Whether a terminal can be opened on it now: it is running, and terminals are offered here. */
3948
+ available: boolean;
3949
+ /** @description Why not, when it cannot. Null when it can. */
3950
+ reason: string | null;
3951
+ /** @description How long a terminal stays open with nothing typed in it. */
3952
+ idleSeconds: number;
3953
+ };
3954
+ SandboxTerminalTicket: {
3955
+ /** @description Opens one terminal on this sandbox, once: with the verifier of the challenge it was asked with, or, asked without one, from the address it was asked from. Sent as the WebSocket subprotocol ticket.<ticket>, never in a URL. */
3956
+ ticket: string;
3957
+ /** @description When it stops working, 30 seconds after it was given. */
3958
+ expiresAt: string;
3959
+ /**
3960
+ * @description Where the WebSocket is opened, on this API's own address.
3961
+ * @example /v1/sandboxes/sbx_0123456789abcdef/terminal
3962
+ */
3963
+ path: string;
3964
+ /** @description The subprotocols to open it with: agental.terminal.v1, and the ticket. Asked with a challenge, add verifier.<verifier>. */
3965
+ protocols: string[];
3966
+ };
3967
+ OpenSandboxTerminal: {
3968
+ /** @example 120 */
3969
+ cols: number;
3970
+ /** @example 32 */
3971
+ rows: number;
3972
+ /**
3973
+ * @description The base64url SHA-256, unpadded, of a verifier kept by the caller: the ticket then opens a terminal only with that verifier.
3974
+ * @example E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
3975
+ */
3976
+ challenge?: string;
3977
+ };
3896
3978
  Schedule: {
3897
3979
  /** @example sch_0123456789abcdef */
3898
3980
  id: string;
@@ -4711,6 +4793,8 @@ export interface components {
4711
4793
  desktop: boolean;
4712
4794
  /** @description Whether a sandbox's browser can be driven from outside it, over the Chrome DevTools Protocol: by Playwright, Puppeteer, browser-use or Stagehand on your own computer. Where it can, PUT /v1/sandboxes/{id}/browser starts Chrome in the sandbox and answers with the address to connect to. */
4713
4795
  browser: boolean;
4796
+ /** @description Whether a sandbox's terminal can be opened: a login shell in it, typed in from a browser or a program over a WebSocket. Where it can, POST /v1/sandboxes/{id}/terminal gives a ticket to open it with. */
4797
+ terminal: boolean;
4714
4798
  /** @description Whether a sandbox can be stopped with its memory kept: POST /v1/sandboxes/{id}/stop with keepMemory, after which a start puts back every process as it was. A stopped sandbox that keeps its memory costs 10% of its running price, and 5% without. */
4715
4799
  keepMemory: boolean;
4716
4800
  /** @description Whether a stopped sandbox can be archived: its machine kept in storage until it is started again. An archived sandbox is still stopped and loses nothing, and a start of it answers 202 and takes longer. */
@@ -4849,10 +4933,15 @@ export interface components {
4849
4933
  */
4850
4934
  halfLifeMinutes: number;
4851
4935
  /**
4852
- * @description What a GiB started costs once the meter is at twice the free burst, in millionths of a US dollar. It costs nothing at the free burst's edge and rises in a straight line with how far over the meter goes: fee = feeMicrosPerGib / (2 × free) × (over after² − over before²), in GiB. A burst to twice the free burst costs about $0.04 for each small sandbox past it, one to three times about $0.08.
4853
- * @example 20000
4936
+ * @description What each GiB of a start that is past the free burst costs, in millionths of a US dollar: fee = min(feeMicrosPerGib × GiB over, feeCapHours × the size's list price an hour). A small past the free burst costs $0.027, a large $0.108.
4937
+ * @example 10000
4854
4938
  */
4855
4939
  feeMicrosPerGib: number;
4940
+ /**
4941
+ * @description The most one start costs in burst fees, in hours of its size's list price.
4942
+ * @example 1
4943
+ */
4944
+ feeCapHours: number;
4856
4945
  /**
4857
4946
  * @description What an account spends on burst fees in a month at most unless it sets another budget: PUT /v1/burst/budget.
4858
4947
  * @example 50000000
@@ -5487,6 +5576,76 @@ export interface components {
5487
5576
  /** @description Always null: nothing raises an account but a change of plan. */
5488
5577
  next: null;
5489
5578
  };
5579
+ Headroom: {
5580
+ now: components["schemas"]["Burst"];
5581
+ from: string;
5582
+ to: string;
5583
+ /** @enum {string} */
5584
+ step: "10m" | "hour" | "day";
5585
+ series: {
5586
+ /** @description The step's start. */
5587
+ at: string;
5588
+ /** @description What ran at the step's end, in MB: 4096 is one small. */
5589
+ runningMb: number;
5590
+ /** @description What ran at its most in the step. */
5591
+ peakRunningMb: number;
5592
+ /** @description The burst meter at the step's end, in MB. */
5593
+ meterMb: number;
5594
+ starts: number;
5595
+ feesMicros: number;
5596
+ /** @description Creates and starts that did not start in the step, every try counted. */
5597
+ refused: number;
5598
+ }[];
5599
+ /** @description Each stretch when the burst meter was over the free burst, so that every start in it paid a fee, the newest first. One that paid nothing is left out. */
5600
+ bursts: {
5601
+ startedAt: string;
5602
+ /** @description Null where the meter was still over the free burst when the range ended. */
5603
+ endedAt: string | null;
5604
+ peakMeterMb: number;
5605
+ feesMicros: number;
5606
+ starts: number;
5607
+ bySize: {
5608
+ [key: string]: number;
5609
+ };
5610
+ bySource: {
5611
+ /**
5612
+ * @description Who started it: a runs-on repository's machine, a sandbox made with an API key, or neither (made in the console, or by agental itself).
5613
+ * @enum {string}
5614
+ */
5615
+ kind: "runs-on" | "key" | "other";
5616
+ /** @description The repository, as owner/name, or the key's name. */
5617
+ name: string | null;
5618
+ starts: number;
5619
+ feesMicros: number;
5620
+ }[];
5621
+ /** @description What did not start during it, by reason. */
5622
+ refused: {
5623
+ [key: string]: number;
5624
+ };
5625
+ }[];
5626
+ refused: {
5627
+ total: number;
5628
+ /** @description running_count: the plan's running count (running_limit_reached). budget: the month's budget for burst fees (burst_budget_reached). fee_cap: the most the caller would pay (burst_fee_too_high). room: no room on agental's servers. other: any other refusal, by its code. */
5629
+ byReason: {
5630
+ /** @enum {string} */
5631
+ reason: "running_count" | "budget" | "fee_cap" | "room" | "other";
5632
+ code: string;
5633
+ count: number;
5634
+ }[];
5635
+ };
5636
+ /** @description From a create or start being let through to its sandbox running, over those that ran in the range. */
5637
+ speed: {
5638
+ count: number;
5639
+ p50Ms: number | null;
5640
+ p90Ms: number | null;
5641
+ p99Ms: number | null;
5642
+ maxMs: number | null;
5643
+ };
5644
+ /** @description How long, in the range, the account ran within one small sandbox of its running count. */
5645
+ atRunningCountMs: number;
5646
+ peakRunningMb: number;
5647
+ peakAt: string | null;
5648
+ };
5490
5649
  EgressAccount: {
5491
5650
  /** @description Whether this deployment offers residential egress at all, as GET /v1/policy says residentialEgress. */
5492
5651
  offered: boolean;
@@ -5861,7 +6020,7 @@ export interface operations {
5861
6020
  "application/json": components["schemas"]["Error"];
5862
6021
  };
5863
6022
  };
5864
- /** @description running_limit_reached: the account runs as many sandboxes as its plan's runningUnits allows. burst_fee_too_high: the start would cost more in burst fees than the Agental-Max-Burst-Fee header allows. burst_budget_reached: the burst fee would take this month's fees past the account's budget. feeMicros says what the start would have cost; retryAfterSeconds and the Retry-After header say when it would cost nothing. Nothing was created. */
6023
+ /** @description running_limit_reached: the account runs as many sandboxes as its plan's runningUnits allows. burst_fee_too_high: the start would cost more in burst fees than the Agental-Max-Burst-Fee header allows. burst_budget_reached: the burst fee would take this month's fees past the account's budget. feeMicros says what the start would have cost; retryAfterSeconds and the Retry-After header say when it would cost nothing. refusedLastHour says how many of the account's creates and starts were refused with the same code in the last hour, this one with them, and headroomUrl where it sees them all (GET /v1/headroom). Nothing was created. */
5865
6024
  429: {
5866
6025
  headers: {
5867
6026
  [name: string]: unknown;
@@ -6563,7 +6722,7 @@ export interface operations {
6563
6722
  "application/json": components["schemas"]["Error"];
6564
6723
  };
6565
6724
  };
6566
- /** @description running_limit_reached: the account runs as many sandboxes as its plan's runningUnits allows. burst_fee_too_high: the start would cost more in burst fees than the Agental-Max-Burst-Fee header allows. burst_budget_reached: the burst fee would take this month's fees past the account's budget. feeMicros says what the start would have cost; retryAfterSeconds and the Retry-After header say when it would cost nothing. It is left stopped. */
6725
+ /** @description running_limit_reached: the account runs as many sandboxes as its plan's runningUnits allows. burst_fee_too_high: the start would cost more in burst fees than the Agental-Max-Burst-Fee header allows. burst_budget_reached: the burst fee would take this month's fees past the account's budget. feeMicros says what the start would have cost; retryAfterSeconds and the Retry-After header say when it would cost nothing. refusedLastHour says how many of the account's creates and starts were refused with the same code in the last hour, this one with them, and headroomUrl where it sees them all (GET /v1/headroom). It is left stopped. */
6567
6726
  429: {
6568
6727
  headers: {
6569
6728
  [name: string]: unknown;
@@ -7219,7 +7378,7 @@ export interface operations {
7219
7378
  "application/json": components["schemas"]["Error"];
7220
7379
  };
7221
7380
  };
7222
- /** @description running_limit_reached: the account runs as many sandboxes as its plan's runningUnits allows. burst_fee_too_high: the start would cost more in burst fees than the Agental-Max-Burst-Fee header allows. burst_budget_reached: the burst fee would take this month's fees past the account's budget. feeMicros says what the start would have cost; retryAfterSeconds and the Retry-After header say when it would cost nothing. It is left stopped. */
7381
+ /** @description running_limit_reached: the account runs as many sandboxes as its plan's runningUnits allows. burst_fee_too_high: the start would cost more in burst fees than the Agental-Max-Burst-Fee header allows. burst_budget_reached: the burst fee would take this month's fees past the account's budget. feeMicros says what the start would have cost; retryAfterSeconds and the Retry-After header say when it would cost nothing. refusedLastHour says how many of the account's creates and starts were refused with the same code in the last hour, this one with them, and headroomUrl where it sees them all (GET /v1/headroom). It is left stopped. */
7223
7382
  429: {
7224
7383
  headers: {
7225
7384
  [name: string]: unknown;
@@ -7280,7 +7439,7 @@ export interface operations {
7280
7439
  "application/json": components["schemas"]["Error"];
7281
7440
  };
7282
7441
  };
7283
- /** @description The sandbox was not running, and bringing it back on is a start. running_limit_reached: the account runs as many sandboxes as its plan's runningUnits allows. burst_fee_too_high: the start would cost more in burst fees than the Agental-Max-Burst-Fee header allows. burst_budget_reached: the burst fee would take this month's fees past the account's budget. feeMicros says what the start would have cost; retryAfterSeconds and the Retry-After header say when it would cost nothing. It is left as it was. */
7442
+ /** @description The sandbox was not running, and bringing it back on is a start. running_limit_reached: the account runs as many sandboxes as its plan's runningUnits allows. burst_fee_too_high: the start would cost more in burst fees than the Agental-Max-Burst-Fee header allows. burst_budget_reached: the burst fee would take this month's fees past the account's budget. feeMicros says what the start would have cost; retryAfterSeconds and the Retry-After header say when it would cost nothing. refusedLastHour says how many of the account's creates and starts were refused with the same code in the last hour, this one with them, and headroomUrl where it sees them all (GET /v1/headroom). It is left as it was. */
7284
7443
  429: {
7285
7444
  headers: {
7286
7445
  [name: string]: unknown;
@@ -7396,7 +7555,7 @@ export interface operations {
7396
7555
  "application/json": components["schemas"]["Error"];
7397
7556
  };
7398
7557
  };
7399
- /** @description running_limit_reached: the account runs as many sandboxes as its plan's runningUnits allows. burst_fee_too_high: the start would cost more in burst fees than the Agental-Max-Burst-Fee header allows. burst_budget_reached: the burst fee would take this month's fees past the account's budget. feeMicros says what the start would have cost; retryAfterSeconds and the Retry-After header say when it would cost nothing. Nothing was forked. */
7558
+ /** @description running_limit_reached: the account runs as many sandboxes as its plan's runningUnits allows. burst_fee_too_high: the start would cost more in burst fees than the Agental-Max-Burst-Fee header allows. burst_budget_reached: the burst fee would take this month's fees past the account's budget. feeMicros says what the start would have cost; retryAfterSeconds and the Retry-After header say when it would cost nothing. refusedLastHour says how many of the account's creates and starts were refused with the same code in the last hour, this one with them, and headroomUrl where it sees them all (GET /v1/headroom). Nothing was forked. */
7400
7559
  429: {
7401
7560
  headers: {
7402
7561
  [name: string]: unknown;
@@ -11772,6 +11931,117 @@ export interface operations {
11772
11931
  };
11773
11932
  };
11774
11933
  };
11934
+ getSandboxTerminal: {
11935
+ parameters: {
11936
+ query?: never;
11937
+ header?: never;
11938
+ path: {
11939
+ id: string;
11940
+ };
11941
+ cookie?: never;
11942
+ };
11943
+ requestBody?: never;
11944
+ responses: {
11945
+ /** @description Whether a terminal can be opened. */
11946
+ 200: {
11947
+ headers: {
11948
+ [name: string]: unknown;
11949
+ };
11950
+ content: {
11951
+ "application/json": components["schemas"]["SandboxTerminal"];
11952
+ };
11953
+ };
11954
+ /** @description Missing or invalid API key. */
11955
+ 401: {
11956
+ headers: {
11957
+ [name: string]: unknown;
11958
+ };
11959
+ content: {
11960
+ "application/json": components["schemas"]["Error"];
11961
+ };
11962
+ };
11963
+ /** @description Not found. */
11964
+ 404: {
11965
+ headers: {
11966
+ [name: string]: unknown;
11967
+ };
11968
+ content: {
11969
+ "application/json": components["schemas"]["Error"];
11970
+ };
11971
+ };
11972
+ };
11973
+ };
11974
+ openSandboxTerminal: {
11975
+ parameters: {
11976
+ query?: never;
11977
+ header?: never;
11978
+ path: {
11979
+ id: string;
11980
+ };
11981
+ cookie?: never;
11982
+ };
11983
+ requestBody: {
11984
+ content: {
11985
+ "application/json": components["schemas"]["OpenSandboxTerminal"];
11986
+ };
11987
+ };
11988
+ responses: {
11989
+ /** @description A ticket to open the terminal with. */
11990
+ 201: {
11991
+ headers: {
11992
+ [name: string]: unknown;
11993
+ };
11994
+ content: {
11995
+ "application/json": components["schemas"]["SandboxTerminalTicket"];
11996
+ };
11997
+ };
11998
+ /** @description Missing or invalid API key. */
11999
+ 401: {
12000
+ headers: {
12001
+ [name: string]: unknown;
12002
+ };
12003
+ content: {
12004
+ "application/json": components["schemas"]["Error"];
12005
+ };
12006
+ };
12007
+ /** @description Not found. */
12008
+ 404: {
12009
+ headers: {
12010
+ [name: string]: unknown;
12011
+ };
12012
+ content: {
12013
+ "application/json": components["schemas"]["Error"];
12014
+ };
12015
+ };
12016
+ /** @description sandbox_not_running: start it first. */
12017
+ 409: {
12018
+ headers: {
12019
+ [name: string]: unknown;
12020
+ };
12021
+ content: {
12022
+ "application/json": components["schemas"]["Error"];
12023
+ };
12024
+ };
12025
+ /** @description too_many_tickets: 16 terminals are being opened on it already. too_many_terminals: this key or account has 16 terminals open or being opened. */
12026
+ 429: {
12027
+ headers: {
12028
+ [name: string]: unknown;
12029
+ };
12030
+ content: {
12031
+ "application/json": components["schemas"]["Error"];
12032
+ };
12033
+ };
12034
+ /** @description terminal_unavailable: terminals are not offered here. */
12035
+ 501: {
12036
+ headers: {
12037
+ [name: string]: unknown;
12038
+ };
12039
+ content: {
12040
+ "application/json": components["schemas"]["Error"];
12041
+ };
12042
+ };
12043
+ };
12044
+ };
11775
12045
  listSchedules: {
11776
12046
  parameters: {
11777
12047
  query?: never;
@@ -17764,6 +18034,66 @@ export interface operations {
17764
18034
  };
17765
18035
  };
17766
18036
  };
18037
+ setHeadroomBudget: {
18038
+ parameters: {
18039
+ query?: never;
18040
+ header?: never;
18041
+ path?: never;
18042
+ cookie?: never;
18043
+ };
18044
+ requestBody: {
18045
+ content: {
18046
+ "application/json": components["schemas"]["BurstBudget"];
18047
+ };
18048
+ };
18049
+ responses: {
18050
+ /** @description The budget is set, and the account is answered as it stands now (the now of GET /v1/headroom). */
18051
+ 200: {
18052
+ headers: {
18053
+ [name: string]: unknown;
18054
+ };
18055
+ content: {
18056
+ "application/json": components["schemas"]["Burst"];
18057
+ };
18058
+ };
18059
+ /** @description invalid_request. The budget is not a whole number from 0 to 100000000000, or null, or the key belongs to no account. */
18060
+ 400: {
18061
+ headers: {
18062
+ [name: string]: unknown;
18063
+ };
18064
+ content: {
18065
+ "application/json": components["schemas"]["Error"];
18066
+ };
18067
+ };
18068
+ /** @description Missing or invalid API key. */
18069
+ 401: {
18070
+ headers: {
18071
+ [name: string]: unknown;
18072
+ };
18073
+ content: {
18074
+ "application/json": components["schemas"]["Error"];
18075
+ };
18076
+ };
18077
+ /** @description role_required: in a team, only an owner sets its budget. */
18078
+ 403: {
18079
+ headers: {
18080
+ [name: string]: unknown;
18081
+ };
18082
+ content: {
18083
+ "application/json": components["schemas"]["Error"];
18084
+ };
18085
+ };
18086
+ /** @description The account behind the key is gone. */
18087
+ 404: {
18088
+ headers: {
18089
+ [name: string]: unknown;
18090
+ };
18091
+ content: {
18092
+ "application/json": components["schemas"]["Error"];
18093
+ };
18094
+ };
18095
+ };
18096
+ };
17767
18097
  setBurstBudget: {
17768
18098
  parameters: {
17769
18099
  query?: never;
@@ -17777,7 +18107,7 @@ export interface operations {
17777
18107
  };
17778
18108
  };
17779
18109
  responses: {
17780
- /** @description The budget is set, and the account is answered as it stands now. */
18110
+ /** @description The budget is set, and the account is answered as it stands now (the now of GET /v1/headroom). */
17781
18111
  200: {
17782
18112
  headers: {
17783
18113
  [name: string]: unknown;
@@ -17871,6 +18201,60 @@ export interface operations {
17871
18201
  };
17872
18202
  };
17873
18203
  };
18204
+ getHeadroom: {
18205
+ parameters: {
18206
+ query?: {
18207
+ /** @description Where the range begins, in ISO 8601. Today's midnight UTC when left out. */
18208
+ from?: string;
18209
+ /** @description Where it ends. Now when left out, and never later than now. */
18210
+ to?: string;
18211
+ /** @description How often the series is read: 10m, hour or day. Left out, 10m up to two days, hour up to 8, day past that. */
18212
+ step?: "10m" | "hour" | "day";
18213
+ };
18214
+ header?: never;
18215
+ path?: never;
18216
+ cookie?: never;
18217
+ };
18218
+ requestBody?: never;
18219
+ responses: {
18220
+ /** @description How close the caller's account runs to its plan's limits: where it stands now, and over a range, what it ran against its running count, its burst meter against its free burst, each burst (a stretch when the meter was over the free burst, so every start in it paid a fee) with who started what in it, what did not start and why, and how fast what started ran. */
18221
+ 200: {
18222
+ headers: {
18223
+ [name: string]: unknown;
18224
+ };
18225
+ content: {
18226
+ "application/json": components["schemas"]["Headroom"];
18227
+ };
18228
+ };
18229
+ /** @description invalid_request: from is not before to, the range is longer than 90 days, or the key belongs to no account. */
18230
+ 400: {
18231
+ headers: {
18232
+ [name: string]: unknown;
18233
+ };
18234
+ content: {
18235
+ "application/json": components["schemas"]["Error"];
18236
+ };
18237
+ };
18238
+ /** @description Missing or invalid API key. */
18239
+ 401: {
18240
+ headers: {
18241
+ [name: string]: unknown;
18242
+ };
18243
+ content: {
18244
+ "application/json": components["schemas"]["Error"];
18245
+ };
18246
+ };
18247
+ /** @description The account behind the key is gone. */
18248
+ 404: {
18249
+ headers: {
18250
+ [name: string]: unknown;
18251
+ };
18252
+ content: {
18253
+ "application/json": components["schemas"]["Error"];
18254
+ };
18255
+ };
18256
+ };
18257
+ };
17874
18258
  getEgress: {
17875
18259
  parameters: {
17876
18260
  query?: never;
package/dist/sandbox.d.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import { type Http } from "./http.js";
2
2
  import { Secrets, type Template } from "./template.js";
3
+ import { Terminal, type TerminalOptions } from "./terminal.js";
3
4
  import type { BrowserState, CreateSchedule, Schedule, ScheduleRun, UpdateSchedule, SshKey, SshState, Command, DesktopLink, DesktopScreenshot, DesktopState, EmailMessage, EmailMessageList, EmailMessageSummary, ExecResult, HostRoute, SandboxAutoStop, SandboxEmail, SandboxInfo, SandboxMetrics, SandboxNetworkDetail, SandboxOwnNetwork, SandboxTemplate, SandboxUsage, SendEmail, SetAutoStop, Size, Snapshot, Egress, EgressInput } from "./types.js";
4
5
  /** A create answers when the machine is ready, usually in under a minute. The API says to allow it three. */
5
6
  declare const CREATE_TIMEOUT_MS = 180000;
@@ -31,7 +32,7 @@ export interface BurstOptions {
31
32
  * The most this start may cost in burst fees, in millionths of a US dollar: 0 refuses any
32
33
  * fee. A start that would cost more throws ApiError burst_fee_too_high, whose feeMicros
33
34
  * says what it would cost and retryAfterSeconds when it would cost nothing. Left out, it
34
- * pays what the account's monthly burst budget allows. burst() says what a start costs now.
35
+ * pays what the account's monthly burst budget allows. headroom() says what a start costs now (now.nextStart).
35
36
  */
36
37
  maxBurstFeeMicros?: number;
37
38
  /**
@@ -547,6 +548,21 @@ export declare class Sandbox {
547
548
  * proxy or a move may have done part of its work.
548
549
  */
549
550
  exec(command: CommandLine, options?: ExecOptions): Promise<ExecResult>;
551
+ /**
552
+ * Opens a terminal on it: a login shell as root in /root, with what a command runs with, in
553
+ * a terminal of cols by rows (80 by 24 unless given). Read its output by iterating it, type
554
+ * with write(), change its size with resize(), and end it with close(); exited says how it
555
+ * ended. It needs the key action exec, and the sandbox running. It is closed by the API after
556
+ * 30 minutes with nothing typed, and when the key or the sandbox no longer lets it be open.
557
+ *
558
+ * const terminal = await sandbox.terminal({ cols: 120, rows: 32 });
559
+ * terminal.write("uname -a; exit\n");
560
+ * for await (const chunk of terminal) process.stdout.write(chunk);
561
+ * console.log((await terminal.exited).exitCode);
562
+ *
563
+ * It is opened with the runtime's WebSocket: in Node 20, pass new Agental({ WebSocket }).
564
+ */
565
+ terminal(options?: TerminalOptions): Promise<Terminal>;
550
566
  /** Runs a command and gives its output as it arrives, then what it exited with. */
551
567
  execStream(command: CommandLine, options?: ExecOptions): AsyncGenerator<ExecEvent, void, void>;
552
568
  /**
package/dist/sandbox.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { AgentalError, ApiError, ConnectionError, TimeoutError } from "./errors.js";
2
2
  import { sleep, tagSegment } from "./http.js";
3
3
  import { Secrets } from "./template.js";
4
+ import { Terminal, terminalPkce, terminalSize } from "./terminal.js";
4
5
  /** A create answers when the machine is ready, usually in under a minute. The API says to allow it three. */
5
6
  const CREATE_TIMEOUT_MS = 180_000;
6
7
  /** An archived sandbox is brought back in as long as its disk is large. */
@@ -662,6 +663,27 @@ export class Sandbox {
662
663
  async exec(command, options = {}) {
663
664
  return (await this.http.json(this.command("/exec", command, options))).body;
664
665
  }
666
+ /**
667
+ * Opens a terminal on it: a login shell as root in /root, with what a command runs with, in
668
+ * a terminal of cols by rows (80 by 24 unless given). Read its output by iterating it, type
669
+ * with write(), change its size with resize(), and end it with close(); exited says how it
670
+ * ended. It needs the key action exec, and the sandbox running. It is closed by the API after
671
+ * 30 minutes with nothing typed, and when the key or the sandbox no longer lets it be open.
672
+ *
673
+ * const terminal = await sandbox.terminal({ cols: 120, rows: 32 });
674
+ * terminal.write("uname -a; exit\n");
675
+ * for await (const chunk of terminal) process.stdout.write(chunk);
676
+ * console.log((await terminal.exited).exitCode);
677
+ *
678
+ * It is opened with the runtime's WebSocket: in Node 20, pass new Agental({ WebSocket }).
679
+ */
680
+ async terminal(options = {}) {
681
+ const { cols, rows } = terminalSize(options);
682
+ const WebSocket = this.http.WebSocket;
683
+ const { verifier, challenge } = await terminalPkce();
684
+ const { ticket, path } = (await this.http.json({ method: "POST", path: `${this.path}/terminal`, body: { cols, rows, challenge } })).body;
685
+ return await Terminal.open(WebSocket, this.http.webSocketUrl(path), ticket, verifier);
686
+ }
665
687
  /** Runs a command and gives its output as it arrives, then what it exited with. */
666
688
  async *execStream(command, options = {}) {
667
689
  for await (const { event, data } of this.http.events(this.command("/exec/stream", command, options))) {