@mutagent/sdk 0.3.34 → 0.3.35

package/src/models/operations/post-api-sandbox.ts

@@ -0,0 +1,422 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v4-mini";
+import { safeParse } from "../../lib/schemas.js";
+import * as openEnums from "../../types/enums.js";
+import { OpenEnum } from "../../types/enums.js";
+import { Result as SafeParseResult } from "../../types/fp.js";
+import * as types from "../../types/primitives.js";
+import { SDKValidationError } from "../errors/sdk-validation-error.js";
+
+/**
+ * CPU architecture the image was built for. Validated against the provider at preflight.
+ */
+export enum PostApiSandboxArchRequest {
+  X8664 = "x86_64",
+  Arm64 = "arm64",
+}
+
+/**
+ * Requested resources. A provider that does not expose a given dial REJECTS a definition that sets it, at preflight — never a silent downgrade.
+ */
+export type PostApiSandboxResources = {
+  /**
+   * Requested vCPU count
+   */
+  vcpu?: number | undefined;
+  /**
+   * Requested memory in MB
+   */
+  memoryMb?: number | undefined;
+  /**
+   * Requested disk in MB
+   */
+  diskMb?: number | undefined;
+  /**
+   * Whether a GPU is required
+   */
+  gpu?: boolean | undefined;
+};
+
+/**
+ * Outbound policy. Defaults to deny — opening egress is explicit.
+ */
+export enum PostApiSandboxEgress {
+  Deny = "deny",
+  Allowlist = "allowlist",
+  Allow = "allow",
+}
+
+/**
+ * What this rule constrains
+ */
+export enum PostApiSandboxKind {
+  Port = "port",
+  Cidr = "cidr",
+  Domain = "domain",
+}
+
+/**
+ * A single outbound-access allowance
+ */
+export type PostApiSandboxAllow = {
+  /**
+   * What this rule constrains
+   */
+  kind?: PostApiSandboxKind | undefined;
+  /**
+   * Port, CIDR block, or domain
+   */
+  value: string;
+};
+
+/**
+ * Network policy for the sandbox
+ */
+export type PostApiSandboxNetwork = {
+  /**
+   * Outbound policy. Defaults to deny — opening egress is explicit.
+   */
+  egress?: PostApiSandboxEgress | undefined;
+  /**
+   * Allowances, when egress is "allowlist". Requires provider egressControl support.
+   */
+  allow?: Array<PostApiSandboxAllow> | undefined;
+};
+
+/**
+ * Non-secret environment variables. Secret material must come from an Environment.
+ */
+export type PostApiSandboxVars = {};
+
+/**
+ * Sandbox configuration. Separate artifact from the image content (R-C20).
+ */
+export type PostApiSandboxDefinition = {
+  /**
+   * Human-readable definition name
+   */
+  name: string;
+  /**
+   * Image reference (repository:tag or @digest). The image content is a separate artifact.
+   */
+  image: string;
+  /**
+   * CPU architecture the image was built for. Validated against the provider at preflight.
+   */
+  arch?: PostApiSandboxArchRequest | undefined;
+  /**
+   * Requested resources. A provider that does not expose a given dial REJECTS a definition that sets it, at preflight — never a silent downgrade.
+   */
+  resources?: PostApiSandboxResources | undefined;
+  /**
+   * Network policy for the sandbox
+   */
+  network?: PostApiSandboxNetwork | undefined;
+  /**
+   * Name of the Environment (secrets + variables) to load at spawn. Distinct from `provider`.
+   */
+  environment?: string | undefined;
+  /**
+   * Provider registry key. When omitted the backend default applies.
+   */
+  provider?: string | undefined;
+  /**
+   * Requested max lifetime. Rejected at preflight if it exceeds the provider ceiling.
+   */
+  timeoutMs?: number | undefined;
+  /**
+   * Working directory inside the sandbox
+   */
+  workdir?: string | undefined;
+  /**
+   * Non-secret environment variables. Secret material must come from an Environment.
+   */
+  vars?: PostApiSandboxVars | undefined;
+};
+
+/**
+ * Spawn a sandbox from a definition
+ */
+export type PostApiSandboxRequest = {
+  /**
+   * Sandbox configuration. Separate artifact from the image content (R-C20).
+   */
+  definition: PostApiSandboxDefinition;
+  /**
+   * Correlation id for trace attribution
+   */
+  runId?: string | undefined;
+};
+
+/**
+ * CPU architecture the image was built for. Validated against the provider at preflight.
+ */
+export enum PostApiSandboxArchResponse {
+  X8664 = "x86_64",
+  Arm64 = "arm64",
+}
+/**
+ * CPU architecture the image was built for. Validated against the provider at preflight.
+ */
+export type PostApiSandboxArchResponseOpen = OpenEnum<
+  typeof PostApiSandboxArchResponse
+>;
+
+export enum PostApiSandboxStatus {
+  Pending = "pending",
+  Starting = "starting",
+  Running = "running",
+  Paused = "paused",
+  Stopping = "stopping",
+  Stopped = "stopped",
+  Failed = "failed",
+}
+export type PostApiSandboxStatusOpen = OpenEnum<typeof PostApiSandboxStatus>;
+
+/**
+ * A sandbox as recorded by the service — one record whether spawned from CLI or platform
+ */
+export type PostApiSandboxResponse = {
+  /**
+   * Sandbox identifier
+   */
+  id: string;
+  /**
+   * Bumps when the underlying instance is replaced
+   */
+  generation: number;
+  /**
+   * Provider that owns this sandbox
+   */
+  provider: string;
+  /**
+   * CPU architecture the image was built for. Validated against the provider at preflight.
+   */
+  arch: PostApiSandboxArchResponseOpen;
+  status: PostApiSandboxStatusOpen;
+  definitionName: string;
+  environmentName?: string | undefined;
+  /**
+   * ISO timestamp
+   */
+  createdAt: string;
+};
+
+/** @internal */
+export const PostApiSandboxArchRequest$outboundSchema: z.ZodMiniEnum<
+  typeof PostApiSandboxArchRequest
+> = z.enum(PostApiSandboxArchRequest);
+
+/** @internal */
+export type PostApiSandboxResources$Outbound = {
+  vcpu?: number | undefined;
+  memoryMb?: number | undefined;
+  diskMb?: number | undefined;
+  gpu?: boolean | undefined;
+};
+
+/** @internal */
+export const PostApiSandboxResources$outboundSchema: z.ZodMiniType<
+  PostApiSandboxResources$Outbound,
+  PostApiSandboxResources
+> = z.object({
+  vcpu: z.optional(z.number()),
+  memoryMb: z.optional(z.number()),
+  diskMb: z.optional(z.number()),
+  gpu: z.optional(z.boolean()),
+});
+
+export function postApiSandboxResourcesToJSON(
+  postApiSandboxResources: PostApiSandboxResources,
+): string {
+  return JSON.stringify(
+    PostApiSandboxResources$outboundSchema.parse(postApiSandboxResources),
+  );
+}
+
+/** @internal */
+export const PostApiSandboxEgress$outboundSchema: z.ZodMiniEnum<
+  typeof PostApiSandboxEgress
+> = z.enum(PostApiSandboxEgress);
+
+/** @internal */
+export const PostApiSandboxKind$outboundSchema: z.ZodMiniEnum<
+  typeof PostApiSandboxKind
+> = z.enum(PostApiSandboxKind);
+
+/** @internal */
+export type PostApiSandboxAllow$Outbound = {
+  kind: string;
+  value: string;
+};
+
+/** @internal */
+export const PostApiSandboxAllow$outboundSchema: z.ZodMiniType<
+  PostApiSandboxAllow$Outbound,
+  PostApiSandboxAllow
+> = z.object({
+  kind: z._default(PostApiSandboxKind$outboundSchema, PostApiSandboxKind.Port),
+  value: z.string(),
+});
+
+export function postApiSandboxAllowToJSON(
+  postApiSandboxAllow: PostApiSandboxAllow,
+): string {
+  return JSON.stringify(
+    PostApiSandboxAllow$outboundSchema.parse(postApiSandboxAllow),
+  );
+}
+
+/** @internal */
+export type PostApiSandboxNetwork$Outbound = {
+  egress: string;
+  allow?: Array<PostApiSandboxAllow$Outbound> | undefined;
+};
+
+/** @internal */
+export const PostApiSandboxNetwork$outboundSchema: z.ZodMiniType<
+  PostApiSandboxNetwork$Outbound,
+  PostApiSandboxNetwork
+> = z.object({
+  egress: z._default(
+    PostApiSandboxEgress$outboundSchema,
+    PostApiSandboxEgress.Deny,
+  ),
+  allow: z.optional(z.array(z.lazy(() => PostApiSandboxAllow$outboundSchema))),
+});
+
+export function postApiSandboxNetworkToJSON(
+  postApiSandboxNetwork: PostApiSandboxNetwork,
+): string {
+  return JSON.stringify(
+    PostApiSandboxNetwork$outboundSchema.parse(postApiSandboxNetwork),
+  );
+}
+
+/** @internal */
+export type PostApiSandboxVars$Outbound = {};
+
+/** @internal */
+export const PostApiSandboxVars$outboundSchema: z.ZodMiniType<
+  PostApiSandboxVars$Outbound,
+  PostApiSandboxVars
+> = z.object({});
+
+export function postApiSandboxVarsToJSON(
+  postApiSandboxVars: PostApiSandboxVars,
+): string {
+  return JSON.stringify(
+    PostApiSandboxVars$outboundSchema.parse(postApiSandboxVars),
+  );
+}
+
+/** @internal */
+export type PostApiSandboxDefinition$Outbound = {
+  name: string;
+  image: string;
+  arch: string;
+  resources?: PostApiSandboxResources$Outbound | undefined;
+  network?: PostApiSandboxNetwork$Outbound | undefined;
+  environment?: string | undefined;
+  provider?: string | undefined;
+  timeoutMs?: number | undefined;
+  workdir?: string | undefined;
+  vars?: PostApiSandboxVars$Outbound | undefined;
+};
+
+/** @internal */
+export const PostApiSandboxDefinition$outboundSchema: z.ZodMiniType<
+  PostApiSandboxDefinition$Outbound,
+  PostApiSandboxDefinition
+> = z.object({
+  name: z.string(),
+  image: z.string(),
+  arch: z._default(
+    PostApiSandboxArchRequest$outboundSchema,
+    PostApiSandboxArchRequest.X8664,
+  ),
+  resources: z.optional(z.lazy(() => PostApiSandboxResources$outboundSchema)),
+  network: z.optional(z.lazy(() => PostApiSandboxNetwork$outboundSchema)),
+  environment: z.optional(z.string()),
+  provider: z.optional(z.string()),
+  timeoutMs: z.optional(z.number()),
+  workdir: z.optional(z.string()),
+  vars: z.optional(z.lazy(() => PostApiSandboxVars$outboundSchema)),
+});
+
+export function postApiSandboxDefinitionToJSON(
+  postApiSandboxDefinition: PostApiSandboxDefinition,
+): string {
+  return JSON.stringify(
+    PostApiSandboxDefinition$outboundSchema.parse(postApiSandboxDefinition),
+  );
+}
+
+/** @internal */
+export type PostApiSandboxRequest$Outbound = {
+  definition: PostApiSandboxDefinition$Outbound;
+  runId?: string | undefined;
+};
+
+/** @internal */
+export const PostApiSandboxRequest$outboundSchema: z.ZodMiniType<
+  PostApiSandboxRequest$Outbound,
+  PostApiSandboxRequest
+> = z.object({
+  definition: z.lazy(() => PostApiSandboxDefinition$outboundSchema),
+  runId: z.optional(z.string()),
+});
+
+export function postApiSandboxRequestToJSON(
+  postApiSandboxRequest: PostApiSandboxRequest,
+): string {
+  return JSON.stringify(
+    PostApiSandboxRequest$outboundSchema.parse(postApiSandboxRequest),
+  );
+}
+
+/** @internal */
+export const PostApiSandboxArchResponse$inboundSchema: z.ZodMiniType<
+  PostApiSandboxArchResponseOpen,
+  unknown
+> = openEnums.inboundSchema(PostApiSandboxArchResponse);
+
+/** @internal */
+export const PostApiSandboxStatus$inboundSchema: z.ZodMiniType<
+  PostApiSandboxStatusOpen,
+  unknown
+> = openEnums.inboundSchema(PostApiSandboxStatus);
+
+/** @internal */
+export const PostApiSandboxResponse$inboundSchema: z.ZodMiniType<
+  PostApiSandboxResponse,
+  unknown
+> = z.object({
+  id: types.string(),
+  generation: types.number(),
+  provider: types.string(),
+  arch: z._default(
+    PostApiSandboxArchResponse$inboundSchema,
+    PostApiSandboxArchResponse.X8664,
+  ),
+  status: z._default(
+    PostApiSandboxStatus$inboundSchema,
+    PostApiSandboxStatus.Pending,
+  ),
+  definitionName: types.string(),
+  environmentName: types.optional(types.string()),
+  createdAt: types.string(),
+});
+
+export function postApiSandboxResponseFromJSON(
+  jsonString: string,
+): SafeParseResult<PostApiSandboxResponse, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => PostApiSandboxResponse$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'PostApiSandboxResponse' from JSON`,
+  );
+}

package/src/sdk/sandbox.ts

@@ -0,0 +1,247 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { sandboxDeleteApiSandboxById } from "../funcs/sandbox-delete-api-sandbox-by-id.js";
+import { sandboxGetApiSandboxByIdStream } from "../funcs/sandbox-get-api-sandbox-by-id-stream.js";
+import { sandboxGetApiSandboxByIdTraces } from "../funcs/sandbox-get-api-sandbox-by-id-traces.js";
+import { sandboxGetApiSandboxById } from "../funcs/sandbox-get-api-sandbox-by-id.js";
+import { sandboxGetApiSandboxPresets } from "../funcs/sandbox-get-api-sandbox-presets.js";
+import { sandboxGetApiSandboxProviders } from "../funcs/sandbox-get-api-sandbox-providers.js";
+import { sandboxGetApiSandbox } from "../funcs/sandbox-get-api-sandbox.js";
+import { sandboxPostApiSandboxAgentRun } from "../funcs/sandbox-post-api-sandbox-agent-run.js";
+import { sandboxPostApiSandboxByIdExec } from "../funcs/sandbox-post-api-sandbox-by-id-exec.js";
+import { sandboxPostApiSandboxPreflight } from "../funcs/sandbox-post-api-sandbox-preflight.js";
+import { sandboxPostApiSandboxRun } from "../funcs/sandbox-post-api-sandbox-run.js";
+import { sandboxPostApiSandboxTelemetryV1Traces } from "../funcs/sandbox-post-api-sandbox-telemetry-v1-traces.js";
+import { sandboxPostApiSandboxToken } from "../funcs/sandbox-post-api-sandbox-token.js";
+import { sandboxPostApiSandbox } from "../funcs/sandbox-post-api-sandbox.js";
+import { ClientSDK, RequestOptions } from "../lib/sdks.js";
+import * as operations from "../models/operations/index.js";
+import { unwrapAsync } from "../types/fp.js";
+
+export class Sandbox extends ClientSDK {
+  /**
+   * Spawn a sandbox
+   *
+   * @remarks
+   * Requires an operator token. A session or task token is rejected with 403.
+   */
+  async postApiSandbox(
+    request: operations.PostApiSandboxRequest,
+    options?: RequestOptions,
+  ): Promise<operations.PostApiSandboxResponse> {
+    return unwrapAsync(sandboxPostApiSandbox(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * List sandboxes
+   *
+   * @remarks
+   * Always tenant-scoped. There is no unscoped listing path.
+   */
+  async getApiSandbox(
+    options?: RequestOptions,
+  ): Promise<Array<operations.GetApiSandboxResponse>> {
+    return unwrapAsync(sandboxGetApiSandbox(
+      this,
+      options,
+    ));
+  }
+
+  /**
+   * Run one command in a fresh sandbox
+   *
+   * @remarks
+   * Spawns from a preset, runs the command, tears the sandbox down. Requires an operator token — a one-shot run creates a sandbox. 200, not 201: the durable outcome is a result, and the sandbox it names is already gone unless `keep` was set. Blocking, and therefore bounded by the provider invocation timeout — long or interactive runs belong on POST /api/sandbox + /:id/exec.
+   */
+  async postApiSandboxRun(
+    request: operations.PostApiSandboxRunRequest,
+    options?: RequestOptions,
+  ): Promise<operations.PostApiSandboxRunResponse> {
+    return unwrapAsync(sandboxPostApiSandboxRun(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Run one agent turn in a fresh sandbox
+   *
+   * @remarks
+   * `prompt` is WHO the agent is (the agent definition) and `task` is WHAT to do this turn. They are two different prompts and are never concatenated. The turn's output comes back on stdout with the agent's real exit code. With `?stream=1` the same turn is delivered as it happens, in the event framing of `GET /:id/stream`: a `sandbox` event naming the box, then `stdout`/`stderr` as the agent produces them, then a `result` event carrying the exit code and whether the sandbox was torn down, then the terminal `status`. Disconnecting mid-stream releases the sandbox.
+   */
+  async postApiSandboxAgentRun(
+    request: operations.PostApiSandboxAgentRunRequest,
+    options?: RequestOptions,
+  ): Promise<operations.PostApiSandboxAgentRunResponse> {
+    return unwrapAsync(sandboxPostApiSandboxAgentRun(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * List sandbox presets
+   *
+   * @remarks
+   * Named definitions a one-shot run can name. A preset is what lets a caller run something without knowing our registry, region or image tag. Image references are deliberately not returned.
+   */
+  async getApiSandboxPresets(
+    options?: RequestOptions,
+  ): Promise<operations.GetApiSandboxPresetsResponse> {
+    return unwrapAsync(sandboxGetApiSandboxPresets(
+      this,
+      options,
+    ));
+  }
+
+  /**
+   * List sandbox providers
+   *
+   * @remarks
+   * Providers this backend can reach and which is the default. A CLI that has no provider configured uses the default.
+   */
+  async getApiSandboxProviders(
+    options?: RequestOptions,
+  ): Promise<operations.GetApiSandboxProvidersResponse> {
+    return unwrapAsync(sandboxGetApiSandboxProviders(
+      this,
+      options,
+    ));
+  }
+
+  /**
+   * Preflight a sandbox definition
+   *
+   * @remarks
+   * Validate a definition against a provider without creating anything. Returns every violation, not just the first.
+   */
+  async postApiSandboxPreflight(
+    request: operations.PostApiSandboxPreflightRequest,
+    options?: RequestOptions,
+  ): Promise<operations.PostApiSandboxPreflightResponse> {
+    return unwrapAsync(sandboxPostApiSandboxPreflight(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Exchange a platform API key for a sandbox operator token
+   *
+   * @remarks
+   * Trades a platform API key (`x-api-key: mg_live_…`) for a short-lived operator token scoped to one workspace. The caller must be able to create resources in that workspace.
+   */
+  async postApiSandboxToken(
+    request: operations.PostApiSandboxTokenRequest,
+    options?: RequestOptions,
+  ): Promise<operations.PostApiSandboxTokenResponse> {
+    return unwrapAsync(sandboxPostApiSandboxToken(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Ingest OTLP spans from inside a sandbox
+   *
+   * @remarks
+   * OTLP/HTTP JSON. Requires a task token; spans are attributed to the sandbox the token is bound to, never to the sandbox named in the payload.
+   */
+  async postApiSandboxTelemetryV1Traces(
+    options?: RequestOptions,
+  ): Promise<operations.PostApiSandboxTelemetryV1TracesResponse> {
+    return unwrapAsync(sandboxPostApiSandboxTelemetryV1Traces(
+      this,
+      options,
+    ));
+  }
+
+  /**
+   * Get sandbox status
+   */
+  async getApiSandboxById(
+    request: operations.GetApiSandboxByIdRequest,
+    options?: RequestOptions,
+  ): Promise<operations.GetApiSandboxByIdResponse> {
+    return unwrapAsync(sandboxGetApiSandboxById(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Tear down a sandbox
+   *
+   * @remarks
+   * Idempotent. The record is forgotten even if the provider teardown fails.
+   */
+  async deleteApiSandboxById(
+    request: operations.DeleteApiSandboxByIdRequest,
+    options?: RequestOptions,
+  ): Promise<operations.DeleteApiSandboxByIdResponse> {
+    return unwrapAsync(sandboxDeleteApiSandboxById(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Run a command in a sandbox
+   *
+   * @remarks
+   * Returns the command's real exit code. A task token is rejected — in-sandbox code reports on itself, it does not drive the box. With `?stream=1` the same result comes back as the event stream of `GET /:id/stream`, scoped to this one invocation and terminated by a `status` event carrying the exit code.
+   */
+  async postApiSandboxByIdExec(
+    request: operations.PostApiSandboxByIdExecRequest,
+    options?: RequestOptions,
+  ): Promise<operations.PostApiSandboxByIdExecResponse> {
+    return unwrapAsync(sandboxPostApiSandboxByIdExec(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Watch a sandbox's output live
+   *
+   * @remarks
+   * Server-sent events: `stdout`, `stderr`, `status`, `ping` (every 15s), `error`. `seq` is monotonic per sandbox and starts at 1; pass the last one seen as `?since=` to resume. If the buffer has already rolled past `since`, an `error` event names the lost range rather than skipping it silently. Disconnecting tears down the upstream.
+   */
+  async getApiSandboxByIdStream(
+    request: operations.GetApiSandboxByIdStreamRequest,
+    options?: RequestOptions,
+  ): Promise<void> {
+    return unwrapAsync(sandboxGetApiSandboxByIdStream(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Read a sandbox's captured spans
+   */
+  async getApiSandboxByIdTraces(
+    request: operations.GetApiSandboxByIdTracesRequest,
+    options?: RequestOptions,
+  ): Promise<operations.GetApiSandboxByIdTracesResponse> {
+    return unwrapAsync(sandboxGetApiSandboxByIdTraces(
+      this,
+      request,
+      options,
+    ));
+  }
+}

package/src/sdk/sdk.ts

@@ -8,6 +8,7 @@ import { Invitations } from "./invitations.js";
 import { OrganizationMembers } from "./organization-members.js";
 import { Organizations } from "./organizations.js";
 import { ProviderConfigs } from "./provider-configs.js";
+import { Sandbox } from "./sandbox.js";
 import { UserProfile } from "./user-profile.js";
 import { WorkspaceMembers } from "./workspace-members.js";
 import { Workspaces } from "./workspaces.js";
@@ -54,4 +55,9 @@ export class Mutagent extends ClientSDK {
   get invitations(): Invitations {
     return (this._invitations ??= new Invitations(this._options));
   }
+
+  private _sandbox?: Sandbox;
+  get sandbox(): Sandbox {
+    return (this._sandbox ??= new Sandbox(this._options));
+  }
 }