@aexhq/sdk 0.40.16 → 0.41.1

package/docs/public-surface.json

@@ -2,7 +2,7 @@
   "brand": "aex",
   "productName": "Agent Executor",
   "oneLine": "aex is an agent execution platform for launching autonomous agents from a simple TypeScript SDK and CLI.",
-  "description": "Open durable agent sessions, send turns, stream events, capture outputs, and compose agents with skills, files, MCP, secrets, networking controls, and subagents across the managed runtime.",
+  "description": "Open durable agent sessions, send turns, stream events, capture files, and compose agents with skills, files, MCP, secrets, networking controls, and subagents across the managed runtime.",
   "alpha": {
     "label": "Alpha testing",
     "description": "Access is limited to invited testers while we harden the hosted runtime, dashboard, and SDK workflows."
@@ -26,7 +26,7 @@
       "console.log(result.status, result.text);"
     ],
     "cliLines": [
-      "aex run \\",
+      "aex start \\",
       "  --api-key \"$AEX_API_KEY\" \\",
       "  --anthropic-api-key \"$ANTHROPIC_API_KEY\" \\",
       "  --model claude-haiku-4-5 \\",
@@ -49,13 +49,13 @@
       "slug": "agent-runtime",
       "href": "/docs/features/#agent-runtime",
       "title": "Agent runtime",
-      "description": "Managed autonomous runs with filesystem read/edit, grep/glob/head/tail, open web fetch/search, background commands, code execution, git, and subagents."
+      "description": "Managed autonomous sessions with filesystem read/edit, grep/glob/head/tail, open web fetch/search, background commands, code execution, git, and subagents."
     },
     {
       "slug": "durable-infrastructure",
       "href": "/docs/features/#durable-infrastructure",
       "title": "Durable infrastructure",
-      "description": "Run records, status, wait/cancel/delete, idempotency, typed events, output capture, downloads, timeouts, and runtime sizes."
+      "description": "SessionRecord records, status, wait/cancel/delete, idempotency, typed events, file capture, downloads, timeouts, and runtime sizes."
     },
     {
       "slug": "agent-composition",
@@ -67,7 +67,7 @@
       "slug": "subagents",
       "href": "/docs/features/#subagents",
       "title": "Subagents",
-      "description": "Typed parent/child lineage for async child runs, output handoff, and bounded agent delegation."
+      "description": "Typed parent/child lineage for async child sessions, file handoff, and bounded agent delegation."
     },
     {
       "slug": "models-and-providers",
@@ -79,7 +79,7 @@
       "slug": "typed-control-surface",
       "href": "/docs/features/#typed-control-surface",
       "title": "Typed control surface",
-      "description": "Strongly typed SDK inputs, CLI parity, BYOK provider keys, workspace secrets, redaction, and output modes."
+      "description": "Strongly typed SDK inputs, CLI parity, BYOK provider keys, workspace secrets, redaction, assistant text modes, and file capture policy."
     }
   ]
 }

package/docs/quickstart.md

@@ -16,8 +16,8 @@ This installs the TypeScript SDK exports and the bundled `aex` CLI.
 
 aex is currently in **invite-only beta**: workspaces and API keys are issued
 by the aex team — contact <support@aex.dev> for beta access. Once you have
-access, create a quickstart SDK token with `runs:read`, `runs:write`,
-`outputs:read`, and `billing:read` in the dashboard at <https://aex.dev>. The
+access, create a quickstart SDK token with `sessions:read`, `sessions:write`,
+`files:read`, and `billing:read` in the dashboard at <https://aex.dev>. The
 examples also need your BYOK provider key for the model you choose. For the
 Claude examples below:
 
@@ -45,11 +45,11 @@ const first = await session.send("Write a short report and save it as a file.").
 console.log(first.status, first.costUsd, first.text);
 ```
 
-`send().done()` (and `run()`) **await settle by default**, so the result always
+`send().done()` (and `start()`) **await settle by default**, so the result always
 carries a terminal `status` (`succeeded` / `failed` / `timed_out` / `cancelled`
 — never a bare `idle`) plus `costUsd` and `usage`. Pass `await: 'park'` to
 return early at the render-complete park event when you don't need cost/usage.
-`costUsd` is aex runtime/storage spend and **excludes** your BYOK provider
+`costUsd` is aex starttime/storage spend and **excludes** your BYOK provider
 charges — price those from `usage` token counts against your provider's rates.
 
 The session parks as `idle` between turns and automatically moves to
@@ -62,17 +62,17 @@ await resumed.send("Now run the validation command and summarize the result.").d
 
 ## 4. One-shot convenience
 
-`run()` opens a session, sends `message` as one turn, and returns the collected
-result. Its `runId` is the session id.
+`start()` opens a session, sends `message` as one turn, and returns the collected
+result. Its `sessionId` is the session id.
 
 ```ts
-const result = await aex.run({
+const result = await aex.start({
   model: Models.CLAUDE_HAIKU_4_5,
   apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! },
   message: "Write a short report and save it as a file."
 });
 
-console.log(result.runId, result.status, result.text);
+console.log(result.sessionId, result.status, result.text);
 ```
 
 ## 5. Session control: stream, wait, download
@@ -101,7 +101,7 @@ console.log(messages.at(-1)?.text);
 const record = await session.wait();
 console.log(record.status);
 
-// Download the whole session record (metadata, events, outputs) as a zip.
+// Download the whole session record (metadata, events, files) as a zip.
 await session.download({ to: "./session.zip" });
 ```
 
@@ -109,7 +109,7 @@ The same run from the bundled CLI (`npx aex` on a local install; or
 `npm i -g @aexhq/sdk` for a bare `aex`):
 
 ```bash
-npx aex run \
+npx aex start \
   --api-key "$AEX_API_KEY" \
   --anthropic-api-key "$ANTHROPIC_API_KEY" \
   --model claude-haiku-4-5 \
@@ -120,7 +120,7 @@ npx aex run \
 ## Add capabilities
 
 - Add files, skills, AGENTS.md, MCP servers, packages, and networking controls with [Composition](concepts/composition.md).
-- Delegate bounded sub-tasks to child runs with [Subagents](concepts/subagents.md).
-- Get notified when a run finishes with [Webhooks](webhooks.md).
-- Narrow output capture or download individual files with [Outputs](outputs.md).
+- Delegate bounded sub-tasks to child sessions with [Subagents](concepts/subagents.md).
+- Get notified when a session finishes with [Webhooks](webhooks.md).
+- Narrow file capture or download individual files with [Files](files.md).
 - Check supported providers and models in the [provider/runtime capability matrix](provider-runtime-capabilities.md).

package/docs/release.md

@@ -21,7 +21,7 @@ bun run docs:build
 bun run pack:sdk
 ```
 
-`bun run pack:sdk` builds the SDK, runs a Bun pack dry-run, and runs the public
+`bun run pack:sdk` builds the SDK, sessions a Bun pack dry-run, and sessions the public
 boundary gate. Offline user tests install the packed SDK into a clean Bun
 project and exercise the SDK and CLI from that install tree.
 
@@ -30,15 +30,15 @@ project and exercise the SDK and CLI from that install tree.
 The manual `.github/workflows/release.yml` workflow:
 
 - Installs with `bun ci`.
-- Runs lint, unit/security, offline user tests, docs build, and `pack:sdk`.
+- Sessions lint, unit/security, offline user tests, docs build, and `pack:sdk`.
 - Refuses to publish if `@aexhq/sdk@<package version>` already exists.
 - Packs `packages/sdk` with `bun pm pack`.
-- Runs the publish job in the `npm-release` GitHub Environment and requires its
+- Sessions the publish job in the `npm-release` GitHub Environment and requires its
   `NPM_TOKEN` secret.
 - Publishes the tarball with npm provenance to the selected dist-tag (`canary`
   by default).
 - Waits for npm visibility.
-- Runs live user tests against the exact published version.
+- Sessions live user tests against the exact published version.
 
 Publish canary first for release validation. Promote the same immutable version
 only after the downstream platform release gate is green.
@@ -64,7 +64,7 @@ CLI version that supports OIDC trusted publishing.
 
 The manual `.github/workflows/promote.yml` workflow assigns an npm dist-tag to
 an already-published `@aexhq/sdk` version, usually `latest` after canary and
-platform validation. It also runs in `npm-release`, requires `NPM_TOKEN`, and
+platform validation. It also sessions in `npm-release`, requires `NPM_TOKEN`, and
 does not rebuild or republish the package.
 
 ## What ships in the tarball

package/docs/retries.md

@@ -50,7 +50,7 @@ Turn it off entirely with `retry: false`, or make a single attempt with
 ## Idempotent by construction
 
 Retries — whether the built-in transport retry or your own re-invocation of
-`run(...)` — never double-bill. The one-shot `run(...)` and `sessions.run(...)`
+`run(...)` — never double-bill. The one-shot `run(...)` and `sessions.start(...)`
 derive the turn's idempotency key from the session-create key, so re-invoking
 either with the same `idempotencyKey` de-duplicates **both** the session create
 and the billable turn server-side:
@@ -58,7 +58,7 @@ and the billable turn server-side:
 ```ts
 // A retried call with the same idempotencyKey resolves to the same run,
 // not a second billable one.
-const result = await aex.run({
+const result = await aex.start({
   model: "claude-haiku-4-5",
   message: "Write a short report and save it as a file.",
   apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! },
@@ -106,7 +106,7 @@ working, and it carries structured, non-leaky detail:
 import { isRateLimited } from "@aexhq/sdk";
 
 try {
-  await aex.run({ /* … */ });
+  await aex.start({ /* … */ });
 } catch (err) {
   if (isRateLimited(err)) {
     err.status;         // 429 | 503 | 529

package/docs/secrets.md

@@ -4,14 +4,14 @@ title: Secrets
 
 # Secrets
 
-aex supports BYOK provider keys, per-run credentials, and reusable workspace
+aex supports BYOK provider keys, per-session credentials, and reusable workspace
 secrets. Secret values are excluded from the idempotency fingerprint and do not
-belong in run config.
+belong in session config.
 
 Runnable examples need both `AEX_API_KEY` for aex and the matching BYOK
 provider key, such as `ANTHROPIC_API_KEY` for Claude.
 
-## Use A Provider Key For One Run
+## Use A Provider Key For One SessionRecord
 
 ### TypeScript
 
@@ -20,7 +20,7 @@ import { Aex, Models } from "@aexhq/sdk";
 
 const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
 
-await aex.run({
+await aex.start({
   model: Models.CLAUDE_HAIKU_4_5,
   message: "Write a short report and save it as a file.",
   apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
@@ -30,7 +30,7 @@ await aex.run({
 ### CLI
 
 ```bash
-aex run \
+aex start \
   --api-key "$AEX_API_KEY" \
   --anthropic-api-key "$ANTHROPIC_API_KEY" \
   --model claude-haiku-4-5 \
@@ -40,7 +40,7 @@ aex run \
 ## Upload An Env Secret
 
 Use `Secret.value(...).upload(...)` when you start with an ephemeral value and
-want to persist it as a named workspace secret for later runs.
+want to persist it as a named workspace secret for later sessions.
 
 ```ts
 import { Aex, Models, Providers, Secret } from "@aexhq/sdk";
@@ -51,7 +51,7 @@ const githubToken = await Secret.value(process.env.GITHUB_TOKEN!).upload(aex, {
   name: "github-token"
 });
 
-await aex.run({
+await aex.start({
   provider: Providers.ANTHROPIC,
   model: Models.CLAUDE_HAIKU_4_5,
   message: "Inspect the repository issues.",
@@ -86,7 +86,7 @@ const secrets = await aex.secrets.list();
 const metadata = await aex.secrets.get("serper-api-key");
 ```
 
-## Inject A Workspace Secret Into A Run
+## Inject A Workspace Secret Into A SessionRecord
 
 Reference workspace secrets with `Secret.ref(name)`. The value resolves
 server-side and is injected as the named environment variable.
@@ -94,7 +94,7 @@ server-side and is injected as the named environment variable.
 ```ts
 import { Models, Providers, Secret } from "@aexhq/sdk";
 
-await aex.run({
+await aex.start({
   provider: Providers.ANTHROPIC,
   model: Models.CLAUDE_HAIKU_4_5,
   message: "Use SERPER_API_KEY for web search.",
@@ -111,19 +111,19 @@ await aex.run({
 await aex.secrets.delete("serper-api-key");
 ```
 
-The CLI supports per-run provider and MCP credentials. Workspace secret
+The CLI supports per-session provider and MCP credentials. Workspace secret
 administration is exposed through the SDK.
 
-## Redaction Scope And Output Files
+## Redaction Scope And Session Files
 
-Registered secret values are redacted from the run's **event stream** (both tool
+Registered secret values are redacted from the session's **event stream** (both tool
 output and model-authored surfaces) — a value you inject via `environment.secrets`
 is masked regardless of its shape. Two surfaces are intentionally *not* scrubbed:
 
-- **Captured output files** (`outputs().download()` / `read()` / the `aex download`
-  zip) are returned **verbatim**. They are your run's own artifacts, so the platform
+- **Captured session files** (`files().download()` / `read()` / the `aex download`
+  zip) are returned **verbatim**. They are your session's own artifacts, so the platform
   does not rewrite their bytes — if the agent writes a secret into a deliverable file,
-  that file contains it. Treat downloaded outputs as unredacted.
-- An **unregistered** secret (a credential the run produces itself and never declared
+  that file contains it. Treat downloaded files as unredacted.
+- An **unregistered** secret (a credential the session produces itself and never declared
   via `environment.secrets`) can only be masked heuristically by shape; register the
   values you care about so they are masked by value.

package/docs/session-config.md

@@ -0,0 +1,58 @@
+---
+title: SessionRecord configuration
+---
+
+# SessionRecord configuration
+
+A session config is the credential-free subset of the session options (`openSession` / `run`) that you can keep in code or load from a JSON file. It is not a platform object, saved definition, DSL, trigger, or persistent agent profile. aex only stores the immutable session record created when the session lands.
+
+Allowed fields:
+
+- `model` - required.
+- `system` - optional system message.
+- `mcpServers` - array of `McpServerRef`; headers are split into the vaulted secrets channel server-side.
+- `environment` - `{ networking?, packages?, variables? }`. Networking is open by default; set `networking.mode` to `limited` only when you want an allowlist. `variables` are merged into the in-container `RUNTIME.env` / `RUNTIME.json` mounts. (SessionRecord secrets go in `environment.secrets`, which carries live `Secret` instances and is not part of a shareable config.)
+- `runtime` - optional managed-runtime preset. Prefer `Sizes` in TypeScript.
+- `metadata` - non-secret structured metadata.
+- `overrides` - `{ idleTtl?, timeout?, maxSpendUsd?, maxTurns? }`. `timeout` is an optional session deadline (e.g. `"30m"`, `"2h"`); `maxSpendUsd` stops the session once its spend would exceed the cap; `maxTurns` caps the agent's iteration count for the turn (a positive integer — omit to accept the platform default of 20, clamped to the ceiling). See [Limits & quotas](limits-and-quotas.md).
+
+`message` (the one-shot `run` input), `agentsMd`, `files`, `fileCapture`, `tools`, `skills`, `includeBuiltinTools`, and `outputMode` are `openSession` / `run` options, not reusable session-config fields. They carry the turn input, mounted bytes, capture behavior, or agent tool / assistant-text controls that belong on a concrete call. Skill bundles are `skills` entries built with `Skill.fromDir(...)`, `Skill.fromUrl(...)`, or the other `Skill.from*` factories, so they too are SDK-code options rather than config fields. Subagents are session-internal (the in-run `subagent` tool — see [Subagents](concepts/subagents.md)); there is no `parentSessionId` option. The wire contract carries a per-session `limits` object (the exported `SessionLimits` type: `maxConcurrentChildSessions`, `maxSubagentDepth`, `maxSpendUsd`, `maxTurns`), and the session surface exposes its spend and iteration dials via `overrides.maxSpendUsd` and `overrides.maxTurns`; the subagent depth/breadth dials are not settable per-session today and take the platform defaults.
+
+Secrets never live in session config. Pass provider keys through the top-level
+`apiKeys` map and runtime secrets through `environment.secrets` in the SDK, or
+the equivalent host-mode flags (`--anthropic-api-key`, `--mcp-auth`) in the CLI.
+See [Secrets](secrets.md) for secret lifecycles and [Credentials](credentials.md)
+for credential handling.
+
+## Reuse in code
+
+Use an ordinary function when you want reusable typed parameters. aex does not store or execute this function; it only receives the parameters you pass.
+
+```ts
+import { Models } from "@aexhq/sdk";
+
+function summarise(topic: string) {
+  return {
+    model: Models.CLAUDE_HAIKU_4_5,
+    system: "You are a concise automation agent.",
+    message: `Write a short answer about ${topic}.`
+  };
+}
+
+await aex.start({
+  ...summarise("agent-first SDK design"),
+  apiKeys: { anthropic: apiKey }
+});
+```
+
+## CLI
+
+The `aex start` host subcommand accepts the same session config either as a JSON file:
+
+```bash
+aex start --config ./main.json \
+  --api-key "$AEX_API_KEY" \
+  --anthropic-api-key "$ANTHROPIC_API_KEY"
+```
+
+...or as explicit flags (`--model`, `--system`, `--prompt`, `--mcp`, `--mcp-auth`, `--runtime-size`, `--session-timeout`, `--metadata`). The two modes are mutually exclusive. Composition inputs attach with repeatable flags that map onto the SDK's `Skill`/`Tool`/`AgentsMd`/`File` factories: `--skill @bundle` (workspace skill), `--tool @tool.js` (custom tool module), `--agents-md @AGENTS.md`, and `--file @path` (mount a file into `/workspace`).

package/docs/{run-record.md → session-record.md}

@@ -1,14 +1,14 @@
 ---
-title: Run record
+title: Session record
 ---
 
-# Run record
+# Session record
 
-The run record is the durable product primitive for one session. It is the public-safe bundle of status metadata, the non-secret submission snapshot when available, typed events, captured outputs, and manifest entries for custody and cost telemetry.
+The session record is the durable product primitive for one session. It is the public-safe bundle of status metadata, the non-secret submission snapshot when available, typed events, captured files, and manifest entries for custody and cost telemetry.
 
 ## Listing sessions
 
-`aex.sessions.list(query?)` enumerates the sessions in this workspace, most-recent first, one page at a time. The workspace is derived server-side from the API key, so this only ever returns your own sessions. It is the workspace-wide discovery entry point: combine it with `aex.sessions.outputs(id).list()` / `.read(...)` (see [Outputs](outputs.md)) to reach any session's deliverables.
+`aex.sessions.list(query?)` enumerates the sessions in this workspace, most-recent first, one page at a time. The workspace is derived server-side from the API key, so this only ever returns your own sessions. It is the workspace-wide discovery entry point: combine it with `aex.sessions.files(id).list()` / `.read(...)` (see [Files](files.md)) to reach any session's deliverables.
 
 ```ts
 let cursor: string | undefined;
@@ -23,33 +23,33 @@ do {
 
 `query` fields are all optional: `status` (single session status, e.g. `"idle"`), `since` (ISO-8601 lower bound on `createdAt`), `limit` (defaults to 25, clamped to `[1, 100]`), and `cursor` (the opaque keyset cursor from a prior page's `nextCursor` — absent on the last page). Each page row is a public-safe `SessionSummary` (`id`, `status`, `createdAt`, `updatedAt`, and `costUsd` once settled); it deliberately omits the submission snapshot (model / system / env). Use `aex.sessions.get(id)` for status / timing / cost on one session, or `session.unit()` on a handle for the full self-contained record including the parsed submission.
 
-## Downloading a run record
+## Downloading a session record
 
 `session.download()` and `aex download <session-id>` return a zip with this layout:
 
 ```text
 manifest.json
-metadata/run.json
+metadata/session.json
 metadata/submission.json      # when a public-safe submission snapshot is returned by the read API
 metadata/cost.json            # when public cost telemetry is returned by the read API
 events/events.jsonl
-outputs/<captured deliverable files>
+files/<captured deliverable files>
 ```
 
-`manifest.json` is versioned as `RunRecordManifestV1`:
+`manifest.json` is versioned as `SessionRecordManifestV1`:
 
 | Field | Meaning |
 | --- | --- |
-| `schemaVersion` | `aex.run-record.manifest.v1`. |
-| `runRecordSchemaVersion` | `aex.run-record.v1`. |
-| `runId` | The run the archive was assembled for. |
-| `namespaces[]` | The documented top-level namespaces: `metadata`, `events`, `outputs`. |
+| `schemaVersion` | `aex.session-record.manifest.v1`. |
+| `sessionRecordSchemaVersion` | `aex.session-record.v1`. |
+| `sessionId` | The session the archive was assembled for. |
+| `namespaces[]` | The documented top-level namespaces: `metadata`, `events`, `files`. |
 | `files[]` | Inventory of expected and present files with `namespace`, `path`, `role`, and `status`. |
-| `outputs[]` | Compatibility alias for present captured output artifacts. |
+| `sessionFiles[]` | Session file metadata for entries present under the `files/` namespace. |
 | `errors[]` | Per-artifact byte fetch failures during archive assembly. |
 
-Current v1 downloads always include `metadata/run.json` and `events/events.jsonl`. `events/events.jsonl` contains typed event-channel records only; internal diagnostics and full internal streams are not mixed into that file.
+Current v1 downloads always include `metadata/session.json` and `events/events.jsonl`. `events/events.jsonl` contains typed event-channel records only; internal diagnostics and full internal streams are not mixed into that file.
 
-`metadata/submission.json` is present only when the run read shape includes a public-safe submission snapshot. `metadata/cost.json` is present only when the run read shape includes public `costTelemetry`; otherwise cost stays `pending`. `metadata/custody.json` remains `pending` until the custody manifest writer and public read surface land. `events/manifest.json` remains `unavailable` in this client-side slice because there is no public coordinator-manifest download route.
+`metadata/submission.json` is present only when the session read shape includes a public-safe submission snapshot. `metadata/cost.json` is present only when the session read shape includes public `costTelemetry`; otherwise cost stays `pending`. `metadata/custody.json` remains `pending` until the custody manifest writer and public read surface land. `events/manifest.json` remains `unavailable` in this client-side slice because there is no public coordinator-manifest download route.
 
-The record boundary is public-safe. It must not contain provider API keys, runner bearers, workspace tokens, signed URLs, raw provider response bodies, object-store keys, Vault ids, raw query strings, secret-shaped values, or internal diagnostic files. Credentials are supplied per run and vaulted separately for the run lifetime.
+The record boundary is public-safe. It must not contain provider API keys, runner bearers, workspace tokens, signed URLs, raw provider response bodies, object-store keys, Vault ids, raw query strings, secret-shaped values, or internal diagnostic files. Credentials are supplied per session and vaulted separately for the session lifetime.

package/docs/skills.md

@@ -7,7 +7,7 @@ title: Skills
 A skill is a bundle of instructional or executable content (`SKILL.md` plus any
 supporting files) that the agent can pull into context on demand. Skills are a
 **first-class concept, separate from tools**: you pass them on the session's own
-`skills` input (not `tools`), and the run gets a single `skills` meta-tool the
+`skills` input (not `tools`), and the session gets a single `skills` meta-tool the
 model uses to list and load them.
 
 Build a skill with the `Skill.from*` factories. Each reads a bundle, lifts the
@@ -34,7 +34,7 @@ import { Aex, Models, Skill } from "@aexhq/sdk";
 
 const aex = new Aex({ apiKey });
 
-await aex.run({
+await aex.start({
   model: Models.CLAUDE_HAIKU_4_5,
   message,
   skills: [await Skill.fromDir("./skills/rules", { name: "rules" })],
@@ -48,17 +48,17 @@ A skill is bound to the workspace **by name**. `skill.upload(client)` UPSERTS th
 workspace skill under its name; a re-upload under the same name changes what
 every future run referencing that name sees. The wire ref is name-only —
 `{ kind:"skill", name }` — with no `assetId` and no hash, so the idempotency hash
-of two runs that reference the same skill name is identical even if the skill's
+of two sessions that reference the same skill name is identical even if the skill's
 bytes changed between them.
 
 Passing a **draft** `Skill` in `skills:` auto-upserts it on submit (the same
 ergonomic as a draft `Tool` / `File`). To upsert explicitly and reuse the name
-across many runs:
+across many sessions:
 
 ```ts
 const rules = await Skill.fromDir("./skills/rules", { name: "rules" });
 await rules.upload(aex);              // stage bytes + PUT /skills/rules
-await aex.run({ model, message, skills: [rules], apiKeys });
+await aex.start({ model, message, skills: [rules], apiKeys });
 ```
 
 `upload()` is idempotent on an instance (it caches the resolved name, so reuse
@@ -82,7 +82,7 @@ concurrency and run concurrently with each other.
 
 ## The `skills` meta-tool
 
-When a run references at least one skill, the platform injects a single `skills`
+When a session references at least one skill, the platform injects a single `skills`
 meta-tool:
 
 - `skills({ action: "list" })` returns each skill's `name` + `description`
@@ -92,9 +92,9 @@ meta-tool:
 
 A skill's supporting files are staged to disk under `/workspace/skills/<name>/`
 from the first turn, so `load` pulls the instructions while `read_file` / `bash`
-read the rest. The run resolves each referenced name to the workspace skill's
-current bytes at submit time and snapshots them into durable run asset storage
-(`runs/<runId>/assets/<hash>`); run-scoped copies are removed by run deletion or
+read the rest. The session resolves each referenced name to the workspace skill's
+current bytes at submit time and snapshots them into durable session asset storage
+(`sessions/<sessionId>/assets/<hash>`); session-scoped copies are removed by session deletion or
 retention cleanup.
 
 ## Workspace skill admin

package/docs/vision-skills.md

@@ -5,22 +5,22 @@ title: Call a vision API from a skill
 # Call a vision API from a skill
 
 aex has no built-in vision tool. The agent's `provider` / `model` selects the
-reasoning model for the run; if a skill needs image understanding mid-run, ship a
+reasoning model for the session; if a skill needs image understanding mid-session, ship a
 skill that calls the vision provider with normal HTTP and pass that provider key
 as a runtime secret.
 
-The runnable example lives at [`examples/vision-skill/`](../../../examples/vision-skill).
+The sessionnable example lives at [`examples/vision-skill/`](../../../examples/vision-skill).
 It captions a frame with ByteDance Doubao Seed Vision (Ark) and returns a
 per-noun "does the frame depict X?" verdict.
 
-## Submit the run
+## Submit the session
 
 ```ts
 import { Aex, Models, Secret, Skill } from "@aexhq/sdk";
 
 const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
 
-const result = await aex.run({
+const result = await aex.start({
   model: Models.CLAUDE_HAIKU_4_5,
   message: "Read skills/frame-vision-gate/SKILL.md, then caption and verify the frame.",
   skills: [await Skill.fromDir("./vision-skill", { name: "frame-vision-gate" })],
@@ -36,16 +36,16 @@ const result = await aex.run({
   apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
 });
 
-console.log(result.runId, result.text);
+console.log(result.sessionId, result.text);
 ```
 
 `Skill.fromDir("./vision-skill", ...)` is resolved relative to the process
-CWD. Run the script from the directory that contains `vision-skill/` (in this
+CWD. SessionRecord the script from the directory that contains `vision-skill/` (in this
 repo, `examples/`).
 
 ## Call the provider from the skill
 
-Inside the run, the skill reads `DOUBAO_API_KEY` and makes an
+Inside the session, the skill reads `DOUBAO_API_KEY` and makes an
 OpenAI-compatible chat-completions request with Python's standard HTTP client.
 The image is base64-inlined as a data URL in the request body:
 

package/docs/webhooks.md

@@ -4,9 +4,9 @@ title: Webhooks
 
 # Webhooks
 
-aex can notify your endpoint when a run finishes. Webhooks are **per-run**: you
+aex can notify your endpoint when a session finishes. Webhooks are **per-session**: you
 pass a callback URL with the submission, and the platform delivers exactly one
-`run.finished` event to it when the run reaches its terminal state.
+`session.finished` event to it when the session reaches its terminal state.
 
 ## Register a callback
 
@@ -23,7 +23,7 @@ const session = await aex.openSession({
 ```
 
 ```bash
-aex run \
+aex start \
   --api-key "$AEX_API_KEY" \
   --anthropic-api-key "$ANTHROPIC_API_KEY" \
   --model claude-haiku-4-5 \
@@ -37,9 +37,9 @@ idempotency key but a different callback URL never conflicts.
 
 ## What gets delivered
 
-One POST carrying the terminal `run.finished` event, sent at the
-settle-consistent barrier — when you receive it, the run record is already
-terminal and its outputs are complete and readable. The body is built once at
+One POST carrying the terminal `session.finished` event, sent at the
+settle-consistent barrier — when you receive it, the session record is already
+terminal and its files are complete and readable. The body is built once at
 settle, frozen, and re-sent byte-identical on every retry or manual redelivery:
 
 ```json
@@ -47,11 +47,11 @@ settle, frozen, and re-sent byte-identical on every retry or manual redelivery:
   "specversion": "1.0",
   "id": "<delivery id — matches the webhook-id header>",
   "source": "aex",
-  "type": "run.finished",
-  "subject": "<the run id>",
+  "type": "session.finished",
+  "subject": "<the session id>",
   "time": "2026-07-02T12:34:56.000Z",
   "data": {
-    "runId": "<the run id>",
+    "sessionId": "<the session id>",
     "status": "succeeded",
     "terminalAt": "2026-07-02T12:34:56.000Z",
     "reason": null,
@@ -108,7 +108,7 @@ is compromised, contact <support@aex.dev>.
 
 ## Delivery ledger and redelivery
 
-Each run keeps a delivery ledger — attempts, last status code, and last error:
+Each session keeps a delivery ledger — attempts, last status code, and last error:
 
 ```ts
 const deliveries = await session.webhooks().list();
@@ -121,7 +121,7 @@ aex deliveries <session-id> --api-key "$AEX_API_KEY"
 
 Redelivery re-sends the frozen payload with the **same** `webhook-id`, so a
 consumer that dedupes on `webhook-id` handles retries, redeliveries, and
-at-least-once delivery uniformly. An empty ledger means the run carried no
+at-least-once delivery uniformly. An empty ledger means the session carried no
 `webhook` or has not reached a terminal state yet.
 
 For the terminal-event mechanics behind delivery timing, see