@mutagent/sdk 0.6.1 → 0.6.2

package/README.md

@@ -1,179 +1,65 @@
-# MutagenT SDK
+![MutagenT](../assets/brand/mutagent-banner.svg)
 
-<!-- NOTE: README.npm.md is the public-facing README for npm publish.
-     See publish workflow for copy step. -->
-
-```bash
-╔════════════════════════════════════════════════════════════════════════════════════════════╗
-║                                                                                            ║
-║        ███╗   ███╗██╗   ██╗████████╗ █████╗  ██████╗ ███████╗███╗   ██╗████████╗           ║
-║        ████╗ ████║██║   ██║╚══██╔══╝██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝           ║
-║        ██╔████╔██║██║   ██║   ██║   ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║              ║
-║        ██║╚██╔╝██║██║   ██║   ██║   ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║              ║
-║        ██║ ╚═╝ ██║╚██████╔╝   ██║   ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║              ║
-║        ╚═╝     ╚═╝ ╚═════╝    ╚═╝   ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝              ║
-║                                                                                            ║
-║                   ███████╗██████╗ ██╗  ██╗                                                 ║
-║                   ██╔════╝██╔══██╗██║ ██╔╝                                                 ║
-║                   ███████╗██║  ██║█████╔╝                                                  ║
-║                   ╚════██║██║  ██║██╔═██╗                                                  ║
-║                   ███████║██████╔╝██║  ██╗                                                 ║
-║                   ╚══════╝╚═════╝ ╚═╝  ╚═╝                                                 ║
-║                                                                                            ║
-║                         TypeScript SDK for AI-Native Development.                          ║
-║                                                                                            ║
-╚════════════════════════════════════════════════════════════════════════════════════════════╝
-```
+# MutagenT TypeScript SDK
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@mutagent/sdk"><img src="https://img.shields.io/npm/v/@mutagent/sdk?style=for-the-badge&color=cb3837&logo=npm&logoColor=white" alt="npm"></a>
   <a href="https://bun.sh"><img src="https://img.shields.io/badge/Bun-1.1+-f472b6?style=for-the-badge&logo=bun&logoColor=white" alt="Bun"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-18+-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js"></a>
   <a href="https://www.typescriptlang.org"><img src="https://img.shields.io/badge/TypeScript-5.0+-3178C6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript"></a>
-  <a href="#"><img src="https://img.shields.io/badge/License-Proprietary-ff6b6b?style=for-the-badge" alt="License: Proprietary"></a>
+  <a href="#"><img src="https://img.shields.io/badge/License-Apache_2.0-blue?style=for-the-badge" alt="License: Apache 2.0"></a>
 </p>
 
 <p align="center">
   <em>The TypeScript client for the MutagenT platform API.</em>
 </p>
 
----
-
-## What the SDK covers
-
-`@mutagent/sdk` is generated from the MutagenT platform OpenAPI document. One `Mutagent` client
-exposes 13 groups of methods:
-
-| Group | What it calls |
-|-------|---------------|
-| `userProfile` | The signed-in user's profile, password and login sessions |
-| `organizations` | Organizations, slug lookups and member counts |
-| `organizationMembers` | Organization membership and roles |
-| `workspaces` | Workspaces and the default workspace |
-| `workspaceMembers` | Workspace membership and roles |
-| `invitations` | Organization invitations |
-| `agents` | Agent records: create, read, update, delete, look up by slug |
-| `llmProviders` | LLM provider configurations, model catalog, connection tests |
-| `managedAgents` | Managed agent deployments: slots, revisions, operations |
-| `traces` | Trace ingestion and reads of traces, spans and logs |
-| `sandbox` | Sandbox providers, presets, sandbox lifecycle, commands, the sandbox token exchange, and Helix sessions addressed by sandbox id |
-| `environments` | Workspace Environments (named sets of variables and secrets) |
-| `helixSessions` | Helix sessions addressed by session reference: launch, list, input, signal, checkpoint, restore, stream |
-
-Every method is also available as a standalone function (see [Standalone functions](#standalone-functions)).
+**Status:** `@mutagent/sdk` is on `0.6.1`, generated from `openapi.json` via Speakeasy. 13 client groups, all with sync methods and standalone-function equivalents. The manual tracing subsystem (`src/tracing/`) documented in older revisions of this file has been removed — tracing/observability was retired platform-wide; there is no `./tracing` export and no tracing tests in this package today.
 
 ---
 
-## 0.6.0 breaking changes
-
-0.6.0 is one breaking release after 0.5.x. Code written against 0.5.x needs the following changes.
-
-**Client groups**
-
-- `sandbox` holds sandbox providers, presets, the sandbox lifecycle, commands, the token exchange
-  (`createSandboxToken`) and the session routes addressed by sandbox id.
-- New group `helixSessions`: `launchHelixSession`, `listHelixSessions`, `sendHelixSessionInput`,
-  `closeHelixSessionInput`, `signalHelixSession`, `checkpointHelixSession`,
-  `listHelixSessionCheckpoints`, `restoreHelixSession`, `streamHelixSession`, `getHelixModels`,
-  `setHelixDefaultModels`. The ones that existed in 0.5.x were methods of `sandbox`.
-- New group `environments`. In 0.5.x its operations were methods of `sandbox`.
-- `helixAgentDeployments` is renamed `managedAgents`. Its method names are unchanged.
-- `providerConfigs` is renamed `llmProviders`. Its methods are renamed too; see the table below.
-- `userProfile` keeps its name. Two of its methods are renamed; see the table below.
-
-**Operation names**
-
-39 operations are renamed. In the first 27 rows the 0.5.x name was derived from the route. The last
-12 rows rename operations that already had their own names.
-
-| 0.5.x | 0.6.0 |
-|-------|-------|
-| `sandbox.getApiSandboxProviders` | `sandbox.listSandboxProviders` |
-| `sandbox.postApiSandboxPreflight` | `sandbox.preflightSandbox` |
-| `sandbox.getApiSandboxPresets` | `sandbox.listSandboxPresets` |
-| `sandbox.postApiSandboxRun` | `sandbox.runSandboxCommand` |
-| `sandbox.postApiSandbox` | `sandbox.createSandbox` |
-| `sandbox.getApiSandbox` | `sandbox.listSandboxes` |
-| `sandbox.getApiSandboxById` | `sandbox.getSandbox` |
-| `sandbox.deleteApiSandboxById` | `sandbox.deleteSandbox` |
-| `sandbox.getApiSandboxByIdStream` | `sandbox.streamSandbox` |
-| `sandbox.postApiSandboxByIdExec` | `sandbox.execSandboxCommand` |
-| `sandbox.postApiSandboxTelemetryV1Traces` | `sandbox.ingestSandboxTraces` |
-| `sandbox.getApiSandboxByIdTraces` | `sandbox.listSandboxSpans` |
-| `sandbox.postApiSandboxByIdSession` | `sandbox.startSandboxHelixSession` |
-| `sandbox.getApiSandboxHelixDefaults` | `helixSessions.getHelixModels` |
-| `sandbox.putApiSandboxHelixDefaults` | `helixSessions.setHelixDefaultModels` |
-| `sandbox.getApiSandboxByIdSessions` | `sandbox.listSandboxHelixSessions` |
-| `sandbox.postApiSandboxByIdInput` | `sandbox.sendSandboxHelixSessionInput` |
-| `sandbox.postApiSandboxByIdSignal` | `sandbox.signalSandboxHelixSession` |
-| `sandbox.postApiSandboxByIdCheckpoint` | `sandbox.checkpointSandboxHelixSession` |
-| `sandbox.getApiSandboxByIdCheckpoints` | `sandbox.listSandboxCheckpoints` |
-| `sandbox.postApiSandboxByIdRestore` | `sandbox.restoreSandbox` |
-| `sandbox.postApiSandboxToken` | `sandbox.createSandboxToken` |
-| `sandbox.getApiSandboxEnvironments` | `environments.listEnvironments` |
-| `sandbox.getApiSandboxEnvironmentsByName` | `environments.getEnvironment` |
-| `sandbox.putApiSandboxEnvironmentsByName` | `environments.replaceEnvironment` |
-| `sandbox.patchApiSandboxEnvironmentsByName` | `environments.updateEnvironment` |
-| `sandbox.deleteApiSandboxEnvironmentsByName` | `environments.deleteEnvironment` |
-| `userProfile.listSessions` | `userProfile.listUserSessions` |
-| `userProfile.deleteSession` | `userProfile.revokeUserSession` |
-| `sandbox.listHelixWorkspaceSessions` | `helixSessions.listHelixSessions` |
-| `sandbox.inputHelixSession` | `helixSessions.sendHelixSessionInput` |
-| `providerConfigs.listProviders` | `llmProviders.listProviderConfigs` |
-| `providerConfigs.createProvider` | `llmProviders.createProviderConfig` |
-| `providerConfigs.getProvider` | `llmProviders.getProviderConfig` |
-| `providerConfigs.updateProvider` | `llmProviders.updateProviderConfig` |
-| `providerConfigs.deleteProvider` | `llmProviders.deleteProviderConfig` |
-| `providerConfigs.getModelsCatalog` | `llmProviders.getModelCatalog` |
-| `providerConfigs.listProviderModels` | `llmProviders.listProviderConfigModels` |
-| `providerConfigs.testProvider` | `llmProviders.testProviderConfig` |
-
-The standalone function names follow the same change, including the group prefix. For example
-`sandboxGetApiSandboxById` is now `sandboxGetSandbox`, and `providerConfigsTestProvider` is now
-`llmProvidersTestProviderConfig`.
-
-**Model, enum and error names**
-
-Model, enum and error class names come from the schema names in the API document, for example
-`Mode`, `HelixArm`, `HelixSignal`, `HelixLaunchRequest`, `LlmProviderType` and
-`ErrorResponse`. Names the generator invented in 0.5.x, such as `Schemadefaul7`, `ModeArmModel` and
-`NameSlugDescription5`, no longer exist.
+## Context
 
-**Session mode values**
+`@mutagent/sdk` is the official TypeScript client for the MutagenT platform API. One `Mutagent` client class exposes every route in the platform's OpenAPI document as a typed method, grouped by API tag. See the [root README](../README.md) for where this SDK sits relative to the platform API and the other clients (Python SDK, CLI, `mutagent-client`).
 
-A Helix session mode is `headless` or `interactive` (`Mode.Headless`, `Mode.Interactive`). The
-0.5.x values `oneshot` and `rpc` are gone.
+## Concepts
 
-**Default server**
-
-The default server is `https://api.mutagent.io`. In 0.5.x it was `http://localhost:3003`. To call a
-local server, pass `serverURL: "http://localhost:3003"` or `serverIdx: 1`.
-
-**Streams**
-
-`streamHelixSession` and `streamSandbox` send `Accept: text/event-stream`. They resolve to the event
-text as one string when the server closes the stream. They do not yield events as they arrive.
-
----
+- **Client groups** — one namespace per API tag on the `Mutagent` instance (`mutagent.agents`, `mutagent.sandbox`, …). See the table in [Components](#components).
+- **Security schemes** — `apiKey` (`x-api-key` header) and `bearerAuth` (`Authorization: Bearer`), set via the `security` client option or per environment variable; see [Configuration](#configuration).
+- **Sandbox token** — a short-lived bearer credential, exchanged for an API key via `sandbox.createSandboxToken`, required by the `sandbox`, `environments` and `helixSessions` groups.
+- **Standalone functions** — every method is also exported as a tree-shakeable function for bundle-size-sensitive apps; rationale and pattern in [FUNCTIONS.md](./FUNCTIONS.md), per-operation names in [docs/sdks/](./docs/sdks/).
+- **Streaming** — `streamHelixSession` / `streamSandbox` resolve to the whole event text as one string after the server closes the connection; they do not yield events incrementally.
+- **Pagination** — endpoints that page resolve to a response that is also an async iterable (`for await...of`).
 
-## Installation
+## Components
 
-```bash
-npm install @mutagent/sdk
-# or
-pnpm add @mutagent/sdk
-# or
-bun add @mutagent/sdk
-# or
-yarn add @mutagent/sdk
+```
+mutagent-sdk/
+├── openapi.json      # fetched from server, processed by scripts/fix-openapi.ts
+├── .speakeasy/        # Speakeasy config (gen.yaml, workflow.yaml, gen.lock)
+├── src/
+│   ├── sdk/           # [generated] client classes, one file per group
+│   ├── models/        # [generated] request/response types, errors
+│   ├── funcs/         # [generated] standalone functions
+│   └── lib/           # [generated] HTTP client, config, security, retries
+├── docs/sdks/          # [generated] one page per group: every method, parameter, error
+├── examples/           # [generated] runnable usage examples
+├── __tests__/unit/     # [manual] tests for the generation scripts (fix-openapi.ts etc.)
+├── scripts/            # [manual] generate-sdk.sh, fix-openapi.ts, post-generate.ts
+└── README.md           # this file — not tracked by Speakeasy, safe to hand-edit
 ```
 
-This package ships CommonJS (`require`) and ES module (`import`) builds. Supported runtimes are listed
-in [RUNTIMES.md](./RUNTIMES.md).
+| Command | What it does |
+| --- | --- |
+| `npm add @mutagent/sdk` / `bun add @mutagent/sdk` | Install (npm, pnpm, Bun and Yarn all work; CJS + ESM builds ship) |
+| `bun run build` | tshy dual ESM + CommonJS build |
+| `bun test __tests__/unit` | Runs the unit tests for the generation scripts (the only hand-written tests) |
+| `bun run lint` | ESLint |
+| `./scripts/generate-sdk.sh` | Full pipeline: fetch spec → `fix-openapi.ts` → `speakeasy run` → `post-generate.ts`. Needs the MutagenT API on `http://localhost:3003` and the `speakeasy` CLI |
 
----
+Supported runtimes and recommended `tsconfig.json` options: [RUNTIMES.md](./RUNTIMES.md).
 
-## Quick Start
+### Quick start
 
 ```typescript
 import { Mutagent } from "@mutagent/sdk";
@@ -195,37 +81,18 @@ async function run() {
 run();
 ```
 
----
-
-## Authentication
-
-The `security` option has two fields. Both are read from the environment when you do not pass them.
+### Authentication
 
-| Option | Sent as | Environment variable | Used by |
-|--------|---------|----------------------|---------|
-| `apiKey` | `x-api-key` header | `MUTAGENT_API_KEY` | Every group except `sandbox`, `environments` and `helixSessions` |
-| `bearerAuth` | `Authorization: Bearer` header | `MUTAGENT_BEARER_AUTH` | `sandbox` (except `createSandboxToken`), `environments` and `helixSessions`, which accept no other credential. The other groups also declare it |
+The `security` option has two fields, each read from its environment variable when not passed explicitly (see [Configuration](#configuration)):
 
-When an operation accepts both and both are set, the SDK sends the API key.
-
-### API key
-
-A platform API key starts with `mg_live_`. Create one in the MutagenT app under Settings, API Keys.
-
-```typescript
-import { Mutagent } from "@mutagent/sdk";
-
-const mutagent = new Mutagent({
-  security: { apiKey: process.env["MUTAGENT_API_KEY"] ?? "" },
-});
-```
+| Option | Sent as | Used by |
+|--------|---------|---------|
+| `apiKey` | `x-api-key` header | Every group except `sandbox`, `environments` and `helixSessions` |
+| `bearerAuth` | `Authorization: Bearer` header | `sandbox` (except `createSandboxToken`), `environments` and `helixSessions` |
 
-### Sandbox token
+When an operation accepts both and both are set, the SDK sends the API key. `security` also accepts an async function that returns the credentials, useful for refreshing a sandbox token before it expires.
 
-The `sandbox`, `environments` and `helixSessions` operations do not accept an API key. They require a
-short-lived sandbox token, sent as a bearer token. Exchange an API key for one with
-`sandbox.createSandboxToken`. That call takes the API key in its own first argument; it does not read
-the client's `security` option or `MUTAGENT_API_KEY`.
+The `sandbox`, `environments` and `helixSessions` operations require a short-lived sandbox token instead of an API key. Exchange one with `sandbox.createSandboxToken`, which takes the API key as its own argument (it does not read `security` or `MUTAGENT_API_KEY`):
 
 ```typescript
 import { Mutagent } from "@mutagent/sdk";
@@ -240,345 +107,322 @@ async function sandboxClient(workspaceId: string): Promise<Mutagent> {
   );
   console.log(`sandbox token expires in ${expiresIn}s`);
 
-  // apiKey stays in place for the platform groups; bearerAuth is used by
-  // sandbox, environments and helixSessions.
   return new Mutagent({ security: { apiKey, bearerAuth: token } });
 }
 ```
 
-`security` also accepts an async function that returns the credentials, which lets you refresh the
-sandbox token before it expires.
+### Client groups
 
----
-
-## Client groups
+Full per-method reference — every parameter and response type — lives in [docs/sdks/](./docs/sdks/), one page per group:
 
-The examples below assume a client built as in [Authentication](#authentication). Examples for
-`sandbox`, `environments` and `helixSessions` need a client that holds a sandbox token.
+| Group | Covers | Reference |
+| --- | --- | --- |
+| `userProfile` | The signed-in user's profile, password and login sessions | [docs/sdks/userprofile/](docs/sdks/userprofile/README.md) |
+| `organizations` | Organizations, slug lookups and member counts | [docs/sdks/organizations/](docs/sdks/organizations/README.md) |
+| `organizationMembers` | Organization membership and roles | [docs/sdks/organizationmembers/](docs/sdks/organizationmembers/README.md) |
+| `workspaces` | Workspaces and the default workspace | [docs/sdks/workspaces/](docs/sdks/workspaces/README.md) |
+| `workspaceMembers` | Workspace membership and roles | [docs/sdks/workspacemembers/](docs/sdks/workspacemembers/README.md) |
+| `invitations` | Organization invitations | [docs/sdks/invitations/](docs/sdks/invitations/README.md) |
+| `agents` | Agent records: create, read, update, delete, look up by slug | [docs/sdks/agents/](docs/sdks/agents/README.md) |
+| `llmProviders` | LLM provider configurations, model catalog, connection tests | [docs/sdks/llmproviders/](docs/sdks/llmproviders/README.md) |
+| `managedAgents` | Managed agent deployments: slots, revisions, operations | [docs/sdks/managedagents/](docs/sdks/managedagents/README.md) |
+| `traces` | Trace ingestion and reads of traces, spans and logs | [docs/sdks/traces/](docs/sdks/traces/README.md) |
+| `sandbox` | Sandbox providers, presets, lifecycle, commands, token exchange, sandbox-hosted Helix sessions | [docs/sdks/sandbox/](docs/sdks/sandbox/README.md) |
+| `environments` | Workspace Environments (named sets of variables and secrets) | [docs/sdks/environments/](docs/sdks/environments/README.md) |
+| `helixSessions` | Helix sessions addressed by session reference: launch, list, input, signal, checkpoint, restore, stream | [docs/sdks/helixsessions/](docs/sdks/helixsessions/README.md) |
 
-### userProfile
+Two representative examples (the rest are one call each, per the reference pages above):
 
 ```typescript
 import { Mutagent } from "@mutagent/sdk";
+import { LlmProviderType } from "@mutagent/sdk/models";
 
 async function example(mutagent: Mutagent) {
-  const profile = await mutagent.userProfile.getProfile();
-  const sessions = await mutagent.userProfile.listUserSessions();
-  console.log(profile, sessions);
+  const provider = await mutagent.llmProviders.createProviderConfig({
+    name: "Anthropic",
+    provider: LlmProviderType.Anthropic,
+    apiKey: process.env["ANTHROPIC_API_KEY"] ?? "",
+  });
+  console.log(await mutagent.llmProviders.testProviderConfig({ id: provider.id }));
 }
 ```
 
-### organizations
-
 ```typescript
 import { Mutagent } from "@mutagent/sdk";
+import { HelixSignal, Mode } from "@mutagent/sdk/models";
 
+// Requires a sandbox token (see Authentication above).
 async function example(mutagent: Mutagent) {
-  const organization = await mutagent.organizations.getOrganizationBySlug({ slug: "acme" });
-  const memberCount = await mutagent.organizations.getOrganizationMemberCount({ orgId: "<org-id>" });
-  console.log(organization, memberCount);
+  const session = await mutagent.helixSessions.launchHelixSession({
+    mode: Mode.Interactive,
+    environment: "staging",
+  });
+  await mutagent.helixSessions.sendHelixSessionInput({
+    reference: session.reference,
+    body: { line: JSON.stringify({ type: "prompt", id: "p1", message: "List the files" }) },
+  });
+  await mutagent.helixSessions.signalHelixSession({
+    reference: session.reference,
+    body: { signal: HelixSignal.Sigint },
+  });
 }
 ```
 
-### organizationMembers
+### Streaming
 
 ```typescript
-import { Mutagent } from "@mutagent/sdk";
-
-async function example(mutagent: Mutagent) {
-  const members = await mutagent.organizationMembers.listOrganizationMembers({ orgId: "<org-id>" });
-  console.log(members);
+async function example(mutagent: Mutagent, reference: string) {
+  const eventText = await mutagent.helixSessions.streamHelixSession({ reference });
+  for (const block of eventText.split("\n\n")) {
+    console.log(block);
+  }
 }
 ```
 
-### workspaces
+Pass the last `seq` you have read as `since` to receive only later events.
 
-```typescript
-import { Mutagent } from "@mutagent/sdk";
-
-async function example(mutagent: Mutagent) {
-  const workspace = await mutagent.workspaces.createWorkspace({
-    name: "Support",
-    slug: "support",
-  });
-  await mutagent.workspaces.setDefaultWorkspace({ wsId: workspace.id });
-}
-```
+### Error handling
 
-### workspaceMembers
+Every HTTP error extends `MutagentError`; most operations also document `ErrorResponse` (`error`, `message`). Full error class list: [Reference § Error classes](#error-classes).
 
 ```typescript
-import { Mutagent } from "@mutagent/sdk";
+import * as errors from "@mutagent/sdk/models/errors";
 
 async function example(mutagent: Mutagent) {
-  const members = await mutagent.workspaceMembers.listWorkspaceMembers({ wsId: "<workspace-id>" });
-  console.log(members);
+  try {
+    await mutagent.agents.getAgent({ id: 404 });
+  } catch (error) {
+    if (error instanceof errors.ErrorResponse) {
+      console.error(error.statusCode, error.data$.error, error.data$.message);
+    } else if (error instanceof errors.MutagentError) {
+      console.error(`HTTP ${error.statusCode}: ${error.body}`);
+    } else {
+      throw error;
+    }
+  }
 }
 ```
 
-### invitations
+## Configuration
 
-```typescript
-import { Mutagent } from "@mutagent/sdk";
-import { OrganizationRole } from "@mutagent/sdk/models";
+| Variable | Required | Default | Read at | Secret | Purpose |
+| --- | --- | --- | --- | --- | --- |
+| `MUTAGENT_API_KEY` | No (or pass `security.apiKey`) | none | `src/lib/security.ts:255` | Yes | Fallback for the `apiKey` security scheme |
+| `MUTAGENT_BEARER_AUTH` | No (or pass `security.bearerAuth`) | none | `src/lib/security.ts:262` | Yes | Fallback for the `bearerAuth` security scheme (sandbox token) |
+| `MUTAGENT_DEBUG` | No | `false` | `src/lib/sdks.ts:114` | No | Enables `console` debug logging when no `debugLogger` option is passed — reveals secrets in log output, development only |
 
-async function example(mutagent: Mutagent) {
-  const invitation = await mutagent.invitations.createInvitation({
-    orgId: "<org-id>",
-    body: { email: "dev@example.com", role: OrganizationRole.Editor },
-  });
-  console.log(invitation.id);
-}
-```
+All three are user-set (this package owns no platform infrastructure). The default server URL is not an environment variable — it is hardcoded to `https://api.mutagent.io` in [`src/lib/config.ts`](src/lib/config.ts) (index `0` in the server list; `http://localhost:3003` is index `1`), overridable via the `serverURL` or `serverIdx` client options. See [`.env.example`](.env.example) for placeholder values.
 
-### agents
+---
 
-```typescript
-import { Mutagent } from "@mutagent/sdk";
+## Reference
 
-async function example(mutagent: Mutagent) {
-  const agent = await mutagent.agents.createAgent({
-    name: "Support Agent",
-    slug: "support-agent",
-    systemPrompt: "You answer customer support questions.",
-  });
+### API naming migration
 
-  const sameAgent = await mutagent.agents.getAgentBySlug({ slug: "support-agent" });
-  await mutagent.agents.updateAgent({ id: agent.id, body: { description: "Tier 1 support" } });
-  console.log(sameAgent.id === agent.id);
-}
-```
+The checked-in client is `0.6.1` on npm. `0.6.0` was the first release published under a version number that officially carries the renamed groups and operations below; `0.5.13`, published about twelve minutes earlier from the same source changes, already carried the same renames under the old numbering (see [PR #2113](https://github.com/architech-printworks/mutagent-monorepo/pull/2113)).
 
-### llmProviders
+**Client groups**
 
-```typescript
-import { Mutagent } from "@mutagent/sdk";
-import { LlmProviderType } from "@mutagent/sdk/models";
+- `sandbox` holds sandbox providers, presets, the sandbox lifecycle, commands, the token exchange (`createSandboxToken`) and the session routes addressed by sandbox id.
+- New group `helixSessions`: `launchHelixSession`, `listHelixSessions`, `sendHelixSessionInput`, `closeHelixSessionInput`, `signalHelixSession`, `checkpointHelixSession`, `listHelixSessionCheckpoints`, `restoreHelixSession`, `streamHelixSession`, `getHelixModels`, `setHelixDefaultModels`. These existed as `sandbox` methods in `0.5.x`.
+- New group `environments`. In `0.5.x` its operations were methods of `sandbox`.
+- `helixAgentDeployments` is renamed `managedAgents`; method names are unchanged.
+- `providerConfigs` is renamed `llmProviders`; its methods are renamed too (table below).
+- `userProfile` keeps its name; two of its methods are renamed (table below).
 
-async function example(mutagent: Mutagent) {
-  const provider = await mutagent.llmProviders.createProviderConfig({
-    name: "Anthropic",
-    provider: LlmProviderType.Anthropic,
-    apiKey: process.env["ANTHROPIC_API_KEY"] ?? "",
-  });
+<details><summary>39 renamed operations</summary>
 
-  const test = await mutagent.llmProviders.testProviderConfig({ id: provider.id });
-  const models = await mutagent.llmProviders.listProviderConfigModels({ id: provider.id });
-  console.log(test, models);
-}
-```
+| Previous name | Checked-in name |
+|-------|-------|
+| `sandbox.getApiSandboxProviders` | `sandbox.listSandboxProviders` |
+| `sandbox.postApiSandboxPreflight` | `sandbox.preflightSandbox` |
+| `sandbox.getApiSandboxPresets` | `sandbox.listSandboxPresets` |
+| `sandbox.postApiSandboxRun` | `sandbox.runSandboxCommand` |
+| `sandbox.postApiSandbox` | `sandbox.createSandbox` |
+| `sandbox.getApiSandbox` | `sandbox.listSandboxes` |
+| `sandbox.getApiSandboxById` | `sandbox.getSandbox` |
+| `sandbox.deleteApiSandboxById` | `sandbox.deleteSandbox` |
+| `sandbox.getApiSandboxByIdStream` | `sandbox.streamSandbox` |
+| `sandbox.postApiSandboxByIdExec` | `sandbox.execSandboxCommand` |
+| `sandbox.postApiSandboxTelemetryV1Traces` | `sandbox.ingestSandboxTraces` |
+| `sandbox.getApiSandboxByIdTraces` | `sandbox.listSandboxSpans` |
+| `sandbox.postApiSandboxByIdSession` | `sandbox.startSandboxHelixSession` |
+| `sandbox.getApiSandboxHelixDefaults` | `helixSessions.getHelixModels` |
+| `sandbox.putApiSandboxHelixDefaults` | `helixSessions.setHelixDefaultModels` |
+| `sandbox.getApiSandboxByIdSessions` | `sandbox.listSandboxHelixSessions` |
+| `sandbox.postApiSandboxByIdInput` | `sandbox.sendSandboxHelixSessionInput` |
+| `sandbox.postApiSandboxByIdSignal` | `sandbox.signalSandboxHelixSession` |
+| `sandbox.postApiSandboxByIdCheckpoint` | `sandbox.checkpointSandboxHelixSession` |
+| `sandbox.getApiSandboxByIdCheckpoints` | `sandbox.listSandboxCheckpoints` |
+| `sandbox.postApiSandboxByIdRestore` | `sandbox.restoreSandbox` |
+| `sandbox.postApiSandboxToken` | `sandbox.createSandboxToken` |
+| `sandbox.getApiSandboxEnvironments` | `environments.listEnvironments` |
+| `sandbox.getApiSandboxEnvironmentsByName` | `environments.getEnvironment` |
+| `sandbox.putApiSandboxEnvironmentsByName` | `environments.replaceEnvironment` |
+| `sandbox.patchApiSandboxEnvironmentsByName` | `environments.updateEnvironment` |
+| `sandbox.deleteApiSandboxEnvironmentsByName` | `environments.deleteEnvironment` |
+| `userProfile.listSessions` | `userProfile.listUserSessions` |
+| `userProfile.deleteSession` | `userProfile.revokeUserSession` |
+| `sandbox.listHelixWorkspaceSessions` | `helixSessions.listHelixSessions` |
+| `sandbox.inputHelixSession` | `helixSessions.sendHelixSessionInput` |
+| `providerConfigs.listProviders` | `llmProviders.listProviderConfigs` |
+| `providerConfigs.createProvider` | `llmProviders.createProviderConfig` |
+| `providerConfigs.getProvider` | `llmProviders.getProviderConfig` |
+| `providerConfigs.updateProvider` | `llmProviders.updateProviderConfig` |
+| `providerConfigs.deleteProvider` | `llmProviders.deleteProviderConfig` |
+| `providerConfigs.getModelsCatalog` | `llmProviders.getModelCatalog` |
+| `providerConfigs.listProviderModels` | `llmProviders.listProviderConfigModels` |
+| `providerConfigs.testProvider` | `llmProviders.testProviderConfig` |
 
-### managedAgents
+Standalone function names follow the same change, including the group prefix (e.g. `sandboxGetApiSandboxById` → `sandboxGetSandbox`).
 
-```typescript
-import { Mutagent } from "@mutagent/sdk";
+</details>
 
-async function example(mutagent: Mutagent) {
-  const agents = await mutagent.managedAgents.listHelixAgents({ limit: 20 });
-  for (const agent of agents.data) {
-    const detail = await mutagent.managedAgents.getHelixAgent({ slug: agent.slug });
-    console.log(detail);
-  }
-}
-```
+- **Model, enum and error names** come from the schema names in the API document (`Mode`, `HelixArm`, `HelixSignal`, `HelixLaunchRequest`, `LlmProviderType`, `ErrorResponse`). Generator-invented names from `0.5.x` (`Schemadefaul7`, `ModeArmModel`, `NameSlugDescription5`) no longer exist.
+- **Session mode values**: `headless` or `interactive` (`Mode.Headless`, `Mode.Interactive`). The `0.5.x` values `oneshot` and `rpc` are gone.
+- **Default server**: `https://api.mutagent.io`; was `http://localhost:3003` in `0.5.x`. Pass `serverURL: "http://localhost:3003"` or `serverIdx: 1` for a local server.
 
-### traces
+### Standalone functions
 
-```typescript
-import { Mutagent } from "@mutagent/sdk";
+Every method above is also available as a standalone function, for bundlers that tree-shake unused functionality. Rationale and a worked example: [FUNCTIONS.md](./FUNCTIONS.md). The standalone function name for each operation is listed on its own page under [docs/sdks/](./docs/sdks/) (one page per group — see the [Client groups](#client-groups) table above), under that operation's "Standalone function" heading.
 
-async function example(mutagent: Mutagent) {
-  const traces = await mutagent.traces.listTraces({ limit: 10 });
-  for (const trace of traces.data) {
-    const spans = await mutagent.traces.listTraceSpans({ traceId: trace.traceId });
-    console.log(trace.traceId, spans);
+### Pagination
+
+```typescript
+async function run(mutagent: Mutagent) {
+  const result = await mutagent.agents.listAgents({ limit: 0, offset: 0, isPublic: false });
+  for await (const page of result) {
+    console.log(page);
   }
 }
 ```
 
-### sandbox
+### Retries
 
-Requires a sandbox token (see [Sandbox token](#sandbox-token)).
+Endpoints that support retries fall back to the API's default retry strategy. Override per call or for the whole SDK:
 
 ```typescript
-import { Mutagent } from "@mutagent/sdk";
-import { SandboxArch } from "@mutagent/sdk/models";
-
-async function example(mutagent: Mutagent) {
-  // One command in a new sandbox, deleted after the run.
-  const run = await mutagent.sandbox.runSandboxCommand({ command: ["uname", "-a"] });
-  console.log(run.exitCode, run.stdout);
+// Per call
+await mutagent.userProfile.getProfile({
+  retries: {
+    strategy: "backoff",
+    backoff: { initialInterval: 1, maxInterval: 50, exponent: 1.1, maxElapsedTime: 100 },
+    retryConnectionErrors: false,
+  },
+});
 
-  // A sandbox you keep, run commands in, and delete.
-  const sandbox = await mutagent.sandbox.createSandbox({
-    definition: { name: "build", image: "<image>", arch: SandboxArch.X8664 },
-  });
-  const result = await mutagent.sandbox.execSandboxCommand({
-    id: sandbox.id,
-    body: { command: ["ls", "-la"] },
-  });
-  console.log(result.exitCode, result.stdout, result.stderr);
-  await mutagent.sandbox.deleteSandbox({ id: sandbox.id });
-}
+// SDK-wide
+const mutagent = new Mutagent({
+  retryConfig: {
+    strategy: "backoff",
+    backoff: { initialInterval: 1, maxInterval: 50, exponent: 1.1, maxElapsedTime: 100 },
+    retryConnectionErrors: false,
+  },
+  security: { apiKey: process.env["MUTAGENT_API_KEY"] ?? "" },
+});
 ```
 
-### environments
-
-Requires a sandbox token.
+### Error classes
 
-```typescript
-import { Mutagent } from "@mutagent/sdk";
+[`MutagentError`](./src/models/errors/mutagent-error.ts) is the base class; it carries `message`, `statusCode`, `headers`, `body`, `rawResponse` and an optional `data$` for structured errors.
 
-async function example(mutagent: Mutagent) {
-  await mutagent.environments.replaceEnvironment({
-    name: "staging",
-    body: {
-      vars: { LOG_LEVEL: "debug" },
-      secrets: { DATABASE_URL: "<secret>" },
-    },
-  });
+<details><summary>18 less-common error classes</summary>
 
-  const environments = await mutagent.environments.listEnvironments();
-  console.log(environments);
-}
-```
+**Network errors:**
+* [`ConnectionError`](./src/models/errors/http-client-errors.ts): HTTP client was unable to make a request to a server.
+* [`RequestTimeoutError`](./src/models/errors/http-client-errors.ts): HTTP request timed out due to an AbortSignal signal.
+* [`RequestAbortedError`](./src/models/errors/http-client-errors.ts): HTTP request was aborted by the client.
+* [`InvalidRequestError`](./src/models/errors/http-client-errors.ts): Any input used to create a request is invalid.
+* [`UnexpectedClientError`](./src/models/errors/http-client-errors.ts): Unrecognised or unexpected error.
 
-### helixSessions
+**Inherit from `MutagentError`:**
+* [`ErrorResponse`](./src/models/errors/error-response.ts): Applicable to 75 of 96 methods.
+* [`ErrorResponseWithStatus`](./src/models/errors/error-response-with-status.ts): Applicable to 61 of 96 methods.
+* [`ProviderError`](./src/models/errors/provider-error.ts): Applicable to 8 of 96 methods.
+* [`DeploymentError`](./src/models/errors/deployment-error.ts): Response for status 400. Applicable to 7 of 96 methods.
+* [`WsError`](./src/models/errors/ws-error.ts): Applicable to 6 of 96 methods.
+* [`SandboxPayloadTooLargeError`](./src/models/errors/sandbox-payload-too-large-error.ts): Status `413`. Applicable to 5 of 96 methods.
+* [`ModelNotInListError`](./src/models/errors/model-not-in-list-error.ts): Status `422`. Applicable to 5 of 96 methods.
+* [`ModelResolutionError`](./src/models/errors/model-resolution-error.ts): Status `422`. Applicable to 5 of 96 methods.
+* [`NoProviderConfiguredError`](./src/models/errors/no-provider-configured-error.ts): Status `428`. Applicable to 4 of 96 methods.
+* [`TestConnectionResultError`](./src/models/errors/test-connection-result-error.ts): Provider connection test result. Applicable to 1 of 96 methods.
+* [`WorkspaceModelListingError`](./src/models/errors/workspace-model-listing-error.ts): Applicable to 1 of 96 methods.
+* [`SandboxProviderUnreachableError`](./src/models/errors/sandbox-provider-unreachable-error.ts): Status `503`. Applicable to 1 of 96 methods.
+* [`ResponseValidationError`](./src/models/errors/response-validation-error.ts): Type mismatch between the server response and the SDK's expected structure. See `error.rawValue` / `error.pretty()`.
 
-Requires a sandbox token. A `headless` session runs the task in its arguments and ends. An
-`interactive` session stays open and reads one JSON command per `sendHelixSessionInput` call.
+</details>
 
-```typescript
-import { Mutagent } from "@mutagent/sdk";
-import { HelixSignal, Mode } from "@mutagent/sdk/models";
+### Server selection
 
-async function example(mutagent: Mutagent) {
-  const headless = await mutagent.helixSessions.launchHelixSession({
-    mode: Mode.Headless,
-    args: ["-p", "Summarise the README in the working directory"],
-  });
-  console.log(headless.reference, headless.sandboxId);
+| # | Server | Description |
+| --- | --- | --- |
+| 0 | `https://api.mutagent.io` | Production |
+| 1 | `http://localhost:3003` | Development server |
 
-  const session = await mutagent.helixSessions.launchHelixSession({
-    mode: Mode.Interactive,
-    environment: "staging",
-  });
-  await mutagent.helixSessions.sendHelixSessionInput({
-    reference: session.reference,
-    body: { line: JSON.stringify({ type: "prompt", id: "p1", message: "List the files" }) },
-  });
-  await mutagent.helixSessions.signalHelixSession({
-    reference: session.reference,
-    body: { signal: HelixSignal.Sigint },
-  });
-}
+```typescript
+const mutagent = new Mutagent({ serverIdx: 0, security: { apiKey: process.env["MUTAGENT_API_KEY"] ?? "" } });
+// or
+const mutagent = new Mutagent({ serverURL: "http://localhost:3003", security: { apiKey: process.env["MUTAGENT_API_KEY"] ?? "" } });
 ```
 
-Per-method reference, with every parameter and response type, is in [docs/sdks/](./docs/sdks/).
-
----
+### Custom HTTP client
 
-## Streaming
-
-`helixSessions.streamHelixSession` and `sandbox.streamSandbox` request `Accept: text/event-stream`. The
-returned promise resolves to the whole event text as one string after the server closes the stream. The
-SDK does not parse the events and does not yield them while the stream is open. Pass the last `seq` you
-have read as `since` to receive only later events.
+`HTTPClient` wraps the native Fetch API and exposes `beforeRequest` / `requestError` hooks and a custom `fetcher` (e.g. to route through an [undici](https://www.npmjs.com/package/undici) `ProxyAgent`, or to mock `fetch` in tests):
 
 ```typescript
-import { Mutagent } from "@mutagent/sdk";
+import { HTTPClient } from "@mutagent/sdk/lib/http";
+import { ProxyAgent } from "undici";
 
-async function example(mutagent: Mutagent, reference: string) {
-  const eventText = await mutagent.helixSessions.streamHelixSession({ reference });
-  for (const block of eventText.split("\n\n")) {
-    console.log(block);
-  }
-}
-```
+const dispatcher = new ProxyAgent("http://proxy.example.com:8080");
+const httpClient = new HTTPClient({
+  fetcher: (input, init) => fetch(input, { ...init, dispatcher } as RequestInit),
+});
+httpClient.addHook("beforeRequest", (request) => {
+  const next = new Request(request, { signal: request.signal || AbortSignal.timeout(5000) });
+  next.headers.set("x-custom-header", "custom value");
+  return next;
+});
+httpClient.addHook("requestError", (error, request) => {
+  console.error("Request Error:", `${error}`, `${request.method} ${request.url}`);
+});
 
----
+const sdk = new Mutagent({ httpClient });
+```
 
-## Error Handling
+### Debugging
 
-Every HTTP error extends `MutagentError`. Most operations document `ErrorResponse`, whose data has
-`error` and `message`. The generated [Error Handling](#error-handling-1) section below lists every error
-class.
+Pass a `console`-shaped logger via `debugLogger`, or set `MUTAGENT_DEBUG=true` to enable one by default. Debug logging reveals secrets (API tokens in headers) — development only.
 
 ```typescript
-import { Mutagent } from "@mutagent/sdk";
-import * as errors from "@mutagent/sdk/models/errors";
-
-async function example(mutagent: Mutagent) {
-  try {
-    await mutagent.agents.getAgent({ id: 404 });
-  } catch (error) {
-    if (error instanceof errors.ErrorResponse) {
-      console.error(error.statusCode, error.data$.error, error.data$.message);
-    } else if (error instanceof errors.MutagentError) {
-      console.error(`HTTP ${error.statusCode}: ${error.body}`);
-    } else {
-      throw error;
-    }
-  }
-}
+const sdk = new Mutagent({ debugLogger: console });
 ```
 
 ---
 
 ## Development
 
-The code under `src/sdk`, `src/models`, `src/funcs`, `src/lib`, `src/types` and `src/hooks`, and the
-pages under `docs/`, are generated by Speakeasy from `openapi.json`. Do not edit them by hand: the next
-generation overwrites them. Change the API route definitions or the scripts in `scripts/` instead.
+The code under `src/sdk`, `src/models`, `src/funcs`, `src/lib`, `src/types`, `src/hooks`, and `docs/`, is generated by Speakeasy from `openapi.json`; do not hand-edit it, the next generation overwrites it (see [CLAUDE.md](CLAUDE.md) for the escalation path). Change the backend Elysia route annotations, `scripts/fix-openapi.ts` or `scripts/post-generate.ts` instead.
 
-Prerequisites: [Bun](https://bun.sh) 1.1 or later, the `speakeasy` CLI, and the MutagenT API running on
-`http://localhost:3003`.
+Prerequisites: [Bun](https://bun.sh) 1.1+, the `speakeasy` CLI, and the MutagenT API running on `http://localhost:3003`.
 
 ```bash
-# Fetch the spec, generate the SDK, apply the post-generation patches
-./scripts/generate-sdk.sh
-
-# Build the ESM and CommonJS output
-bun run build
-
-# Run the unit tests for the generation scripts
-bun test __tests__/unit
+./scripts/generate-sdk.sh   # fetch spec, generate, apply post-generation patches
+bun run build                # ESM + CommonJS output
+bun test __tests__/unit      # unit tests for the generation scripts
 ```
 
----
-
-## API Reference
-
-- [docs/sdks/](./docs/sdks/): one page per group, with every method, parameter and error
-- [FUNCTIONS.md](./FUNCTIONS.md): standalone functions
-- [RUNTIMES.md](./RUNTIMES.md): supported runtimes and TypeScript compiler options
-- [docs.mutagent.io](https://docs.mutagent.io): platform documentation
-
----
-
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).
 
----
-
 ## License
 
 This software is proprietary and confidential. Unauthorized copying, distribution, or use is strictly prohibited.
 
 © 2026 MutagenT. All rights reserved.
 
----
-
-<p align="center">
-  <sub>Built with ❤️ by the MutagenT Team</sub>
-</p>
-
 <p align="center">
-  <a href="https://twitter.com/mutagent">Twitter</a> •
-  <a href="https://discord.gg/mutagent">Discord</a> •
-  <a href="https://mutagent.io">Website</a> •
-  <a href="https://docs.mutagent.io">Documentation</a>
+  <sub>Built with care by the MutagenT Team &bull; <a href="https://mutagent.io">mutagent.io</a></sub>
 </p>
 
 <!-- Start Summary [summary] -->
@@ -590,28 +434,24 @@ MutagenT Server API Documentation: MutagenT platform API: workspaces, LLM provid
 <!-- Start Table of Contents [toc] -->
 ## Table of Contents
 <!-- $toc-max-depth=2 -->
-* [MutagenT SDK](#mutagent-sdk)
-  * [What the SDK covers](#what-the-sdk-covers)
-  * [0.6.0 breaking changes](#060-breaking-changes)
-  * [Installation](#installation)
-  * [Quick Start](#quick-start)
-  * [Authentication](#authentication)
-  * [Client groups](#client-groups)
-  * [Streaming](#streaming)
-  * [Error Handling](#error-handling)
+* [MutagenT TypeScript SDK](#mutagent-typescript-sdk)
+  * [Context](#context)
+  * [Concepts](#concepts)
+  * [Components](#components)
+  * [Configuration](#configuration)
+  * [Reference](#reference)
   * [Development](#development)
-  * [API Reference](#api-reference)
   * [Contributing](#contributing)
   * [License](#license)
   * [SDK Installation](#sdk-installation)
   * [Requirements](#requirements)
   * [SDK Example Usage](#sdk-example-usage)
-  * [Authentication](#authentication-1)
+  * [Authentication](#authentication)
   * [Available Resources and Operations](#available-resources-and-operations)
   * [Standalone functions](#standalone-functions)
   * [Pagination](#pagination)
   * [Retries](#retries)
-  * [Error Handling](#error-handling-1)
+  * [Error Handling](#error-handling)
   * [Server Selection](#server-selection)
   * [Custom HTTP Client](#custom-http-client)
   * [Debugging](#debugging)

package/dist/commonjs/lib/config.d.ts

@@ -35,8 +35,8 @@ export declare function serverURLFromOptions(options: SDKOptions): URL | null;
 export declare const SDK_METADATA: {
     readonly language: "typescript";
     readonly openapiDocVersion: "2.0.0";
-    readonly sdkVersion: "0.6.1";
+    readonly sdkVersion: "0.6.2";
     readonly genVersion: "2.938.0";
-    readonly userAgent: "speakeasy-sdk/typescript 0.6.1 2.938.0 2.0.0 @mutagent/sdk";
+    readonly userAgent: "speakeasy-sdk/typescript 0.6.2 2.938.0 2.0.0 @mutagent/sdk";
 };
 //# sourceMappingURL=config.d.ts.map

package/dist/commonjs/lib/config.js

@@ -35,8 +35,8 @@ function serverURLFromOptions(options) {
 exports.SDK_METADATA = {
     language: "typescript",
     openapiDocVersion: "2.0.0",
-    sdkVersion: "0.6.1",
+    sdkVersion: "0.6.2",
     genVersion: "2.938.0",
-    userAgent: "speakeasy-sdk/typescript 0.6.1 2.938.0 2.0.0 @mutagent/sdk",
+    userAgent: "speakeasy-sdk/typescript 0.6.2 2.938.0 2.0.0 @mutagent/sdk",
 };
 //# sourceMappingURL=config.js.map

package/dist/esm/lib/config.d.ts

@@ -35,8 +35,8 @@ export declare function serverURLFromOptions(options: SDKOptions): URL | null;
 export declare const SDK_METADATA: {
     readonly language: "typescript";
     readonly openapiDocVersion: "2.0.0";
-    readonly sdkVersion: "0.6.1";
+    readonly sdkVersion: "0.6.2";
     readonly genVersion: "2.938.0";
-    readonly userAgent: "speakeasy-sdk/typescript 0.6.1 2.938.0 2.0.0 @mutagent/sdk";
+    readonly userAgent: "speakeasy-sdk/typescript 0.6.2 2.938.0 2.0.0 @mutagent/sdk";
 };
 //# sourceMappingURL=config.d.ts.map

package/dist/esm/lib/config.js

@@ -31,8 +31,8 @@ export function serverURLFromOptions(options) {
 export const SDK_METADATA = {
     language: "typescript",
     openapiDocVersion: "2.0.0",
-    sdkVersion: "0.6.1",
+    sdkVersion: "0.6.2",
     genVersion: "2.938.0",
-    userAgent: "speakeasy-sdk/typescript 0.6.1 2.938.0 2.0.0 @mutagent/sdk",
+    userAgent: "speakeasy-sdk/typescript 0.6.2 2.938.0 2.0.0 @mutagent/sdk",
 };
 //# sourceMappingURL=config.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutagent/sdk",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "author": "Speakeasy",
   "tshy": {
     "sourceDialects": [