@aexhq/sdk 0.46.4-canary → 0.50.0

package/docs/events.md

@@ -1,143 +0,0 @@
----
-title: Events
----
-
-# Events
-
-Durable event reads use one `AexEventView` shape with CloudEvents identity,
-monotonic `sequence`, real AG-UI `threadId`, and real `runId`.
-The `AEX_EVENT_TYPES` and `AEX_EVENT_SOURCES` arrays list the events authored by
-the current SDK, but the raw envelope accepts future type and source strings.
-Unknown events are yielded with their original fields and data intact; `toAGUI`
-projects an unknown type through AG-UI's `CUSTOM` carrier without changing the
-raw event.
-
-```ts
-const session = await aex.sessions.open(sessionId);
-for await (const event of session.events.iterate()) {
-  if (event.isTextMessage()) console.log(event.data.text);
-  if (event.isToolCallStart()) console.log(event.data.name);
-}
-```
-
-`iterate()` follows cursor pages lazily and retains at most one API page. Use
-`list()` only when the full history is known to fit comfortably in memory.
-
-## Run lifecycle
-
-The public lifecycle is:
-
-- `RUN_STARTED`: the accepted run began.
-- `RUN_FINISHED`: all run state is committed, including the checkpoint.
-- `RUN_ERROR`: the run failed. It may have no checkpoint when failure happened
-  before a checkpoint could be created.
-
-Runtime execution ending is internal and is not emitted as a public lifecycle
-event. Consumers observe only the committed `RUN_FINISHED` or `RUN_ERROR`
-terminal boundary.
-
-```ts
-const run = session.messages.send("Continue the task.");
-
-for await (const event of run) {
-  if (event.isRunFinished()) {
-    console.log(event.data.checkpoint);
-  }
-}
-
-const result = await run.finished();
-```
-
-Message sends do not accept a historical `from` cursor. Their stream and
-finished result are scoped to the run accepted by that send, so events from an
-earlier run cannot be replayed into the current result. Use
-`session.events.iterate()`, `.list()`, `.stream({ from })`, or
-`.streamEnvelopes({ from })`
-when intentionally reading session history.
-
-`finished()` and `aex.start()` return the same run outcome vocabulary:
-`succeeded`, `failed`, `timed_out`, `cancelled`, or `interrupted`. A run held by
-suspension or approval is `interrupted`; the session lifecycle separately says
-`suspended` or `awaiting_approval`. Only `succeeded` sets `result.ok` to true.
-
-## Live stream
-
-```ts
-for await (const event of session.events.streamEnvelopes({ from: 0 })) {
-  if (event.replayable === false) {
-    console.log("live", event.liveSequence, event.type);
-  } else {
-    console.log("durable", event.sequence, event.type);
-  }
-}
-```
-
-`session.messages.send(...)` and `session.events.streamEnvelopes(...)` yield
-`AexStreamEventView`, a discriminated union:
-
-- Durable events have `sequence` and are replayable. They are the only events
-  returned by `events.iterate()`, `events.list()`, polling streams, archives,
-  and finished results.
-- Provisional live events have `replayable: false`, a per-run `liveSequence`,
-  `ephemeral: true`, the coordinator `receivedAt` time, and no durable
-  `sequence`. They are not replayed from storage.
-
-The SDK mints a short-lived coordinator ticket, reconnects durable events from
-the last sequence after transient transport loss, deduplicates repeated live
-frames by event id, and stops on a durable run terminal. The caller can tune
-transport watchdogs with `idleTimeoutMs`, `pingIntervalMs`, and
-`eventQuietRecheckMs`; these reconnect the event transport and never retry an
-application run.
-
-For a polling snapshot stream, use `session.events.stream()`. At invocation it
-targets the session's current run, or its last completed run when idle. Older
-run terminals cannot end that poll. The inclusive `from` cursor
-(`sequence >= from`) filters yielded history without hiding the target run's
-completion boundary:
-
-```ts
-for await (const event of session.events.stream({ from: 1024 })) {
-  console.log(event.sequence, event.type);
-}
-```
-
-The cursor must be a non-negative safe integer. A session with no runs returns
-one bounded snapshot instead of waiting for a terminal that cannot exist. For
-an explicitly bounded read, use `session.events.list()`.
-
-## Assistant messages
-
-Messages are a separate resource from raw events:
-
-```ts
-const messages = await session.messages.list();
-console.log(messages.at(-1)?.text);
-```
-
-Messages come directly from the messages endpoint. A missing or broken route is
-surfaced as an API failure rather than projected from another resource.
-
-## Output granularity
-
-`outputMode: "buffered"` emits coalesced assistant text. `"stream"` first emits
-provisional live token deltas, then exactly one durable coalesced
-`TEXT_MESSAGE_CONTENT` before the run terminal. Final `result.text`,
-`result.messages`, and `result.events` use the durable coalesced event and do
-not duplicate provisional deltas. Stream mode is rejected before submission
-for providers that do not support it; it is never silently downgraded.
-
-## Archives
-
-```ts
-const link = await session.events.archiveLink({ expiresIn: "1h" });
-const archive = await session.events.download();
-```
-
-The event archive contains the same public events the SDK returns, byte-identical.
-`archiveLink()` is a bounded convenience export. A session that exceeds the
-bulk-export limits returns a typed `413` API error; an export that cannot finish
-inside the server's request budget returns a typed `503` API error. The SDK does
-not retry either response automatically. Traverse large histories with
-`for await (const event of session.events.iterate())`; iteration follows bounded
-cursor pages without retaining the whole history. `events.list()` and
-`events.download()` are materializing convenience methods.

package/docs/files.md

@@ -1,130 +0,0 @@
----
-title: Files
----
-
-# Files
-
-There are two different file concepts:
-
-- `aex.workspace.files`: reusable, versioned input resources.
-- `session.files`: files captured from one session checkpoint.
-
-Raw uploaded bytes are assets. A workspace file is a typed resource that pins
-an asset, logical resource ID, version, hash, name, and mount path.
-
-`mountPath` is always a destination directory. The runtime preserves each
-source/archive filename inside that directory, so an `input.csv` published
-with `mountPath: "/workspace/input"` appears at
-`/workspace/input/input.csv`. `File.fromBytes({ name })` accepts the filename
-stored in the archive; the optional `File.fromPath(path, { name })` override is
-a filename-shaped label used only for resource identity while the source
-basename remains in the archive. The SDK derives a lowercase, hyphenated 2–64
-character value from either input. The result is the resource's storage slug; it never renames the mounted file.
-This compatibility slug is distinct from the
-directly supplied persisted name used by instructions. Multiple files can
-intentionally share one mount directory as long as their resulting paths do not
-collide.
-
-## Reusable workspace files
-
-```ts
-import { File } from "@aexhq/sdk";
-
-const source = await aex.workspace.files.publish(
-  await File.fromPath("./data/input.csv", { mountPath: "/workspace/input" })
-);
-
-const session = await aex.sessions.create({
-  model: "anthropic/claude-haiku-4-5",
-  assets: { files: [source] },
-});
-```
-
-`publish()` uploads immutable bytes, then creates or versions the workspace
-resource. `list()`, `get(resourceId, version?)`, and `delete(resourceId)` manage
-the catalog. Runs always receive pinned refs; they never resolve a mutable
-"latest" version during execution.
-
-As a run boots, each attached input archive is checked against a separate
-runtime materialization envelope: at most 16 MiB compressed, 128 MiB expanded,
-and 1,000 materialized files or safe symlinks. The runtime may overlap bulk skill extraction with
-the first model call, but it blocks the first tool, any post-run hook, and run
-completion until every promised input is ready. These execution-safety bounds
-are distinct from the broader raw-asset storage quota. The SDK and workspace
-publisher reject known violations before a resource can be pinned, and the
-runtime revalidates the immutable archive before use. An invalid input fails explicitly;
-tools and terminal results never observe a silently partial input tree.
-
-## Session file snapshots
-
-```ts
-const result = await session.messages.send("Create reports/summary.md").finished();
-const snapshot = await session.files.list({
-  checkpointId: result.checkpoint?.checkpointId
-});
-
-console.log(snapshot.revision);
-console.log(snapshot.files);
-```
-
-`SessionFilesSnapshot` contains both `revision` and `files`. Every file carries
-the same `checkpointId` as the revision, plus its exact `sizeBytes` and
-lowercase `sha256` digest. After `RUN_FINISHED`, this is the final committed
-state for that run. During an active run, an older complete checkpoint may
-still be visible.
-
-## Find and read
-
-```ts
-const report = await session.files.findOne({
-  filename: "summary.md",
-  extension: "md"
-});
-
-if (report) {
-  const preview = await session.files.read(report, { maxBytes: 50_000 });
-  console.log(preview.text, preview.truncated);
-}
-```
-
-Use `list(query?)`, `find(query)`, or `findOne(query)`. Cross-session file
-search is not part of the public SDK. Open the owning session and query its
-checkpoint instead.
-
-## Download and links
-
-```ts
-const file = snapshot.files[0];
-if (file) {
-  const bytes = await session.files.download(file);
-  const link = await session.files.link(file, { expiresIn: "15m" });
-  const response = await session.files.fetch(file);
-}
-```
-
-ID selectors must include their checkpoint:
-
-```ts
-await session.files.download({ id: "file_123", checkpointId: "cp_123" });
-```
-
-A string ID alone is intentionally rejected because an ID without a revision
-can resolve inconsistently after a later run.
-
-`download()` resolves the selector against that checkpoint and verifies both
-the byte length and SHA-256 digest before returning. An integrity mismatch
-fails immediately and is not retried. `read()` remains a bounded prefix read
-for large files and verifies integrity when it consumes the complete file.
-`link()` returns the resolved file metadata alongside the direct storage URL;
-`fetch()` returns only the raw one-shot storage `Response`, so retain metadata
-from `list()`, `findOne()`, or `link()` when independently verifying that stream.
-
-Omit the selector from `session.files.download()` to download the files
-namespace archive. `session.download()` returns the complete public session
-archive containing metadata, events, and files.
-
-## Failed runs
-
-A `RUN_ERROR` can occur before any checkpoint exists. In that case the result
-has `files: []` and `checkpoint === undefined`. A `RUN_FINISHED` without a
-checkpoint is a contract error and the SDK fails loudly.

package/docs/limits-and-quotas.md

@@ -1,114 +0,0 @@
----
-title: Limits & quotas
----
-
-# Limits & quotas
-
-These public ceilings bound a session, workspace, or request. Defaults that
-apply when you omit an option are also summarized in [Defaults](defaults.md).
-Your workspace's effective adjustable limits are available from `aex.whoami()`
-(CLI: `aex whoami`); contact support when a documented limit is adjustable but
-your workspace needs a higher value.
-
-## Session scope
-
-| Limit | Value | Adjustable? |
-| --- | --- | --- |
-| Session timeout | 1 minute minimum; 8 hours maximum and default | Per session with `overrides.timeout` |
-| Per-call exec timeout | 30 minutes by default | Per tool call with `timeoutMs` |
-| MCP connect timeout | 30 seconds by default | Per MCP server with `connectTimeoutMs` |
-| MCP call timeout | 30 minutes by default | Per MCP server with `callTimeoutMs` |
-| Per-session spend cap | None by default | Per session with `overrides.maxSpendUsd` |
-| Agent iterations | 20 by default; 200 maximum | Per session with `overrides.maxTurns` |
-
-### SessionFile capture
-
-When a capture cap is reached, remaining files are dropped and counted in the
-capture summary.
-
-| Limit | Value |
-| --- | --- |
-| Capture wall-clock budget | 1 hour |
-| Files captured | 50,000 maximum |
-| Bytes per captured file | 500 GB (decimal) maximum |
-| Total captured bytes | 500 GB (decimal) maximum |
-
-These two bound a single session's capture. They are not a workspace storage
-cap — see [Workspace scope](#workspace-scope) for what actually bounds stored
-bytes.
-
-### Tool output
-
-| Limit | Value | Adjustable? |
-| --- | --- | --- |
-| `web_fetch` returned body | 500 KB (UTF-8) by default | Per call with `max_bytes` |
-| `bash_output` per-read body | 1 MB (UTF-8) | No |
-| `grep` maximum file size | 25 MB; use `bash grep` for larger files | No |
-| `head`/`tail` maximum file size | 100 MB; use the equivalent shell commands for larger files | No |
-| `grep`/`glob` files visited per recursive walk | 100,000, then the result is truncated with a notice | No |
-
-### Attached archives
-
-An archive that exceeds any of these bounds is rejected before its contents are
-available to session code; a partial archive is never exposed.
-
-| Limit | Value |
-| --- | --- |
-| Compressed archive bytes | 16 MiB maximum |
-| Expanded archive bytes | 128 MiB maximum |
-| Materialized files and safe symlinks | 1,000 maximum per archive |
-| Fidelity metadata | 8 MiB maximum |
-| Planned entries across attached workspace-file archives | 10,000 maximum |
-
-### Subagents
-
-Subagent breadth and depth use managed budgets rather than fixed numeric
-entitlements. The service supports high recursive depth and workloads ranging
-to hundreds or thousands of live child agents, subject to admission at spawn
-time. Contact support before relying on unusually large fan-out.
-
-## Managed runtime
-
-- Only `/workspace` persists across turns of the same session. Everything else
-  is reset between turns and removed when the session ends.
-- Declare OS and language packages with `environment.packages`. Packages
-  installed ad hoc during a turn are best-effort and do not persist to the next
-  turn. Python environments may enforce PEP 668; prefer declared packages or a
-  virtual environment under `/workspace`.
-- The selected runtime preset's `memoryMb` is the memory ceiling. See the public
-  [`runtime-sizes.ts`](https://github.com/aexhq/aex/blob/main/packages/contracts/src/runtime-sizes.ts)
-  definitions and [Defaults](defaults.md).
-- `overrides.maxTurns` controls the agent-loop limit (20 by default, 200
-  maximum).
-
-## Workspace scope
-
-Stored bytes are bounded by your plan's monthly storage grant, not by a fixed
-per-workspace number. The Free plan includes 5 GB. An upload that cannot be
-paid for is refused at admission with `quota_exhausted` (HTTP 409) and a
-remedy telling you which of the two options applies: upgrade the plan, or add
-a payment method and enable overage. Paid plans with overage enabled are not
-refused; the usage is billed.
-
-Use `aex.whoami()` to read the effective concurrency and submission limits
-attached to the current workspace. Stable admission errors include
-`quota_exhausted`, `workspace_concurrency_exceeded` and
-`workspace_submit_rate_exceeded`.
-
-| Limit | Value | Adjustable? |
-| --- | --- | --- |
-| Runtime asset archive | 16 MiB compressed, 128 MiB expanded, 1,000 materialized entries | No |
-| Skill bundle directory depth | 16 | Contact support |
-| Skill bundle entry path | 512 characters | No |
-| `File.mountPath` | 512 characters | No |
-
-`File.mountPath` names a directory, not a destination filename. The attached
-file retains its source/archive filename below that directory; see
-[Files](files.md).
-
-## Request scope
-
-| Limit | Value | Adjustable? |
-| --- | --- | --- |
-| Signed file URL TTL | 300 seconds at the API layer | Per call with `expiresSeconds` |
-| Event-stream connection ticket TTL | 60 seconds | Per mint with `ttlMs` |

package/docs/limits.md

@@ -1,51 +0,0 @@
----
-title: Limits
----
-
-# Limits
-
-aex sessions autonomous agents on the hosted managed runtime. The SDK opens durable
-sessions, sends turns, streams events, captures files, and exposes auth-gated
-reads and downloads.
-
-For what the product supports, see [Features](https://aex.dev/docs/features/).
-For the current provider/model set, see the generated
-[provider/runtime capability matrix](provider-runtime-capabilities.md).
-
-## Current Defaults
-
-| Area | Default |
-| --- | --- |
-| Workspace storage | Bounded by the plan's monthly storage grant (Free: 5 GB); paid plans bill beyond the allowance once overage is enabled. |
-
-## Product Boundaries
-
-| Area | Boundary |
-| --- | --- |
-| Runtime | New submissions run on a managed runtime. `runtime.kind` selects `spot_container` (the default), `container`, or `lambda`; `runtime.size` selects a managed machine-size preset (`Sizes.*`). Both fields are optional. Runtimes differ in capability and delivery semantics, not only in price — each publishes a profile at `whoami().runtimeCapabilities.profilesByRuntimeKind`, and a submission exceeding the selected profile is refused before execution. See [Models & runtimes](../concepts/providers-and-runtimes.md). |
-| Single effect | One atomic LLM call or tool call runs for at most 14 minutes on every runtime (`profile.limits.maxSingleEffectMs`). On `lambda` the live budget may be shorter, bounded by the remaining invocation time. An overrun fails that call with a typed error. |
-| Provider policy | Provider retention, training exclusion, HIPAA/BAA, data residency, abuse policy, and pricing belong to the selected provider account, endpoint, and contract. |
-| Secrets | Provider keys, MCP credentials, and environment secrets are caller-owned. aex excludes secret values from idempotency and uses the explicit secret surfaces described in [Secrets](secrets.md). |
-| MCP servers | Remote MCP servers are customer-trusted systems. aex validates declarations and routes credentials; it does not make an untrusted MCP server safe. |
-| Files | Captured files, events, and metadata are stored under the session record and downloaded through auth-gated routes. SessionFile content is customer content. |
-| Human review | Sessions execute after submission. Cancellation is available, but aex does not pause a session for platform-mediated approval or interactive clarification. |
-| Sessions | The durable product primitive is the session record. Sessions can be resumed by id and auto-suspend after the configured idle window; persistent named agent profiles and saved agent definitions are out of scope. |
-| Hosting | The SDK and CLI connect to the hosted aex API. `baseUrl` may also target the localhost development stack; self-hosting is not supported. |
-| Model cost | Model tokens are served through the platform's managed gateway and billed by aex as a usage dimension on the run. Finished results report the cost and provider usage recorded for that run. |
-
-## Provider Policy Links
-
-These links are starting points for provider-owned policy areas; they do not
-create aex guarantees.
-
-- Anthropic API data retention policy: <https://platform.claude.com/docs/en/manage-claude/api-and-data-retention>
-- OpenAI API data controls: <https://platform.openai.com/docs/guides/your-data>
-- Mistral privacy and API data handling: <https://docs.mistral.ai/admin/security-access/privacy>
-- Gemini API data handling: <https://ai.google.dev/gemini-api/docs/logs-policy>
-
-## Unsupported Claims
-
-Do not describe aex as providing self-hosting, provider-wide retention,
-HIPAA/BAA or data-residency guarantees, a general-purpose sandbox for every
-downstream service, human-in-the-loop approval checkpoints, or persistent agent
-identity.

package/docs/mcp.md

@@ -1,47 +0,0 @@
----
-title: MCP
----
-
-# MCP
-
-MCP support is remote HTTPS/SSE only. Stdio MCP servers are rejected because aex is a remote session dispatcher, not a local process supervisor.
-
-Rules:
-
-- MCP servers are declared in the session request config (`mcpServers`).
-- Runtime HITL is disabled.
-- Tool policy must be configured before session start.
-- Enabled MCP tools use `always_allow` provider permissions.
-- `always_ask` is not used by aex MVP.
-- Bearer/OAuth-style auth is carried by the `McpServer` instance (its `headers`); the SDK splits it into the vaulted secrets channel server-side.
-
-Use allowlists for sensitive servers whenever possible.
-
-## Large-payload responses
-
-aex is a session dispatcher, not an MCP runtime. We intentionally do
-**not** interpose on the transport between the model and an upstream MCP
-server, so we cannot elide MCP responses or write them to the session
-filesystem on the user's behalf. Anything an MCP tool returns lands
-directly in the model's context.
-
-For ingestion-style MCP servers that return large JSON blobs (search results,
-catalogue dumps, bulk reads), prefer a skill that writes files instead of
-putting the whole response in model context:
-
-1. Package the upstream helper as a Skill (`Skill.fromDir` / `Skill.fromUrl`)
-   and pass it via the top-level `skills` option. The skill can include a CLI
-   binary or script that the agent invokes with its bash tool.
-2. Keep any upstream HTTPS credentials in `environment.secrets`.
-3. Have the CLI write the full payload to the session filesystem. By default,
-   files it creates or modifies are captured automatically; pass
-   `fileCapture.allowedDirs` only when you want to narrow capture to specific roots.
-   Return only a small handle (path, item count, summary) to the model.
-
-The agent sees the handle in context; the bytes ride out through
-`download()` as normal captured files.
-
-If you genuinely want everything in context (small responses, code
-search, etc.), use MCP. If the payload would blow your context budget,
-the CLI-as-skill pattern is the supported answer — there is no platform
-flag to elide MCP responses.

package/docs/networking.md

@@ -1,114 +0,0 @@
----
-title: Networking
----
-
-# Networking
-
-Session networking is managed by aex. Your code can make ordinary outbound HTTP
-requests, subject to the session's `environment.networking` policy and the
-service-wide safety boundary. Private, loopback, link-local, and otherwise
-unsafe destinations remain blocked.
-
-`environment.networking` has two modes:
-
-- `open` is the default and does not require a per-session allowlist.
-- `limited` restricts supported outbound HTTP clients to the hosts you list in
-  `allowedHosts`.
-
-`allowedHosts` is a useful least-privilege control and an auditable statement of
-intent. It is not a security boundary against adversarial code executing inside
-the session; low-level networking that bypasses supported HTTP client behavior
-may fail and remains subject to the service-wide egress policy.
-
-## Paths that always work
-
-These managed capabilities are not subject to `environment.networking`, so you
-do not list their hosts:
-
-- The model/provider call for the session and its subagents.
-- The built-in `web_search` and `web_fetch` tools.
-- Remote MCP servers declared in `mcpServers`; see [MCP](mcp.md).
-- Package registries used by packages declared in `environment.packages`.
-
-`environment.networking` governs other outbound requests made by your code,
-such as `curl` in the `bash` tool, Python `requests`, Node `fetch`, or a
-third-party SDK.
-
-## Restrict a session to an allowlist
-
-Set `mode: "limited"` and list the hosts your code needs. A supported HTTP
-client is refused when it requests a host that is neither listed nor covered by
-one of the managed capabilities above. Package registries implied by
-`environment.packages` are allowed automatically.
-
-### TypeScript
-
-```ts
-import { Aex } from "@aexhq/sdk";
-
-const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
-
-await aex.start({
-  model: "anthropic/claude-haiku-4-5",
-  message: "Fetch the public status page and summarize it.",
-  environment: {
-    networking: {
-      mode: "limited",
-      allowedHosts: ["api.example.com", "status.example.com"]
-    }
-  },
-});
-```
-
-`allowedHosts` entries are lowercased host names such as `api.example.com`.
-Include a non-default port when needed (`api.example.com:8443`); a bare host
-covers HTTPS on port 443. Matching is exact, not wildcard or suffix based, so
-list each required host.
-
-Keep the allowlist in your session options so the network policy stays next to
-the code that needs it.
-
-## Open mode
-
-A session that omits `environment.networking` uses `open` mode. Set
-`mode: "open"` explicitly when you want that choice visible in configuration.
-Open mode removes the per-session allowlist, but the service-wide safety
-boundary still applies.
-
-```ts
-await aex.start({
-  model: "anthropic/claude-haiku-4-5",
-  message: "Research the topic across the open web.",
-  environment: { networking: { mode: "open" } },
-});
-```
-
-Built-in web research uses the managed `web_search` and `web_fetch` tools and
-does not require an allowlist entry.
-
-## Ordinary HTTP clients work without extra setup
-
-Use normal HTTP clients without configuring a per-request proxy or installing a
-custom certificate. For example, in a limited session that allows
-`api.example.com`:
-
-```bash
-curl -sS https://api.example.com/v1/status   # works
-curl -sS https://other-host.example          # refused (not in allowlist)
-```
-
-Clients that override standard network or certificate behavior, or use a
-non-HTTP protocol, may fail even for a listed host. Let the client use its
-normal defaults whenever possible.
-
-## Limitations
-
-- `allowedHosts` applies only in `limited` mode.
-- A listed host can still be unavailable under the service-wide safety policy.
-- Exact host matching means subdomains must be listed separately.
-- Contact support when a required public host is unavailable.
-
-For credentialed HTTP calls, pass the credential through
-`environment.secrets` and let your code use its normal HTTP client. For remote
-tool servers, see [MCP](mcp.md). For all session configuration fields, see
-[Session configuration](session-config.md).

package/docs/provider-runtime-capabilities.md

@@ -1,32 +0,0 @@
----
-title: Model access
----
-
-# Model access
-
-Generated from `packages/contracts/src/models.ts`.
-
-Regenerate with `bun run capabilities:generate`; check with `bun run capabilities:check`.
-
-Aex routes every model through the managed Vercel AI Gateway. You name a model
-by its gateway `creator/model` **slug** and the platform's single managed key
-handles the upstream provider relationship — you never supply a provider API
-key, and there is no `provider` field.
-
-## Model ids are gateway slugs
-
-- A model id is a `creator/model` slug string, validated at the boundary by `parseModelSlug` against `^[a-z0-9-]+\/[A-Za-z0-9._:-]+$` (lowercase creator, then `/`, then the model segment).
-- Examples: `anthropic/claude-haiku-4-5`, `anthropic/claude-sonnet-4-6`, `deepseek/deepseek-v4-flash`, `openai/gpt-4.1`, `google/gemini-2.5-flash`.
-- The catalog is OPEN: adding a model the gateway serves needs zero code — a well-formed slug just works. A slug this SDK does not recognize is still accepted at the boundary and arbitrated by the gateway at submit time; a truly unknown model fails there.
-
-## Streaming
-
-`outputMode: "stream"` is honored for ALL models — every model streams through the gateway. There is no per-model streaming-capability gate.
-
-## Skills
-
-Skills are supplied through the top-level `skills` option. Build one with `Skill.fromDir`, `Skill.fromUrl`, `Skill.fromFiles`, `Skill.fromContent`, or `Skill.fromBytes`; each normalizes to a named workspace skill that the platform snapshots into durable session asset storage.
-
-## Runtime selection is independent of model
-
-Runtime selection is independent of the model: `runtime.kind` accepts `container`, `spot_container`, or `lambda`; `runtime.size` accepts the managed size presets.