@mutagent/sdk 0.5.12 → 0.6.0

package/README.md

@@ -34,513 +34,535 @@
 </p>
 
 <p align="center">
-  <strong>Type-safe. Framework-agnostic. Production-ready.</strong><br>
-  <em>The official SDK for building with the MutagenT AI platform.</em>
+  <em>The TypeScript client for the MutagenT platform API.</em>
 </p>
 
 ---
 
-## 🎯 What is MutagenT SDK?
+## 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)).
 
-The **MutagenT SDK** is a developer-friendly, type-safe TypeScript client for the MutagenT AI platform. Built for modern AI applications, it provides:
-
-- 🔒 **Full Type Safety** - End-to-end TypeScript with Zod validation
-- 🚀 **Multiple Runtimes** - Works with Bun, Node.js, Deno, and Edge runtimes
-- 📦 **Multiple Module Formats** - ESM, CommonJS, and UMD support
-- 🌲 **Tree-shakeable** - Import only what you need
-- ⚡ **Auto-generated** - Always in sync with the latest API
-
-### Core Capabilities
+---
 
-| Feature | Description |
-|---------|-------------|
-| **Prompt Management** | Create, version, and optimize prompts programmatically |
-| **Dataset Operations** | Import, export, and manage evaluation datasets |
-| **Evaluation Engine** | Run automated evaluations against your prompts |
-| **Auto-Optimization** | Let AI improve your prompts based on metrics |
-| **Trace Collection** | Replace Langfuse with native observability |
-| **Multi-tenant** | Organizations, workspaces, and teams |
+## 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.
+
+**Session mode values**
+
+A Helix session mode is `headless` or `interactive` (`Mode.Headless`, `Mode.Interactive`). The
+0.5.x values `oneshot` and `rpc` are gone.
+
+**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.
 
 ---
 
-## 📦 Installation
-
-### Using npm
+## Installation
 
 ```bash
 npm install @mutagent/sdk
-```
-
-### Using pnpm
-
-```bash
+# or
 pnpm add @mutagent/sdk
-```
-
-### Using Bun
-
-```bash
+# or
 bun add @mutagent/sdk
-```
-
-### Using Yarn
-
-```bash
+# or
 yarn add @mutagent/sdk
 ```
 
-> **Note:** This package supports both CommonJS (`require`) and ES Modules (`import`).
+This package ships CommonJS (`require`) and ES module (`import`) builds. Supported runtimes are listed
+in [RUNTIMES.md](./RUNTIMES.md).
 
 ---
 
-## 🚀 Quick Start
-
-### 1. Initialize the Client
+## Quick Start
 
 ```typescript
-import { Mutagent } from '@mutagent/sdk';
+import { Mutagent } from "@mutagent/sdk";
 
 const mutagent = new Mutagent({
   security: {
-    apiKey: process.env.MUTAGENT_API_KEY,
+    apiKey: process.env["MUTAGENT_API_KEY"] ?? "",
   },
-  serverURL: 'https://api.mutagent.io/v1', // Optional
 });
-```
 
-### 2. Create Your First Prompt
+async function run() {
+  const profile = await mutagent.userProfile.getProfile();
+  console.log(profile);
 
-```typescript
-const prompt = await mutagent.prompt.createPrompt({
-  name: 'Customer Support Template',
-  content: 'You are a helpful support agent. User query: {{query}}',
-  variables: ['query'],
-});
+  const workspaces = await mutagent.workspaces.listWorkspaces();
+  console.log(workspaces);
+}
 
-console.log(`Created prompt: ${prompt.id}`);
+run();
 ```
 
-### 3. Add a Dataset
-
-```typescript
-const dataset = await mutagent.promptDatasets.createPromptDataset({
-  id: prompt.id,
-  name: 'Support Tickets',
-  description: 'Real customer support interactions',
-});
+---
 
-// Add items to dataset
-await mutagent.promptDatasetItems.bulkCreatePromptDatasetItems({
-  id: dataset.id,
-  items: [
-    { input: { query: 'How do I reset my password?' }, expected: '...' },
-    { input: { query: 'What are your business hours?' }, expected: '...' },
-  ],
-});
-```
+## Authentication
 
-### 4. Run Optimization
+The `security` option has two fields. Both are read from the environment when you do not pass them.
 
-```typescript
-const optimization = await mutagent.optimization.optimizePrompt({
-  id: prompt.id,
-  datasetId: dataset.id,
-  metric: 'response_quality',
-});
+| 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 |
 
-// Check progress
-const status = await mutagent.optimization.getOptimization({
-  id: optimization.id,
-});
+When an operation accepts both and both are set, the SDK sends the API key.
 
-console.log(`Optimization progress: ${status.progress}%`);
-```
+### API key
 
-### 5. Get Optimized Prompt
+A platform API key starts with `mg_live_`. Create one in the MutagenT app under Settings, API Keys.
 
 ```typescript
-const results = await mutagent.optimization.getOptimizationProgress({
-  id: optimization.id,
-});
+import { Mutagent } from "@mutagent/sdk";
 
-// Use the optimized version
-const optimizedPrompt = results.bestVersion;
+const mutagent = new Mutagent({
+  security: { apiKey: process.env["MUTAGENT_API_KEY"] ?? "" },
+});
 ```
 
----
-
-## 🔐 Authentication
+### Sandbox token
 
-The SDK supports both API key and Bearer token authentication. Set your credentials when initializing:
+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`.
 
 ```typescript
-const mutagent = new Mutagent({
-  security: {
-    apiKey: process.env.MUTAGENT_API_KEY,
-    // OR use bearerAuth:
-    // bearerAuth: process.env.MUTAGENT_BEARER_AUTH,
-  },
-});
-```
+import { Mutagent } from "@mutagent/sdk";
 
-Or use environment variables:
+async function sandboxClient(workspaceId: string): Promise<Mutagent> {
+  const apiKey = process.env["MUTAGENT_API_KEY"] ?? "";
+  const platform = new Mutagent({ security: { apiKey } });
 
-```bash
-export MUTAGENT_API_KEY="sk_live_xxxxxxxx"
-# OR
-export MUTAGENT_BEARER_AUTH="your-bearer-token"
+  const { token, expiresIn } = await platform.sandbox.createSandboxToken(
+    { apiKey },
+    { workspaceId },
+  );
+  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.
 
-## 📚 Core Resources
+---
 
-### Prompts
+## Client groups
 
-```typescript
-// List all prompts
-const prompts = await mutagent.prompt.listPrompts();
+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.
 
-// Get a specific prompt
-const prompt = await mutagent.prompt.getPrompt({ id: 'prompt-id' });
+### userProfile
 
-// Update a prompt
-await mutagent.prompt.updatePrompt({
-  id: 'prompt-id',
-  content: 'Updated prompt content...',
-});
+```typescript
+import { Mutagent } from "@mutagent/sdk";
 
-// Create a new version
-await mutagent.prompt.createPromptVersion({
-  id: 'prompt-id',
-  content: 'New version content...',
-});
+async function example(mutagent: Mutagent) {
+  const profile = await mutagent.userProfile.getProfile();
+  const sessions = await mutagent.userProfile.listUserSessions();
+  console.log(profile, sessions);
+}
 ```
 
-### Datasets
+### organizations
 
 ```typescript
-// List datasets for a prompt
-const datasets = await mutagent.promptDatasets.listDatasetsForPrompt({
-  id: 'prompt-id',
-});
-
-// Create dataset
-const dataset = await mutagent.promptDatasets.createPromptDataset({
-  id: 'prompt-id',
-  name: 'My Dataset',
-});
+import { Mutagent } from "@mutagent/sdk";
 
-// Export dataset
-const exportData = await mutagent.promptDatasets.exportPromptDataset({
-  id: 'dataset-id',
-});
+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);
+}
 ```
 
-### Evaluations
+### organizationMembers
 
 ```typescript
-// Create evaluation
-const evaluation = await mutagent.promptEvaluations.createEvaluation({
-  promptId: 'prompt-id',
-  datasetId: 'dataset-id',
-  metrics: ['accuracy', 'relevance'],
-});
-
-// Run evaluation
-await mutagent.promptEvaluations.runEvaluation({
-  id: evaluation.id,
-});
+import { Mutagent } from "@mutagent/sdk";
 
-// Get results
-const results = await mutagent.promptEvaluations.getEvaluationResult({
-  id: evaluation.id,
-});
+async function example(mutagent: Mutagent) {
+  const members = await mutagent.organizationMembers.listOrganizationMembers({ orgId: "<org-id>" });
+  console.log(members);
+}
 ```
 
-### Agents
+### workspaces
 
 ```typescript
-// Create an agent
-const agent = await mutagent.agents.createAgent({
-  name: 'Support Agent',
-  description: 'Handles customer support queries',
-  promptId: 'prompt-id',
-});
-
-// Create conversation
-const conversation = await mutagent.agentConversations.createAgentConversation({
-  id: agent.id,
-});
+import { Mutagent } from "@mutagent/sdk";
 
-// Send message
-await mutagent.conversations.sendConversationMessage({
-  id: conversation.id,
-  content: 'How do I reset my password?',
-});
+async function example(mutagent: Mutagent) {
+  const workspace = await mutagent.workspaces.createWorkspace({
+    name: "Support",
+    slug: "support",
+  });
+  await mutagent.workspaces.setDefaultWorkspace({ wsId: workspace.id });
+}
 ```
 
----
-
-## 📊 Tracing & Observability
-
-The SDK includes built-in tracing support to collect and analyze LLM interactions, chains, and agent workflows.
-
-### Initialize Tracing
+### workspaceMembers
 
 ```typescript
-import { initTracing, shutdownTracing } from '@mutagent/sdk';
-
-// Initialize tracing with your MutagenT API key
-initTracing({
-  apiKey: process.env.MUTAGENT_API_KEY!,
-  endpoint: 'https://api.mutagent.io',
-  environment: 'production',
-  batchSize: 10,        // Optional: spans per batch (default: 10)
-  flushInterval: 5000,  // Optional: flush every 5s (default: 5000ms)
-});
-
-// Your application code here...
+import { Mutagent } from "@mutagent/sdk";
 
-// Shutdown tracing when your app exits (flushes remaining spans)
-await shutdownTracing();
+async function example(mutagent: Mutagent) {
+  const members = await mutagent.workspaceMembers.listWorkspaceMembers({ wsId: "<workspace-id>" });
+  console.log(members);
+}
 ```
 
-### Using the @trace Decorator
-
-Automatically instrument class methods with the `@trace` decorator:
+### invitations
 
 ```typescript
-import { trace } from '@mutagent/sdk';
-
-class MyAgent {
-  @trace({ kind: 'agent', name: 'customer-support-agent' })
-  async processQuery(query: string) {
-    // Method automatically traced with input/output/duration
-    const response = await this.generateResponse(query);
-    return response;
-  }
+import { Mutagent } from "@mutagent/sdk";
+import { OrganizationRole } from "@mutagent/sdk/models";
 
-  @trace({ kind: 'llm.chat', name: 'openai-gpt4' })
-  private async generateResponse(query: string) {
-    // LLM call is traced separately
-    return await callOpenAI(query);
-  }
+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);
 }
 ```
 
-### Using the withTrace Wrapper
-
-For functional-style code or fine-grained control:
+### agents
 
 ```typescript
-import { withTrace } from '@mutagent/sdk';
+import { Mutagent } from "@mutagent/sdk";
 
-async function ragPipeline(query: string) {
-  return await withTrace(
-    { kind: 'chain', name: 'rag-pipeline' },
-    async (span) => {
-      // Add custom attributes
-      span.setAttributes({
-        'gen_ai.model': 'gpt-4',
-        'user.query': query,
-      });
+async function example(mutagent: Mutagent) {
+  const agent = await mutagent.agents.createAgent({
+    name: "Support Agent",
+    slug: "support-agent",
+    systemPrompt: "You answer customer support questions.",
+  });
+
+  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);
+}
+```
 
-      // Retrieve documents
-      const docs = await retrieveDocuments(query);
-      span.addEvent('documents_retrieved', { count: docs.length });
+### llmProviders
 
-      // Generate answer
-      const answer = await generateAnswer(query, docs);
+```typescript
+import { Mutagent } from "@mutagent/sdk";
+import { LlmProviderType } from "@mutagent/sdk/models";
 
-      // Set output
-      span.setOutput({ text: answer, sources: docs.map(d => d.id) });
+async function example(mutagent: Mutagent) {
+  const provider = await mutagent.llmProviders.createProviderConfig({
+    name: "Anthropic",
+    provider: LlmProviderType.Anthropic,
+    apiKey: process.env["ANTHROPIC_API_KEY"] ?? "",
+  });
 
-      return answer;
-    }
-  );
+  const test = await mutagent.llmProviders.testProviderConfig({ id: provider.id });
+  const models = await mutagent.llmProviders.listProviderConfigModels({ id: provider.id });
+  console.log(test, models);
 }
 ```
 
-### SpanKinds Taxonomy
-
-The SDK supports the following span kinds for categorizing traces:
-
-| SpanKind | Description | Example Use Case |
-|----------|-------------|------------------|
-| `llm.chat` | Chat completion calls | OpenAI ChatGPT, Anthropic Claude |
-| `llm.completion` | Text completion calls | GPT-3 Davinci, Legacy completions |
-| `llm.embedding` | Embedding generation | OpenAI Embeddings, Cohere Embed |
-| `chain` | Sequential processing pipeline | LangChain chains, RAG pipelines |
-| `agent` | Autonomous agent execution | ReAct agents, AutoGPT |
-| `graph` | State graph execution | LangGraph workflows |
-| `node` | Individual graph node | Graph state transitions |
-| `edge` | Graph transitions | Conditional routing |
-| `workflow` | Multi-step workflows | Business process automation |
-| `middleware` | Request/response processing | Auth, rate limiting |
-| `tool` | External tool calls | API calls, calculators |
-| `retrieval` | Document retrieval | Vector search, keyword search |
-| `rerank` | Result reranking | Cohere Rerank, cross-encoders |
-| `guardrail` | Safety/validation checks | PII detection, content filtering |
-| `custom` | Custom operations | Your domain-specific ops |
+### managedAgents
 
----
+```typescript
+import { Mutagent } from "@mutagent/sdk";
 
-## 🌲 Tree-shakeable Imports
+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);
+  }
+}
+```
 
-Import only what you need for smaller bundle sizes:
+### traces
 
 ```typescript
-// Import specific operations as standalone functions
-import {
-  promptListPrompts,
-  promptCreatePrompt,
-  promptDatasetsListDatasetsForPrompt,
-} from '@mutagent/sdk/functions';
-
-// Use standalone functions (pass client or security directly)
-const prompts = await promptListPrompts(client);
-const prompt = await promptCreatePrompt(client, {
-  name: 'New Prompt',
-  content: 'Template with {{variable}}',
-});
+import { Mutagent } from "@mutagent/sdk";
+
+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);
+  }
+}
 ```
 
----
+### sandbox
 
-## 🔄 Error Handling
+Requires a sandbox token (see [Sandbox token](#sandbox-token)).
 
 ```typescript
-import { Mutagent } from '@mutagent/sdk';
+import { Mutagent } from "@mutagent/sdk";
+import { SandboxArch } from "@mutagent/sdk/models";
 
-const mutagent = new Mutagent({
-  security: {
-    apiKey: process.env.MUTAGENT_API_KEY,
-  },
-});
+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);
 
-try {
-  const prompt = await mutagent.prompt.getPrompt({ id: 'invalid-id' });
-} catch (error) {
-  if (error.statusCode === 404) {
-    console.error('Prompt not found');
-  } else if (error.statusCode === 401) {
-    console.error('Authentication failed');
-  } else {
-    console.error('Unknown error:', error);
-  }
+  // 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 });
 }
 ```
 
----
-
-## 🛠️ Framework Integrations
-
-Use MutagenT with your favorite framework:
+### environments
 
-### Mastra
+Requires a sandbox token.
 
 ```typescript
-import { MutagentObserver } from '@mutagent/sdk/mastra';
+import { Mutagent } from "@mutagent/sdk";
 
-const observer = new MutagentObserver({
-  apiKey: process.env.MUTAGENT_API_KEY,
-});
+async function example(mutagent: Mutagent) {
+  await mutagent.environments.replaceEnvironment({
+    name: "staging",
+    body: {
+      vars: { LOG_LEVEL: "debug" },
+      secrets: { DATABASE_URL: "<secret>" },
+    },
+  });
+
+  const environments = await mutagent.environments.listEnvironments();
+  console.log(environments);
+}
 ```
 
-### LangChain
+### helixSessions
+
+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.
 
 ```typescript
-import { MutagentCallbackHandler } from '@mutagent/sdk/langchain';
+import { Mutagent } from "@mutagent/sdk";
+import { HelixSignal, Mode } from "@mutagent/sdk/models";
 
-const handler = new MutagentCallbackHandler({
-  apiKey: process.env.MUTAGENT_API_KEY,
-  promptId: 'my-prompt',
-});
+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);
 
-const llm = new ChatOpenAI({ callbacks: [handler] });
+  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 },
+  });
+}
 ```
 
-### Vercel AI SDK
+Per-method reference, with every parameter and response type, is in [docs/sdks/](./docs/sdks/).
 
-```typescript
-import { withMutagent } from '@mutagent/sdk/vercel-ai';
+---
 
-const result = await withMutagent(
-  streamText({ model: openai('gpt-4o'), messages }),
-  { apiKey: process.env.MUTAGENT_API_KEY }
-);
-```
+## Streaming
 
-See full integration guides with the [MutagenT CLI](https://github.com/mutagent/mutagent-cli):
+`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.
 
-```bash
-npx @mutagent/cli integrate mastra
+```typescript
+import { Mutagent } from "@mutagent/sdk";
+
+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);
+  }
+}
 ```
 
 ---
 
-## 🌍 Server Selection
+## Error Handling
+
+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.
 
 ```typescript
-const mutagent = new Mutagent({
-  security: {
-    apiKey: process.env.MUTAGENT_API_KEY,
-  },
-  serverURL: 'https://api.mutagent.io/v1', // Production (default)
-  // serverURL: 'https://staging-api.mutagent.io/v1', // Staging
-  // serverURL: 'http://localhost:3003', // Local development
-});
+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;
+    }
+  }
+}
 ```
 
 ---
 
-## 🧪 Development
-
-### Prerequisites
+## Development
 
-- [Bun](https://bun.sh) >= 1.1.0
-- Node.js >= 18.0.0
+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.
 
-### Setup
+Prerequisites: [Bun](https://bun.sh) 1.1 or later, the `speakeasy` CLI, and the MutagenT API running on
+`http://localhost:3003`.
 
 ```bash
-git clone https://github.com/mutagent/mutagent-sdk.git
-cd mutagent-sdk
-bun install
-```
-
-### Build
+# Fetch the spec, generate the SDK, apply the post-generation patches
+./scripts/generate-sdk.sh
 
-```bash
+# Build the ESM and CommonJS output
 bun run build
-```
-
-### Test
 
-```bash
-bun test
+# Run the unit tests for the generation scripts
+bun test __tests__/unit
 ```
 
 ---
 
-## 📖 API Reference
-
-For detailed API documentation, see:
+## API Reference
 
-- [SDK Reference](./docs/sdks/)
-- [Standalone Functions](./FUNCTIONS.md)
-- [Runtime Support](./RUNTIMES.md)
+- [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
+## Contributing
 
-Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ---
 
-## 📄 License
+## License
 
 This software is proprietary and confidential. Unauthorized copying, distribution, or use is strictly prohibited.
 
@@ -548,10 +570,6 @@ This software is proprietary and confidential. Unauthorized copying, distributio
 
 ---
 
-For full API reference, see [docs.mutagent.io](https://docs.mutagent.io)
-
----
-
 <p align="center">
   <sub>Built with ❤️ by the MutagenT Team</sub>
 </p>
@@ -566,27 +584,25 @@ For full API reference, see [docs.mutagent.io](https://docs.mutagent.io)
 <!-- Start Summary [summary] -->
 ## Summary
 
-MutagenT Server API Documentation: Comprehensive API documentation for MutagenT AI Agent Server with Auto-tuning capabilities
+MutagenT Server API Documentation: MutagenT platform API: workspaces, LLM providers, agents, traces, cloud sandboxes and Helix Cloud sessions.
 <!-- End Summary [summary] -->
 
 <!-- Start Table of Contents [toc] -->
 ## Table of Contents
 <!-- $toc-max-depth=2 -->
 * [MutagenT SDK](#mutagent-sdk)
-  * [🎯 What is MutagenT SDK?](#what-is-mutagent-sdk)
-  * [📦 Installation](#installation)
-  * [🚀 Quick Start](#quick-start)
-  * [🔐 Authentication](#authentication)
-  * [📚 Core Resources](#core-resources)
-  * [📊 Tracing & Observability](#tracing-observability)
-  * [🌲 Tree-shakeable Imports](#tree-shakeable-imports)
-  * [🔄 Error Handling](#error-handling)
-  * [🛠️ Framework Integrations](#framework-integrations)
-  * [🌍 Server Selection](#server-selection)
-  * [🧪 Development](#development)
-  * [📖 API Reference](#api-reference)
-  * [🤝 Contributing](#contributing)
-  * [📄 License](#license)
+  * [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)
+  * [Development](#development)
+  * [API Reference](#api-reference)
+  * [Contributing](#contributing)
+  * [License](#license)
   * [SDK Installation](#sdk-installation)
   * [Requirements](#requirements)
   * [SDK Example Usage](#sdk-example-usage)
@@ -596,7 +612,7 @@ MutagenT Server API Documentation: Comprehensive API documentation for MutagenT
   * [Pagination](#pagination)
   * [Retries](#retries)
   * [Error Handling](#error-handling-1)
-  * [Server Selection](#server-selection-1)
+  * [Server Selection](#server-selection)
   * [Custom HTTP Client](#custom-http-client)
   * [Debugging](#debugging)
 
@@ -707,7 +723,7 @@ import { Mutagent } from "@mutagent/sdk";
 const mutagent = new Mutagent();
 
 async function run() {
-  const result = await mutagent.sandbox.postApiSandboxToken({}, {
+  const result = await mutagent.sandbox.createSandboxToken({}, {
     workspaceId: "<id>",
   });
 
@@ -734,15 +750,27 @@ run();
 * [deleteAgent](docs/sdks/agents/README.md#deleteagent) - Delete agent
 * [getAgentBySlug](docs/sdks/agents/README.md#getagentbyslug) - Get agent by slug
 
-### [HelixAgentDeployments](docs/sdks/helixagentdeployments/README.md)
+### [Environments](docs/sdks/environments/README.md)
 
-* [getHelixAgentCapabilities](docs/sdks/helixagentdeployments/README.md#gethelixagentcapabilities) - Inspect managed agent deployment capabilities
-* [listHelixAgents](docs/sdks/helixagentdeployments/README.md#listhelixagents) - List the workspace's managed agents and their slots
-* [getHelixAgent](docs/sdks/helixagentdeployments/README.md#gethelixagent) - Inspect a managed agent: revisions, slots and launched sessions
-* [deployHelixAgent](docs/sdks/helixagentdeployments/README.md#deployhelixagent) - Deploy a managed agent package into a slot (agent × Environment)
-* [activateHelixAgent](docs/sdks/helixagentdeployments/README.md#activatehelixagent) - Point an existing slot at a revision (an older one is a rollback)
-* [retireHelixAgent](docs/sdks/helixagentdeployments/README.md#retirehelixagent) - Disable a slot: new launches are refused, running sessions finish
-* [getHelixAgentOperation](docs/sdks/helixagentdeployments/README.md#gethelixagentoperation) - Inspect a durable deployment operation
+* [listEnvironments](docs/sdks/environments/README.md#listenvironments) - List workspace Environments
+* [getEnvironment](docs/sdks/environments/README.md#getenvironment) - Describe one workspace Environment
+* [replaceEnvironment](docs/sdks/environments/README.md#replaceenvironment) - Create or replace a workspace Environment
+* [updateEnvironment](docs/sdks/environments/README.md#updateenvironment) - Set or unset entries of a workspace Environment
+* [deleteEnvironment](docs/sdks/environments/README.md#deleteenvironment) - Delete a workspace Environment
+
+### [HelixSessions](docs/sdks/helixsessions/README.md)
+
+* [launchHelixSession](docs/sdks/helixsessions/README.md#launchhelixsession) - Launch a Helix session
+* [listHelixSessions](docs/sdks/helixsessions/README.md#listhelixsessions) - List the workspace's Helix sessions across all sandboxes
+* [sendHelixSessionInput](docs/sdks/helixsessions/README.md#sendhelixsessioninput) - Send a JSON command to a session
+* [closeHelixSessionInput](docs/sdks/helixsessions/README.md#closehelixsessioninput) - Close a session's input
+* [signalHelixSession](docs/sdks/helixsessions/README.md#signalhelixsession) - Stop a live Helix process
+* [checkpointHelixSession](docs/sdks/helixsessions/README.md#checkpointhelixsession) - Checkpoint a Helix session
+* [listHelixSessionCheckpoints](docs/sdks/helixsessions/README.md#listhelixsessioncheckpoints) - List the checkpoints of a session's sandbox
+* [restoreHelixSession](docs/sdks/helixsessions/README.md#restorehelixsession) - Restore a session from a checkpoint
+* [streamHelixSession](docs/sdks/helixsessions/README.md#streamhelixsession) - Stream a session's output
+* [getHelixModels](docs/sdks/helixsessions/README.md#gethelixmodels) - List the workspace's Helix Cloud models and its default
+* [setHelixDefaultModels](docs/sdks/helixsessions/README.md#sethelixdefaultmodels) - Set the workspace's default Helix Cloud models
 
 ### [Invitations](docs/sdks/invitations/README.md)
 
@@ -752,6 +780,28 @@ run();
 * [deleteInvitation](docs/sdks/invitations/README.md#deleteinvitation) - Delete/revoke invitation
 * [resendInvitation](docs/sdks/invitations/README.md#resendinvitation) - Resend invitation
 
+### [LLMProviders](docs/sdks/llmproviders/README.md)
+
+* [listProviderConfigs](docs/sdks/llmproviders/README.md#listproviderconfigs) - List provider configs
+* [createProviderConfig](docs/sdks/llmproviders/README.md#createproviderconfig) - Create provider config
+* [listAvailableModels](docs/sdks/llmproviders/README.md#listavailablemodels) - List available models
+* [getProviderConfig](docs/sdks/llmproviders/README.md#getproviderconfig) - Get provider config
+* [updateProviderConfig](docs/sdks/llmproviders/README.md#updateproviderconfig) - Update provider config
+* [deleteProviderConfig](docs/sdks/llmproviders/README.md#deleteproviderconfig) - Delete provider config
+* [getModelCatalog](docs/sdks/llmproviders/README.md#getmodelcatalog) - Get models catalog
+* [listProviderConfigModels](docs/sdks/llmproviders/README.md#listproviderconfigmodels) - List a provider configuration models
+* [testProviderConfig](docs/sdks/llmproviders/README.md#testproviderconfig) - Test provider connection
+
+### [ManagedAgents](docs/sdks/managedagents/README.md)
+
+* [getHelixAgentCapabilities](docs/sdks/managedagents/README.md#gethelixagentcapabilities) - Inspect managed agent deployment capabilities
+* [listHelixAgents](docs/sdks/managedagents/README.md#listhelixagents) - List the workspace's managed agents and their slots
+* [getHelixAgent](docs/sdks/managedagents/README.md#gethelixagent) - Inspect a managed agent: revisions, slots and launched sessions
+* [deployHelixAgent](docs/sdks/managedagents/README.md#deployhelixagent) - Deploy a managed agent package into a slot (agent × Environment)
+* [activateHelixAgent](docs/sdks/managedagents/README.md#activatehelixagent) - Point an existing slot at a revision (an older one is a rollback)
+* [retireHelixAgent](docs/sdks/managedagents/README.md#retirehelixagent) - Disable a slot: new launches are refused, running sessions finish
+* [getHelixAgentOperation](docs/sdks/managedagents/README.md#gethelixagentoperation) - Inspect a durable deployment operation
+
 ### [OrganizationMembers](docs/sdks/organizationmembers/README.md)
 
 * [listOrganizationMembers](docs/sdks/organizationmembers/README.md#listorganizationmembers) - List organization members
@@ -770,56 +820,28 @@ run();
 * [checkOrganizationSlug](docs/sdks/organizations/README.md#checkorganizationslug) - Check slug availability
 * [getOrganizationMemberCount](docs/sdks/organizations/README.md#getorganizationmembercount) - Get member count
 
-### [ProviderConfigs](docs/sdks/providerconfigs/README.md)
-
-* [listProviders](docs/sdks/providerconfigs/README.md#listproviders) - List provider configs
-* [createProvider](docs/sdks/providerconfigs/README.md#createprovider) - Create provider config
-* [listAvailableModels](docs/sdks/providerconfigs/README.md#listavailablemodels) - List available models
-* [getProvider](docs/sdks/providerconfigs/README.md#getprovider) - Get provider config
-* [updateProvider](docs/sdks/providerconfigs/README.md#updateprovider) - Update provider config
-* [deleteProvider](docs/sdks/providerconfigs/README.md#deleteprovider) - Delete provider config
-* [getModelsCatalog](docs/sdks/providerconfigs/README.md#getmodelscatalog) - Get models catalog
-* [listProviderModels](docs/sdks/providerconfigs/README.md#listprovidermodels) - List a provider configuration models
-* [testProvider](docs/sdks/providerconfigs/README.md#testprovider) - Test provider connection
-
 ### [Sandbox](docs/sdks/sandbox/README.md)
 
-* [getApiSandboxProviders](docs/sdks/sandbox/README.md#getapisandboxproviders) - List sandbox providers
-* [postApiSandboxPreflight](docs/sdks/sandbox/README.md#postapisandboxpreflight) - Preflight a sandbox definition
-* [getApiSandboxPresets](docs/sdks/sandbox/README.md#getapisandboxpresets) - List sandbox presets
-* [postApiSandboxRun](docs/sdks/sandbox/README.md#postapisandboxrun) - Run one command in a fresh sandbox
-* [postApiSandbox](docs/sdks/sandbox/README.md#postapisandbox) - Spawn a sandbox
-* [getApiSandbox](docs/sdks/sandbox/README.md#getapisandbox) - List sandboxes
-* [getApiSandboxById](docs/sdks/sandbox/README.md#getapisandboxbyid) - Get sandbox status
-* [deleteApiSandboxById](docs/sdks/sandbox/README.md#deleteapisandboxbyid) - Tear down a sandbox
-* [getApiSandboxByIdStream](docs/sdks/sandbox/README.md#getapisandboxbyidstream) - Watch a sandbox's output live
-* [postApiSandboxByIdExec](docs/sdks/sandbox/README.md#postapisandboxbyidexec) - Run a command in a sandbox
-* [postApiSandboxTelemetryV1Traces](docs/sdks/sandbox/README.md#postapisandboxtelemetryv1traces) - Ingest OTLP spans from inside a sandbox
-* [getApiSandboxByIdTraces](docs/sdks/sandbox/README.md#getapisandboxbyidtraces) - Read a sandbox's captured spans
-* [getApiSandboxEnvironments](docs/sdks/sandbox/README.md#getapisandboxenvironments) - List workspace Environments
-* [getApiSandboxEnvironmentsByName](docs/sdks/sandbox/README.md#getapisandboxenvironmentsbyname) - Describe one workspace Environment
-* [putApiSandboxEnvironmentsByName](docs/sdks/sandbox/README.md#putapisandboxenvironmentsbyname) - Create or replace a workspace Environment
-* [patchApiSandboxEnvironmentsByName](docs/sdks/sandbox/README.md#patchapisandboxenvironmentsbyname) - Set or unset entries of a workspace Environment
-* [deleteApiSandboxEnvironmentsByName](docs/sdks/sandbox/README.md#deleteapisandboxenvironmentsbyname) - Delete a workspace Environment
-* [launchHelixSession](docs/sdks/sandbox/README.md#launchhelixsession) - Provision and launch a headless Helix session
-* [listHelixWorkspaceSessions](docs/sdks/sandbox/README.md#listhelixworkspacesessions) - List the workspace's Helix sessions across all sandboxes
-* [inputHelixSession](docs/sdks/sandbox/README.md#inputhelixsession) - Write native JSONL to a live Helix session
-* [closeHelixSessionInput](docs/sdks/sandbox/README.md#closehelixsessioninput) - Explicitly close native RPC stdin
-* [signalHelixSession](docs/sdks/sandbox/README.md#signalhelixsession) - Stop a live Helix process
-* [checkpointHelixSession](docs/sdks/sandbox/README.md#checkpointhelixsession) - Checkpoint a live Helix session
-* [listHelixSessionCheckpoints](docs/sdks/sandbox/README.md#listhelixsessioncheckpoints) - List the checkpoints of the box a session runs on
-* [restoreHelixSession](docs/sdks/sandbox/README.md#restorehelixsession) - Rebuild the box a session runs on from a checkpoint
-* [streamHelixSession](docs/sdks/sandbox/README.md#streamhelixsession) - Follow one Helix execution
-* [postApiSandboxByIdSession](docs/sdks/sandbox/README.md#postapisandboxbyidsession) - Start a Helix session in a sandbox
-* [getApiSandboxHelixDefaults](docs/sdks/sandbox/README.md#getapisandboxhelixdefaults) - List the workspace's Helix Cloud models and its default
-* [putApiSandboxHelixDefaults](docs/sdks/sandbox/README.md#putapisandboxhelixdefaults) - Set the workspace's default Helix Cloud models
-* [getApiSandboxByIdSessions](docs/sdks/sandbox/README.md#getapisandboxbyidsessions) - List the Helix sessions a sandbox is hosting
-* [postApiSandboxByIdInput](docs/sdks/sandbox/README.md#postapisandboxbyidinput) - Write one line to a Helix session's stdin
-* [postApiSandboxByIdSignal](docs/sdks/sandbox/README.md#postapisandboxbyidsignal) - Stop a running Helix session without destroying its sandbox
-* [postApiSandboxByIdCheckpoint](docs/sdks/sandbox/README.md#postapisandboxbyidcheckpoint) - Capture a Helix session's own transcript
-* [getApiSandboxByIdCheckpoints](docs/sdks/sandbox/README.md#getapisandboxbyidcheckpoints) - List checkpoints captured from this sandbox
-* [postApiSandboxByIdRestore](docs/sdks/sandbox/README.md#postapisandboxbyidrestore) - Rebuild this sandbox from a checkpoint, with full state
-* [postApiSandboxToken](docs/sdks/sandbox/README.md#postapisandboxtoken) - Exchange a platform API key for a sandbox operator token
+* [listSandboxProviders](docs/sdks/sandbox/README.md#listsandboxproviders) - List sandbox providers
+* [preflightSandbox](docs/sdks/sandbox/README.md#preflightsandbox) - Preflight a sandbox definition
+* [listSandboxPresets](docs/sdks/sandbox/README.md#listsandboxpresets) - List sandbox presets
+* [runSandboxCommand](docs/sdks/sandbox/README.md#runsandboxcommand) - Run one command in a fresh sandbox
+* [createSandbox](docs/sdks/sandbox/README.md#createsandbox) - Spawn a sandbox
+* [listSandboxes](docs/sdks/sandbox/README.md#listsandboxes) - List sandboxes
+* [getSandbox](docs/sdks/sandbox/README.md#getsandbox) - Get sandbox status
+* [deleteSandbox](docs/sdks/sandbox/README.md#deletesandbox) - Tear down a sandbox
+* [streamSandbox](docs/sdks/sandbox/README.md#streamsandbox) - Watch a sandbox's output live
+* [execSandboxCommand](docs/sdks/sandbox/README.md#execsandboxcommand) - Run a command in a sandbox
+* [ingestSandboxTraces](docs/sdks/sandbox/README.md#ingestsandboxtraces) - Ingest OTLP spans from inside a sandbox
+* [listSandboxSpans](docs/sdks/sandbox/README.md#listsandboxspans) - Read a sandbox's captured spans
+* [startSandboxHelixSession](docs/sdks/sandbox/README.md#startsandboxhelixsession) - Start a Helix session in a sandbox
+* [listSandboxHelixSessions](docs/sdks/sandbox/README.md#listsandboxhelixsessions) - List the Helix sessions a sandbox is hosting
+* [sendSandboxHelixSessionInput](docs/sdks/sandbox/README.md#sendsandboxhelixsessioninput) - Write one line to a Helix session's stdin
+* [signalSandboxHelixSession](docs/sdks/sandbox/README.md#signalsandboxhelixsession) - Stop a running Helix session without destroying its sandbox
+* [checkpointSandboxHelixSession](docs/sdks/sandbox/README.md#checkpointsandboxhelixsession) - Capture a Helix session's own transcript
+* [listSandboxCheckpoints](docs/sdks/sandbox/README.md#listsandboxcheckpoints) - List checkpoints captured from this sandbox
+* [restoreSandbox](docs/sdks/sandbox/README.md#restoresandbox) - Rebuild this sandbox from a checkpoint, with full state
+* [createSandboxToken](docs/sdks/sandbox/README.md#createsandboxtoken) - Exchange a platform API key for a sandbox operator token
 
 ### [Traces](docs/sdks/traces/README.md)
 
@@ -835,8 +857,8 @@ run();
 * [updateProfile](docs/sdks/userprofile/README.md#updateprofile) - Update user profile
 * [deleteAccount](docs/sdks/userprofile/README.md#deleteaccount) - Delete account
 * [changePassword](docs/sdks/userprofile/README.md#changepassword) - Change password
-* [listSessions](docs/sdks/userprofile/README.md#listsessions) - List active sessions
-* [deleteSession](docs/sdks/userprofile/README.md#deletesession) - Revoke session
+* [listUserSessions](docs/sdks/userprofile/README.md#listusersessions) - List active sessions
+* [revokeUserSession](docs/sdks/userprofile/README.md#revokeusersession) - Revoke session
 
 ### [WorkspaceMembers](docs/sdks/workspacemembers/README.md)
 
@@ -878,18 +900,43 @@ To read more about standalone functions, check [FUNCTIONS.md](./FUNCTIONS.md).
 - [`agentsGetAgentBySlug`](docs/sdks/agents/README.md#getagentbyslug) - Get agent by slug
 - [`agentsListAgents`](docs/sdks/agents/README.md#listagents) - List agents
 - [`agentsUpdateAgent`](docs/sdks/agents/README.md#updateagent) - Update agent
-- [`helixAgentDeploymentsActivateHelixAgent`](docs/sdks/helixagentdeployments/README.md#activatehelixagent) - Point an existing slot at a revision (an older one is a rollback)
-- [`helixAgentDeploymentsDeployHelixAgent`](docs/sdks/helixagentdeployments/README.md#deployhelixagent) - Deploy a managed agent package into a slot (agent × Environment)
-- [`helixAgentDeploymentsGetHelixAgent`](docs/sdks/helixagentdeployments/README.md#gethelixagent) - Inspect a managed agent: revisions, slots and launched sessions
-- [`helixAgentDeploymentsGetHelixAgentCapabilities`](docs/sdks/helixagentdeployments/README.md#gethelixagentcapabilities) - Inspect managed agent deployment capabilities
-- [`helixAgentDeploymentsGetHelixAgentOperation`](docs/sdks/helixagentdeployments/README.md#gethelixagentoperation) - Inspect a durable deployment operation
-- [`helixAgentDeploymentsListHelixAgents`](docs/sdks/helixagentdeployments/README.md#listhelixagents) - List the workspace's managed agents and their slots
-- [`helixAgentDeploymentsRetireHelixAgent`](docs/sdks/helixagentdeployments/README.md#retirehelixagent) - Disable a slot: new launches are refused, running sessions finish
+- [`environmentsDeleteEnvironment`](docs/sdks/environments/README.md#deleteenvironment) - Delete a workspace Environment
+- [`environmentsGetEnvironment`](docs/sdks/environments/README.md#getenvironment) - Describe one workspace Environment
+- [`environmentsListEnvironments`](docs/sdks/environments/README.md#listenvironments) - List workspace Environments
+- [`environmentsReplaceEnvironment`](docs/sdks/environments/README.md#replaceenvironment) - Create or replace a workspace Environment
+- [`environmentsUpdateEnvironment`](docs/sdks/environments/README.md#updateenvironment) - Set or unset entries of a workspace Environment
+- [`helixSessionsCheckpointHelixSession`](docs/sdks/helixsessions/README.md#checkpointhelixsession) - Checkpoint a Helix session
+- [`helixSessionsCloseHelixSessionInput`](docs/sdks/helixsessions/README.md#closehelixsessioninput) - Close a session's input
+- [`helixSessionsGetHelixModels`](docs/sdks/helixsessions/README.md#gethelixmodels) - List the workspace's Helix Cloud models and its default
+- [`helixSessionsLaunchHelixSession`](docs/sdks/helixsessions/README.md#launchhelixsession) - Launch a Helix session
+- [`helixSessionsListHelixSessionCheckpoints`](docs/sdks/helixsessions/README.md#listhelixsessioncheckpoints) - List the checkpoints of a session's sandbox
+- [`helixSessionsListHelixSessions`](docs/sdks/helixsessions/README.md#listhelixsessions) - List the workspace's Helix sessions across all sandboxes
+- [`helixSessionsRestoreHelixSession`](docs/sdks/helixsessions/README.md#restorehelixsession) - Restore a session from a checkpoint
+- [`helixSessionsSendHelixSessionInput`](docs/sdks/helixsessions/README.md#sendhelixsessioninput) - Send a JSON command to a session
+- [`helixSessionsSetHelixDefaultModels`](docs/sdks/helixsessions/README.md#sethelixdefaultmodels) - Set the workspace's default Helix Cloud models
+- [`helixSessionsSignalHelixSession`](docs/sdks/helixsessions/README.md#signalhelixsession) - Stop a live Helix process
+- [`helixSessionsStreamHelixSession`](docs/sdks/helixsessions/README.md#streamhelixsession) - Stream a session's output
 - [`invitationsCreateInvitation`](docs/sdks/invitations/README.md#createinvitation) - Create invitation
 - [`invitationsDeleteInvitation`](docs/sdks/invitations/README.md#deleteinvitation) - Delete/revoke invitation
 - [`invitationsGetInvitation`](docs/sdks/invitations/README.md#getinvitation) - Get invitation
 - [`invitationsListInvitations`](docs/sdks/invitations/README.md#listinvitations) - List organization invitations
 - [`invitationsResendInvitation`](docs/sdks/invitations/README.md#resendinvitation) - Resend invitation
+- [`llmProvidersCreateProviderConfig`](docs/sdks/llmproviders/README.md#createproviderconfig) - Create provider config
+- [`llmProvidersDeleteProviderConfig`](docs/sdks/llmproviders/README.md#deleteproviderconfig) - Delete provider config
+- [`llmProvidersGetModelCatalog`](docs/sdks/llmproviders/README.md#getmodelcatalog) - Get models catalog
+- [`llmProvidersGetProviderConfig`](docs/sdks/llmproviders/README.md#getproviderconfig) - Get provider config
+- [`llmProvidersListAvailableModels`](docs/sdks/llmproviders/README.md#listavailablemodels) - List available models
+- [`llmProvidersListProviderConfigModels`](docs/sdks/llmproviders/README.md#listproviderconfigmodels) - List a provider configuration models
+- [`llmProvidersListProviderConfigs`](docs/sdks/llmproviders/README.md#listproviderconfigs) - List provider configs
+- [`llmProvidersTestProviderConfig`](docs/sdks/llmproviders/README.md#testproviderconfig) - Test provider connection
+- [`llmProvidersUpdateProviderConfig`](docs/sdks/llmproviders/README.md#updateproviderconfig) - Update provider config
+- [`managedAgentsActivateHelixAgent`](docs/sdks/managedagents/README.md#activatehelixagent) - Point an existing slot at a revision (an older one is a rollback)
+- [`managedAgentsDeployHelixAgent`](docs/sdks/managedagents/README.md#deployhelixagent) - Deploy a managed agent package into a slot (agent × Environment)
+- [`managedAgentsGetHelixAgent`](docs/sdks/managedagents/README.md#gethelixagent) - Inspect a managed agent: revisions, slots and launched sessions
+- [`managedAgentsGetHelixAgentCapabilities`](docs/sdks/managedagents/README.md#gethelixagentcapabilities) - Inspect managed agent deployment capabilities
+- [`managedAgentsGetHelixAgentOperation`](docs/sdks/managedagents/README.md#gethelixagentoperation) - Inspect a durable deployment operation
+- [`managedAgentsListHelixAgents`](docs/sdks/managedagents/README.md#listhelixagents) - List the workspace's managed agents and their slots
+- [`managedAgentsRetireHelixAgent`](docs/sdks/managedagents/README.md#retirehelixagent) - Disable a slot: new launches are refused, running sessions finish
 - [`organizationMembersAddOrganizationMember`](docs/sdks/organizationmembers/README.md#addorganizationmember) - Add organization member
 - [`organizationMembersListOrganizationMembers`](docs/sdks/organizationmembers/README.md#listorganizationmembers) - List organization members
 - [`organizationMembersRemoveOrganizationMember`](docs/sdks/organizationmembers/README.md#removeorganizationmember) - Remove organization member
@@ -902,51 +949,26 @@ To read more about standalone functions, check [FUNCTIONS.md](./FUNCTIONS.md).
 - [`organizationsGetOrganizationMemberCount`](docs/sdks/organizations/README.md#getorganizationmembercount) - Get member count
 - [`organizationsListOrganizations`](docs/sdks/organizations/README.md#listorganizations) - List user organizations
 - [`organizationsUpdateOrganization`](docs/sdks/organizations/README.md#updateorganization) - Update organization
-- [`providerConfigsCreateProvider`](docs/sdks/providerconfigs/README.md#createprovider) - Create provider config
-- [`providerConfigsDeleteProvider`](docs/sdks/providerconfigs/README.md#deleteprovider) - Delete provider config
-- [`providerConfigsGetModelsCatalog`](docs/sdks/providerconfigs/README.md#getmodelscatalog) - Get models catalog
-- [`providerConfigsGetProvider`](docs/sdks/providerconfigs/README.md#getprovider) - Get provider config
-- [`providerConfigsListAvailableModels`](docs/sdks/providerconfigs/README.md#listavailablemodels) - List available models
-- [`providerConfigsListProviderModels`](docs/sdks/providerconfigs/README.md#listprovidermodels) - List a provider configuration models
-- [`providerConfigsListProviders`](docs/sdks/providerconfigs/README.md#listproviders) - List provider configs
-- [`providerConfigsTestProvider`](docs/sdks/providerconfigs/README.md#testprovider) - Test provider connection
-- [`providerConfigsUpdateProvider`](docs/sdks/providerconfigs/README.md#updateprovider) - Update provider config
-- [`sandboxCheckpointHelixSession`](docs/sdks/sandbox/README.md#checkpointhelixsession) - Checkpoint a live Helix session
-- [`sandboxCloseHelixSessionInput`](docs/sdks/sandbox/README.md#closehelixsessioninput) - Explicitly close native RPC stdin
-- [`sandboxDeleteApiSandboxById`](docs/sdks/sandbox/README.md#deleteapisandboxbyid) - Tear down a sandbox
-- [`sandboxDeleteApiSandboxEnvironmentsByName`](docs/sdks/sandbox/README.md#deleteapisandboxenvironmentsbyname) - Delete a workspace Environment
-- [`sandboxGetApiSandbox`](docs/sdks/sandbox/README.md#getapisandbox) - List sandboxes
-- [`sandboxGetApiSandboxById`](docs/sdks/sandbox/README.md#getapisandboxbyid) - Get sandbox status
-- [`sandboxGetApiSandboxByIdCheckpoints`](docs/sdks/sandbox/README.md#getapisandboxbyidcheckpoints) - List checkpoints captured from this sandbox
-- [`sandboxGetApiSandboxByIdSessions`](docs/sdks/sandbox/README.md#getapisandboxbyidsessions) - List the Helix sessions a sandbox is hosting
-- [`sandboxGetApiSandboxByIdStream`](docs/sdks/sandbox/README.md#getapisandboxbyidstream) - Watch a sandbox's output live
-- [`sandboxGetApiSandboxByIdTraces`](docs/sdks/sandbox/README.md#getapisandboxbyidtraces) - Read a sandbox's captured spans
-- [`sandboxGetApiSandboxEnvironments`](docs/sdks/sandbox/README.md#getapisandboxenvironments) - List workspace Environments
-- [`sandboxGetApiSandboxEnvironmentsByName`](docs/sdks/sandbox/README.md#getapisandboxenvironmentsbyname) - Describe one workspace Environment
-- [`sandboxGetApiSandboxHelixDefaults`](docs/sdks/sandbox/README.md#getapisandboxhelixdefaults) - List the workspace's Helix Cloud models and its default
-- [`sandboxGetApiSandboxPresets`](docs/sdks/sandbox/README.md#getapisandboxpresets) - List sandbox presets
-- [`sandboxGetApiSandboxProviders`](docs/sdks/sandbox/README.md#getapisandboxproviders) - List sandbox providers
-- [`sandboxInputHelixSession`](docs/sdks/sandbox/README.md#inputhelixsession) - Write native JSONL to a live Helix session
-- [`sandboxLaunchHelixSession`](docs/sdks/sandbox/README.md#launchhelixsession) - Provision and launch a headless Helix session
-- [`sandboxListHelixSessionCheckpoints`](docs/sdks/sandbox/README.md#listhelixsessioncheckpoints) - List the checkpoints of the box a session runs on
-- [`sandboxListHelixWorkspaceSessions`](docs/sdks/sandbox/README.md#listhelixworkspacesessions) - List the workspace's Helix sessions across all sandboxes
-- [`sandboxPatchApiSandboxEnvironmentsByName`](docs/sdks/sandbox/README.md#patchapisandboxenvironmentsbyname) - Set or unset entries of a workspace Environment
-- [`sandboxPostApiSandbox`](docs/sdks/sandbox/README.md#postapisandbox) - Spawn a sandbox
-- [`sandboxPostApiSandboxByIdCheckpoint`](docs/sdks/sandbox/README.md#postapisandboxbyidcheckpoint) - Capture a Helix session's own transcript
-- [`sandboxPostApiSandboxByIdExec`](docs/sdks/sandbox/README.md#postapisandboxbyidexec) - Run a command in a sandbox
-- [`sandboxPostApiSandboxByIdInput`](docs/sdks/sandbox/README.md#postapisandboxbyidinput) - Write one line to a Helix session's stdin
-- [`sandboxPostApiSandboxByIdRestore`](docs/sdks/sandbox/README.md#postapisandboxbyidrestore) - Rebuild this sandbox from a checkpoint, with full state
-- [`sandboxPostApiSandboxByIdSession`](docs/sdks/sandbox/README.md#postapisandboxbyidsession) - Start a Helix session in a sandbox
-- [`sandboxPostApiSandboxByIdSignal`](docs/sdks/sandbox/README.md#postapisandboxbyidsignal) - Stop a running Helix session without destroying its sandbox
-- [`sandboxPostApiSandboxPreflight`](docs/sdks/sandbox/README.md#postapisandboxpreflight) - Preflight a sandbox definition
-- [`sandboxPostApiSandboxRun`](docs/sdks/sandbox/README.md#postapisandboxrun) - Run one command in a fresh sandbox
-- [`sandboxPostApiSandboxTelemetryV1Traces`](docs/sdks/sandbox/README.md#postapisandboxtelemetryv1traces) - Ingest OTLP spans from inside a sandbox
-- [`sandboxPostApiSandboxToken`](docs/sdks/sandbox/README.md#postapisandboxtoken) - Exchange a platform API key for a sandbox operator token
-- [`sandboxPutApiSandboxEnvironmentsByName`](docs/sdks/sandbox/README.md#putapisandboxenvironmentsbyname) - Create or replace a workspace Environment
-- [`sandboxPutApiSandboxHelixDefaults`](docs/sdks/sandbox/README.md#putapisandboxhelixdefaults) - Set the workspace's default Helix Cloud models
-- [`sandboxRestoreHelixSession`](docs/sdks/sandbox/README.md#restorehelixsession) - Rebuild the box a session runs on from a checkpoint
-- [`sandboxSignalHelixSession`](docs/sdks/sandbox/README.md#signalhelixsession) - Stop a live Helix process
-- [`sandboxStreamHelixSession`](docs/sdks/sandbox/README.md#streamhelixsession) - Follow one Helix execution
+- [`sandboxCheckpointSandboxHelixSession`](docs/sdks/sandbox/README.md#checkpointsandboxhelixsession) - Capture a Helix session's own transcript
+- [`sandboxCreateSandbox`](docs/sdks/sandbox/README.md#createsandbox) - Spawn a sandbox
+- [`sandboxCreateSandboxToken`](docs/sdks/sandbox/README.md#createsandboxtoken) - Exchange a platform API key for a sandbox operator token
+- [`sandboxDeleteSandbox`](docs/sdks/sandbox/README.md#deletesandbox) - Tear down a sandbox
+- [`sandboxExecSandboxCommand`](docs/sdks/sandbox/README.md#execsandboxcommand) - Run a command in a sandbox
+- [`sandboxGetSandbox`](docs/sdks/sandbox/README.md#getsandbox) - Get sandbox status
+- [`sandboxIngestSandboxTraces`](docs/sdks/sandbox/README.md#ingestsandboxtraces) - Ingest OTLP spans from inside a sandbox
+- [`sandboxListSandboxCheckpoints`](docs/sdks/sandbox/README.md#listsandboxcheckpoints) - List checkpoints captured from this sandbox
+- [`sandboxListSandboxes`](docs/sdks/sandbox/README.md#listsandboxes) - List sandboxes
+- [`sandboxListSandboxHelixSessions`](docs/sdks/sandbox/README.md#listsandboxhelixsessions) - List the Helix sessions a sandbox is hosting
+- [`sandboxListSandboxPresets`](docs/sdks/sandbox/README.md#listsandboxpresets) - List sandbox presets
+- [`sandboxListSandboxProviders`](docs/sdks/sandbox/README.md#listsandboxproviders) - List sandbox providers
+- [`sandboxListSandboxSpans`](docs/sdks/sandbox/README.md#listsandboxspans) - Read a sandbox's captured spans
+- [`sandboxPreflightSandbox`](docs/sdks/sandbox/README.md#preflightsandbox) - Preflight a sandbox definition
+- [`sandboxRestoreSandbox`](docs/sdks/sandbox/README.md#restoresandbox) - Rebuild this sandbox from a checkpoint, with full state
+- [`sandboxRunSandboxCommand`](docs/sdks/sandbox/README.md#runsandboxcommand) - Run one command in a fresh sandbox
+- [`sandboxSendSandboxHelixSessionInput`](docs/sdks/sandbox/README.md#sendsandboxhelixsessioninput) - Write one line to a Helix session's stdin
+- [`sandboxSignalSandboxHelixSession`](docs/sdks/sandbox/README.md#signalsandboxhelixsession) - Stop a running Helix session without destroying its sandbox
+- [`sandboxStartSandboxHelixSession`](docs/sdks/sandbox/README.md#startsandboxhelixsession) - Start a Helix session in a sandbox
+- [`sandboxStreamSandbox`](docs/sdks/sandbox/README.md#streamsandbox) - Watch a sandbox's output live
 - [`tracesGetTrace`](docs/sdks/traces/README.md#gettrace) - Get one trace envelope
 - [`tracesIngestTraceBatch`](docs/sdks/traces/README.md#ingesttracebatch) - Ingest a batch of traces (mutagent-cli hook format)
 - [`tracesListLogs`](docs/sdks/traces/README.md#listlogs) - List recent log records
@@ -954,9 +976,9 @@ To read more about standalone functions, check [FUNCTIONS.md](./FUNCTIONS.md).
 - [`tracesListTraceSpans`](docs/sdks/traces/README.md#listtracespans) - Get every span of one trace
 - [`userProfileChangePassword`](docs/sdks/userprofile/README.md#changepassword) - Change password
 - [`userProfileDeleteAccount`](docs/sdks/userprofile/README.md#deleteaccount) - Delete account
-- [`userProfileDeleteSession`](docs/sdks/userprofile/README.md#deletesession) - Revoke session
 - [`userProfileGetProfile`](docs/sdks/userprofile/README.md#getprofile) - Get current user profile
-- [`userProfileListSessions`](docs/sdks/userprofile/README.md#listsessions) - List active sessions
+- [`userProfileListUserSessions`](docs/sdks/userprofile/README.md#listusersessions) - List active sessions
+- [`userProfileRevokeUserSession`](docs/sdks/userprofile/README.md#revokeusersession) - Revoke session
 - [`userProfileUpdateProfile`](docs/sdks/userprofile/README.md#updateprofile) - Update user profile
 - [`workspaceMembersAddWorkspaceMember`](docs/sdks/workspacemembers/README.md#addworkspacemember) - Add workspace member
 - [`workspaceMembersListWorkspaceMembers`](docs/sdks/workspacemembers/README.md#listworkspacemembers) - List workspace members
@@ -1116,7 +1138,7 @@ async function run() {
       console.log(error.headers);
 
       // Depending on the method different errors may be thrown
-      if (error instanceof errors.ErrorMessage) {
+      if (error instanceof errors.ErrorResponse) {
         console.log(error.data$.error); // string
         console.log(error.data$.message); // string
       }
@@ -1132,7 +1154,7 @@ run();
 **Primary error:**
 * [`MutagentError`](./src/models/errors/mutagent-error.ts): The base class for HTTP error responses.
 
-<details><summary>Less common errors (17)</summary>
+<details><summary>Less common errors (18)</summary>
 
 <br />
 
@@ -1145,17 +1167,18 @@ run();
 
 
 **Inherit from [`MutagentError`](./src/models/errors/mutagent-error.ts)**:
-* [`ErrorMessage`](./src/models/errors/error-message.ts): Applicable to 75 of 96 methods.*
-* [`ErrorMessageStatusCode`](./src/models/errors/error-message-status-code.ts): Applicable to 61 of 96 methods.*
+* [`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): Standard error response. Applicable to 8 of 96 methods.*
-* [`ErrorCodeMessage`](./src/models/errors/error-code-message.ts): Response for status 400. Applicable to 7 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): Standard error response. Applicable to 6 of 96 methods.*
-* [`ErrorMessageModel`](./src/models/errors/error-message-model.ts): Response for status 422. Status code `422`. Applicable to 5 of 96 methods.*
-* [`ErrorMessage2`](./src/models/errors/error-message2.ts): Response for status 422. Status code `422`. Applicable to 5 of 96 methods.*
-* [`ErrorMessageCode`](./src/models/errors/error-message-code.ts): Response for status 428. Status code `428`. Applicable to 4 of 96 methods.*
+* [`SandboxPayloadTooLargeError`](./src/models/errors/sandbox-payload-too-large-error.ts): Payload Too Large: the sandbox provider refused the request for its size. Retrying the same request fails the same way. Status code `413`. Applicable to 5 of 96 methods.*
+* [`ModelNotInListError`](./src/models/errors/model-not-in-list-error.ts): Response for status 422. Status code `422`. Applicable to 5 of 96 methods.*
+* [`ModelResolutionError`](./src/models/errors/model-resolution-error.ts): Response for status 422. Status code `422`. Applicable to 5 of 96 methods.*
+* [`NoProviderConfiguredError`](./src/models/errors/no-provider-configured-error.ts): Response for status 428. Status code `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): A provider configuration's models, with this workspace's enablement applied. Applicable to 1 of 96 methods.*
-* [`ServiceUnavailableError`](./src/models/errors/service-unavailable-error.ts): Response for status 503. Status code `503`. Applicable to 1 of 96 methods.*
+* [`SandboxProviderUnreachableError`](./src/models/errors/sandbox-provider-unreachable-error.ts): Response for status 503. Status code `503`. Applicable to 1 of 96 methods.*
 * [`ResponseValidationError`](./src/models/errors/response-validation-error.ts): Type mismatch between the data returned from the server and the structure expected by the SDK. See `error.rawValue` for the raw value and `error.pretty()` for a nicely formatted multi-line string.
 
 </details>
@@ -1166,9 +1189,40 @@ run();
 <!-- Start Server Selection [server] -->
 ## Server Selection
 
+### Select Server by Index
+
+You can override the default server globally by passing a server index to the `serverIdx: number` optional parameter when initializing the SDK client instance. The selected server will then be used as the default on the operations that use it. This table lists the indexes associated with the available servers:
+
+| #   | Server                    | Description        |
+| --- | ------------------------- | ------------------ |
+| 0   | `https://api.mutagent.io` | Production         |
+| 1   | `http://localhost:3003`   | Development server |
+
+#### Example
+
+```typescript
+import { Mutagent } from "@mutagent/sdk";
+
+const mutagent = new Mutagent({
+  serverIdx: 0,
+  security: {
+    apiKey: process.env["MUTAGENT_API_KEY"] ?? "",
+  },
+});
+
+async function run() {
+  const result = await mutagent.userProfile.getProfile();
+
+  console.log(result);
+}
+
+run();
+
+```
+
 ### Override Server URL Per-Client
 
-The default server can be overridden globally by passing a URL to the `serverURL: string` optional parameter when initializing the SDK client instance. For example:
+The default server can also be overridden globally by passing a URL to the `serverURL: string` optional parameter when initializing the SDK client instance. For example:
 ```typescript
 import { Mutagent } from "@mutagent/sdk";