@aexhq/sdk 0.33.1 → 0.34.0

package/docs/outputs.md

@@ -4,42 +4,48 @@ title: Outputs
 
 # Outputs
 
-Every run produces durable metadata (status, events, snapshots, cleanup state) and an outputs namespace. By default, managed runs capture every regular file the run creates or modifies in the container: the runner snapshots the filesystem just before the agent starts, rescans it when the agent exits, and uploads the delta. There is no default or official output directory. Use `outputs.allowedDirs` only when you want to narrow capture to specific roots, and `outputs.deniedDirs` to subtract noise. `aex.download(runId)` returns the public run record — metadata, typed events, and captured output bytes — as a zip; the per-namespace verbs (`downloadOutputs` / `downloadEvents` / `downloadMetadata`) return one slice each.
+Every session produces durable metadata (status, events, snapshots, cleanup state) and an outputs namespace. By default, managed runs capture every regular file the agent creates or modifies in the container: the runner snapshots the filesystem just before the agent starts, rescans it when the agent exits, and uploads the delta. There is no default or official output directory. Use `outputs.allowedDirs` only when you want to narrow capture to specific roots, and `outputs.deniedDirs` to subtract noise. `session.download()` returns the public session record — metadata, typed events, and captured output bytes — as a zip; the per-namespace verbs (`session.outputs().download()` / `session.events().download()` / `session.downloadMetadata()`) return one slice each.
+
+The output verbs below hang off the session's `outputs()` accessor
+(`session.outputs().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 runId = await aex.submit({
+const session = await aex.openSession({
   model: Models.CLAUDE_HAIKU_4_5,
-  prompt: "Produce a report and save it as a file.",
-  secrets: { apiKeys: { anthropic: apiKey } }
+  apiKeys: { anthropic: apiKey }
 });
 
-await aex.wait(runId);
-await aex.download(runId, { to: "./run.zip" });
+await session.send("Produce a report and save it as a file.").done();
+await session.wait();
+await session.download({ to: "./session.zip" });
 ```
 
 ```bash
-aex download <run-id> --out ./run.zip --api-token …
+aex download <session-id> --out ./session.zip --api-token …
 ```
 
 ## The three namespaces
 
-A run'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 (`getRun` + `listEvents` + `listOutputs` + per-output `/download`) — there is no server-side archive route.
+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.outputs().list()` + per-output `/download`) — there is no server-side archive route.
 
 | Namespace | What it holds | Verb | CLI |
 | --- | --- | --- | --- |
-| `outputs` | The run's real deliverables. | `downloadOutputs(runId)` | `download <id> --only outputs` |
-| `events` | Typed event-channel records (`events.jsonl`). | `downloadEvents(runId)` | `download <id> --only events` |
-| `metadata` | The run record (`run.json`). | `downloadMetadata(runId)` | `download <id> --only metadata` |
+| `outputs` | The session's real deliverables. | `session.outputs().download()` | `download <id> --only outputs` |
+| `events` | Typed event-channel records (`events.jsonl`). | `session.events().download()` | `download <id> --only events` |
+| `metadata` | The session record (`run.json`). | `session.downloadMetadata()` | `download <id> --only metadata` |
 
 Platform diagnostics are stored outside the public archive under `runs/<runId>/internal/logs/` for internal/admin access only. They are not exposed by the SDK download helpers or the public CLI.
 
-## What `download()` returns
+## What `session.download()` returns
 
-`download(runId)` is the **whole-run** verb — it bundles the public namespaces as top-level folders. It is distinct from `downloadOutput(runId, selector)`, which fetches a single file. Layout:
+`session.download()` is the **whole-session** verb — it bundles the public namespaces as top-level folders. It is distinct from `session.outputs().download(selector)`, which fetches a single file. Layout:
 
 ```
 metadata/run.json     # run record (status, runId, timestamps, snapshot)
@@ -60,30 +66,29 @@ manifest.json         # RunRecordManifestV1
 | `outputs[]` | `{ id, filename, sizeBytes?, contentType? }` — one row per file successfully written under `outputs/`. |
 | `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. `downloadOutputs(runId)` -> `report.txt` + a `manifest.json`; `downloadEvents(runId)` -> `events.jsonl`).
+The single-namespace verbs return the same per-file bytes at the zip root (e.g. `session.outputs().download()` -> `report.txt` + a `manifest.json`; `session.events().download()` -> `events.jsonl`).
 
 ## Downloading one output
 
-`downloadOutput(runId, selector)` returns a `Uint8Array`. Omit the selector to download the whole outputs namespace as a zip; pass an output from `aex.outputs(runId)`, an `{ id }`, or a path selector against the listed `Output.filename` values to download one file:
+`session.outputs().download(selector)` returns a `Uint8Array`. Omit the selector to download the whole outputs namespace as a zip; pass an output from `session.outputs().list()`, an `{ id }`, or a path selector against the listed `Output.filename` values to download one file:
 
 ```ts
-const allOutputs = await aex.downloadOutput(runId);
-await aex.downloadOutput(runId, undefined, { to: "./outputs.zip" });
+const allOutputs = await session.outputs().download();
+await session.outputs().download(undefined, { to: "./outputs.zip" });
 
-const report = await aex.downloadOutput(runId, { path: "reports/report.txt" });
+const report = await session.outputs().download({ path: "reports/report.txt" });
 console.log(new TextDecoder().decode(report));
 
-const looseReport = await aex.downloadOutput(runId, { path: "report.txt", match: "suffix" });
+const looseReport = await session.outputs().download({ path: "report.txt", match: "suffix" });
 console.log(looseReport.byteLength);
 ```
 
 ## Reading one output as text
 
-`readOutputText(runId, selector, options?)` reads ONE output 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 run's output to an LLM tool. Select the file the same way as `downloadOutput`: by `{ path }` (suffix-matchable) or `{ id }`.
+`session.outputs().read(selector, options?)` reads ONE output 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's output 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.outputs(sessionId).read(selector, options?)` — the same accessor, addressed by id.
 
 ```ts
-const { text, truncated, totalBytes } = await aex.readOutputText(
-  runId,
+const { text, truncated, totalBytes } = await session.outputs().read(
   { path: "report.md", match: "suffix" },
   { maxBytes: 50_000, grep: "error" }
 );
@@ -97,25 +102,25 @@ Check `truncated` before treating `text` as complete. Pass `options.grep` (a sub
 
 ### Chatting over a workspace's outputs
 
-`createDataTools(client)` packages the read surface (`listRuns` + `listOutputs` + `readOutputText`) as a vendor-neutral LLM tool set (`{ tools, instructions, execute }`) so you can build a search-then-fetch chat over your runs and their outputs in a few lines on top of the public SDK. The `tools` are plain JSON-Schema definitions (the shape every major LLM tool API accepts); `execute(name, input)` dispatches a tool call against the workspace-scoped client. See the runnable `examples/data-chat/` example.
+`createDataTools(client)` packages the read surface (`sessions.list` + `sessions.outputs(id).list` + `sessions.outputs(id).read`) as a vendor-neutral LLM tool set (`{ tools, instructions, execute }`) so you can build a search-then-fetch chat over your sessions and their outputs in a few lines on top of the public SDK. The `tools` are plain JSON-Schema definitions (the shape every major LLM tool API accepts); `execute(name, input)` dispatches a tool call against the workspace-scoped client. See the runnable `examples/data-chat/` example.
 
 ## Finding outputs
 
-`listOutputs(runId, query?)` and its alias `outputs(runId, query?)` can filter the captured output list client-side. Use `findOutputs` when you want discovery to be explicit, or `findOutput` when exactly one file is expected:
+`session.outputs().list(query?)` can filter the captured output list client-side. Use `session.outputs().find(query)` when you want discovery to be explicit, or `session.outputs().findOne(query)` when exactly one file is expected:
 
 ```ts
-const images = await aex.findOutputs(runId, { type: "image" });
-const jsonReports = await aex.outputs(runId, {
+const images = await session.outputs().find({ type: "image" });
+const jsonReports = await session.outputs().list({
   dir: "reports",
   extension: ".json"
 });
 
-const report = await aex.findOutput(runId, {
+const report = await session.outputs().findOne({
   filename: "summary.json",
   contentType: "application/json"
 });
 if (report) {
-  const bytes = await aex.downloadOutput(runId, report);
+  const bytes = await session.outputs().download(report);
 }
 ```
 
@@ -130,15 +135,14 @@ Query fields compose with AND semantics:
 | `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`. |
 
-`findOutput` returns `null` when nothing matches and throws `RunStateError` when the query matches more than one output.
+`session.outputs().findOne(query)` returns `null` when nothing matches and throws `RunStateError` when the query matches more than one output.
 
 ## Temporary output links
 
-Use `outputLink(runId, selectorOrQuery, options?)` when another process, browser, media tag, or downloader needs a direct artifact URL instead of bytes buffered through the SDK. `createOutputLink` remains as the compatibility name.
+Use `session.outputs().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 aex.outputLink(
-  runId,
+const link = await session.outputs().link(
   { path: "reports/summary.json" },
   { expiresIn: "15m" }
 );
@@ -150,16 +154,16 @@ Selectors can be an output id, an `Output` object, a path selector, or an `Outpu
 
 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, `fetchOutput` mints the same temporary URL and returns the `Response` from fetching it directly, without adding the SDK API token to that second request:
+For large files, `session.outputs().fetch()` mints the same temporary URL and returns the `Response` from fetching it directly, without adding the SDK API token to that second request:
 
 ```ts
-const response = await aex.fetchOutput(runId, { type: "video", filename: /clip\.mp4$/ });
+const response = await session.outputs().fetch({ type: "video", filename: /clip\.mp4$/ });
 const stream = response.body;
 ```
 
 ## Lifecycle behaviour
 
-`download()` works at any run state — it reads whatever the public endpoints currently expose, so the zip reflects the run as of the call:
+`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:
 
 | Run state | Behaviour |
 | --- | --- |
@@ -170,8 +174,8 @@ const stream = response.body;
 ## `outputs.allowedDirs` — override capture roots
 
 ```ts
-aex.submit({
-  /* ... */,
+aex.openSession({
+  /* ... */
   outputs: {
     allowedDirs: ["/workspace/reports", "/workspace/state"]
   }
@@ -195,8 +199,8 @@ Runtime notes:
 ## `outputs.deniedDirs` — subtract noise
 
 ```ts
-aex.submit({
-  /* ... */,
+aex.openSession({
+  /* ... */
   outputs: {
     deniedDirs: ["node_modules", "/var/cache", "*.tmp"]
   }
@@ -227,7 +231,7 @@ Metadata still gets the full treatment. aex captures every regular file the run
 
 ## Mid-session download semantics
 
-Mid-session calls are **best-effort and side-effect-free**: they expose whatever artifacts have already been uploaded. Files written by the agent are normally uploaded near terminal, after the filesystem diff. If you need the full output set, wait for the run to reach terminal status and call `download()` again.
+Mid-session calls are **best-effort and side-effect-free**: they expose whatever artifacts have already been uploaded. Files written by the agent are normally uploaded near terminal, after the filesystem diff. If you need the full output set, wait for the session to park and call `session.download()` again.
 
 ## Safety
 

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
 
-Only asset-backed skills are accepted on submissions. Supply skill bytes through `Skill.fromFiles`, `Skill.fromPath`, `Skill.fromUrl`, or `Skill.fromCatalog`; each path normalizes to an asset that the platform snapshots into durable run asset storage.
+Skills are supplied as load-tools in the `tools` array. Build one with `Tools.fromSkillDir` or `Tools.fromSkillUrl`; each normalizes to an asset that the platform snapshots into durable run asset storage.
 
 Notes:
 

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": "Submit typed runs, stream durable events, capture outputs, and compose agents with skills, files, MCP, proxy endpoints, and subagents across the managed runtime.",
+  "description": "Open durable agent sessions, send turns, stream events, capture outputs, and compose agents with skills, files, MCP, proxy endpoints, 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."
@@ -49,7 +49,7 @@
       "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 defaults, and optional notebook tools."
+      "description": "Managed autonomous runs with filesystem read/edit, grep/glob/head/tail, open web fetch/search, background commands, code execution, git, and subagents."
     },
     {
       "slug": "durable-infrastructure",

package/docs/quickstart.md

@@ -65,26 +65,36 @@ const result = await aex.run({
 console.log(result.runId, result.status, result.text);
 ```
 
-## 5. Low-level run control
+## 5. Session control: stream, wait, download
 
-The lower-level `submit` path remains available for explicit run-record
-workflows:
+Sessions are the low-level API. The handle a session gives you can do everything
+to itself — stream its events, wait for it to park, and download its record:
 
 ```ts
-const runId = await aex.submit({
+const session = await aex.openSession({
   model: Models.CLAUDE_HAIKU_4_5,
-  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } },
-  prompt: "Write a short report and save it as a file."
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
 });
 
-for await (const event of aex.stream(runId)) {
+// A turn streams its own events; iterate them, then collect the result.
+const turn = session.send("Write a short report and save it as a file.");
+for await (const event of turn) {
   console.log(event.type);
 }
+await turn.done();
+
+// Reads/streams/downloads are grouped into accessor sub-resources:
+// session.messages() / events() / outputs() / webhooks(). Grab the last
+// assistant message (an AssistantTextEntry; use ?.text for the string).
+const lastText = (await session.messages().last())?.text;
+console.log(lastText);
 
-const run = await aex.wait(runId);
-console.log(run.status);
+// Poll the record until the session parks (idle / suspended / error).
+const record = await session.wait();
+console.log(record.status);
 
-await aex.download(runId, { to: "./run.zip" });
+// Download the whole session record (metadata, events, outputs) as a zip.
+await session.download({ to: "./session.zip" });
 ```
 
 The same run from the bundled CLI:

package/docs/run-config.md

@@ -4,28 +4,26 @@ title: Run configuration
 
 # Run configuration
 
-A run config is the credential-free subset of a `submit` request 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 run record created when you submit.
+A run 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.
-- `prompt` - required, string or array of strings.
 - `system` - optional system message.
-- `skills` - array of storage-neutral `kind:"asset"` refs. Config files cannot carry local draft bytes; use `Skill.fromPath(...)` / `Skill.fromFiles(...)` in SDK code first, or reference an existing asset/catalog skill.
-- `mcpServers` - array of `McpServerRef`; headers are split into `secrets.mcpServers` server-side.
-- `environment` - `{ networking?, packages?, envVars? }`. Networking is open by default; set `networking.mode` to `limited` only when you want an allowlist. `envVars` are merged into the in-container `RUNTIME.env` / `RUNTIME.json` mounts.
-- `runtimeSize` - optional managed-runtime preset. Prefer `RuntimeSizes` in TypeScript.
-- `timeout` - optional run deadline duration string such as `"30m"` or `"2h"`.
-- `proxyEndpoints` - array of `PlatformProxyEndpoint`; endpoint-level `retry` is allowed here and remains declaration-based.
+- `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. (Run 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.
+- `proxyEndpoints` - array of `ProxyEndpoint` instances; endpoint-level `retry` is allowed here and remains declaration-based.
 - `metadata` - non-secret structured metadata.
+- `overrides` - `{ idleTtl?, timeout?, maxSpendUsd? }`. `timeout` is an optional session deadline (e.g. `"30m"`, `"2h"`); `maxSpendUsd` stops the session once its spend would exceed the cap (see [Limits & quotas](limits-and-quotas.md)).
 
-`agentsMd`, `files`, `outputs`, `tools`, `includeBuiltinTools`, `limits`, and `outputMode` are top-level `submit` options, not run-config fields. They carry bytes, capture behavior, or agent tool/output controls that belong on a concrete run submission. The `limits` option sets per-run caps: the subagent-lineage caps (`maxConcurrentChildRuns`, `maxSubagentDepth`) and a USD spend cap (`maxSpendUsd`, which stops the run once its spend would exceed the cap); see [Limits & quotas](limits-and-quotas.md).
+`message` (the one-shot `run` input), `agentsMd`, `files`, `outputs`, `tools`, `includeBuiltinTools`, and `outputMode` are `openSession` / `run` options, not reusable run-config fields. They carry the turn input, bytes, capture behavior, or agent tool/output controls that belong on a concrete call. Skill bundles are `tools` entries built with `Tools.fromSkillDir(...)` / `Tools.fromSkillUrl(...)`, so they too are SDK-code options rather than config fields. Subagents run in-process; there is no `limits` / `parentRunId` option.
 
-Secrets never live in run config. Pass credentials through `submit({ ...config, secrets })` in the SDK or the equivalent host-mode flags (`--anthropic-api-key`, `--mcp-auth`, `--proxy-auth`) in the CLI. See [Secrets](secrets.md) for secret lifecycles and [Credentials](credentials.md) for the proxy endpoint policy/auth split and retry fields.
+Secrets never live in run config. Pass provider keys through the top-level `apiKeys` map (and run secrets through `environment.secrets`) in the SDK, or the equivalent host-mode flags (`--anthropic-api-key`, `--mcp-auth`, `--proxy-auth`) in the CLI. See [Secrets](secrets.md) for secret lifecycles and [Credentials](credentials.md) for the proxy endpoint policy/auth split and retry fields.
 
 ## 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 run parameters you submit.
+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";
@@ -34,13 +32,13 @@ function summarise(topic: string) {
   return {
     model: Models.CLAUDE_HAIKU_4_5,
     system: "You are a concise automation agent.",
-    prompt: `Write a short answer about ${topic}.`
+    message: `Write a short answer about ${topic}.`
   };
 }
 
-await aex.submit({
+await aex.run({
   ...summarise("agent-first SDK design"),
-  secrets: { apiKeys: { anthropic: apiKey } }
+  apiKeys: { anthropic: apiKey }
 });
 ```
 

package/docs/run-record.md

@@ -4,28 +4,28 @@ title: Run record
 
 # Run record
 
-The run record is the durable product primitive for one run id. 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 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.
 
-## Listing runs
+## Listing sessions
 
-`aex.listRuns(query?)` enumerates the runs in this workspace, most-recent first, one page at a time. The workspace is derived server-side from the API token, so this only ever returns your own runs. It is the workspace-wide discovery entry point: combine it with `listOutputs` / `readOutputText` (see [Outputs](outputs.md)) to reach any run'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 token, 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.
 
 ```ts
 let cursor: string | undefined;
 do {
-  const page = await aex.listRuns({ status: "succeeded", limit: 25, cursor });
-  for (const run of page.runs) {
-    console.log(run.id, run.status, run.createdAt, run.costUsd);
+  const page = await aex.sessions.list({ status: "idle", limit: 25, cursor });
+  for (const session of page.sessions) {
+    console.log(session.id, session.status, session.createdAt, session.costUsd);
   }
   cursor = page.nextCursor;
 } while (cursor);
 ```
 
-`query` fields are all optional: `status` (single run status, e.g. `"succeeded"`), `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 `RunSummary` (`id`, `status`, `createdAt`, `updatedAt`, and `costUsd` once settled); it deliberately omits the submission snapshot (model / prompt / env). Use `aex.getRun(runId)` for status / timing / cost on one run, or `aex.getRunUnit(runId)` (alias `getUnit`) for the full self-contained record including the parsed submission.
+`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
 
-`aex.download(runId)` and `aex download <run-id>` return a zip with this layout:
+`session.download()` and `aex download <session-id>` return a zip with this layout:
 
 ```text
 manifest.json

package/docs/secrets.md

@@ -16,14 +16,14 @@ provider key, such as `ANTHROPIC_API_KEY` for Claude.
 ### TypeScript
 
 ```ts
-import { AgentExecutor, Models } from "@aexhq/sdk";
+import { Aex, Models } from "@aexhq/sdk";
 
-const aex = new AgentExecutor({ apiToken: process.env.AEX_API_TOKEN! });
+const aex = new Aex({ apiToken: process.env.AEX_API_TOKEN! });
 
-await aex.submit({
+await aex.run({
   model: Models.CLAUDE_HAIKU_4_5,
-  prompt: "Write a short report and save it as a file.",
-  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }
+  message: "Write a short report and save it as a file.",
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
 });
 ```
 
@@ -43,20 +43,20 @@ Use `Secret.value(...).upload(...)` when you start with an ephemeral value and
 want to persist it as a named workspace secret for later runs.
 
 ```ts
-import { AgentExecutor, Models, Providers, Secret } from "@aexhq/sdk";
+import { Aex, Models, Providers, Secret } from "@aexhq/sdk";
 
-const aex = new AgentExecutor({ apiToken: process.env.AEX_API_TOKEN! });
+const aex = new Aex({ apiToken: process.env.AEX_API_TOKEN! });
 
 const githubToken = await Secret.value(process.env.GITHUB_TOKEN!).upload(aex, {
   name: "github-token"
 });
 
-await aex.submit({
+await aex.run({
   provider: Providers.ANTHROPIC,
   model: Models.CLAUDE_HAIKU_4_5,
-  prompt: "Inspect the repository issues.",
-  secretEnv: { GITHUB_TOKEN: githubToken },
-  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }
+  message: "Inspect the repository issues.",
+  environment: { secrets: { GITHUB_TOKEN: githubToken } },
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
 });
 ```
 
@@ -86,16 +86,6 @@ const secrets = await aex.secrets.list();
 const metadata = await aex.secrets.get("serper-api-key");
 ```
 
-## Get A Secret Value
-
-Use `get_value` only when the value is intentionally needed outside a run. It is
-the explicit audited value-read path.
-
-```ts
-const secretValue = await aex.secrets.get_value("serper-api-key");
-console.log(secretValue.value);
-```
-
 ## Inject A Workspace Secret Into A Run
 
 Reference workspace secrets with `Secret.ref(name)`. The value resolves
@@ -104,14 +94,14 @@ server-side and is injected as the named environment variable.
 ```ts
 import { Models, Providers, Secret } from "@aexhq/sdk";
 
-await aex.submit({
+await aex.run({
   provider: Providers.ANTHROPIC,
   model: Models.CLAUDE_HAIKU_4_5,
-  prompt: "Use SERPER_API_KEY for web search.",
-  secretEnv: {
-    SERPER_API_KEY: Secret.ref("serper-api-key")
+  message: "Use SERPER_API_KEY for web search.",
+  environment: {
+    secrets: { SERPER_API_KEY: Secret.ref("serper-api-key") }
   },
-  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
 });
 ```