agental-sdk 0.5.0 → 0.6.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
@@ -514,7 +514,7 @@ await agental.rotateWebhookSecret(hook.id); // a new signingSecret; the old one
514
514
  await agental.deleteWebhook(hook.id);
515
515
  ```
516
516
 
517
- `events` takes the kinds of event, such as `sandbox.started`, `sandbox.stopped` and `sandbox.error`. `sandbox.auto_stop_set` is a running sandbox's stop moved: its `data` has `autoStopAt`, `previousAutoStopAt`, and `by`, `account` or `sandbox`.
517
+ `events` takes the kinds of event, such as `sandbox.started`, `sandbox.stopped` and `sandbox.error`. `sandbox.auto_stop_set` is a running sandbox's stop moved: its `data` has `autoStopAt`, `previousAutoStopAt`, and `by`, `account` or `sandbox`. A group by its name and `.*`, such as `headroom.*` or `sandbox.*`, takes every kind of the group and any added to it later; a `*` anywhere else is refused. The `headroom.*` events are your organization's, about no sandbox: `headroom.burst_started` and `headroom.burst_ended` (a stretch over the free burst, with what it cost), `headroom.refused` (starts refused, at most one a minute for each reason), `headroom.running_count_reached`, `headroom.budget_threshold` (burst fees past 80% of the month's budget) and `headroom.budget_reached` (the budget refused a start). Money is in micros of a dollar, memory in MB.
518
518
 
519
519
  Check each post your server receives:
520
520
 
package/dist/client.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import { Http, type AgentalOptions } from "./http.js";
2
2
  import { Email, Sandbox, type CreateOptions } from "./sandbox.js";
3
3
  import { Templates } from "./template.js";
4
- import type { AccountEmail, AccountExport, ApiKey, ApiKeyUsage, Billing, Headroom, HeadroomNow, HeadroomRange, Catalog, HostRoute, Invite, Me, Member, Organization, Region, AutoReload, Checkout, DataRetention, CreateApiKey, CreatedApiKey, MetricsAtMoment, Policy, Prices, RunningOverTime, SandboxSummary, SandboxJob, SandboxJobItem, SandboxJobPreview, Snapshot, Team, TeamRole, Telemetry, TelemetryTest, RunsOnRepository, RunsOnRepositories, Usage, Webhook, EgressAccount } from "./types.js";
4
+ import type { AccountEmail, AccountExport, ApiKey, ApiKeyUsage, Billing, Headroom, HeadroomNow, HeadroomRange, Catalog, HostRoute, Invite, Me, Member, Organization, Region, AutoReload, Checkout, DataRetention, CreateApiKey, CreatedApiKey, MetricsAtMoment, Policy, Prices, RunningOverTime, SandboxSummary, SandboxJob, SandboxJobItem, SandboxJobPreview, Snapshot, Team, TeamRole, Telemetry, TelemetryTest, ClaudeConnection, ClaudeSession, RunsOnRepository, RunsOnRepositories, Usage, Webhook, EgressAccount } from "./types.js";
5
5
  /** What a list of sandboxes is narrowed to. Each field left out narrows nothing; a list of values is any of them. */
6
6
  export interface SandboxFilter {
7
7
  /** Tags every sandbox has. */
@@ -406,6 +406,40 @@ export declare class Agental {
406
406
  testTelemetry(): Promise<TelemetryTest>;
407
407
  /** Removes your collector, with its headers, and nothing more is sent to it. When none is set it throws an ApiError with the status 404. */
408
408
  deleteTelemetry(): Promise<void>;
409
+ /**
410
+ * The Claude Managed Agents self-hosted environments connected to your account. Each
411
+ * session of one runs its tool calls in a sandbox of your own. Their keys and signing
412
+ * secrets are never shown. Only where policy() says managedAgents.
413
+ */
414
+ listClaudeConnections(): Promise<ClaudeConnection[]>;
415
+ /**
416
+ * Connects a self-hosted environment from the Claude Console: its id, its environment key,
417
+ * and, for a turn to start at once, its webhook's signing secret. The key and secret are
418
+ * kept sealed and never shown again, and the key never goes into a sandbox. Each session
419
+ * gets a sandbox on templateId (the account's default when left out), stopped between turns
420
+ * and deleted once it has slept keepDays (7). Set the answer's webhookUrl as the
421
+ * environment's webhook for session.status_run_started in the Claude Console.
422
+ */
423
+ connectClaude(connection: {
424
+ environmentId: string;
425
+ environmentKey: string;
426
+ webhookSecret?: string;
427
+ templateId?: string | null;
428
+ keepDays?: number;
429
+ }): Promise<ClaudeConnection>;
430
+ /** One connected environment. */
431
+ getClaudeConnection(id: string): Promise<ClaudeConnection>;
432
+ /** The sessions of a connected environment that have run here, the latest active first: each one's sandbox, whether it runs or sleeps, when a sleeping one's sandbox is deleted, and why its last turn was not served. */
433
+ listClaudeSessions(id: string): Promise<ClaudeSession[]>;
434
+ /** Changes a connection: a new key or signing secret (null forgets it), another template (null for the default), or keepDays. What is left out stays as it was. */
435
+ updateClaudeConnection(id: string, change: {
436
+ environmentKey?: string;
437
+ webhookSecret?: string | null;
438
+ templateId?: string | null;
439
+ keepDays?: number;
440
+ }): Promise<ClaudeConnection>;
441
+ /** Disconnects an environment: its key and signing secret are forgotten, and no more of its work is claimed. Its sessions' sandboxes are left as they are. */
442
+ disconnectClaude(id: string): Promise<void>;
409
443
  /**
410
444
  * GitHub Actions jobs on sandboxes: each repository's pool, how many sandboxes of each size it
411
445
  * keeps and the template they are made on. available is false where jobs do not run on
@@ -440,8 +474,10 @@ export declare class Agental {
440
474
  listWebhooks(): Promise<Webhook[]>;
441
475
  /**
442
476
  * Adds a webhook. url is posted each event it takes, and has to be on the public internet.
443
- * events names the kinds it takes, such as sandbox.stopped, or "*" for every one and any
444
- * added later, which is what it takes when events is left out. The answer holds
477
+ * events names the kinds it takes, such as sandbox.stopped or headroom.burst_ended, a group
478
+ * of them by its name and .*, such as "headroom.*", which takes the group's kinds added later
479
+ * too, or "*" for every one and any added later, which is what it takes when events is left
480
+ * out. A * anywhere else is refused. The answer holds
445
481
  * signingSecret, the one time it is given: each post's X-Agental-Signature is checked
446
482
  * against it with verifyWebhook. It is sent once, so a lost answer is not sent again.
447
483
  */
package/dist/client.js CHANGED
@@ -541,6 +541,41 @@ export class Agental {
541
541
  async deleteTelemetry() {
542
542
  await this.http.send({ method: "DELETE", path: "/v1/telemetry" });
543
543
  }
544
+ /**
545
+ * The Claude Managed Agents self-hosted environments connected to your account. Each
546
+ * session of one runs its tool calls in a sandbox of your own. Their keys and signing
547
+ * secrets are never shown. Only where policy() says managedAgents.
548
+ */
549
+ async listClaudeConnections() {
550
+ return (await this.http.json({ method: "GET", path: "/v1/claude/connections", replay: true })).body.data;
551
+ }
552
+ /**
553
+ * Connects a self-hosted environment from the Claude Console: its id, its environment key,
554
+ * and, for a turn to start at once, its webhook's signing secret. The key and secret are
555
+ * kept sealed and never shown again, and the key never goes into a sandbox. Each session
556
+ * gets a sandbox on templateId (the account's default when left out), stopped between turns
557
+ * and deleted once it has slept keepDays (7). Set the answer's webhookUrl as the
558
+ * environment's webhook for session.status_run_started in the Claude Console.
559
+ */
560
+ async connectClaude(connection) {
561
+ return (await this.http.json({ method: "POST", path: "/v1/claude/connections", body: connection })).body.connection;
562
+ }
563
+ /** One connected environment. */
564
+ async getClaudeConnection(id) {
565
+ return (await this.http.json({ method: "GET", path: `/v1/claude/connections/${encodeURIComponent(id)}`, replay: true })).body.connection;
566
+ }
567
+ /** The sessions of a connected environment that have run here, the latest active first: each one's sandbox, whether it runs or sleeps, when a sleeping one's sandbox is deleted, and why its last turn was not served. */
568
+ async listClaudeSessions(id) {
569
+ return (await this.http.json({ method: "GET", path: `/v1/claude/connections/${encodeURIComponent(id)}/sessions`, replay: true })).body.data;
570
+ }
571
+ /** Changes a connection: a new key or signing secret (null forgets it), another template (null for the default), or keepDays. What is left out stays as it was. */
572
+ async updateClaudeConnection(id, change) {
573
+ return (await this.http.json({ method: "PATCH", path: `/v1/claude/connections/${encodeURIComponent(id)}`, body: change, replay: true })).body.connection;
574
+ }
575
+ /** Disconnects an environment: its key and signing secret are forgotten, and no more of its work is claimed. Its sessions' sandboxes are left as they are. */
576
+ async disconnectClaude(id) {
577
+ await this.http.send({ method: "DELETE", path: `/v1/claude/connections/${encodeURIComponent(id)}` });
578
+ }
544
579
  /**
545
580
  * GitHub Actions jobs on sandboxes: each repository's pool, how many sandboxes of each size it
546
581
  * keeps and the template they are made on. available is false where jobs do not run on
@@ -584,8 +619,10 @@ export class Agental {
584
619
  }
585
620
  /**
586
621
  * Adds a webhook. url is posted each event it takes, and has to be on the public internet.
587
- * events names the kinds it takes, such as sandbox.stopped, or "*" for every one and any
588
- * added later, which is what it takes when events is left out. The answer holds
622
+ * events names the kinds it takes, such as sandbox.stopped or headroom.burst_ended, a group
623
+ * of them by its name and .*, such as "headroom.*", which takes the group's kinds added later
624
+ * too, or "*" for every one and any added later, which is what it takes when events is left
625
+ * out. A * anywhere else is refused. The answer holds
589
626
  * signingSecret, the one time it is given: each post's X-Agental-Signature is checked
590
627
  * against it with verifyWebhook. It is sent once, so a lost answer is not sent again.
591
628
  */
package/dist/index.d.ts CHANGED
@@ -8,5 +8,5 @@ export { 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
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, 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, RunsOnRepository, RunsOnRepositories, TemplateApplied, TemplateInfo, TemplateNetwork, TemplateSandbox, TemplateStart, TemplateSsh, Usage, Webhook, WebhookDelivery, } from "./types.js";
11
+ export type { AccountEmail, ApiKey, ApiKeyAction, ApiKeyPreset, ApiKeyUsage, Billing, BrowserState, BurstFee, BurstQuote, Headroom, HeadroomNow, HeadroomRange, HeadroomStep, Catalog, Region, AutoReload, 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";
12
12
  export { verifyWebhook } from "./webhooks.js";
package/dist/openapi.d.ts CHANGED
@@ -2715,6 +2715,54 @@ export interface paths {
2715
2715
  patch?: never;
2716
2716
  trace?: never;
2717
2717
  };
2718
+ "/v1/claude/connections": {
2719
+ parameters: {
2720
+ query?: never;
2721
+ header?: never;
2722
+ path?: never;
2723
+ cookie?: never;
2724
+ };
2725
+ get: operations["listClaudeConnections"];
2726
+ put?: never;
2727
+ post: operations["connectClaude"];
2728
+ delete?: never;
2729
+ options?: never;
2730
+ head?: never;
2731
+ patch?: never;
2732
+ trace?: never;
2733
+ };
2734
+ "/v1/claude/connections/{id}": {
2735
+ parameters: {
2736
+ query?: never;
2737
+ header?: never;
2738
+ path?: never;
2739
+ cookie?: never;
2740
+ };
2741
+ get: operations["getClaudeConnection"];
2742
+ put?: never;
2743
+ post?: never;
2744
+ delete: operations["disconnectClaude"];
2745
+ options?: never;
2746
+ head?: never;
2747
+ patch: operations["updateClaudeConnection"];
2748
+ trace?: never;
2749
+ };
2750
+ "/v1/claude/connections/{id}/sessions": {
2751
+ parameters: {
2752
+ query?: never;
2753
+ header?: never;
2754
+ path?: never;
2755
+ cookie?: never;
2756
+ };
2757
+ get: operations["listClaudeSessions"];
2758
+ put?: never;
2759
+ post?: never;
2760
+ delete?: never;
2761
+ options?: never;
2762
+ head?: never;
2763
+ patch?: never;
2764
+ trace?: never;
2765
+ };
2718
2766
  "/v1/burst": {
2719
2767
  parameters: {
2720
2768
  query?: never;
@@ -4819,6 +4867,8 @@ export interface components {
4819
4867
  hiddenVariables: boolean;
4820
4868
  /** @description Whether a sandbox's web traffic can leave through a residential address, at $3 a GB: PUT /v1/sandboxes/{id}/egress, and egress on a create or a template. GET /v1/egress says whether the account may. False, asking for it answers 501 residential_egress_unavailable. */
4821
4869
  residentialEgress: boolean;
4870
+ /** @description Whether Claude Managed Agents' self-hosted environments can be connected, so that their sessions' tool calls run in this account's sandboxes: /v1/claude/connections. False, those calls answer 501 claude_unavailable. */
4871
+ managedAgents: boolean;
4822
4872
  /** @description Whether a sandbox's CPU, memory, disk and network are read and kept: GET /v1/sandboxes/{id}/metrics and GET /v1/metrics. False, both answer 501 metrics_unavailable. GET /v1/metrics/running answers either way. */
4823
4873
  metrics: boolean;
4824
4874
  /** @description Whether an account can have its sandboxes' metrics and lifecycle events sent to a collector of its own, over OTLP/HTTP: GET, PUT and DELETE /v1/telemetry, and POST /v1/telemetry/test. Metrics are sent only where metrics is true as well. False, those calls answer 501 telemetry_unavailable. */
@@ -5469,6 +5519,100 @@ export interface components {
5469
5519
  /** @description What went wrong, or what the collector said it did not take. */
5470
5520
  message: string | null;
5471
5521
  };
5522
+ ClaudeConnection: {
5523
+ /** @example ccn_7f3a91c2d04e5b18 */
5524
+ id: string;
5525
+ /**
5526
+ * @description The self-hosted environment at Anthropic whose sessions run in this account's sandboxes.
5527
+ * @example env_01UykHXsjAbCdEfGhIjKlMnO
5528
+ */
5529
+ environmentId: string;
5530
+ /** @description The template each session's sandbox is made from. Null for the account's default template, and for a template deleted since. */
5531
+ templateId: string | null;
5532
+ /**
5533
+ * @description How many days a sleeping session's stopped sandbox is kept before it is deleted.
5534
+ * @example 7
5535
+ */
5536
+ keepDays: number;
5537
+ /** @description Whether the webhook's signing secret is kept. Without it no webhook is taken, and sessions are found by a pass every minute alone. */
5538
+ hasWebhookSecret: boolean;
5539
+ /**
5540
+ * @description The address to give the Claude Console as this environment's webhook, for session.status_run_started.
5541
+ * @example https://agental.io/v1/claude/webhook/ccn_7f3a91c2d04e5b18
5542
+ */
5543
+ webhookUrl: string;
5544
+ createdAt: string;
5545
+ updatedAt: string;
5546
+ };
5547
+ ClaudeConnectInput: {
5548
+ /**
5549
+ * @description A self-hosted environment's id from the Claude Console.
5550
+ * @example env_01UykHXsjAbCdEfGhIjKlMnO
5551
+ */
5552
+ environmentId: string;
5553
+ /**
5554
+ * @description The environment's key from the Claude Console. It is kept sealed, never shown again, and never put into a sandbox in plain.
5555
+ * @example <ENVIRONMENT_KEY>
5556
+ */
5557
+ environmentKey: string;
5558
+ /**
5559
+ * @description The webhook's signing secret from the Claude Console. Kept sealed and never shown again.
5560
+ * @example <WEBHOOK_SIGNING_SECRET>
5561
+ */
5562
+ webhookSecret?: string;
5563
+ /**
5564
+ * @description A template of this account. Left out or null, the account's default template.
5565
+ * @example tpl_97b3405a8aad303a
5566
+ */
5567
+ templateId?: string | null;
5568
+ /**
5569
+ * @description Days a sleeping session's stopped sandbox is kept: 1 to 90. 7 when left out.
5570
+ * @example 7
5571
+ */
5572
+ keepDays?: number;
5573
+ };
5574
+ ClaudeSession: {
5575
+ /** @example sesn_015kpQZQkF1Puu8vYEgsmGtY */
5576
+ sessionId: string;
5577
+ /** @description The session's sandbox, or null while one is being made. */
5578
+ sandboxId: string | null;
5579
+ /** @description The sandbox's status now, or null where it was deleted. */
5580
+ sandboxStatus: string | null;
5581
+ /**
5582
+ * @description running while its worker may be up; sleeping once its sandbox is stopped, until its next turn.
5583
+ * @enum {string}
5584
+ */
5585
+ state: "running" | "sleeping";
5586
+ /** @description When its last turn's worker was started. */
5587
+ lastTurnAt: string | null;
5588
+ lastActiveAt: string;
5589
+ /** @description When its sandbox is deleted, while it sleeps: keepDays after it went to sleep. */
5590
+ deletesAt: string | null;
5591
+ /** @description Why its last turn was not served, such as a sandbox that could not be made. Null when it was. */
5592
+ error: string | null;
5593
+ };
5594
+ ClaudeConnectionChange: {
5595
+ /**
5596
+ * @description The environment's key from the Claude Console. It is kept sealed, never shown again, and never put into a sandbox in plain.
5597
+ * @example <ENVIRONMENT_KEY>
5598
+ */
5599
+ environmentKey?: string;
5600
+ /**
5601
+ * @description A new signing secret, or null to forget it.
5602
+ * @example <WEBHOOK_SIGNING_SECRET>
5603
+ */
5604
+ webhookSecret?: string | null;
5605
+ /**
5606
+ * @description A template of this account. Left out or null, the account's default template.
5607
+ * @example tpl_97b3405a8aad303a
5608
+ */
5609
+ templateId?: string | null;
5610
+ /**
5611
+ * @description Days a sleeping session's stopped sandbox is kept: 1 to 90. 7 when left out.
5612
+ * @example 7
5613
+ */
5614
+ keepDays?: number;
5615
+ };
5472
5616
  Burst: {
5473
5617
  /** @description Whether the account is held to its plan: a start past the running count is refused, and a fast one costs a fee. False: what it starts is only measured. */
5474
5618
  enforced: boolean;
@@ -11428,10 +11572,11 @@ export interface operations {
11428
11572
  */
11429
11573
  url: string;
11430
11574
  /**
11431
- * @description What to send: sandbox.created, sandbox.started, sandbox.stopped, sandbox.archived, sandbox.error, sandbox.moved, sandbox.deleted, sandbox.auto_stop_set, sandbox.labels_changed, prompt.created, template.created, template.updated, template.secrets_changed (named, never with a value), template.labels_changed and template.deleted, or * for all of them, which is what is sent when this is left out. Each event has the same id in every webhook it is sent to, and a sandbox.* event in the log record a collector set with PUT /v1/telemetry is sent.
11575
+ * @description What to send: sandbox.created, sandbox.started, sandbox.stopped, sandbox.archived, sandbox.error, sandbox.moved, sandbox.deleted, sandbox.auto_stop_set, sandbox.labels_changed, sandbox.scheduled_run, sandbox.schedule_paused, sandbox.low_cpu, prompt.created, email.received, email.delivered, email.bounced, member.invited, member.joined, member.removed, member.role_changed, key.revoked, template.created, template.updated, template.secrets_changed (named, never with a value), template.labels_changed, template.deleted, and Headroom's headroom.burst_started, headroom.burst_ended, headroom.refused, headroom.running_count_reached, headroom.budget_threshold and headroom.budget_reached, which are the organization's and about no sandbox. A group by its name and .*, as headroom.* or sandbox.*, is every event of the group and any added to it later; * alone is every event, which is what is sent when this is left out. A * anywhere else is refused. Each event has the same id in every webhook it is sent to, and a sandbox.* or headroom.* event is sent as a log record to the collector set with PUT /v1/telemetry.
11432
11576
  * @example [
11433
11577
  * "sandbox.created",
11434
- * "sandbox.error"
11578
+ * "sandbox.error",
11579
+ * "headroom.*"
11435
11580
  * ]
11436
11581
  */
11437
11582
  events?: string[];
@@ -11625,10 +11770,11 @@ export interface operations {
11625
11770
  */
11626
11771
  url?: string;
11627
11772
  /**
11628
- * @description What to send: sandbox.created, sandbox.started, sandbox.stopped, sandbox.archived, sandbox.error, sandbox.moved, sandbox.deleted, sandbox.auto_stop_set, sandbox.labels_changed, prompt.created, template.created, template.updated, template.secrets_changed (named, never with a value), template.labels_changed and template.deleted, or * for all of them, which is what is sent when this is left out. Each event has the same id in every webhook it is sent to, and a sandbox.* event in the log record a collector set with PUT /v1/telemetry is sent.
11773
+ * @description What to send: sandbox.created, sandbox.started, sandbox.stopped, sandbox.archived, sandbox.error, sandbox.moved, sandbox.deleted, sandbox.auto_stop_set, sandbox.labels_changed, sandbox.scheduled_run, sandbox.schedule_paused, sandbox.low_cpu, prompt.created, email.received, email.delivered, email.bounced, member.invited, member.joined, member.removed, member.role_changed, key.revoked, template.created, template.updated, template.secrets_changed (named, never with a value), template.labels_changed, template.deleted, and Headroom's headroom.burst_started, headroom.burst_ended, headroom.refused, headroom.running_count_reached, headroom.budget_threshold and headroom.budget_reached, which are the organization's and about no sandbox. A group by its name and .*, as headroom.* or sandbox.*, is every event of the group and any added to it later; * alone is every event, which is what is sent when this is left out. A * anywhere else is refused. Each event has the same id in every webhook it is sent to, and a sandbox.* or headroom.* event is sent as a log record to the collector set with PUT /v1/telemetry.
11629
11774
  * @example [
11630
11775
  * "sandbox.created",
11631
- * "sandbox.error"
11776
+ * "sandbox.error",
11777
+ * "headroom.*"
11632
11778
  * ]
11633
11779
  */
11634
11780
  events?: string[];
@@ -17982,6 +18128,357 @@ export interface operations {
17982
18128
  };
17983
18129
  };
17984
18130
  };
18131
+ listClaudeConnections: {
18132
+ parameters: {
18133
+ query?: never;
18134
+ header?: never;
18135
+ path?: never;
18136
+ cookie?: never;
18137
+ };
18138
+ requestBody?: never;
18139
+ responses: {
18140
+ /** @description The account's connected environments. Their keys and signing secrets are never shown. */
18141
+ 200: {
18142
+ headers: {
18143
+ [name: string]: unknown;
18144
+ };
18145
+ content: {
18146
+ "application/json": {
18147
+ data: components["schemas"]["ClaudeConnection"][];
18148
+ };
18149
+ };
18150
+ };
18151
+ /** @description Missing or invalid API key. */
18152
+ 401: {
18153
+ headers: {
18154
+ [name: string]: unknown;
18155
+ };
18156
+ content: {
18157
+ "application/json": components["schemas"]["Error"];
18158
+ };
18159
+ };
18160
+ /** @description claude_unavailable: Claude Managed Agents are not served here. GET /v1/policy says so as managedAgents. */
18161
+ 501: {
18162
+ headers: {
18163
+ [name: string]: unknown;
18164
+ };
18165
+ content: {
18166
+ "application/json": components["schemas"]["Error"];
18167
+ };
18168
+ };
18169
+ };
18170
+ };
18171
+ connectClaude: {
18172
+ parameters: {
18173
+ query?: never;
18174
+ header?: never;
18175
+ path?: never;
18176
+ cookie?: never;
18177
+ };
18178
+ requestBody: {
18179
+ content: {
18180
+ "application/json": components["schemas"]["ClaudeConnectInput"];
18181
+ };
18182
+ };
18183
+ responses: {
18184
+ /** @description The environment is connected. Set webhookUrl as its webhook in the Claude Console, with session.status_run_started, and give its signing secret here. The key is not tried now: a key Anthropic refuses is said on the connection once its work is claimed. */
18185
+ 201: {
18186
+ headers: {
18187
+ [name: string]: unknown;
18188
+ };
18189
+ content: {
18190
+ "application/json": {
18191
+ connection: components["schemas"]["ClaudeConnection"];
18192
+ };
18193
+ };
18194
+ };
18195
+ /** @description invalid_request: the environment's id, its key, the signing secret or keepDays is not of the shape it should be. template_required: the key is limited to templates, the default is not one of them, and no templateId was sent. */
18196
+ 400: {
18197
+ headers: {
18198
+ [name: string]: unknown;
18199
+ };
18200
+ content: {
18201
+ "application/json": components["schemas"]["Error"];
18202
+ };
18203
+ };
18204
+ /** @description Missing or invalid API key. */
18205
+ 401: {
18206
+ headers: {
18207
+ [name: string]: unknown;
18208
+ };
18209
+ content: {
18210
+ "application/json": components["schemas"]["Error"];
18211
+ };
18212
+ };
18213
+ /** @description role_required: in a team, only an owner or an admin connects an environment. key_action_forbidden: the key may not sandbox.create. */
18214
+ 403: {
18215
+ headers: {
18216
+ [name: string]: unknown;
18217
+ };
18218
+ content: {
18219
+ "application/json": components["schemas"]["Error"];
18220
+ };
18221
+ };
18222
+ /** @description template_not_found: no template of this account has that id, or the key does not reach it. */
18223
+ 404: {
18224
+ headers: {
18225
+ [name: string]: unknown;
18226
+ };
18227
+ content: {
18228
+ "application/json": components["schemas"]["Error"];
18229
+ };
18230
+ };
18231
+ /** @description environment_connected: this account has connected the environment already. connection_limit_reached: the account has 20 connections. */
18232
+ 409: {
18233
+ headers: {
18234
+ [name: string]: unknown;
18235
+ };
18236
+ content: {
18237
+ "application/json": components["schemas"]["Error"];
18238
+ };
18239
+ };
18240
+ /** @description claude_unavailable: Claude Managed Agents are not served here. GET /v1/policy says so as managedAgents. */
18241
+ 501: {
18242
+ headers: {
18243
+ [name: string]: unknown;
18244
+ };
18245
+ content: {
18246
+ "application/json": components["schemas"]["Error"];
18247
+ };
18248
+ };
18249
+ };
18250
+ };
18251
+ getClaudeConnection: {
18252
+ parameters: {
18253
+ query?: never;
18254
+ header?: never;
18255
+ path: {
18256
+ id: string;
18257
+ };
18258
+ cookie?: never;
18259
+ };
18260
+ requestBody?: never;
18261
+ responses: {
18262
+ /** @description The connection. */
18263
+ 200: {
18264
+ headers: {
18265
+ [name: string]: unknown;
18266
+ };
18267
+ content: {
18268
+ "application/json": {
18269
+ connection: components["schemas"]["ClaudeConnection"];
18270
+ };
18271
+ };
18272
+ };
18273
+ /** @description Missing or invalid API key. */
18274
+ 401: {
18275
+ headers: {
18276
+ [name: string]: unknown;
18277
+ };
18278
+ content: {
18279
+ "application/json": components["schemas"]["Error"];
18280
+ };
18281
+ };
18282
+ /** @description not_found: no connection of this account has that id. */
18283
+ 404: {
18284
+ headers: {
18285
+ [name: string]: unknown;
18286
+ };
18287
+ content: {
18288
+ "application/json": components["schemas"]["Error"];
18289
+ };
18290
+ };
18291
+ /** @description claude_unavailable: Claude Managed Agents are not served here. GET /v1/policy says so as managedAgents. */
18292
+ 501: {
18293
+ headers: {
18294
+ [name: string]: unknown;
18295
+ };
18296
+ content: {
18297
+ "application/json": components["schemas"]["Error"];
18298
+ };
18299
+ };
18300
+ };
18301
+ };
18302
+ disconnectClaude: {
18303
+ parameters: {
18304
+ query?: never;
18305
+ header?: never;
18306
+ path: {
18307
+ id: string;
18308
+ };
18309
+ cookie?: never;
18310
+ };
18311
+ requestBody?: never;
18312
+ responses: {
18313
+ /** @description The environment is disconnected, and its key and signing secret are forgotten. Its sessions' sandboxes are left as they are. */
18314
+ 204: {
18315
+ headers: {
18316
+ [name: string]: unknown;
18317
+ };
18318
+ content?: never;
18319
+ };
18320
+ /** @description Missing or invalid API key. */
18321
+ 401: {
18322
+ headers: {
18323
+ [name: string]: unknown;
18324
+ };
18325
+ content: {
18326
+ "application/json": components["schemas"]["Error"];
18327
+ };
18328
+ };
18329
+ /** @description role_required: in a team, only an owner or an admin disconnects an environment. */
18330
+ 403: {
18331
+ headers: {
18332
+ [name: string]: unknown;
18333
+ };
18334
+ content: {
18335
+ "application/json": components["schemas"]["Error"];
18336
+ };
18337
+ };
18338
+ /** @description not_found: no connection of this account has that id. */
18339
+ 404: {
18340
+ headers: {
18341
+ [name: string]: unknown;
18342
+ };
18343
+ content: {
18344
+ "application/json": components["schemas"]["Error"];
18345
+ };
18346
+ };
18347
+ /** @description claude_unavailable: Claude Managed Agents are not served here. GET /v1/policy says so as managedAgents. */
18348
+ 501: {
18349
+ headers: {
18350
+ [name: string]: unknown;
18351
+ };
18352
+ content: {
18353
+ "application/json": components["schemas"]["Error"];
18354
+ };
18355
+ };
18356
+ };
18357
+ };
18358
+ updateClaudeConnection: {
18359
+ parameters: {
18360
+ query?: never;
18361
+ header?: never;
18362
+ path: {
18363
+ id: string;
18364
+ };
18365
+ cookie?: never;
18366
+ };
18367
+ requestBody: {
18368
+ content: {
18369
+ "application/json": components["schemas"]["ClaudeConnectionChange"];
18370
+ };
18371
+ };
18372
+ responses: {
18373
+ /** @description The connection, changed: a new key or signing secret, another template, or another keepDays. What is left out stays as it was. */
18374
+ 200: {
18375
+ headers: {
18376
+ [name: string]: unknown;
18377
+ };
18378
+ content: {
18379
+ "application/json": {
18380
+ connection: components["schemas"]["ClaudeConnection"];
18381
+ };
18382
+ };
18383
+ };
18384
+ /** @description invalid_request: the key, the signing secret or keepDays is not of the shape it should be. template_required: templateId is null, the key is limited to templates, and the default is not one of them. */
18385
+ 400: {
18386
+ headers: {
18387
+ [name: string]: unknown;
18388
+ };
18389
+ content: {
18390
+ "application/json": components["schemas"]["Error"];
18391
+ };
18392
+ };
18393
+ /** @description Missing or invalid API key. */
18394
+ 401: {
18395
+ headers: {
18396
+ [name: string]: unknown;
18397
+ };
18398
+ content: {
18399
+ "application/json": components["schemas"]["Error"];
18400
+ };
18401
+ };
18402
+ /** @description role_required: in a team, only an owner or an admin changes a connection. key_action_forbidden: the key may not sandbox.create. */
18403
+ 403: {
18404
+ headers: {
18405
+ [name: string]: unknown;
18406
+ };
18407
+ content: {
18408
+ "application/json": components["schemas"]["Error"];
18409
+ };
18410
+ };
18411
+ /** @description not_found: no connection of this account has that id. template_not_found: no template of this account has that id, or the key does not reach it. */
18412
+ 404: {
18413
+ headers: {
18414
+ [name: string]: unknown;
18415
+ };
18416
+ content: {
18417
+ "application/json": components["schemas"]["Error"];
18418
+ };
18419
+ };
18420
+ /** @description claude_unavailable: Claude Managed Agents are not served here. GET /v1/policy says so as managedAgents. */
18421
+ 501: {
18422
+ headers: {
18423
+ [name: string]: unknown;
18424
+ };
18425
+ content: {
18426
+ "application/json": components["schemas"]["Error"];
18427
+ };
18428
+ };
18429
+ };
18430
+ };
18431
+ listClaudeSessions: {
18432
+ parameters: {
18433
+ query?: never;
18434
+ header?: never;
18435
+ path: {
18436
+ id: string;
18437
+ };
18438
+ cookie?: never;
18439
+ };
18440
+ requestBody?: never;
18441
+ responses: {
18442
+ /** @description The sessions of this environment that have run here, the latest active first, at most 200: each one's sandbox, whether it runs or sleeps, and why its last turn was not served, where it was not. */
18443
+ 200: {
18444
+ headers: {
18445
+ [name: string]: unknown;
18446
+ };
18447
+ content: {
18448
+ "application/json": {
18449
+ data: components["schemas"]["ClaudeSession"][];
18450
+ };
18451
+ };
18452
+ };
18453
+ /** @description Missing or invalid API key. */
18454
+ 401: {
18455
+ headers: {
18456
+ [name: string]: unknown;
18457
+ };
18458
+ content: {
18459
+ "application/json": components["schemas"]["Error"];
18460
+ };
18461
+ };
18462
+ /** @description not_found: no connection of this account has that id. */
18463
+ 404: {
18464
+ headers: {
18465
+ [name: string]: unknown;
18466
+ };
18467
+ content: {
18468
+ "application/json": components["schemas"]["Error"];
18469
+ };
18470
+ };
18471
+ /** @description claude_unavailable: Claude Managed Agents are not served here. GET /v1/policy says so as managedAgents. */
18472
+ 501: {
18473
+ headers: {
18474
+ [name: string]: unknown;
18475
+ };
18476
+ content: {
18477
+ "application/json": components["schemas"]["Error"];
18478
+ };
18479
+ };
18480
+ };
18481
+ };
17985
18482
  getBurst: {
17986
18483
  parameters: {
17987
18484
  query?: {
package/dist/types.d.ts CHANGED
@@ -149,6 +149,10 @@ export type DataRetention = Schemas["DataRetention"];
149
149
  export type AccountExport = Schemas["AccountExport"];
150
150
  /** What your collector answered one empty export. */
151
151
  export type TelemetryTest = Schemas["TelemetryTest"];
152
+ /** A Claude Managed Agents self-hosted environment connected to your account: its sessions' tool calls run in your sandboxes. Its key and signing secret are never shown. */
153
+ export type ClaudeConnection = Schemas["ClaudeConnection"];
154
+ /** A session of a connected environment that has run here: its sandbox, whether it runs or sleeps, and why its last turn was not served. */
155
+ export type ClaudeSession = Schemas["ClaudeSession"];
152
156
  /** A repository's runs-on pool: how many sandboxes of each size it keeps, the template they are made on, and the ones it has. */
153
157
  export type RunsOnRepository = Schemas["RunsOnRepository"];
154
158
  /** Each repository's runs-on pool, and the size a pool keeps where none was set. */
package/dist/version.d.ts CHANGED
@@ -1,2 +1,2 @@
1
1
  /** This package's version, as package.json says it. A test holds the two to the same. */
2
- export declare const VERSION = "0.5.0";
2
+ export declare const VERSION = "0.6.0";
package/dist/version.js CHANGED
@@ -1,2 +1,2 @@
1
1
  /** This package's version, as package.json says it. A test holds the two to the same. */
2
- export const VERSION = "0.5.0";
2
+ export const VERSION = "0.6.0";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agental-sdk",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "description": "TypeScript SDK for agental.io: Linux sandboxes for your agents. The agental command is the package agental.",
5
5
  "license": "MIT",
6
6
  "author": "VERTIXER LTD",