@evolvingmachines/evolve 0.0.55-project-sable.20260916.db0bc0bb → 0.0.56

package/docs-agents/python/index.md

@@ -1,122 +0,0 @@
-# Evolve Python SDK
-
-Run CLI agents in secure sandboxes with built-in observability.
-
-```bash
-pip install evolvingmachines-evolve
-```
-
-```python
-from evolve import Evolve
-
-evolve = Evolve()
-await evolve.run(prompt='Hello world')
-```
-
----
-
-## Reference
-
-### Getting Started
-
-| Topic | Link |
-|-------|------|
-| Installation (Python 3.10+, Node.js 18+) | [Getting Started → Installation](./01-getting-started.md#installation) |
-| Quick Start (3 steps) | [Getting Started → Quick Start](./01-getting-started.md#quick-start) |
-| Core Lifecycle (run → get_output_files → kill) | [Getting Started → Core Lifecycle](./01-getting-started.md#core-lifecycle) |
-| Streaming basics | [Getting Started → Streaming](./01-getting-started.md#streaming) |
-| Gateway, managed BYO provider keys, and direct keys | [Getting Started → Authentication](./01-getting-started.md#authentication) |
-| Gateway mode (EVOLVE_API_KEY) | [Getting Started → Gateway Mode](./01-getting-started.md#gateway-mode-evolve_api_key) |
-| Managed BYO provider keys | [Getting Started → Managed BYO Provider Keys](./01-getting-started.md#managed-byo-provider-keys) |
-| Managed secrets | [Configuration → Managed Secrets](./02-configuration.md#managed-secrets) |
-| Direct provider key mode (local BYOK) | [Getting Started → Direct Provider Key Mode](./01-getting-started.md#direct-provider-key-mode-local-byok) |
-| BYO Claude Max / Codex / Gemini subscription | [Getting Started → BYO Claude Max Subscription](./01-getting-started.md#byo-claude-max-subscription) |
-| Supported agents & models | [Getting Started → Agent Reference](./01-getting-started.md#agent-reference) |
-| Agent-specific options (reasoning_effort) | [Getting Started → Agent Reference](./01-getting-started.md#agent-reference) |
-
-### Configuration
-
-| Topic | Link |
-|-------|------|
-| Sandbox providers (E2B, Modal, Daytona) | [Configuration → Sandbox Providers](./02-configuration.md#sandbox-providers) |
-| Provider auto-resolution from env | [Configuration → Sandbox Providers](./02-configuration.md#auto-resolution) |
-| `sandbox_create_options=` (image, network, user, homeDir) | [Configuration → Sandbox Create Options](./02-configuration.md#sandbox-create-options) |
-| `workspace_mode=` (knowledge / swe) | [Configuration → Workspace Modes](./02-configuration.md#workspace-modes) |
-| Evolve instance (full constructor API) | [Configuration → Evolve Instance](./02-configuration.md#evolve-instance) |
-| `AgentConfig` | [Configuration → Evolve Instance](./02-configuration.md#evolve-instance) |
-| `sandbox=` provider | [Configuration → Sandbox Providers](./02-configuration.md#sandbox-providers) |
-| `context=` / `files=` | [Configuration → Evolve Instance](./02-configuration.md#evolve-instance) |
-| `system_prompt=` | [Configuration → Evolve Instance](./02-configuration.md#evolve-instance) |
-| `schema=` (Pydantic / JSON Schema) | [Configuration → Evolve Instance](./02-configuration.md#evolve-instance) |
-| `browser=` browser guide | [Configuration → Browser Automation](./02-configuration.md#browser-automation) |
-| `browser_credentials=` browser logins | [Configuration → Browser Credentials](./02-configuration.md#browser-credentials) |
-| `plugins=` | [Configuration → Agent Plugins](./02-configuration.md#agent-plugins) |
-| `skills=` | [Configuration → Agent Skills](./02-configuration.md#agent-skills) |
-| `integrations=` (managed app integrations) | [Configuration → Managed Integrations](./02-configuration.md#managed-integrations) |
-| `managed_secrets=` | [Configuration → Managed Secrets](./02-configuration.md#managed-secrets) |
-| `mcp_servers=` (STDIO / HTTP / SSE) | [Configuration → Evolve Instance](./02-configuration.md#evolve-instance) |
-| `secrets=` | [Configuration → Evolve Instance](./02-configuration.md#evolve-instance) |
-| `storage=` (checkpointing) | [Runtime → Storage & Checkpointing](./03-runtime.md#storage--checkpointing) |
-| `session_tag_prefix=` (observability) | [Runtime → Observability](./03-runtime.md#observability) |
-| Skills catalog (PDF, browser, research, etc.) | [Configuration → Agent Skills](./02-configuration.md#agent-skills) |
-| Integration auth/account helpers | [Configuration → Managed Integrations](./02-configuration.md#managed-integrations) |
-| Integration tool filtering | [Configuration → Managed Integrations](./02-configuration.md#managed-integrations) |
-| MCP server config (McpServerConfig) | [Configuration → Evolve Instance](./02-configuration.md#evolve-instance) |
-
-### Runtime
-
-| Topic | Link |
-|-------|------|
-| `run()` | [Runtime → run](./03-runtime.md#run) |
-| `execute_command()` | [Runtime → execute_command](./03-runtime.md#execute_command) |
-| Streaming events (content, lifecycle, stdout, stderr) | [Streaming Events](./04-streaming.md) |
-| OutputEvent / SessionUpdate types | [Streaming → Type Definitions](./04-streaming.md#type-definitions) |
-| LifecycleEvent / LifecycleReason | [Streaming → LifecycleEvent](./04-streaming.md#lifecycleevent-typeddict-shape) |
-| Tool events (ToolCall, ToolCallUpdate, ToolKind) | [Streaming → Type Definitions](./04-streaming.md#type-definitions) |
-| Browser lifecycle event fields | [Streaming → Browser Automation Streaming](./04-streaming.md#browser-automation-streaming) |
-| UI integration example | [Streaming → UI Integration Example](./04-streaming.md#ui-integration-example) |
-| Upload files (`upload_context()`, `upload_files()`) | [Runtime → Upload](./03-runtime.md#upload-local--sandbox) |
-| Download files (`get_output_files()`, `save_local_dir()`) | [Runtime → Download](./03-runtime.md#download-sandbox--local) |
-| Session controls (interrupt, pause, resume, kill) | [Runtime → Session Controls](./03-runtime.md#session-controls) |
-| `get_host()` (port forwarding) | [Runtime → get_host](./03-runtime.md#get_host) |
-| Async context manager (`async with evolve:`) | [Runtime → Session Management](./03-runtime.md#session-management) |
-| Workspace filesystem layout | [Runtime → Workspace & Structured Output](./03-runtime.md#workspace--structured-output) |
-| Structured output (Pydantic / JSON Schema) | [Runtime → Workspace & Structured Output](./03-runtime.md#structured-output) |
-| Multi-turn conversations | [Runtime → Session Management](./03-runtime.md#session-management) |
-| Pause / resume | [Runtime → Session Management](./03-runtime.md#session-management) |
-| Save and reconnect (`sandbox_id=`, `set_session()`) | [Runtime → Session Management](./03-runtime.md#session-management) |
-| Storage & checkpointing (gateway) | [Runtime → Storage & Checkpointing](./03-runtime.md#storage--checkpointing) |
-| Auto-checkpoint, explicit checkpoint, restore | [Runtime → Storage & Checkpointing](./03-runtime.md#auto-checkpoint-via-run) |
-| Checkpoint lineage | [Runtime → Checkpoint Lineage](./03-runtime.md#checkpoint-lineage) |
-| `storage()` client, `evolve.storage()` | [Runtime → Listing & Browsing Checkpoints](./03-runtime.md#listing--browsing-checkpoints) |
-| `sessions()` client for past sessions & traces | [Runtime → Historical Sessions & Trace Download](./03-runtime.md#historical-sessions--trace-download) |
-| Observability (dashboard + local logs) | [Runtime → Observability](./03-runtime.md#observability) |
-| Error handling | [Runtime → Error Handling](./03-runtime.md#error-handling) |
-
-### Hosted evals
-
-Datasets, jobs, trials, checks, analyses and the `evolve` CLI are documented at https://docs.evolvingmachines.ai. The `evolve-evals` skill carries the same pages.
-
-### Swarm & Pipeline
-
-| Topic | Link |
-|-------|------|
-| Swarm setup (SwarmConfig) | [Swarm & Pipeline](./05-swarm-pipeline.md) |
-| Input types (FileMap, folders, chaining) | [Swarm → Input Types](./05-swarm-pipeline.md#input-types) |
-| `best_of()` (N candidates + judge) | [Swarm → best_of](./05-swarm-pipeline.md#best_of) |
-| `map()` (parallel processing) | [Swarm → map](./05-swarm-pipeline.md#map) |
-| `map()` + best_of | [Swarm → map + best_of](./05-swarm-pipeline.md#map--best_of) |
-| `filter()` (evaluate + threshold) | [Swarm → filter](./05-swarm-pipeline.md#filter) |
-| `reduce()` (synthesize many → one) | [Swarm → reduce](./05-swarm-pipeline.md#reduce) |
-| `verify` (quality gate with feedback loop) | [Swarm → verify](./05-swarm-pipeline.md#verify-quality-gate) |
-| Result types (SwarmResult, ReduceResult, BestOfResult) | [Swarm → Result Types](./05-swarm-pipeline.md#result-types) |
-| Chaining operations (result.json → data.json) | [Swarm → Chaining Operations](./05-swarm-pipeline.md#chaining-operations) |
-| AgentOverride (per-operation agent config — `AgentConfig` in Python) | [Swarm → AgentOverride](./05-swarm-pipeline.md#agentoverride) |
-| Concurrency (semaphore, ordering guarantees) | [Swarm → Concurrency](./05-swarm-pipeline.md#concurrency) |
-| RetryConfig (exponential backoff) | [Swarm & Pipeline](./05-swarm-pipeline.md) |
-| Pipeline (fluent chaining) | [Swarm → Pipeline](./05-swarm-pipeline.md#pipeline) |
-| Pipeline step configs (MapConfig, FilterConfig, ReduceConfig) | [Swarm → Step Configurations](./05-swarm-pipeline.md#step-configurations) |
-| Pipeline events (step_start, step_complete, etc.) | [Swarm → Events](./05-swarm-pipeline.md#events) |
-| Pipeline result (PipelineResult) | [Swarm → Result](./05-swarm-pipeline.md#result) |
-| TerminalPipeline (reduce is terminal) | [Swarm → Terminal Pipeline](./05-swarm-pipeline.md#terminal-pipeline) |
-| Filter `emit` option (success / filtered / all) | [Swarm → Pipeline](./05-swarm-pipeline.md#step-configurations) |

package/docs-agents/typescript/01-getting-started.md

@@ -1,494 +0,0 @@
-# Evolve TypeScript SDK
-
-Run CLI agents ([Claude Code](https://github.com/anthropics/claude-code), [Codex](https://github.com/openai/codex), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Qwen Code](https://github.com/QwenLM/qwen-code), [Kimi Code](https://github.com/MoonshotAI/kimi-code), [OpenCode](https://github.com/anomalyco/opencode), [Droid](https://docs.factory.ai/cli/droid-exec/overview)) in secure sandboxes with built-in observability.
-
----
-
-## Installation
-
-**Requirements:** [Node.js 18+](https://nodejs.org/)
-
-```bash
-npm install @evolvingmachines/evolve
-```
-
-Storage & checkpointing is available in [gateway mode](./03-runtime.md#storage--checkpointing) (`EVOLVE_API_KEY`) — no additional dependencies needed.
-
-For structured output with [Zod](https://zod.dev) schemas (recommended but not required — JSON Schema objects also work):
-
-```bash
-npm install zod
-```
-
----
-
-## Quick Start
-
-**1. Get your API key** from [dashboard.evolvingmachines.ai](https://dashboard.evolvingmachines.ai) — $10 free credits, no CC required.
-
-**2. Set environment variables:**
-
-```bash
-# .env
-EVOLVE_API_KEY=sk-...        # Evolve gateway key (dashboard.evolvingmachines.ai)
-```
-
-**3. Run your first agent:**
-
-Evolve auto-resolves API keys and sandbox providers from environment variables — no need to pass them explicitly.
-
-```ts
-import { Evolve } from "@evolvingmachines/evolve";
-
-const evolve = new Evolve()
-    .withSystemPrompt("You are Manus Evolve, a powerful AI agent. You can execute code, browse the web, manage files, and solve complex tasks.")
-    .withBrowser()  // optional; defaults to remote managed agent-browser automation in Gateway mode
-    .withSkills(["anthropics/skills", "./my-skill"])  // skills.sh / git / local references
-    .withIntegrations({ userId: "root", apps: ["gmail", "notion"] });  // optional; managed integrations in Gateway mode
-
-// Run agent
-const result = await evolve.run({
-    prompt: "Go to Hacker News top posts. Spawn 5 parallel sub-agents to screenshot each of the top 5 posts."
-});
-
-console.log(result.stdout);
-
-// Get output files
-const output = await evolve.getOutputFiles();
-for (const [name, content] of Object.entries(output.files)) {
-    console.log(name);
-}
-
-// Once done, destroy sandbox
-await evolve.kill();
-```
-
-### Core Lifecycle
-
-Every Evolve application follows this pattern:
-
-```
-new Evolve()  →  .run()  →  .getOutputFiles()  →  .kill()
-   setup         execute      retrieve results     ALWAYS cleanup
-```
-
-> **IMPORTANT: Always call `kill()` when done.** Each `run()` creates a cloud sandbox that bills until destroyed. Forgetting `kill()` leaves sandboxes running indefinitely. Use try/finally to guarantee cleanup:
-
-```ts
-const evolve = new Evolve().withAgent({ type: "claude" });
-try {
-    await evolve.run({ prompt: "Analyze the dataset" });
-    const output = await evolve.getOutputFiles();
-    console.log(output.files);           // All files from output/
-    console.log(output.data);            // Parsed result.json (if schema set)
-} finally {
-    await evolve.kill();                 // Always destroy sandbox
-}
-```
-
-- `run()` can be called multiple times — each continues in the same sandbox session with full context/history.
-- `getOutputFiles()` returns files from the `output/` folder. If `.withSchema()` was set, `output.data` contains the validated result.
-- `kill()` destroys the sandbox. The next `run()` creates a fresh one.
-
-### Streaming
-
-Subscribe to real-time agent output:
-
-```ts
-evolve.on("content", (event) => {
-    // event.update.sessionUpdate: "agent_message_chunk" | "tool_call" | "plan" | ...
-    console.log(event.update);
-});
-
-evolve.on("lifecycle", (event) => {
-    // event.reason: "sandbox_ready" | "run_complete" | "run_failed" | ...
-    console.log(event.reason, event.sandbox, event.agent);
-});
-```
-
-See [Streaming Events](./04-streaming.md) for all event types, type definitions, and a full UI integration example.
-
-### Gateway Features
-
-When using `EVOLVE_API_KEY`:
-
-- **Tracing:** Automatic tracing and agent analytics at [dashboard.evolvingmachines.ai](https://dashboard.evolvingmachines.ai) for observability and replay — no extra setup needed. Use `withSessionTagPrefix()` to label sessions for easy filtering.
-- **Browser Automation:** Call `.withBrowser()` for the default and recommended managed browser path with dashboard live view and replay.
-- **Checkpointing:** Snapshot sandbox state to Evolve-managed storage with `.withStorage()` — no S3 credentials needed. See [Storage & Checkpointing](./03-runtime.md#storage--checkpointing).
-- **Hosted Evals:** Score agents against datasets of tasks on managed infrastructure with `jobs()` and `datasets()`, or the `evolve` CLI. See https://docs.evolvingmachines.ai.
-
----
-
-## Authentication
-
-| | Gateway Mode | Managed BYO Provider Keys | Direct Provider Key Mode |
-|---|---------|---------------------------|--------------------------|
-| Setup | `EVOLVE_API_KEY` | `EVOLVE_API_KEY` + provider key saved in Dashboard → Secrets → BYO Provider Keys | [Model provider keys](#agent-reference) + [`E2B_API_KEY`](https://e2b.dev) |
-| Provider key location | Evolve-managed | Encrypted Dashboard secret | Your local environment or app config |
-| Sandbox receives | Evolve gateway runtime config | A short-lived, sandbox-scoped credential — never your raw provider key or `EVOLVE_API_KEY` for that route | Raw provider key environment variable |
-| Observability | [dashboard.evolvingmachines.ai](https://dashboard.evolvingmachines.ai) | [dashboard.evolvingmachines.ai](https://dashboard.evolvingmachines.ai) | `~/.evolve-sdk/observability/` |
-| Browser | `.withBrowser()` is the default and recommended managed browser path with live view and replay. | Same as Gateway Mode | Self-managed browser runtime; no managed live/replay |
-| Model billing | Evolving Machines | Your provider account for enabled providers | Your provider accounts |
-
----
-
-### Gateway Mode (EVOLVE_API_KEY)
-
-Get API key from [dashboard.evolvingmachines.ai](https://dashboard.evolvingmachines.ai).
-
-```bash
-# .env
-EVOLVE_API_KEY=sk-...
-```
-
-```ts
-import { Evolve } from "@evolvingmachines/evolve";
-
-const evolve = new Evolve()
-    .withAgent({ type: "claude" });
-
-await evolve.run({ prompt: "Hello" });
-```
-
----
-
-### Managed BYO Provider Keys
-
-Use this when you want supported provider usage billed to your provider account while keeping gateway features.
-
-1. Save your provider key in Dashboard → Secrets → BYO Provider Keys.
-2. Keep `EVOLVE_API_KEY` in your app.
-3. Run any supported agent normally.
-
-**You can save a key for Anthropic and OpenAI.** Those are the two providers this route serves today, so a Claude run or a Codex run can bill your own account. The gateway itself reaches seven providers — Anthropic, OpenAI, Gemini, DashScope, Kimi, OpenRouter, and Droid/Factory — but the other five have no bring-your-own path, and a run that routes through one of them is billed to Evolve whether or not you have a key saved. That is not a silent fallback so much as arithmetic: an Anthropic key cannot pay for a Moonshot call.
-
-When enabled, Evolve routes supported provider calls through a short-lived, sandbox-scoped credential. The SDK does not receive the raw provider key, and the sandbox does not receive `EVOLVE_API_KEY` for that provider route. If no managed key is enabled for that provider, gateway mode falls back to Evolve-managed model routing.
-
----
-
-### Direct Provider Key Mode (Local BYOK)
-
-Use this when you want to pass provider keys from your own local environment or app config. Requires [E2B API key](https://e2b.dev) for sandbox.
-
-```bash
-# .env
-ANTHROPIC_API_KEY=sk-...
-E2B_API_KEY=e2b_...
-```
-
-```ts
-import { Evolve, createE2BProvider } from "@evolvingmachines/evolve";
-
-const sandbox = createE2BProvider({
-    apiKey: process.env.E2B_API_KEY,
-});
-
-const evolve = new Evolve()
-    .withAgent({
-        type: "claude",
-        providerApiKey: process.env.ANTHROPIC_API_KEY,
-    })
-    .withSandbox(sandbox);
-```
-
-### BYO Claude Max Subscription
-
-```bash
-# Run in terminal, follow login steps -> receive token:
-claude --setup-token
-
-# Long-lived authentication token created successfully!
-# Your OAuth token (valid for 1 year): sk-ant-...
-```
-
-```bash
-# .env
-CLAUDE_CODE_OAUTH_TOKEN=sk-ant-...
-E2B_API_KEY=e2b_...
-```
-
-```ts
-import { Evolve, createE2BProvider } from "@evolvingmachines/evolve";
-
-const sandbox = createE2BProvider({
-    apiKey: process.env.E2B_API_KEY,
-});
-
-const evolve = new Evolve()
-    .withAgent({
-        type: "claude",
-        // SDK reads token from CLAUDE_CODE_OAUTH_TOKEN automatically
-    })
-    .withSandbox(sandbox);
-```
-
-### BYO Codex Subscription
-
-```bash
-# Run in terminal, follow login steps:
-codex auth --provider openai
-
-# Creates auth file at ~/.codex/auth.json
-```
-
-```bash
-# .env
-CODEX_OAUTH_FILE_PATH=~/.codex/auth.json
-E2B_API_KEY=e2b_...
-```
-
-```ts
-import { Evolve, createE2BProvider } from "@evolvingmachines/evolve";
-
-const sandbox = createE2BProvider({
-    apiKey: process.env.E2B_API_KEY,
-});
-
-const evolve = new Evolve()
-    .withAgent({
-        type: "codex",
-        // SDK reads auth file from CODEX_OAUTH_FILE_PATH automatically
-    })
-    .withSandbox(sandbox);
-```
-
-### BYO Gemini Subscription
-
-```bash
-# Run in terminal, follow login steps:
-gemini auth login
-
-# Creates credentials file at ~/.gemini/oauth_creds.json
-```
-
-```bash
-# .env
-GEMINI_OAUTH_FILE_PATH=~/.gemini/oauth_creds.json
-E2B_API_KEY=e2b_...
-```
-
-```ts
-import { Evolve, createE2BProvider } from "@evolvingmachines/evolve";
-
-const sandbox = createE2BProvider({
-    apiKey: process.env.E2B_API_KEY,
-});
-
-const evolve = new Evolve()
-    .withAgent({
-        type: "gemini",
-        // SDK reads credentials file from GEMINI_OAUTH_FILE_PATH automatically
-    })
-    .withSandbox(sandbox);
-```
-
----
-
-### Agent Reference
-
-Set env vars and the SDK picks them up automatically — no need to pass explicitly.
-
-> **IMPORTANT: Only use the exact model names listed below.** The SDK will error on unrecognized model names. Do not invent or guess model identifiers.
-
-The Direct key column applies to Direct Provider Key Mode. Managed BYO Provider Keys use Gateway Mode plus Dashboard-stored provider keys.
-
-| type | models | default | Gateway | Direct key |
-|------|--------|---------|---------|------|
-| `"claude"` | `"fable"` `"opus"` `"sonnet"` `"haiku"` `"opus[1m]"` `"sonnet[1m]"` `"glm-5.3"` `"glm-5.3-flash"` `"openrouter/deepseek/deepseek-v4.1-flash"` `"fireworks/deepseek-v4.1-flash"` | `"opus"` | `EVOLVE_API_KEY` | `ANTHROPIC_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN` |
-| `"codex"` | `"gpt-5.6-sol"` `"gpt-5.6-terra"` `"gpt-5.6-luna"` `"gpt-5.5"` `"gpt-5.3-codex"` | `"gpt-5.6-sol"` | `EVOLVE_API_KEY` | `OPENAI_API_KEY` or `CODEX_OAUTH_FILE_PATH` |
-| `"gemini"` | `"gemini-3.5-flash"` `"gemini-3.5-flash-lite"` `"gemini-3.1-pro-preview"` `"gemini-3.7-flash"` *(not selectable yet — see below)* | `"gemini-3.5-flash"` | `EVOLVE_API_KEY` | `GEMINI_API_KEY` or `GEMINI_OAUTH_FILE_PATH` |
-| `"qwen"` | `"qwen3.7-max"` `"qwen3.7-plus"` `"qwen3.6-flash"` | `"qwen3.7-max"` | `EVOLVE_API_KEY` | `OPENAI_API_KEY` |
-| `"kimi"` | `"kimi-k3"` `"kimi-k2.7-code"` `"kimi-k3-raptor"` `"kimi-k2p7-code-raptor"` | `"kimi-k3"` | `EVOLVE_API_KEY` | `KIMI_API_KEY` |
-| `"opencode"` | `"openrouter/anthropic/claude-fable-5.1"` `"openrouter/anthropic/claude-opus-5"` `"openrouter/anthropic/claude-sonnet-5"` `"openrouter/anthropic/claude-haiku-4.5"` `"openrouter/openai/gpt-5.6-sol"` `"openrouter/openai/gpt-5.6-terra"` `"openrouter/openai/gpt-5.6-luna"` `"openrouter/google/gemini-3.6-flash"` `"openrouter/qwen/qwen3.7-max"` `"openrouter/moonshotai/kimi-k3"` `"openrouter/z-ai/glm-5.3"` `"openrouter/z-ai/glm-5.3-flash"` `"openrouter/deepseek/deepseek-v4.1-flash"` `"fireworks/deepseek-v4.1-flash"` | `"openrouter/anthropic/claude-opus-5"` | `EVOLVE_API_KEY` | `OPENROUTER_API_KEY` |
-| `"droid"` | `"claude-fable-5.1"` `"claude-opus-5"` `"claude-sonnet-5"` `"claude-haiku-4-5"` `"gpt-5.6-sol"` `"gpt-5.6-terra"` `"gpt-5.6-luna"` `"gemini-3.6-flash"` `"qwen3.7-max"` `"kimi-k3"` `"glm-5.3"` `"glm-5.3-flash"` `"openrouter/deepseek/deepseek-v4.1-flash"` `"fireworks/deepseek-v4.1-flash"` | `"claude-opus-5"` | `EVOLVE_API_KEY` | `FACTORY_API_KEY` |
-
-`"gemini-3.7-flash"` is named here for completeness: the gateway carries it as a correctly priced entry and serves it under its own name on a raw call. It is not selectable through the `gemini` agent, and nothing rejects it if you pass it anyway — the stable `gemini` CLI (0.55.1) rewrites the model client-side before the request ever leaves the sandbox, collapsing every name ending in `flash` onto its own current flash model. Ask for `"gemini-3.7-flash"` (or `"gemini-3.6-flash"`) today and you are silently served, and billed for, `gemini-3.5-flash`. Names that do not end in `flash` skip that rewrite, which is why `"gemini-3.5-flash-lite"` and `"gemini-3.1-pro-preview"` serve under their own names. A newer CLI release is not enough on its own, because the swap follows the CLI's own default flash, so a `-flash` name joins the selectable set only once a live probe shows the CLI actually serving it. On the hosted platform the wrong-model integrity guard refuses such a trial rather than scoring it; with your own provider key there is no backstop, so treat the three names above as the gemini lineup you can really run.
-
-Model names route by themselves: pass just the name from the table and Evolve serves it on its default provider, or pass a provider-prefixed name (`openai/gpt-5.5`, `openrouter/moonshotai/kimi-k3`) to pick the provider explicitly. The table's names are the supported, priced set — prefixed routing beyond it works for advanced use but is outside the supported lineup. One agent differs: on "opencode" a prefixed name outside its table is sent as an OpenRouter id (`openrouter/<name>`), so pick a provider there through OpenRouter's own ids; the other agents pass a prefixed name through as written.
-
-`"glm-5.3-flash"` is GLM-5.3 Flash served from one pinned Fireworks host through the gateway: $0.15/M input and $0.50/M output ($0.03/M cached input); `"glm-5.3"` is the full model on OpenRouter.
-
-`"openrouter/deepseek/deepseek-v4.1-flash"` is DeepSeek V4.1 Flash served through OpenRouter, under the same spelling on `"claude"`, `"droid"` and `"opencode"`. The `openrouter/<vendor>/<model>` form is OpenRouter's own model id: the gateway routes any id in that form to OpenRouter and bills the call at OpenRouter's price for it, so other OpenRouter models work the same way — the table lists the supported ones. It is also the default model of the hosted evals analyzer (its default reasoning effort is `"high"`).
-
-`"fireworks/deepseek-v4.1-flash"` is the same DeepSeek V4.1 Flash on a second route, served from Fireworks through the gateway, on the same three agents: $0.22/M input and $0.66/M output ($0.007/M cached input). Pick it when you want the Fireworks host; `"openrouter/deepseek/deepseek-v4.1-flash"` remains the default model of the hosted evals analyzer and task checker. It is served through the Evolve gateway; direct mode has no Fireworks key, so `"opencode"` with your own `OPENROUTER_API_KEY` refuses the name at configuration (`EvolveConfigError`, naming the model) instead of sending it.
-
-Agent-specific option: `reasoningEffort` controls how much reasoning/thinking the selected agent uses when that agent supports it.
-
-| Agent | Default when omitted (pinned by Evolve) | Supported `reasoningEffort` |
-|-------|------------------------------------------|-----------------------------|
-| `"claude"` | `"high"` — Claude Code's documented default | `"low"` `"medium"` `"high"` `"xhigh"` `"max"` |
-| `"codex"` | `"high"` — pinned by Evolve (owner policy: graded harnesses run high) | `"none"` `"low"` `"medium"` `"high"` `"xhigh"` `"max"` (`"none"` and `"max"` are GPT-5.6 values) |
-| `"gemini"` | No effort control | Not supported |
-| `"qwen"` | `"thinking"` | `"thinking"` `"no-thinking"` |
-| `"kimi"` | `"thinking"` at `"max"` effort — the Kimi K3 API default | `"thinking"` `"no-thinking"` `"low"` `"medium"` `"high"` `"xhigh"` `"max"` |
-| `"opencode"` | `"thinking"` + `"high"` | `"thinking"` `"no-thinking"` `"minimal"` `"low"` `"medium"` `"high"` `"xhigh"` `"max"` |
-| `"droid"` | `"high"` — matches Droid’s own default for Opus 5, pinned by Evolve | `"off"` `"minimal"` `"low"` `"medium"` `"high"` `"xhigh"` `"max"`; exact values depend on the Droid model |
-
-When you omit `reasoningEffort`, Evolve does not leave the choice to the CLI. For every harness with an effort control, the SDK stamps the pinned default from the table explicitly on the run — as a flag, an environment variable, or a config-file entry, whatever that CLI reads. This keeps runs reproducible: the effort a run used is always recorded in the run itself, never implied by a vendor default that could change under you. Where the vendor documents a default, the pin matches it; `gemini` has no effort control, so nothing is stamped there.
-
-Note that thinking cannot be disabled on Kimi K3 at the API level — `"no-thinking"` applies to the K2-generation models.
-
-Agent-specific option: `config` supplies the harness's own native settings — a local file path or an inline object. Claude receives it as a settings JSON passed through `--settings`; Codex receives it as the base `~/.codex/config.toml` (an inline object must be losslessly representable as TOML — no `null` values). Your document is the base layer: Evolve's own inputs — gateway routing, MCP servers, the model and effort stamps — always land on top of it, so a config can tune permissions, sandbox settings, or tool behavior but never re-route where the model traffic goes. Only `claude` and `codex` support a native config; naming one on any other agent type throws at `.withAgent()` rather than being silently ignored.
-
-```typescript
-const evolve = new Evolve()
-    .withAgent({
-        type: "claude",
-        config: { permissions: { deny: ["WebSearch", "WebFetch"] } },
-    });
-```
-
-Instead of hand-writing such a config, `preset` names a bundle Evolve ships and guarantees. `preset: "no-internet"` turns off the vendor's server-side web tools — Claude gets that exact `permissions.deny` stamp, Codex gets `-c web_search=disabled` on its command line (Codex's default is `"cached"`, an OpenAI-maintained web index, so only the explicit flag removes the tool). `preset: "pinned-context"` pins one fixed effective context window (200000 tokens) — Claude via `autoCompactWindow`, Codex via `-c model_context_window` — so vendor-side window tuning never changes what a run had to work with. A preset is stamped **on top** of any `config` you also pass, and a preset stamp always wins where the two disagree: your document cannot undo the guarantee. Only `claude` and `codex` can guarantee the presets today; naming one on any other agent type throws at `.withAgent()` rather than running without its guarantee.
-
-```typescript
-const evolve = new Evolve()
-    .withAgent({ type: "codex", preset: "no-internet" });
-```
-
-For Claude Fable 5.1, use `model: "fable"`. For OpenCode via OpenRouter, use `model: "openrouter/anthropic/claude-fable-5.1"`. For Claude 1M context window, use `model: "sonnet[1m]"` or `model: "opus[1m]"`.
-
-#### Harness and Model Pairing
-
-A harness and its model are chosen together, and a few harnesses only accept models from their own family:
-
-- **`qwen`** must run a Qwen-native model (the `qwen3.x` aliases, routed via DashScope). Qwen Code injects the DashScope-only `enable_thinking` request parameter on every call, which OpenAI-family models reject with a `400` — so pointing the `qwen` harness at a non-Qwen model fails.
-- **`opencode`** routes every model through OpenRouter, so its models are the `openrouter/…` ids in the table above (a bare id is prefixed with `openrouter/` for you).
-- **`kimi`** must be told a context ceiling, which Kimi Code sends as the request's `max_tokens`. Its own models get Kimi's 262144; any other model (say `gpt-5.5` behind an OpenAI-compatible gateway) gets a conservative 128000 instead, because an oversized `max_tokens` is rejected outright — LiteLLM answers `400 max_tokens is too large`. Pass the model's real ceiling to skip the guess:
-
-```ts
-.withAgent({
-    type: "kimi",
-    model: "gpt-5.5",
-    maxContextSize: 128000,   // (optional) the model's real completion ceiling, used verbatim
-})
-```
-
-`maxContextSize` is an SDK option, never an environment variable. Harnesses that do not send a ceiling ignore it.
-
-Two harness quirks the SDK handles automatically, with nothing for you to set: the `claude` harness runs with `IS_SANDBOX=1` so Claude Code's `--dangerously-skip-permissions` is allowed under root, and the `gemini` harness boots with workspace trust set so Gemini CLI runs headless instead of refusing an untrusted workspace.
-
-#### Evolve-Provided Gateway Models
-
-These models require Gateway mode (`EVOLVE_API_KEY`) and are routed by Evolve for latency-sensitive runs. Direct provider keys do not apply.
-
-| Agent | Model | Use |
-|-------|-------|-----|
-| `"kimi"` | `"kimi-k3-raptor"` | Kimi K3 fast route for latency-sensitive agent runs |
-| `"kimi"` | `"kimi-k2p7-code-raptor"` | Kimi K2.7 Code Raptor route for interactive coding and agent runs |
-
-### Agent Examples
-
-```bash
-# .env - set env vars for auto-pickup
-ANTHROPIC_API_KEY=sk-...   # claude
-OPENAI_API_KEY=sk-...      # codex, qwen
-GEMINI_API_KEY=...         # gemini
-KIMI_API_KEY=...           # kimi
-OPENROUTER_API_KEY=sk-...  # opencode
-FACTORY_API_KEY=...        # droid
-E2B_API_KEY=e2b_...        # sandbox
-```
-
-```ts
-// claude (auto-picks ANTHROPIC_API_KEY + E2B_API_KEY)
-const evolve = new Evolve()
-    .withAgent({ type: "claude" });
-
-const evolve = new Evolve()
-    .withAgent({ type: "claude", model: "opus" });
-
-const evolve = new Evolve()
-    .withAgent({ type: "claude", model: "fable" });
-
-const evolve = new Evolve()
-    .withAgent({ type: "claude", reasoningEffort: "max" });
-
-const evolve = new Evolve()
-    .withAgent({
-        type: "claude",
-        model: "sonnet[1m]",  // 1M context window
-    });
-```
-
-```ts
-// codex (auto-picks OPENAI_API_KEY + E2B_API_KEY)
-const evolve = new Evolve()
-    .withAgent({ type: "codex" });
-
-const evolve = new Evolve()
-    .withAgent({ type: "codex", model: "gpt-5.3-codex" });
-
-const evolve = new Evolve()
-    .withAgent({ type: "codex", reasoningEffort: "high" });
-```
-
-```ts
-// gemini (auto-picks GEMINI_API_KEY + E2B_API_KEY)
-const evolve = new Evolve()
-    .withAgent({ type: "gemini" });
-
-const evolve = new Evolve()
-    .withAgent({ type: "gemini", model: "gemini-3.1-pro-preview" });
-```
-
-```ts
-// qwen (auto-picks OPENAI_API_KEY + E2B_API_KEY)
-const evolve = new Evolve()
-    .withAgent({ type: "qwen" });
-
-const evolve = new Evolve()
-    .withAgent({ type: "qwen", model: "qwen3.7-max" });
-
-const evolve = new Evolve()
-    .withAgent({ type: "qwen", reasoningEffort: "no-thinking" });
-```
-
-```ts
-// kimi (auto-picks KIMI_API_KEY + E2B_API_KEY)
-const evolve = new Evolve()
-    .withAgent({ type: "kimi" });
-
-const evolve = new Evolve()
-    .withAgent({ type: "kimi", model: "kimi-k3" });
-
-const evolve = new Evolve()
-    .withAgent({
-        type: "kimi",
-        model: "kimi-k2p7-code-raptor",
-        reasoningEffort: "thinking",
-    });
-```
-
-```ts
-// opencode — OpenRouter (auto-picks OPENROUTER_API_KEY + E2B_API_KEY)
-const evolve = new Evolve()
-    .withAgent({ type: "opencode" });
-
-const evolve = new Evolve()
-    .withAgent({ type: "opencode", model: "openrouter/openai/gpt-5.6-sol" });
-
-const evolve = new Evolve()
-    .withAgent({ type: "opencode", model: "openrouter/anthropic/claude-fable-5.1" });
-
-const evolve = new Evolve()
-    .withAgent({ type: "opencode", reasoningEffort: "xhigh" });
-```
-
-```ts
-// droid (auto-picks FACTORY_API_KEY + E2B_API_KEY)
-const evolve = new Evolve()
-    .withAgent({ type: "droid" });
-
-const evolve = new Evolve()
-    .withAgent({ type: "droid", model: "gpt-5.5" });
-```
-
----
-
-## Where to go next
-
-- [Configuration](./02-configuration.md) shapes the sandbox: which provider, which image, which skills, secrets and integrations.
-- [Runtime](./03-runtime.md) covers everything after `run()` — files in and out, sessions, checkpointing, cost.
-- [Streaming](./04-streaming.md) is the event surface a UI subscribes to.
-- [Swarm & Pipeline](./05-swarm-pipeline.md) runs many agents in parallel and chains the results.
-- [Hosted evals](https://docs.evolvingmachines.ai) is the other half of the SDK, and the part that is easiest to miss. Instead of driving one agent yourself, you hand Evolve datasets and a list of agents and read back scored trials — `jobs()` and `datasets()`, or the `evolve` CLI, with no `Evolve` instance involved. Start with `datasets().list()`: what comes back is whatever the platform has published to your account. If that list is empty, you have not hit a wall — [Bring your own dataset](https://docs.evolvingmachines.ai/core-concepts/datasets) publishes a corpus of your own.