@aexhq/sdk 0.40.15 → 0.41.0

package/docs/files.md

@@ -0,0 +1,267 @@
+---
+title: Files
+---
+
+# Files
+
+Every session produces durable metadata (status, events, cleanup state) and a files namespace backed by the latest complete checkpoint of the session workspace. By default, managed sessions expose regular workspace files from that checkpoint, EXCLUDING the inputs the platform itself materialized for you (your mounted `files`/`skills`) — those are excluded by IDENTITY (their exact destination paths and skill-dir prefixes), not by any before/after timing comparison. There is no default or official capture directory. Use `fileCapture.allowedDirs` only when you want to narrow the visible file roots, and `fileCapture.deniedDirs` to subtract noise. `session.download()` returns the public session record — metadata, typed events, and captured file bytes — as a zip; the per-namespace verbs (`session.files().download()` / `session.events().download()` / `session.downloadMetadata()`) return one slice each.
+
+The file verbs below hang off the session's `files()` accessor
+(`session.files().list()`, `.read()`, `.download()`, …). Reach a handle from a
+live session (`openSession` / `run`) or reopen one later with
+`aex.openSession(sessionId)`; the client also exposes cross-session reads under
+`aex.sessions.*`.
+
+## Quickstart
+
+```ts
+import { Models } from "@aexhq/sdk";
+
+const session = await aex.openSession({
+  model: Models.CLAUDE_HAIKU_4_5,
+  apiKeys: { anthropic: apiKey }
+});
+
+await session.send("Produce a report and save it as a file.").done();
+await session.wait();
+await session.download({ to: "./session.zip" });
+```
+
+```bash
+npx aex download <session-id> --out ./session.zip --api-key …
+```
+
+## The three namespaces
+
+A session's downloadable content is organised into three logical namespaces, each with a matching verb. Every zip is assembled **client-side** from the public read endpoints (session record + `session.events().list()` + `session.files().list()` + per-file `/download`) — there is no server-side archive route.
+
+| Namespace | What it holds | Verb | CLI |
+| --- | --- | --- | --- |
+| `files` | The session's real deliverables. | `session.files().download()` | `download <id> --only files` |
+| `events` | Typed event-channel records (`events.jsonl`) plus a namespace manifest. | `session.events().download()` | `download <id> --only events` |
+| `metadata` | The session record (`session.json`) plus a namespace manifest. | `session.downloadMetadata()` | `download <id> --only metadata` |
+
+Platform diagnostics are stored outside the public archive under `sessions/<sessionId>/internal/logs/` for internal/admin access only. They are not exposed by the SDK download helpers or the public CLI.
+
+## What `session.download()` returns
+
+`session.download()` is the **whole-session** verb — it bundles the public namespaces as top-level folders. It is distinct from `session.files().download(selector)`, which fetches a single file. Layout:
+
+```
+metadata/session.json     # session record (status, sessionId, timestamps, snapshot)
+metadata/submission.json # public-safe submission snapshot, when available
+metadata/cost.json    # public cost telemetry, when available
+events/events.jsonl   # typed event-channel records, ordered
+files/<name>        # one file per deliverable
+manifest.json         # SessionRecordManifestV1
+```
+
+`manifest.json` is the versioned `SessionRecordManifestV1` described in [Session record](session-record.md). It carries:
+
+| Field | Meaning |
+| --- | --- |
+| `schemaVersion` / `sessionRecordSchemaVersion` | Manifest and session-record contract versions. |
+| `sessionId` | The session the zip was assembled for. |
+| `namespaces[]` / `files[]` | Namespace inventory and per-file presence state. Optional submission/cost files are marked `present` only when the client assembled actual entries; custody remains `pending` until its writer/read path exists. |
+| `sessionFiles[]` | `{ id, filename, sizeBytes?, contentType? }` — one row per file successfully written under `files/`. |
+| `errors[]` | `{ namespace, id, filename, message }` — per-artifact byte fetches that failed during assembly. Best-effort: a failure records an entry here and is skipped from the tree rather than aborting the whole zip. |
+
+The single-namespace verbs return the same per-file bytes at the zip root (e.g. `session.files().download()` -> `report.txt` + `manifest.json`; `session.events().download()` -> `events.jsonl` + `manifest.json`; `session.downloadMetadata()` -> `session.json` + `manifest.json`).
+
+## Downloading one file
+
+`session.files().download(selector)` returns a `Uint8Array`. Omit the selector to download the whole files namespace as a zip; pass a file from `session.files().list()`, an `{ id }`, or a path selector against the listed `SessionFile.filename` values to download one file:
+
+```ts
+const allFiles = await session.files().download();
+await session.files().download(undefined, { to: "./files.zip" });
+
+const report = await session.files().download({ path: "reports/report.txt" });
+console.log(new TextDecoder().decode(report));
+
+const looseReport = await session.files().download({ path: "report.txt", match: "suffix" });
+console.log(looseReport.byteLength);
+```
+
+## Reading one file as text
+
+`session.files().read(selector, options?)` reads ONE file as byte-capped, decoded UTF-8 text. It streams the file and stops at `options.maxBytes` (default 50 KB, ceiling 10 MB), so a large deliverable never fully buffers — this is the read built for handing a session file to an LLM tool. Select the file by `{ path }` (suffix-matchable) or `{ id }`. To read from a session id without a live handle, use `aex.sessions.files(sessionId).read(selector, options?)` — the same accessor, addressed by id.
+
+```ts
+const { text, truncated, totalBytes } = await session.files().read(
+  { path: "report.md", match: "suffix" },
+  { maxBytes: 50_000, grep: "error" }
+);
+
+if (truncated) {
+  // text is a prefix of a larger file — narrow with `grep` or a tighter `path`.
+}
+```
+
+Check `truncated` before treating `text` as complete. Pass `options.grep` (a substring or `RegExp`) to keep only matching lines of the capped text. The returned `file` is the matched `SessionFile` record, and `totalBytes` is the file's full size when the server reports it.
+
+## Finding files
+
+`session.files().list(query?)` can filter the captured file list client-side. Use `session.files().find(query)` when you want discovery to be explicit, or `session.files().findOne(query)` when exactly one file is expected:
+
+```ts
+const images = await session.files().find({ type: "image" });
+const jsonReports = await session.files().list({
+  dir: "reports",
+  extension: ".json"
+});
+
+const report = await session.files().findOne({
+  filename: "summary.json",
+  contentType: "application/json"
+});
+if (report) {
+  const bytes = await session.files().download(report);
+}
+```
+
+Query fields compose with AND semantics:
+
+| Field | Match |
+| --- | --- |
+| `path` | Exact normalized file path. Leading `/` and `files/` are ignored. |
+| `filename` | Basename match, as a string or `RegExp`. |
+| `dir` / `recursive` | Directory prefix. `recursive` defaults to `true`; set `false` for direct children only. |
+| `extension` | Case-insensitive extension, with or without a leading dot. |
+| `contentType` | Exact content type or a prefix wildcard such as `image/*`. |
+| `type` | High-level type: `text`, `json`, `image`, `audio`, `video`, `pdf`, `archive`, `binary`, or `unknown`. |
+
+`session.files().findOne(query)` returns `null` when nothing matches and throws `SessionStateError` when the query matches more than one file.
+
+## Searching files
+
+Search is metadata-only (reference hits — filename / extension / content type — no bytes). `filename` accepts a `string` (case-insensitive substring) or a `RegExp`. A content-shaped query (`content`/`text`/…) throws a typed "content search unsupported" rather than silently returning zero hits.
+
+```ts
+// One session's files:
+const hits = await session.files().search({ filename: /report/i });
+
+// Across every session in the workspace (or scope with sessionIds):
+const all = await aex.files.search({ extension: "md", sessionIds: ["session-a", "session-b"] });
+```
+
+Each hit is `{ sessionId, fileId, filename?, sizeBytes?, contentType? }`; read the bytes with `session.files().read(...)` / `.download(...)`.
+
+## CLI
+
+The `aex files` verb is a thin pass-through over the same SDK accessor, so every per-file operation has a subcommand (`npx aex` on a local install):
+
+```bash
+npx aex files <session-id>                          # list captured files (NDJSON)
+npx aex files read <session-id> <path>              # read one file as capped text (JSON)
+npx aex files download <session-id> <path> --out f  # download one file's raw bytes
+npx aex files link <session-id> <path>              # mint a temporary download URL (JSON)
+npx aex files find <session-id> --name S --ext E --type T
+npx aex files search --query S --ext E --session-id ID  # cross-session metadata search
+```
+
+`aex files search` (no session id) is the cross-session search (`aex.files.search`); the whole-namespace zip stays `aex download <session-id>`.
+
+## Temporary file links
+
+Use `session.files().link(selectorOrQuery, options?)` when another process, browser, media tag, or downloader needs a direct artifact URL instead of bytes buffered through the SDK.
+
+```ts
+const link = await session.files().link(
+  { path: "reports/summary.json" },
+  { expiresIn: "15m" }
+);
+
+console.log(link.url, link.expiresAt);
+```
+
+Selectors can be a file id, a `SessionFile` object, a path selector, or a `SessionFileQuery`. `expiresIn` accepts seconds or `"15m"`, `"1h"`, or `"1d"`; the default is `"1h"`.
+
+The returned URL is a reusable bearer URL until it expires. Anyone who has it can read that artifact during the TTL. aex does not promise one-time use or early revocation for these direct artifact URLs.
+
+For large files, `session.files().fetch()` mints the same temporary URL and returns the `Response` from fetching it directly, without adding the SDK API key to that second request:
+
+```ts
+const response = await session.files().fetch({ type: "video", filename: /clip\.mp4$/ });
+const stream = response.body;
+```
+
+## Lifecycle behaviour
+
+`session.download()` works at any session state — it reads whatever the public endpoints currently expose, so the zip reflects the session as of the call:
+
+| SessionRecord state | Behaviour |
+| --- | --- |
+| `queued` / `claiming` / `provisioning` | `metadata/session.json` reflects the early state; `events/` and `files/` are typically empty. |
+| `provider_running`, mid-session / `capturing_files` / `cleaning_up` | Whatever events + files have been captured so far. Call again after the session parks for the complete set. |
+| `idle` / `suspended` (parked between turns) | The complete archive for every turn sent so far; a later turn appends to it. |
+| `succeeded` / `failed` / `timed_out` / `cancelled` | The complete typed event archive + all captured files. |
+
+## `fileCapture.allowedDirs` — override capture roots
+
+```ts
+aex.openSession({
+  /* ... */
+  fileCapture: {
+    allowedDirs: ["/workspace/reports", "/workspace/state"]
+  }
+});
+```
+
+When omitted, aex exposes the session workspace files from the latest complete checkpoint, subject to mandatory platform excludes. When supplied, `fileCapture.allowedDirs` is a whitelist that replaces that default with the listed roots. In other words, explicit `fileCapture.allowedDirs` narrows file capture; it does not add paths on top of `/`.
+
+Validation:
+
+- absolute UNIX paths only (`/...`),
+- no `..` segments, no NUL bytes,
+- maximum 32 entries,
+- maximum 512 bytes per entry.
+
+Runtime notes:
+
+- The managed runtime exposes regular files from the latest complete checkpoint under the capture roots, EXCLUDING the inputs the platform itself materialized (your mounted `files`/`skills`) by IDENTITY — their exact destination paths and skill-dir prefixes are threaded into the capture filter, so an untouched mounted input is never re-emitted as a captured file regardless of path policy or timing.
+- If you pass an explicit root that does not exist by terminal time, that root contributes no files.
+
+## `fileCapture.deniedDirs` — subtract noise
+
+```ts
+aex.openSession({
+  /* ... */
+  fileCapture: {
+    deniedDirs: ["node_modules", "/var/cache", "*.tmp"]
+  }
+});
+```
+
+`fileCapture.deniedDirs` is subtracted from the capture roots. Entries may be an absolute subtree (`/var/cache`), a bare path segment (`node_modules`), or a `*.ext` extension match. Denied entries beat allowed roots. Platform-mandatory excludes, including pseudo-filesystems and secret/platform paths, always apply and cannot be re-included.
+
+Mechanism (no platform-magical paths — this is honest):
+
+1. The hosted platform materializes the workspace (your mounted `files`/`skills`) and records the exact destination paths + skill-dir prefixes it wrote.
+2. The agent sessions normally. There is no extra model turn and no synthetic sync instruction.
+3. At a complete checkpoint, the runner scans the capture roots and drops any file whose path is a materialized INPUT (exact path or under a materialized skill dir) — inputs are excluded by WHO PUT THEM THERE (the platform), not by timing.
+4. The runner uploads the remaining regular files to durable session file storage. Diagnostic log paths are routed to internal diagnostics under `sessions/<sessionId>/internal/logs/`; other paths are routed to `files`.
+
+Cost: file capture does not add a model turn. The runner pays a filesystem scan and upload cost near the end of the session.
+
+Capture notes:
+
+- Files over a configured per-file size cap are skipped.
+- Once total file or byte caps are reached, remaining changed files are dropped from upload.
+- Files that vanish between scan and upload are skipped.
+- Upload failures are recorded in runner diagnostics. The zip's `manifest.errors[]` only records byte fetches that failed while assembling the download archive.
+
+## Sessions without explicit `fileCapture.allowedDirs`
+
+Metadata still gets the full treatment. aex exposes every regular workspace file from the latest complete checkpoint outside mandatory platform excludes. A session that produces no files still returns a whole-session zip with `metadata/session.json`, `events/events.jsonl`, and `manifest.json` (manifest `files: []`).
+
+## Mid-session download semantics
+
+Mid-session calls are **best-effort and side-effect-free**: they expose whatever files from a complete checkpoint have already been uploaded. Files written by the agent are normally uploaded after a complete checkpoint, once the runner scans the capture roots. If you need the full file set, wait for the session to park and call `session.download()` again.
+
+## Safety
+
+- Filenames are sanitized for cross-platform safety; collisions are disambiguated with a short id suffix before the extension.
+- Downloads stay within the requested local directory.
+- The archive endpoint is workspace-scoped (`files:read` scope) and rate-limited (`AEX_RATE_LIMIT_SESSION_ARCHIVE_PER_MINUTE`, default 30/min/workspace).
+- `manifest.json` never contains file bytes — only ids, paths, sizes, content types.

package/docs/limits-and-quotas.md

@@ -4,7 +4,7 @@ title: Limits & quotas
 
 # Limits & quotas
 
-These are the hard ceilings and caps that bound a run, a workspace, and a single
+These are the hard ceilings and caps that bound a session, a workspace, and a single
 request. Every value is mirrored from a single source-of-truth constant in the
 platform's limits module; this page is hand-maintained against those constants.
 If a value here ever disagrees with the constant, the constant wins.
@@ -19,21 +19,21 @@ Each row is tagged with its **source**:
 - **aex policy** — an aex platform ceiling, the same for every workspace.
 - **Workspace default** — a per-workspace value with a configurable override.
 
-And whether you can **raise** it: per-run option, per-plan, or no.
+And whether you can **raise** it: per-session option, per-plan, or no.
 
-## Run scope
+## SessionRecord scope
 
 | Limit | Value | Source | Raisable? | Constant |
 | --- | --- | --- | --- | --- |
-| Maximum run timeout | 8 hours (also the default when `timeout` is omitted) | aex policy | Per plan (billing-driven) | `RUN_MAX_TIMEOUT_MS` |
-| Minimum run timeout | 1 minute | aex policy | No (floor) | `RUN_MIN_TIMEOUT_MS` |
-| Per-call exec timeout (default) | 30 minutes | aex policy | Per-call via the tool call's `timeoutMs` | `RUN_DEFAULT_EXEC_TIMEOUT_MS` |
-| MCP connect timeout (default) | 30 seconds | aex policy | Per-port via `connectTimeoutMs` | `RUN_DEFAULT_MCP_CONNECT_TIMEOUT_MS` |
-| MCP call timeout (default) | 30 minutes | aex policy | Per-port via `callTimeoutMs` | `RUN_DEFAULT_MCP_CALL_TIMEOUT_MS` |
+| Maximum session timeout | 8 hours (also the default when `timeout` is omitted) | aex policy | Per plan (billing-driven) | `SESSION_MAX_TIMEOUT_MS` |
+| Minimum session timeout | 1 minute | aex policy | No (floor) | `SESSION_MIN_TIMEOUT_MS` |
+| Per-call exec timeout (default) | 30 minutes | aex policy | Per-call via the tool call's `timeoutMs` | `SESSION_DEFAULT_EXEC_TIMEOUT_MS` |
+| MCP connect timeout (default) | 30 seconds | aex policy | Per-port via `connectTimeoutMs` | `SESSION_DEFAULT_MCP_CONNECT_TIMEOUT_MS` |
+| MCP call timeout (default) | 30 minutes | aex policy | Per-port via `callTimeoutMs` | `SESSION_DEFAULT_MCP_CALL_TIMEOUT_MS` |
 | Per-session spend cap | None by default; when set, the session is stopped once its spend would exceed the cap | aex policy | Per-session via `overrides.maxSpendUsd` (a positive USD amount) | — |
-| Max agent iterations (turns) per run | 20 by default; hard ceiling 200 | aex policy | Per-session via `overrides.maxTurns` (a positive integer, clamped to the ceiling) | `RUN_DEFAULT_MAX_TURNS` / `RUN_MAX_TURNS_CEILING` |
+| Max agent iterations (turns) per session | 20 by default; hard ceiling 200 | aex policy | Per-session via `overrides.maxTurns` (a positive integer, clamped to the ceiling) | `SESSION_DEFAULT_MAX_TURNS` / `SESSION_MAX_TURNS_CEILING` |
 
-### Output capture (per run)
+### SessionFile capture (per session)
 
 Files stream from the container to object storage one at a time. When a cap is
 reached, remaining files are **dropped and counted in the summary**, never
@@ -41,22 +41,22 @@ silently lost.
 
 | Limit | Value | Source | Raisable? | Constant |
 | --- | --- | --- | --- | --- |
-| Capture wall-clock budget | 1 hour | aex policy | No (hard ceiling) | `RUN_CAPTURE_DEFAULT_TIMEOUT_MS` |
-| Max files captured | 50,000 | aex policy | No (hard ceiling) | `RUN_CAPTURE_MAX_FILES` |
-| Max bytes per captured file | 500 GB (decimal) | aex policy | No (hard ceiling) | `RUN_CAPTURE_MAX_FILE_BYTES` |
-| Max total captured bytes | 500 GB (decimal) | aex policy | No (hard ceiling) | `RUN_CAPTURE_MAX_TOTAL_BYTES` |
+| Capture wall-clock budget | 1 hour | aex policy | No (hard ceiling) | `SESSION_CAPTURE_DEFAULT_TIMEOUT_MS` |
+| Max files captured | 50,000 | aex policy | No (hard ceiling) | `SESSION_CAPTURE_MAX_FILES` |
+| Max bytes per captured file | 500 GB (decimal) | aex policy | No (hard ceiling) | `SESSION_CAPTURE_MAX_FILE_BYTES` |
+| Max total captured bytes | 500 GB (decimal) | aex policy | No (hard ceiling) | `SESSION_CAPTURE_MAX_TOTAL_BYTES` |
 
-### Tool output caps (per run)
+### Tool output caps (per session)
 
 | Limit | Value | Source | Raisable? | Constant |
 | --- | --- | --- | --- | --- |
 | `web_fetch` returned body | 500 KB (UTF-8) | aex policy | Per-call via `max_bytes` | `REQUEST_WEB_FETCH_DEFAULT_MAX_BYTES` |
-| `bash_output` per-read body | 1 MB (UTF-8) | aex policy | No (hard ceiling) | `RUN_BASH_BG_OUTPUT_MAX_BYTES` |
-| `grep` max file size (larger files skipped — use `bash grep`) | 25 MB | aex policy | No (hard ceiling) | `RUN_TOOL_GREP_MAX_FILE_BYTES` |
-| `head`/`tail` max file size (larger files rejected — use `bash head`/`tail`) | 100 MB | aex policy | No (hard ceiling) | `RUN_TOOL_HEAD_TAIL_MAX_FILE_BYTES` |
-| `grep`/`glob` files visited per recursive walk (then truncates with a notice) | 100,000 | aex policy | No (hard ceiling) | `RUN_TOOL_WALK_MAX_FILES` |
+| `bash_output` per-read body | 1 MB (UTF-8) | aex policy | No (hard ceiling) | `SESSION_BASH_BG_OUTPUT_MAX_BYTES` |
+| `grep` max file size (larger files skipped — use `bash grep`) | 25 MB | aex policy | No (hard ceiling) | `SESSION_TOOL_GREP_MAX_FILE_BYTES` |
+| `head`/`tail` max file size (larger files rejected — use `bash head`/`tail`) | 100 MB | aex policy | No (hard ceiling) | `SESSION_TOOL_HEAD_TAIL_MAX_FILE_BYTES` |
+| `grep`/`glob` files visited per recursive walk (then truncates with a notice) | 100,000 | aex policy | No (hard ceiling) | `SESSION_TOOL_WALK_MAX_FILES` |
 
-### Subagents (per run lineage)
+### Subagents (per session lineage)
 
 Subagent lineage bounds are enforced server-side but are intentionally not
 advertised as fixed public ceilings because capacity can change. The runtime
@@ -65,19 +65,19 @@ by the platform at spawn time.
 
 | Limit | Value | Source | Raisable? | Constant |
 | --- | --- | --- | --- | --- |
-| Max subagent depth (`subagent` tool) | High recursive subagent depth, bounded server-side. | aex policy | No public per-run override (subagents run in-process) | `RUN_MAX_PUBLIC_SUBAGENT_DEPTH` |
-| Concurrent child runs per lineage root | Designed to scale across hundreds, even thousands, of live child agents, bounded server-side. | aex policy | No public per-run override (subagents run in-process) | `RUN_DEFAULT_MAX_CONCURRENT_CHILD_RUNS` |
+| Max subagent depth (`subagent` tool) | High recursive subagent depth, bounded server-side. | aex policy | No public per-session override (subagents session in-process) | `SESSION_MAX_PUBLIC_SUBAGENT_DEPTH` |
+| Concurrent child sessions per lineage root | Designed to scale across hundreds, even thousands, of live child agents, bounded server-side. | aex policy | No public per-session override (subagents session in-process) | `SESSION_DEFAULT_MAX_CONCURRENT_CHILD_SESSIONS` |
 
-### Retention (per run)
+### Retention (per session)
 
 | Limit | Value | Source | Raisable? | Constant |
 | --- | --- | --- | --- | --- |
-| Per-run metadata record TTL | 24 hours | aex policy | No (hard ceiling) | `RUN_KV_RECORD_TTL_SECONDS` |
-| Per-run secret-envelope TTL | 24 hours | aex policy | No (hard ceiling) | `RUN_KV_SECRET_TTL_SECONDS` |
+| Per-session metadata record TTL | 24 hours | aex policy | No (hard ceiling) | `SESSION_KV_RECORD_TTL_SECONDS` |
+| Per-session secret-envelope TTL | 24 hours | aex policy | No (hard ceiling) | `SESSION_KV_SECRET_TTL_SECONDS` |
 
 ## Sandbox (managed runtime)
 
-Each run executes in an ephemeral Linux container sized by the `runtime` preset.
+Each session executes in an ephemeral Linux container sized by the `runtime` preset.
 A few behaviours are worth knowing before you rely on the filesystem or RAM:
 
 - **Only `/workspace` persists across turns** of the same session. Everything
@@ -95,7 +95,7 @@ A few behaviours are worth knowing before you rely on the filesystem or RAM:
   [`packages/contracts/src/runtime-sizes.ts`](https://github.com/aexhq/aex/blob/main/packages/contracts/src/runtime-sizes.ts);
   see [Defaults](defaults.md).
 - **The agent loop is bounded** by `maxTurns` (default 20, ceiling 200) — a
-  documented, per-run-overridable limit (see the Run scope table above and
+  documented, per-session-overridable limit (see the SessionRecord scope table above and
   `overrides.maxTurns`), not a silent cutoff.
 
 ## Workspace scope
@@ -103,7 +103,7 @@ A few behaviours are worth knowing before you rely on the filesystem or RAM:
 | Limit | Value | Source | Raisable? | Constant |
 | --- | --- | --- | --- | --- |
 | Workspace storage cap | 500 GB (decimal; admins uncapped — not a customer entitlement) | Workspace default | Per-plane via env `AEX_WORKSPACE_STORAGE_CAP_BYTES` | `WORKSPACE_DEFAULT_STORAGE_CAP_BYTES` |
-| Max concurrent runs per workspace | Plan-based: **5** live (non-terminal) root runs on the free plan, **50** on Pro, **200** on Team; hard platform ceiling **200**. One more submit past the cap fails with `429 workspace_concurrency_exceeded` (see [Errors](errors.md)). Subagent children are governed separately by the platform-managed per-lineage budgets above. Read your effective cap from `aex.whoami().limits.maxConcurrentRuns`. | Workspace default (per plan) | Per-plan (upgrade) or per-workspace override (contact support), clamped to the 200 ceiling | `PLANS[planKey].maxConcurrentRuns` / `WORKSPACE_MAX_CONCURRENT_RUNS_CEILING` |
+| Max concurrent sessions per workspace | Plan-based: **5** live (non-terminal) root sessions on the free plan, **50** on Pro, **200** on Team; hard platform ceiling **200**. One more submit past the cap fails with `429 workspace_concurrency_exceeded` (see [Errors](errors.md)). Subagent children are governed separately by the platform-managed per-lineage budgets above. Read your effective cap from `aex.whoami().limits.maxConcurrentSessions`. | Workspace default (per plan) | Per-plan (upgrade) or per-workspace override (contact support), clamped to the 200 ceiling | `PLANS[planKey].maxConcurrentSessions` / `WORKSPACE_MAX_CONCURRENT_SESSIONS_CEILING` |
 | Monthly workspace spend cap | **$250** per rolling UTC calendar month by default; `0` = unlimited. A submit past the cap fails with `402 workspace_spend_cap_exceeded` (see [Errors](errors.md)). | Workspace default | Per-workspace override (contact support) | `WORKSPACE_DEFAULT_SPEND_CAP_USD` |
 | Skill bundle max compressed size (`.zip`) | 10 GiB (enforced at upload by the SDK and re-enforced server-side) | aex policy | No (hard ceiling) | `SKILL_BUNDLE_LIMITS.maxCompressedBytes` |
 | Skill bundle max decompressed size (sum of uncompressed file sizes) | 50 MB | aex policy | No (hard ceiling) | `SKILL_BUNDLE_LIMITS.maxDecompressedBytes` |
@@ -114,8 +114,8 @@ A few behaviours are worth knowing before you rely on the filesystem or RAM:
 
 ### Rate limits (per workspace, per minute)
 
-Run submission has its own platform-enforced velocity cap: **120 submits per
-minute** per workspace by default (`0` = disabled). Past it, `POST /runs` fails
+SessionRecord submission has its own platform-enforced velocity cap: **120 submits per
+minute** per workspace by default (`0` = disabled). Past it, `POST /sessions` fails
 with `429 workspace_submit_rate_exceeded` (see [Errors](errors.md)). It is
 overridable per-plane via `AEX_WORKSPACE_SUBMIT_RATE_PER_MIN` or per-workspace
 via support.
@@ -125,16 +125,16 @@ per-plane via the matching `AEX_RATE_LIMIT_<ACTION>_PER_MINUTE` env var.
 
 | Action | Default per minute | Source | Constant |
 | --- | --- | --- | --- |
-| Run cancel | 30 | Workspace default | `WORKSPACE_RATE_LIMIT_DEFAULTS` |
-| Run delete | 30 | Workspace default | `WORKSPACE_RATE_LIMIT_DEFAULTS` |
-| Signed output link | 120 | Workspace default | `WORKSPACE_RATE_LIMIT_DEFAULTS` |
+| SessionRecord cancel | 30 | Workspace default | `WORKSPACE_RATE_LIMIT_DEFAULTS` |
+| SessionRecord delete | 30 | Workspace default | `WORKSPACE_RATE_LIMIT_DEFAULTS` |
+| Signed file link | 120 | Workspace default | `WORKSPACE_RATE_LIMIT_DEFAULTS` |
 | API key create | 10 | Workspace default | `WORKSPACE_RATE_LIMIT_DEFAULTS` |
 | API key delete | 30 | Workspace default | `WORKSPACE_RATE_LIMIT_DEFAULTS` |
 
 ### Introspecting your effective caps
 
 `aex.whoami()` (CLI: `aex whoami`) returns a `limits` object carrying the
-workspace's *effective* values for the caps above — `maxConcurrentRuns`,
+workspace's *effective* values for the caps above — `maxConcurrentSessions`,
 `submitRatePerMinute`, `spendCapUsd`, plus the live `monthSpendUsd`,
 `balanceUsd`, `balanceGraceFloorUsd`, and `paymentMethodStatus` — resolved by
 the same code the admission gates use, so you can anticipate a `429`/`402`
@@ -145,5 +145,5 @@ before submitting. See [Authentication](authentication.md) and
 
 | Limit | Value | Source | Raisable? | Constant |
 | --- | --- | --- | --- | --- |
-| Signed output URL TTL | 300 seconds | aex policy | Per-call via `expiresSeconds` | `REQUEST_PRESIGN_URL_DEFAULT_TTL_SECONDS` |
+| Signed file URL TTL | 300 seconds | aex policy | Per-call via `expiresSeconds` | `REQUEST_PRESIGN_URL_DEFAULT_TTL_SECONDS` |
 | Event-stream connection ticket TTL | 60 seconds | aex policy | Per-mint via `ttlMs` | `REQUEST_TICKET_DEFAULT_TTL_MS` |

package/docs/limits.md

@@ -4,8 +4,8 @@ title: Limits
 
 # Limits
 
-aex runs autonomous agents on the hosted managed runtime. The SDK opens durable
-sessions, sends turns, streams events, captures outputs, and exposes auth-gated
+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/).
@@ -16,7 +16,7 @@ For the current provider/model set, see the generated
 
 | Area | Default |
 | --- | --- |
-| Workspace storage | 500 GB per workspace for captured outputs and workspace artifacts. aex-maintainer admin workspaces may be unlimited for internal dogfooding; this is not a customer entitlement. |
+| Workspace storage | 500 GB per workspace for captured files and workspace artifacts. aex-maintainer admin workspaces may be unlimited for internal dogfooding; this is not a customer entitlement. |
 
 ## Product Boundaries
 
@@ -26,9 +26,9 @@ For the current provider/model set, see the generated
 | 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 env 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. |
-| Outputs | Captured outputs, events, and metadata are stored under the run record and downloaded through auth-gated routes. Output content is customer content. |
-| Human review | Runs execute after submission. Cancellation is available, but aex does not pause a run for platform-mediated approval or interactive clarification. |
-| Sessions | The durable product primitive is the session/run 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. |
+| 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/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. |
 | Deployment | The supported product is the hosted aex service plus the SDK and CLI. Alternate `baseUrl` values are for local, staging, or hosted aex API planes, not a self-host product promise. |
 | Cost | BYOK provider-token charges accrue to the customer's provider account. aex records report-only telemetry for runtime and storage usage; free trials, billing-grade invoices, and public pricing documents are not shipped unless documented later. |
 

package/docs/mcp.md

@@ -8,7 +8,7 @@ MCP support is remote HTTPS/SSE only. Stdio MCP servers are rejected because aex
 
 Rules:
 
-- MCP servers are declared in the run request config (`mcpServers`).
+- 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.
@@ -35,11 +35,11 @@ putting the whole response in model context:
 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
-   `outputs.allowedDirs` only when you want to narrow capture to specific roots.
+   `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 a normal captured output.
+`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,

package/docs/networking.md

@@ -4,12 +4,12 @@ title: Networking
 
 # Networking
 
-A run executes your agent's code in a sandbox with **no direct route to the
+A session executes your agent's code in a sandbox with **no direct route to the
 internet**. Outbound traffic is governed by **two layers**:
 
-1. **The per-run policy (`environment.networking`)** — enforced by the agent
-   runtime *inside the run*. It applies to the standard proxy path every normal
-   HTTP client uses (see below) and can only *narrow* what the run may reach.
+1. **The per-session policy (`environment.networking`)** — enforced by the agent
+   runtime *inside the session*. It applies to the standard proxy path every normal
+   HTTP client uses (see below) and can only *narrow* what the session may reach.
 2. **The platform ceiling** — a fixed, platform-managed egress boundary every
    connection ultimately traverses. It allows the hosts aex itself manages
    (model providers, built-in tool endpoints, package registries, and related
@@ -20,19 +20,19 @@ internet**. Outbound traffic is governed by **two layers**:
    plane a subprocess that deliberately bypasses the proxy with a **raw socket**
    can still reach the on-link task-metadata IP (`169.254.170.2`), which exposes
    non-secret task identity (AWS account id via the task ARN, cluster/image ref)
-   — but **never IAM credentials** (the run's task role is unset, so the metadata
+   — but **never IAM credentials** (the session's task role is unset, so the metadata
    credential endpoint serves nothing) and never another tenant's data.
 
-Honest boundary statement: the per-run `allowedHosts` policy is enforced by the
-run's own runtime on the standard proxy path — it is **not** yet enforced at
+Honest boundary statement: the per-session `allowedHosts` policy is enforced by the
+session's own runtime on the standard proxy path — it is **not** yet enforced at
 the platform proxy layer. A subprocess that deliberately bypasses the standard
 proxy environment (a raw socket / raw CONNECT) is bounded by the **platform
-ceiling** rather than by the per-run list. Per-run enforcement at the platform
+ceiling** rather than by the per-session list. Per-session enforcement at the platform
 proxy layer is planned; until it ships, treat `allowedHosts` as a strong
 default-path control and an auditable statement of intent, not a hard isolation
-boundary against adversarial code inside the run.
+boundary against adversarial code inside the session.
 
-**Default posture.** A run that does not set `environment.networking` runs in
+**Default posture.** A session that does not set `environment.networking` sessions in
 `open` mode: its own code may reach anything within the platform ceiling with
 no allowlist required. Use `environment.networking` to *narrow* that surface
 when you want a tighter, auditable egress posture. Code cannot widen the
@@ -43,7 +43,7 @@ ceiling from inside the container.
 These reach the network over managed platform paths and are **not** subject to
 `environment.networking`, so you never list their hosts:
 
-- The model / provider call for the run (and its subagents).
+- The model / provider call for the session (and its subagents).
 - The built-in `web_search` and `web_fetch` tools. They run over a managed,
   SSRF-guarded server-side path, which is why they can reach arbitrary public
   URLs even though your own code is bounded by the ceiling.
@@ -57,12 +57,12 @@ These reach the network over managed platform paths and are **not** subject to
 code makes — a `curl` in the `bash` tool, a `requests`/`urllib` call in Python,
 a `fetch` in `code_execution`, or a third-party SDK.
 
-## Restrict a run to an allowlist
+## Restrict a session to an allowlist
 
 Set `mode: "limited"` and list exactly the hosts your code is allowed to reach.
-The run's runtime enforces the list on the standard proxy path: a connection to
+The session's runtime enforces the list on the standard proxy path: a connection to
 a host that is neither on the list nor one of the always-allowed paths above is
-refused before it leaves the run. Package-registry hosts implied by
+refused before it leaves the session. Package-registry hosts implied by
 `environment.packages` are appended automatically so installs keep working.
 
 Note that `allowedHosts` narrows *within* the platform ceiling — listing a host
@@ -76,7 +76,7 @@ import { Aex, Models, Providers } from "@aexhq/sdk";
 
 const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
 
-await aex.run({
+await aex.start({
   provider: Providers.ANTHROPIC,
   model: Models.CLAUDE_HAIKU_4_5,
   message: "Fetch the public status page and summarize it.",
@@ -100,15 +100,15 @@ visible at the same call site as the code that needs it.
 
 ## Open mode
 
-`open` is the default: a run that omits `environment.networking` already runs in
+`open` is the default: a session that omits `environment.networking` already sessions in
 open mode. Set `mode: "open"` explicitly when you want to be unambiguous. Open
-mode applies no per-run allowlist — the run's own code may reach anything the
+mode applies no per-session allowlist — the session's own code may reach anything the
 platform ceiling allows, still subject to the SSRF deny-list. Prefer `limited`
-whenever you can name the hosts — it gives the run a stable, auditable,
+whenever you can name the hosts — it gives the session a stable, auditable,
 least-privilege egress surface (it is the tighter posture, not the default).
 
 ```ts
-await aex.run({
+await aex.start({
   model: Models.CLAUDE_HAIKU_4_5,
   message: "Research the topic across the open web.",
   environment: { networking: { mode: "open" } },
@@ -139,12 +139,12 @@ your client succeeds without extra setup.
 
 ## Limitations and gotchas
 
-- **The per-run policy is enforced by the run's runtime, not at the platform
+- **The per-session policy is enforced by the session's runtime, not at the platform
   proxy.** Clients that honor the standard proxy environment (almost all HTTP
   tooling) are held to the `allowedHosts` list. A subprocess that deliberately
   ignores the proxy environment and opens a raw connection is **not** held to
-  the per-run list — it is bounded by the platform ceiling (the aex-managed
-  provider/tool/registry host set) and the SSRF deny-list instead. Per-run
+  the per-session list — it is bounded by the platform ceiling (the aex-managed
+  provider/tool/registry host set) and the SSRF deny-list instead. Per-session
   enforcement at the platform proxy layer is planned.
 - **A client that hard-bypasses the standard environment may fail to connect.**
   A client that ignores the proxy environment, pins or replaces its certificate
@@ -159,5 +159,5 @@ your client succeeds without extra setup.
 
 For credentialed HTTP calls, pass the credential as an `environment.secrets`
 entry and let your code use its normal HTTP client. For remote tool servers, see
-[MCP](mcp.md). For the full set of run-config fields, see
-[Run configuration](run-config.md).
+[MCP](mcp.md). For the full set of session-config fields, see
+[SessionRecord configuration](session-config.md).

package/docs/provider-runtime-capabilities.md

@@ -40,7 +40,7 @@ All new submissions run on the managed runtime. Public support is expressed as s
 
 ## 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 run asset storage.
+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.
 
 Notes: