@tangle-network/sandbox 0.1.2 → 0.2.1

package/dist/errors-BI75IXOM.d.ts

@@ -0,0 +1,1177 @@
+import { $ as FleetExecDispatchOptions, A as CreateIntelligenceReportOptions, An as SandboxFleetWorkspaceReconcileResult, Bt as PromptResult, C as BatchResult, Cn as SandboxFleetToken, Dn as SandboxFleetTraceOptions, G as ExecOptions, Gt as PublicTemplateInfo, Jn as SecretsManager, Jt as PublishPublicTemplateVersionOptions, K as ExecResult, Kt as PublicTemplateVersionInfo, M as CreateSandboxFleetTokenOptions, Mn as SandboxFleetWorkspaceSnapshotResult, N as CreateSandboxFleetWithCoordinatorOptions, Nn as SandboxInfo, On as SandboxFleetUsage, P as CreateSandboxOptions, Q as FleetDispatchStreamOptions, Qt as ReconcileSandboxFleetsResult, Rt as PromptInputPart, S as BatchOptions, X as FleetDispatchResultBuffer, Xt as ReapExpiredSandboxFleetsResult, Y as FleetDispatchCancelResult, Yt as ReapExpiredSandboxFleetsOptions, Z as FleetDispatchResultBufferOptions, Zt as ReconcileSandboxFleetsOptions, _n as SandboxFleetMachineRecord, _r as UsageInfo, a as TraceExportSink, bt as ListSandboxFleetOptions, cn as SandboxFleetCostEstimate, dn as SandboxFleetDriverCapability, et as FleetExecDispatchResult, fr as TokenRefreshHandler, gt as IntelligenceReportCompareTo, ht as IntelligenceReportBudget, i as TraceExportResult, in as SandboxEnvironment, ir as SubscriptionInfo, j as CreateSandboxFleetOptions, jn as SandboxFleetWorkspaceRestoreResult, m as AttachSandboxFleetMachineOptions, mt as IntelligenceReport, n as SandboxInstance, nn as SandboxClientConfig, nr as SshKeysManager, nt as FleetPromptDispatchOptions, on as SandboxFleetArtifact, pn as SandboxFleetInfo, qt as PublishPublicTemplateOptions, rt as FleetPromptDispatchResult, sn as SandboxFleetArtifactSpec, t as HttpClient, tt as FleetMachineId, un as SandboxFleetDispatchResponse, vt as IntelligenceReportWindow, w as BatchTask, wn as SandboxFleetTraceBundle, x as BatchEvent, xn as SandboxFleetOperationsSummary, xt as ListSandboxOptions, yn as SandboxFleetManifest, zt as PromptOptions } from "./sandbox-aBpWqler.js";
+
+//#region src/lib/sse-parser.d.ts
+/**
+ * SSE Stream Parser
+ *
+ * EventSource stream parsing for SDK consumers. Implements the
+ * subset of the SSE spec (§9.2.6) that the platform actually emits —
+ * LF and CRLF terminators, `event:` / `data:` / `id:` fields, and
+ * multi-line `data:` dispatch. Used by `SandboxClient.streamBatch`
+ * and by the web dashboard's batch page; exported so downstream
+ * surfaces don't maintain their own copies.
+ *
+ * Guarantees:
+ *   - Correctly buffers frames that straddle chunk boundaries.
+ *   - Accepts LF- and CRLF-terminated streams interchangeably.
+ *   - Joins multi-line `data:` per the spec (dispatch joins with
+ *     "\n" before JSON parse).
+ *   - Defaults event type to `"message"` when a frame carries
+ *     `data:` but no `event:` field (SSE spec §9.2.6 step 3).
+ *   - Surfaces optional `id:` so callers can implement reconnection.
+ *   - Flushes a dangling event when the stream closes without a
+ *     terminating blank line (well-behaved servers emit `\n\n`, but
+ *     some close early).
+ *   - Throws `AbortError` when the caller-supplied signal fires, so
+ *     consumers can distinguish "ran to completion" from "cancelled"
+ *     without peeking at signal state.
+ *   - Silently drops frames with malformed JSON — the stream remains
+ *     usable and only the individual frame is lost.
+ *
+ * What it does NOT do:
+ *   - CR-only (legacy Mac) line terminators. No known emitter uses
+ *     them; supporting them would risk splitting payloads that
+ *     legitimately contain CR.
+ *   - Retry/reconnect (caller's responsibility).
+ *   - Event-type filtering (caller's responsibility).
+ */
+interface ParsedSSEEvent {
+  /** Event type from the `event:` field, e.g. `task.completed`. */
+  type: string;
+  /** Parsed JSON payload from joined `data:` lines. */
+  data: Record<string, unknown>;
+  /** Optional `id:` field if the server emitted one. */
+  id?: string;
+}
+interface ParseSSEStreamOptions {
+  /**
+   * Signal to abort the stream. When aborted, the generator throws
+   * `AbortError` — this is a deliberate departure from silent-return
+   * semantics so the consumer's for-await loop propagates the abort
+   * to its own catch block instead of looking like a clean finish.
+   */
+  signal?: AbortSignal;
+}
+/**
+ * Parse a streaming SSE response body into an async iterable of
+ * structured events.
+ *
+ * @throws `TypeError` when the response has no body.
+ * @throws `DOMException` with `name === "AbortError"` on cancellation.
+ */
+declare function parseSSEStream(body: ReadableStream<Uint8Array> | null | undefined, options?: ParseSSEStreamOptions): AsyncGenerator<ParsedSSEEvent>;
+//#endregion
+//#region src/fleet.d.ts
+/**
+ * The subset of `SandboxClient` the fleet classes drive. Declared here
+ * rather than importing the concrete class so `fleet.ts` stays a leaf of
+ * `client.ts` — `client.ts` constructs `SandboxFleetClient`, so the reverse
+ * import would form a cycle. `SandboxClient` satisfies this structurally.
+ */
+interface FleetClientHost {
+  create(options?: CreateSandboxOptions): Promise<SandboxInstance>;
+  list(options?: ListSandboxOptions): Promise<SandboxInstance[]>;
+  get(id: string): Promise<SandboxInstance | null>;
+  fetch(path: string, options?: RequestInit): Promise<Response>;
+  readonly fleets: SandboxFleetClient;
+  readonly intelligence: {
+    createReport(options: CreateIntelligenceReportOptions): Promise<IntelligenceReport>;
+  };
+}
+declare class SandboxFleet {
+  private readonly client;
+  readonly fleetId: string;
+  readonly machines: ReadonlyMap<FleetMachineId, SandboxInfo>;
+  constructor(client: FleetClientHost, fleetId: string, machines: ReadonlyMap<FleetMachineId, SandboxInfo>);
+  get ids(): FleetMachineId[];
+  get(machineId: FleetMachineId): SandboxInfo;
+  sandbox(machineId: FleetMachineId): Promise<SandboxInstance>;
+  collectArtifacts(artifacts: readonly SandboxFleetArtifactSpec[]): Promise<SandboxFleetArtifact[]>;
+  exec(machineId: FleetMachineId, command: string, options?: ExecOptions): Promise<ExecResult>;
+  dispatchExec(command: string, options?: FleetExecDispatchOptions): Promise<FleetExecDispatchResult[]>;
+  dispatchExecDetailed(command: string, options?: FleetExecDispatchOptions): Promise<SandboxFleetDispatchResponse<FleetExecDispatchResult>>;
+  prompt(machineId: FleetMachineId, message: string | PromptInputPart[], options?: PromptOptions): Promise<PromptResult>;
+  dispatchPrompt(message: string | PromptInputPart[], options?: FleetPromptDispatchOptions): Promise<FleetPromptDispatchResult[]>;
+  dispatchPromptDetailed(message: string | PromptInputPart[], options?: FleetPromptDispatchOptions): Promise<SandboxFleetDispatchResponse<FleetPromptDispatchResult>>;
+  manifest(): Promise<SandboxFleetManifest>;
+  attachMachine(machine: AttachSandboxFleetMachineOptions): Promise<SandboxFleetMachineRecord>;
+  detachMachine(machineId: FleetMachineId): Promise<{
+    success: boolean;
+  }>;
+  dispatchResults<T = FleetExecDispatchResult | FleetPromptDispatchResult>(dispatchId: string, options?: FleetDispatchResultBufferOptions): Promise<FleetDispatchResultBuffer<T>>;
+  cancelDispatch(dispatchId: string, reason?: string): Promise<FleetDispatchCancelResult>;
+  createWorkspaceSnapshot(): Promise<SandboxFleetWorkspaceSnapshotResult>;
+  restoreWorkspaceSnapshot(snapshotId: string): Promise<SandboxFleetWorkspaceRestoreResult>;
+  reconcileWorkspace(): Promise<SandboxFleetWorkspaceReconcileResult>;
+  dispatchExecStream(command: string, options?: FleetExecDispatchOptions & FleetDispatchStreamOptions): AsyncGenerator<ParsedSSEEvent, any, any>;
+  dispatchPromptStream(message: string | PromptInputPart[], options?: FleetPromptDispatchOptions & FleetDispatchStreamOptions): AsyncGenerator<ParsedSSEEvent, any, any>;
+  delete(options?: {
+    continueOnError?: boolean;
+  }): Promise<void>;
+  usage(): Promise<SandboxFleetUsage>;
+  trace(options?: SandboxFleetTraceOptions): Promise<SandboxFleetTraceBundle>;
+  intelligence(): Promise<NonNullable<SandboxFleetTraceBundle["intelligence"]>>;
+  createIntelligenceReport(options?: {
+    mode?: "deterministic" | "agentic";
+    acknowledgeCost?: boolean;
+    budget?: IntelligenceReportBudget;
+    metadata?: Record<string, unknown>; /** Narrow the analysis to a single dispatch within this fleet. */
+    dispatchId?: string; /** Bound the analysis to a time window. */
+    window?: IntelligenceReportWindow; /** Compare this fleet against a same-type baseline fleet. */
+    compareTo?: IntelligenceReportCompareTo;
+  }): Promise<IntelligenceReport>;
+  createAgenticIntelligenceReport(options: {
+    maxUsd: number;
+    metadata?: Record<string, unknown>;
+    dispatchId?: string;
+    window?: IntelligenceReportWindow;
+    compareTo?: IntelligenceReportCompareTo;
+  }): Promise<IntelligenceReport>;
+  exportTrace(sink: TraceExportSink): Promise<TraceExportResult>;
+  cost(): Promise<SandboxFleetCostEstimate>;
+  createToken(options?: CreateSandboxFleetTokenOptions): Promise<SandboxFleetToken>;
+  private requireSandbox;
+}
+declare class SandboxFleetClient {
+  private readonly client;
+  constructor(client: FleetClientHost);
+  capabilities(): Promise<{
+    drivers: SandboxFleetDriverCapability[];
+  }>;
+  operations(): Promise<SandboxFleetOperationsSummary>;
+  reconcile(options?: ReconcileSandboxFleetsOptions): Promise<ReconcileSandboxFleetsResult>;
+  estimateCost(options: Pick<CreateSandboxFleetOptions, "defaults" | "machines" | "policy" | "maxConcurrentCreates">): Promise<SandboxFleetCostEstimate>;
+  create(options: CreateSandboxFleetOptions): Promise<SandboxFleet>;
+  createWithCoordinator(options: CreateSandboxFleetWithCoordinatorOptions): Promise<SandboxFleet>;
+  private createMachine;
+  list(options: ListSandboxFleetOptions): Promise<SandboxFleet>;
+  delete(fleetId: string, options?: Omit<ListSandboxFleetOptions, "fleetId"> & {
+    continueOnError?: boolean;
+  }): Promise<void>;
+  fromInfo(info: SandboxFleetInfo): SandboxFleet;
+  private persistFleet;
+  private getServerFleet;
+  deleteRecord(fleetId: string): Promise<void>;
+  usage(fleetId: string): Promise<SandboxFleetUsage>;
+  trace(fleetId: string, options?: SandboxFleetTraceOptions): Promise<SandboxFleetTraceBundle>;
+  intelligence(fleetId: string): Promise<NonNullable<SandboxFleetTraceBundle["intelligence"]>>;
+  createIntelligenceReport(fleetId: string, options?: {
+    mode?: "deterministic" | "agentic";
+    acknowledgeCost?: boolean;
+    budget?: IntelligenceReportBudget;
+    metadata?: Record<string, unknown>;
+  }): Promise<IntelligenceReport>;
+  createAgenticIntelligenceReport(fleetId: string, options: {
+    maxUsd: number;
+    metadata?: Record<string, unknown>;
+  }): Promise<IntelligenceReport>;
+  exportTrace(fleetId: string, sink: TraceExportSink): Promise<TraceExportResult>;
+  cost(fleetId: string): Promise<SandboxFleetCostEstimate>;
+  createToken(fleetId: string, options?: CreateSandboxFleetTokenOptions): Promise<SandboxFleetToken>;
+  manifest(fleetId: string): Promise<SandboxFleetManifest>;
+  attachMachine(fleetId: string, machine: AttachSandboxFleetMachineOptions): Promise<SandboxFleetMachineRecord>;
+  detachMachine(fleetId: string, machineId: FleetMachineId): Promise<{
+    success: boolean;
+  }>;
+  dispatchResults<T = FleetExecDispatchResult | FleetPromptDispatchResult>(fleetId: string, dispatchId: string, options?: FleetDispatchResultBufferOptions): Promise<FleetDispatchResultBuffer<T>>;
+  cancelDispatch(fleetId: string, dispatchId: string, reason?: string): Promise<FleetDispatchCancelResult>;
+  createWorkspaceSnapshot(fleetId: string): Promise<SandboxFleetWorkspaceSnapshotResult>;
+  restoreWorkspaceSnapshot(fleetId: string, snapshotId: string): Promise<SandboxFleetWorkspaceRestoreResult>;
+  reconcileWorkspace(fleetId: string): Promise<SandboxFleetWorkspaceReconcileResult>;
+  dispatchExecStream(fleetId: string, command: string, options?: FleetExecDispatchOptions & FleetDispatchStreamOptions): AsyncGenerator<ParsedSSEEvent>;
+  dispatchPromptStream(fleetId: string, message: string | PromptInputPart[], options?: FleetPromptDispatchOptions & FleetDispatchStreamOptions): AsyncGenerator<ParsedSSEEvent>;
+  reapExpired(options?: ReapExpiredSandboxFleetsOptions): Promise<ReapExpiredSandboxFleetsResult>;
+  private hydrateServerFleet;
+  private listBySandboxMetadata;
+}
+//#endregion
+//#region src/integrations.d.ts
+type IntegrationPrincipalType = "customer" | "team";
+type IntegrationProvider = "generic" | "github" | "generic_oauth2";
+type IntegrationVerificationKind = "none" | "hmac_shared_secret" | "provider:github";
+type IntegrationActionKind = "sandbox.create" | "sandbox.dispatch" | "sandbox.event" | "sandbox.respond_inline";
+type IntegrationDeliveryStatus = "pending" | "delivered" | "failed" | "disabled";
+/**
+ * Opaque JSON value flowing through an integration. Tied to whichever
+ * trigger/endpoint shape is on the wire — the SDK doesn't introspect
+ * it. Aliased instead of using bare `unknown` so call sites read as
+ * "this came from JSON" rather than "this is genuinely any type".
+ */
+type IntegrationJsonValue = unknown;
+interface IntegrationAction {
+  kind: IntegrationActionKind;
+  config: IntegrationJsonValue;
+  mappings?: Record<string, string>;
+}
+interface IntegrationScope {
+  sandboxIds?: string[];
+  sessionIds?: string[];
+  teamId?: string;
+}
+interface ConnectionInfo {
+  id: string;
+  ownerType: IntegrationPrincipalType;
+  ownerId: string;
+  provider: IntegrationProvider;
+  externalId: string;
+  displayName: string | null;
+  authKind: "oauth2" | "api_key" | "signing_only";
+  metadata: Record<string, unknown> | null;
+  status: "active" | "revoked" | "error";
+  installedAt: string;
+}
+interface AutomationInfo {
+  id: string;
+  ownerType: IntegrationPrincipalType;
+  ownerId: string;
+  connectionId: string | null;
+  name: string;
+  description: string | null;
+  recipeId: string | null;
+  enabled: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+interface EndpointInfo {
+  id: string;
+  automationId: string | null;
+  ownerType: IntegrationPrincipalType;
+  ownerId: string;
+  connectionId: string | null;
+  url: string | null;
+  events: string[];
+  scope: IntegrationScope | null;
+  description: string | null;
+  enabled: boolean;
+  ephemeralForSandboxId: string | null;
+  consecutiveFailures: number;
+  disabledReason: string | null;
+  disabledAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+interface EndpointWithSecret extends EndpointInfo {
+  /** Returned only at create / rotate. Save it on your end. */
+  secret: string;
+}
+interface TriggerInfo {
+  id: string;
+  automationId: string | null;
+  ownerType: IntegrationPrincipalType;
+  ownerId: string;
+  connectionId: string | null;
+  urlToken: string;
+  /** Public URL the third party POSTs to. */
+  publicUrl: string;
+  verificationKind: IntegrationVerificationKind;
+  eventFilter: Record<string, unknown> | null;
+  action: IntegrationAction;
+  rateLimitRpm: number;
+  allowIps: string[] | null;
+  description: string | null;
+  enabled: boolean;
+  ephemeralForSandboxId: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+interface TriggerWithSecret extends TriggerInfo {
+  /** Returned only at create. Null when verificationKind === "none". */
+  secret: string | null;
+}
+interface DeliveryAttempt {
+  id: string;
+  endpointId: string;
+  automationId: string | null;
+  type: string;
+  payload: IntegrationJsonValue;
+  status: IntegrationDeliveryStatus;
+  attempts: number;
+  lastAttemptAt: string | null;
+  nextAttemptAt: string | null;
+  lastResponseStatus: number | null;
+  lastResponseBodyExcerpt: string | null;
+  createdAt: string;
+  deliveredAt: string | null;
+}
+interface TriggerRun {
+  id: string;
+  triggerId: string;
+  automationId: string | null;
+  requestId: string;
+  requestHeaders: Record<string, string>;
+  requestBody: string;
+  requestIp: string | null;
+  verificationStatus: "ok" | "bad_signature" | "expired" | "filtered_out" | "rate_limited";
+  actionStatus: "queued" | "running" | "succeeded" | "failed" | "rate_limited" | "skipped";
+  actionResult: Record<string, unknown> | null;
+  errorMessage: string | null;
+  createdAt: string;
+  completedAt: string | null;
+}
+interface RecipeManifest {
+  id: string;
+  title: string;
+  description: string;
+  icon?: string;
+  requiresConnection?: IntegrationProvider;
+  userInputs?: Array<{
+    key: string;
+    label: string;
+    type?: "text" | "select";
+    default?: string;
+    options?: string[];
+    required?: boolean;
+  }>;
+  automation: {
+    name: string;
+    description?: string;
+  };
+}
+interface CreateAutomationInput {
+  teamId?: string;
+  name: string;
+  description?: string;
+  connectionId?: string;
+  recipeId?: string;
+  enabled?: boolean;
+  triggers?: Array<{
+    verificationKind: IntegrationVerificationKind;
+    connectionId?: string;
+    eventFilter?: Record<string, unknown>;
+    action: IntegrationAction;
+    rateLimitRpm?: number;
+    allowIps?: string[];
+    description?: string;
+  }>;
+  endpoints?: Array<{
+    url?: string;
+    connectionId?: string;
+    events: string[];
+    scope?: IntegrationScope;
+    description?: string;
+  }>;
+}
+interface CreateEndpointInput {
+  teamId?: string;
+  automationId?: string;
+  connectionId?: string;
+  url?: string;
+  events: string[];
+  scope?: IntegrationScope;
+  description?: string;
+}
+interface CreateTriggerInput {
+  teamId?: string;
+  automationId?: string;
+  connectionId?: string;
+  verificationKind: IntegrationVerificationKind;
+  eventFilter?: Record<string, unknown>;
+  action: IntegrationAction;
+  rateLimitRpm?: number;
+  allowIps?: string[];
+  description?: string;
+}
+interface InstallRecipeInput {
+  teamId?: string;
+  connectionId?: string;
+  inputs?: Record<string, string>;
+}
+declare class IntegrationsManager {
+  private readonly client;
+  constructor(client: HttpClient);
+  readonly automations: {
+    list: (opts?: {
+      teamId?: string;
+    }) => Promise<AutomationInfo[]>;
+    get: (id: string, opts?: {
+      teamId?: string;
+    }) => Promise<{
+      automation: AutomationInfo;
+      triggers: TriggerInfo[];
+      endpoints: EndpointInfo[];
+    }>;
+    create: (input: CreateAutomationInput) => Promise<{
+      automation: AutomationInfo;
+      triggers: TriggerInfo[];
+      endpoints: EndpointInfo[];
+    }>;
+    update: (id: string, patch: {
+      teamId?: string;
+      name?: string;
+      description?: string;
+      enabled?: boolean;
+      connectionId?: string | null;
+    }) => Promise<AutomationInfo>;
+    delete: (id: string, opts?: {
+      teamId?: string;
+    }) => Promise<void>;
+    /**
+     * Unified inbound + outbound timeline for an automation.
+     * Returns the most recent N rows (default 100). Pagination is
+     * by `since` ISO8601 timestamp.
+     */
+    logs: (id: string, opts?: {
+      teamId?: string;
+      since?: string;
+      limit?: number;
+    }) => Promise<{
+      deliveries: DeliveryAttempt[];
+      runs: TriggerRun[];
+    }>;
+    /**
+     * Install an automation from a recipe manifest. The recipe defines
+     * what gets created (one Automation, plus underlying triggers /
+     * endpoints) and which inputs the user must supply.
+     */
+    installFromRecipe: (recipeId: string, input?: InstallRecipeInput) => Promise<{
+      automation: AutomationInfo;
+      triggers: TriggerInfo[];
+      endpoints: EndpointInfo[];
+    }>;
+  };
+  /**
+   * Iterate all log entries for an automation, paging through
+   * deliveries+runs in 200-row batches. Use this to power export
+   * scripts or dashboards. Defined on the manager (not under
+   * .automations) because async generators can't reference an
+   * enclosing object literal's other methods through `this` cleanly.
+   */
+  iterateAutomationLogs(id: string, opts?: {
+    teamId?: string;
+    since?: string;
+  }): AsyncGenerator<{
+    deliveries: DeliveryAttempt[];
+    runs: TriggerRun[];
+  }>;
+  readonly recipes: {
+    list: () => Promise<RecipeManifest[]>;
+    get: (id: string) => Promise<RecipeManifest>;
+  };
+  readonly connections: {
+    list: (opts?: {
+      teamId?: string;
+    }) => Promise<ConnectionInfo[]>;
+    delete: (id: string, opts?: {
+      teamId?: string;
+    }) => Promise<void>;
+  };
+  readonly endpoints: {
+    list: (opts?: {
+      teamId?: string;
+    }) => Promise<EndpointInfo[]>;
+    create: (input: CreateEndpointInput) => Promise<EndpointWithSecret>;
+    update: (id: string, patch: {
+      teamId?: string;
+      url?: string;
+      events?: string[];
+      scope?: IntegrationScope;
+      description?: string;
+      enabled?: boolean;
+    }) => Promise<EndpointInfo>;
+    delete: (id: string, opts?: {
+      teamId?: string;
+    }) => Promise<void>;
+    rotateSecret: (id: string, opts?: {
+      teamId?: string;
+    }) => Promise<EndpointWithSecret>;
+    listDeliveries: (id: string, opts?: {
+      teamId?: string;
+      since?: string;
+      status?: IntegrationDeliveryStatus;
+      limit?: number;
+    }) => Promise<DeliveryAttempt[]>;
+  };
+  readonly triggers: {
+    list: (opts?: {
+      teamId?: string;
+    }) => Promise<TriggerInfo[]>;
+    create: (input: CreateTriggerInput) => Promise<TriggerWithSecret>;
+    update: (id: string, patch: {
+      teamId?: string;
+      eventFilter?: Record<string, unknown> | null;
+      action?: IntegrationAction;
+      rateLimitRpm?: number;
+      allowIps?: string[] | null;
+      description?: string;
+      enabled?: boolean;
+    }) => Promise<TriggerInfo>;
+    delete: (id: string, opts?: {
+      teamId?: string;
+    }) => Promise<void>;
+    listRuns: (id: string, opts?: {
+      teamId?: string;
+      since?: string;
+      limit?: number;
+    }) => Promise<TriggerRun[]>;
+  };
+}
+//#endregion
+//#region src/client.d.ts
+/**
+ * Client for the Tangle Sandbox platform.
+ *
+ * @example
+ * ```typescript
+ * import { Sandbox } from "@tangle-network/sandbox";
+ *
+ * const client = new Sandbox({
+ *   apiKey: "sk_sandbox_...",
+ *   baseUrl: "https://your-sandbox-api.example.com",
+ * });
+ *
+ * // Create a sandbox
+ * const box = await client.create({
+ *   name: "my-project",
+ *   sshEnabled: true,
+ * });
+ *
+ * // Execute commands
+ * const result = await box.exec("npm install");
+ *
+ * // Clean up
+ * await box.delete();
+ * ```
+ */
+declare class SandboxClient implements HttpClient {
+  private readonly baseUrl;
+  private readonly apiKey;
+  private readonly timeoutMs;
+  private readonly trustLocalCliAuth;
+  private _secrets;
+  private _sshKeys;
+  private _integrations;
+  private _fleets;
+  private _intelligence;
+  constructor(config: SandboxClientConfig);
+  /**
+   * Fleet operations for agent-managed groups of sandboxes.
+   *
+   * Fleets are an SDK-level convenience over the existing sandbox lifecycle
+   * API. Each worker is a normal sandbox tagged with stable fleet metadata,
+   * so older clients and dashboards can still inspect and delete them.
+   */
+  get fleets(): SandboxFleetClient;
+  get intelligence(): IntelligenceClient;
+  getApiKey(): string;
+  /**
+   * Access the secrets manager for storing and retrieving encrypted secrets.
+   *
+   * @example
+   * ```typescript
+   * // Create a secret
+   * await client.secrets.create("HF_TOKEN", "hf_xxx");
+   *
+   * // List secrets (names only)
+   * const secrets = await client.secrets.list();
+   *
+   * // Get secret value
+   * const value = await client.secrets.get("HF_TOKEN");
+   *
+   * // Update secret
+   * await client.secrets.update("HF_TOKEN", "hf_new_value");
+   *
+   * // Delete secret
+   * await client.secrets.delete("HF_TOKEN");
+   * ```
+   */
+  get secrets(): SecretsManager;
+  get sshKeys(): SshKeysManager;
+  /**
+   * Access the integrations manager — webhooks (inbound + outbound),
+   * automations, connections to managed connectors, and recipes.
+   *
+   * Spec: specs/sandbox-integrations.md.
+   *
+   * @example
+   * ```typescript
+   * // Outbound: get pinged when a sandbox fails
+   * const ep = await client.integrations.endpoints.create({
+   *   url: "https://example.com/hook",
+   *   events: ["sandbox.failed", "sandbox.permanently_dead"],
+   * });
+   * console.log(ep.secret); // shown once — store it
+   *
+   * // Inbound: a public URL that, when POSTed to, runs an action
+   * const trg = await client.integrations.triggers.create({
+   *   verificationKind: "hmac_shared_secret",
+   *   action: {
+   *     kind: "sandbox.create",
+   *     config: { template: "node-22", prompt: "Run: ${body.prompt}" },
+   *   },
+   * });
+   * console.log(trg.publicUrl);
+   *
+   * // One-click recipe install
+   * const auto = await client.integrations.automations.installFromRecipe(
+   *   "github.pr-review",
+   *   { connectionId: "ic_…", inputs: { template: "node-22" } },
+   * );
+   * ```
+   */
+  get integrations(): IntegrationsManager;
+  private _environments;
+  /**
+   * Access available development environments.
+   *
+   * @example
+   * ```typescript
+   * const envs = await client.environments.list();
+   * // → [{ id: "universal", description: "Universal environment with all toolchains via Nix", ... }]
+   *
+   * const sandbox = await client.create({ environment: "universal" });
+   * ```
+   */
+  get environments(): EnvironmentsClient;
+  private _teams;
+  private _publicTemplates;
+  /**
+   * Access team management (collaboration groups, invitations,
+   * member roles). Teams scope shared sandboxes — pass `teamId` to
+   * `client.create()` to create a sandbox accessible to a team's
+   * members.
+   *
+   * @example
+   * ```typescript
+   * const teams = await client.teams.list();
+   * const invite = await client.teams.invite(teams[0].id, {
+   *   email: "alice@example.com",
+   *   role: "member",
+   * });
+   * ```
+   */
+  get teams(): TeamsClient;
+  get publicTemplates(): PublicTemplatesClient;
+  /**
+   * Create a new sandbox.
+   *
+   * @param options - Configuration for the new sandbox
+   * @returns A SandboxInstance representing the created sandbox
+   *
+   * @example
+   * ```typescript
+   * const box = await client.create({
+   *   name: "my-project",
+   *   environment: "universal",
+   *   sshEnabled: true,
+   *   env: { NODE_ENV: "development" },
+   * });
+   * ```
+   */
+  create(options?: CreateSandboxOptions): Promise<SandboxInstance>;
+  /**
+   * List all sandboxes.
+   *
+   * @param options - Filtering and pagination options
+   * @returns Array of SandboxInstance objects
+   *
+   * @example
+   * ```typescript
+   * // List all running sandboxes
+   * const running = await client.list({ status: "running" });
+   *
+   * // List with pagination
+   * const page = await client.list({ limit: 10, offset: 0 });
+   * ```
+   */
+  list(options?: ListSandboxOptions): Promise<SandboxInstance[]>;
+  /**
+   * Get a sandbox by ID.
+   *
+   * @param id - The sandbox ID
+   * @returns A SandboxInstance or null if not found
+   *
+   * @example
+   * ```typescript
+   * const box = await client.get("sandbox_abc123");
+   * if (box) {
+   *   console.log(box.status);
+   * }
+   * ```
+   */
+  get(id: string): Promise<SandboxInstance | null>;
+  /**
+   * Get usage information for the account.
+   *
+   * @returns Usage statistics for the current billing period
+   *
+   * @example
+   * ```typescript
+   * const usage = await client.usage();
+   * console.log(`Active sandboxes: ${usage.activeSandboxes}`);
+   * console.log(`Compute minutes: ${usage.computeMinutes}`);
+   * ```
+   */
+  usage(): Promise<UsageInfo>;
+  /**
+   * Get subscription and billing information for the account.
+   *
+   * @returns Subscription details including plan, credits, and limits
+   *
+   * @example
+   * ```typescript
+   * const sub = await client.subscription();
+   * console.log(`Plan: ${sub.plan}`);
+   * console.log(`Credits: $${sub.creditsAvailableUsd.toFixed(2)}`);
+   * ```
+   */
+  subscription(): Promise<SubscriptionInfo>;
+  /**
+   * Check if the Sandbox API is available.
+   *
+   * @returns true if the API is healthy, false otherwise
+   */
+  health(): Promise<boolean>;
+  /**
+   * Check if CRIU checkpointing is available on the platform.
+   *
+   * CRIU enables memory preservation for true pause/resume and fork operations.
+   * It requires specific host configuration.
+   *
+   * @returns CRIU availability status
+   *
+   * @example
+   * ```typescript
+   * const status = await client.criuStatus();
+   * if (status.available) {
+   *   console.log(`CRIU ${status.criuVersion} available`);
+   * } else {
+   *   console.log(`CRIU not available: ${status.reason}`);
+   * }
+   * ```
+   */
+  criuStatus(): Promise<{
+    available: boolean;
+    criuVersion?: string;
+    reason?: string;
+    requirements?: {
+      kernel: boolean;
+      criu: boolean;
+      storageDriver: boolean;
+      experimental: boolean;
+    };
+  }>;
+  /**
+   * Run multiple tasks in parallel across sandboxes.
+   * Returns the aggregated results after all tasks complete.
+   *
+   * @param tasks - Array of tasks to execute
+   * @param options - Batch execution options
+   * @returns Aggregated batch results
+   *
+   * @throws {@link TimeoutError} if the server hasn't begun responding
+   *   before the deadline (pre-stream timeout).
+   * @throws {@link ValidationError} / {@link QuotaError} / other typed
+   *   SDK errors if the server rejects the request before streaming.
+   * @throws `DOMException` with `name === "AbortError"` if
+   *   `options.signal` fires OR the safety-valve deadline fires
+   *   AFTER streaming has begun — parseSSEStream can't distinguish
+   *   the source mid-stream. Callers that need to tell cancel from
+   *   timeout should check `options.signal?.aborted` in their catch.
+   * @throws `Error` with the server message if the stream emits a
+   *   `batch.failed` event.
+   *
+   * @example
+   * ```typescript
+   * const result = await client.runBatch([
+   *   { id: "task-1", message: "Analyze this file" },
+   *   { id: "task-2", message: "Generate a summary" },
+   * ]);
+   * console.log(`Success rate: ${result.successRate}%`);
+   * ```
+   */
+  runBatch(tasks: BatchTask[], options?: BatchOptions): Promise<BatchResult>;
+  /**
+   * Stream events from a batch execution.
+   * Use this for real-time progress updates during batch processing.
+   *
+   * @param tasks - Array of tasks to execute
+   * @param options - Batch execution options
+   *
+   * @throws {@link TimeoutError} if the server hasn't begun responding
+   *   before the deadline (pre-stream timeout).
+   * @throws {@link ValidationError} / {@link QuotaError} / other typed
+   *   SDK errors if the server rejects the request before streaming.
+   * @throws `DOMException` with `name === "AbortError"` if
+   *   `options.signal` fires OR the safety-valve deadline fires
+   *   AFTER streaming has begun. Distinguish via
+   *   `options.signal?.aborted` in the consumer's catch.
+   *
+   * @example
+   * ```typescript
+   * for await (const event of client.streamBatch(tasks)) {
+   *   if (event.type === "task.completed") {
+   *     console.log(`Task ${event.data.taskId} completed`);
+   *   }
+   * }
+   * ```
+   */
+  streamBatch(tasks: BatchTask[], options?: BatchOptions): AsyncGenerator<BatchEvent>;
+  /**
+   * Make an authenticated HTTP request to the API.
+   * This is exposed for use by SandboxInstance.
+   */
+  fetch(path: string, options?: RequestInit): Promise<Response>;
+  private parseInfo;
+  private readonly _tokenRefreshHandlers;
+  /**
+   * Register a handler invoked when the SDK transparently refreshes a
+   * sandbox bearer after a 401 retry. Returns a function that
+   * unregisters the handler when called.
+   */
+  onTokenRefresh(handler: TokenRefreshHandler): () => void;
+  /** @internal — fired by the runtime-fetch retry path after a successful
+   * refresh. Errors thrown by handlers are caught and surfaced as
+   * console warnings so one bad subscriber does not poison the rest. */
+  _emitTokenRefresh(sandboxId: string, newToken: string): void;
+}
+/**
+ * Client for the Intelligence Reports API.
+ *
+ * Two analysis modes:
+ *
+ * - `deterministic` (default): free, rule-based platform analysis over
+ *   the subject's trace evidence. Returns immediately.
+ * - `agentic`: routes to the **Tangle Trace Analyst**, an LLM-driven
+ *   reasoning loop that reads OTLP-shaped trace evidence and emits
+ *   findings, evidence references, recommended actions, and a
+ *   validation plan. Billed against `budget.maxUsd`; the platform
+ *   never spends past the budget the caller sets.
+ *
+ * Subjects: `sandbox` or `fleet`. A fleet subject can be narrowed to
+ * a single coordinated command via `subject.dispatchId`.
+ */
+declare class IntelligenceClient {
+  private readonly client;
+  constructor(client: SandboxClient);
+  /**
+   * Create an intelligence report over the given subject.
+   *
+   * Use `mode: "agentic"` to engage the **Tangle Trace Analyst** with a
+   * spending budget. The budget is enforced server-side before billing
+   * fires — a request whose computed cost exceeds `budget.maxUsd`
+   * returns 402 without charging the customer.
+   */
+  createReport(options: CreateIntelligenceReportOptions): Promise<IntelligenceReport>;
+  createAgenticReport(options: {
+    subject: CreateIntelligenceReportOptions["subject"];
+    maxUsd: number;
+    metadata?: Record<string, unknown>;
+  }): Promise<IntelligenceReport>;
+  /**
+   * Estimate the cost of a prospective report without creating one.
+   * Verifies subject ownership the same way `createReport` does, so it
+   * never becomes an existence oracle for foreign subjects.
+   */
+  estimateReport(options: Pick<CreateIntelligenceReportOptions, "subject"> & {
+    mode?: "deterministic" | "agentic";
+    metadata?: Record<string, unknown>;
+  }): Promise<{
+    mode: "deterministic" | "agentic";
+    costUsd: number;
+    billable: boolean;
+    billedTo: "platform" | "customer";
+    reason: string;
+  }>;
+  getReport(jobId: string): Promise<IntelligenceReport>;
+  listReports(options?: {
+    subjectType?: CreateIntelligenceReportOptions["subject"]["type"];
+    subjectId?: string;
+    limit?: number;
+  }): Promise<IntelligenceReport[]>;
+  waitForReport(jobId: string, options?: {
+    timeoutMs?: number;
+    pollMs?: number;
+  }): Promise<IntelligenceReport>;
+}
+/**
+ * Client for browsing available development environments.
+ */
+declare class EnvironmentsClient {
+  private readonly client;
+  constructor(client: SandboxClient);
+  /**
+   * List available development environments.
+   *
+   * @returns Array of available environments with metadata
+   *
+   * @example
+   * ```typescript
+   * const envs = await client.environments.list();
+   * for (const env of envs) {
+   *   console.log(`${env.id}: ${env.description}`);
+   * }
+   * ```
+   */
+  list(): Promise<SandboxEnvironment[]>;
+  /**
+   * Get details for a specific environment.
+   *
+   * @param id - Environment identifier (e.g., "universal")
+   */
+  get(id: string): Promise<SandboxEnvironment | null>;
+}
+declare class PublicTemplatesClient {
+  private readonly client;
+  constructor(client: SandboxClient);
+  list(options?: {
+    query?: string;
+    tag?: string;
+    featuredOnly?: boolean;
+    limit?: number;
+    offset?: number;
+  }): Promise<PublicTemplateInfo[]>;
+  featured(): Promise<PublicTemplateInfo[]>;
+  get(idOrSlug: string): Promise<PublicTemplateInfo>;
+  versions(idOrSlug: string): Promise<PublicTemplateVersionInfo[]>;
+  publish(options: PublishPublicTemplateOptions): Promise<PublicTemplateInfo>;
+  publishVersion(idOrSlug: string, options: PublishPublicTemplateVersionOptions): Promise<PublicTemplateVersionInfo>;
+}
+/**
+ * Team (collaboration group) record as returned from the API.
+ */
+interface Team {
+  id: string;
+  name: string;
+  ownerCustomerId: string;
+  orgId: string | null;
+  memberCount: number;
+  currentUserRole: "owner" | "admin" | "member" | "viewer";
+  createdAt: string;
+  updatedAt: string;
+}
+interface TeamMember {
+  id: string;
+  teamId: string;
+  customerId: string;
+  customerEmail: string;
+  customerName: string | null;
+  role: "owner" | "admin" | "member" | "viewer";
+  status: "active" | "pending" | "removed";
+  joinedAt: string | null;
+  createdAt: string;
+}
+interface TeamInvitation {
+  id: string;
+  teamId: string;
+  email: string;
+  invitedBy: string;
+  invitedByEmail: string | null;
+  role: "admin" | "member" | "viewer";
+  token: string;
+  status: "pending" | "accepted" | "expired" | "revoked";
+  expiresAt: string;
+  createdAt: string;
+}
+interface TeamInvitationPreview {
+  email: string;
+  role: "admin" | "member" | "viewer";
+  status: "pending" | "accepted" | "expired" | "revoked";
+  expiresAt: string;
+  teamName: string;
+  invitedByEmail: string | null;
+}
+interface TeamSecretRecord {
+  name: string;
+  updatedAt: string;
+  updatedBy: string;
+}
+interface TeamTemplateRecord {
+  id: string;
+  name: string;
+  description: string;
+  snapshotId: string;
+  environment: string;
+  config: Record<string, unknown>;
+  teamId: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+interface CreateTeamTemplateOptions {
+  name: string;
+  snapshotId: string;
+  description?: string;
+  environment?: string;
+  config?: Record<string, unknown>;
+}
+interface CreateTeamOptions {
+  name: string;
+  orgId?: string;
+}
+interface InviteTeamMemberOptions {
+  email: string;
+  role: "admin" | "member" | "viewer";
+  /** Lifetime of the invitation in hours (default 168 = 7 days). */
+  ttlHours?: number;
+}
+/**
+ * Client for managing teams and team-scoped sharing.
+ *
+ * Team resources are scoped to the authenticated user's membership —
+ * the client never needs to pass an org id explicitly.
+ */
+declare class TeamsClient {
+  private readonly client;
+  constructor(client: SandboxClient);
+  list(): Promise<Team[]>;
+  create(options: CreateTeamOptions): Promise<Team>;
+  get(teamId: string): Promise<Team>;
+  update(teamId: string, updates: {
+    name?: string;
+  }): Promise<Team>;
+  delete(teamId: string): Promise<void>;
+  leave(teamId: string): Promise<void>;
+  transferOwnership(teamId: string, newOwnerCustomerId: string): Promise<void>;
+  listMembers(teamId: string): Promise<TeamMember[]>;
+  updateMember(teamId: string, memberId: string, updates: {
+    role?: "admin" | "member" | "viewer";
+    status?: "active" | "removed";
+  }): Promise<TeamMember>;
+  removeMember(teamId: string, memberId: string): Promise<void>;
+  listInvitations(teamId: string): Promise<TeamInvitation[]>;
+  invite(teamId: string, options: InviteTeamMemberOptions): Promise<TeamInvitation>;
+  revokeInvitation(invitationId: string): Promise<void>;
+  acceptInvitation(token: string): Promise<TeamMember>;
+  getInvitation(token: string): Promise<TeamInvitationPreview>;
+  listSecrets(teamId: string): Promise<TeamSecretRecord[]>;
+  upsertSecret(teamId: string, name: string, value: string): Promise<TeamSecretRecord>;
+  deleteSecret(teamId: string, name: string): Promise<void>;
+  revealSecret(teamId: string, name: string): Promise<{
+    name: string;
+    value: string;
+  }>;
+  listTemplates(teamId: string): Promise<TeamTemplateRecord[]>;
+  createTemplate(teamId: string, options: CreateTeamTemplateOptions): Promise<TeamTemplateRecord>;
+  deleteTemplate(teamId: string, templateId: string): Promise<void>;
+}
+/**
+ * Alias for SandboxClient for cleaner imports.
+ */
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Sandbox SDK Errors
+ *
+ * Error classes for the Sandbox client SDK.
+ */
+/**
+ * Base error class for all Sandbox SDK errors.
+ */
+declare class SandboxError extends Error {
+  /** HTTP status code if applicable */
+  readonly status?: number;
+  /** Error code for programmatic handling */
+  readonly code: string;
+  /** Best-effort origin of the failing request */
+  readonly origin?: SandboxErrorOrigin;
+  /** Request path or endpoint when known */
+  readonly endpoint?: string;
+  /** Retry-after duration in ms when surfaced by the upstream */
+  readonly retryAfterMs?: number;
+  /** Sidecar version when the runtime emitted it */
+  readonly sidecarVersion?: string;
+  /** Sidecar image/tag/sha when the runtime emitted it */
+  readonly containerImage?: string;
+  constructor(message: string, code: string, status?: number, metadata?: SandboxErrorMetadata);
+}
+type SandboxErrorOrigin = "sidecar" | "sandbox-api" | "control-plane" | "runtime" | "unknown";
+interface SandboxErrorMetadata {
+  origin?: SandboxErrorOrigin;
+  endpoint?: string;
+  retryAfterMs?: number;
+  sidecarVersion?: string;
+  containerImage?: string;
+}
+type SandboxErrorJson = string | number | boolean | null | {
+  [key: string]: SandboxErrorJson;
+} | SandboxErrorJson[];
+type SandboxFailureDetail = {
+  [key: string]: SandboxErrorJson;
+};
+/**
+ * Authentication failed or API key is invalid.
+ */
+declare class AuthError extends SandboxError {
+  constructor(message?: string, metadata?: SandboxErrorMetadata);
+}
+/**
+ * The requested resource was not found.
+ */
+declare class NotFoundError extends SandboxError {
+  /** The resource type that was not found */
+  readonly resourceType: string;
+  /** The resource ID that was not found */
+  readonly resourceId: string;
+  constructor(resourceType: string, resourceId: string, metadata?: SandboxErrorMetadata);
+}
+/**
+ * Account quota or rate limit exceeded.
+ */
+declare class QuotaError extends SandboxError {
+  /** The type of quota that was exceeded */
+  readonly quotaType: string;
+  /** Current usage */
+  readonly current?: number;
+  /** Maximum allowed */
+  readonly limit?: number;
+  /** Suggested retry-after duration in ms */
+  readonly retryAfterMs?: number;
+  constructor(quotaType: string, message?: string, current?: number, limit?: number, metadata?: SandboxErrorMetadata, status?: number);
+}
+/**
+ * The requested capability is unavailable for the account, driver, or sandbox.
+ */
+declare class CapabilityError extends SandboxError {
+  /** Capability or feature that was rejected when known */
+  readonly capability?: string;
+  constructor(message: string, code?: string, status?: number, metadata?: SandboxErrorMetadata, capability?: string);
+}
+/**
+ * A multi-resource operation failed for one or more branches.
+ */
+declare class PartialFailureError extends SandboxError {
+  /** Per-resource failures returned by the API when available */
+  readonly failures?: SandboxFailureDetail[];
+  constructor(message: string, code?: string, status?: number, metadata?: SandboxErrorMetadata, failures?: SandboxFailureDetail[]);
+}
+/**
+ * The request was invalid or malformed.
+ */
+declare class ValidationError extends SandboxError {
+  /** Field-level validation errors */
+  readonly fields?: Record<string, string>;
+  constructor(message: string, fields?: Record<string, string>, metadata?: SandboxErrorMetadata);
+}
+/**
+ * The sandbox is not in a valid state for the requested operation.
+ */
+declare class StateError extends SandboxError {
+  /** Current state of the sandbox */
+  readonly currentState: string;
+  /** Required state for the operation */
+  readonly requiredState?: string;
+  constructor(message: string, currentState: string, requiredState?: string, metadata?: SandboxErrorMetadata);
+}
+/**
+ * The request timed out.
+ */
+declare class TimeoutError extends SandboxError {
+  /** Timeout duration in milliseconds */
+  readonly timeoutMs: number;
+  constructor(timeoutMs: number, message?: string, metadata?: SandboxErrorMetadata);
+}
+/**
+ * A network or connection error occurred.
+ */
+declare class NetworkError extends SandboxError {
+  /** The underlying error */
+  readonly cause?: Error;
+  constructor(message: string, causeOrMetadata?: Error | SandboxErrorMetadata, metadata?: SandboxErrorMetadata);
+}
+/**
+ * The server returned an unexpected error.
+ */
+declare class ServerError extends SandboxError {
+  constructor(message: string, status?: number, metadata?: SandboxErrorMetadata);
+}
+//#endregion
+export { IntegrationAction as A, TriggerRun as B, CreateAutomationInput as C, EndpointInfo as D, DeliveryAttempt as E, IntegrationScope as F, ParsedSSEEvent as G, SandboxFleet as H, IntegrationVerificationKind as I, parseSSEStream as K, IntegrationsManager as L, IntegrationDeliveryStatus as M, IntegrationPrincipalType as N, EndpointWithSecret as O, IntegrationProvider as P, RecipeManifest as R, ConnectionInfo as S, CreateTriggerInput as T, SandboxFleetClient as U, TriggerWithSecret as V, ParseSSEStreamOptions as W, SandboxClient as _, PartialFailureError as a, TeamMember as b, SandboxErrorJson as c, StateError as d, TimeoutError as f, InviteTeamMemberOptions as g, IntelligenceClient as h, NotFoundError as i, IntegrationActionKind as j, InstallRecipeInput as k, SandboxFailureDetail as l, CreateTeamOptions as m, CapabilityError as n, QuotaError as o, ValidationError as p, NetworkError as r, SandboxError as s, AuthError as t, ServerError as u, Team as v, CreateEndpointInput as w, AutomationInfo as x, TeamInvitation as y, TriggerInfo as z };