@aexhq/sdk 0.33.0 → 0.34.0

package/dist/skill-tool.d.ts

@@ -0,0 +1,102 @@
+import { type FetchLike, type SkillToolRef } from "./_contracts/index.js";
+import { type SkillFiles } from "./bundle.js";
+/**
+ * A skill re-expressed as a TOOL. `Tools.fromSkillDir` / `Tools.fromSkillUrl`
+ * read a skill folder/zip, lift the tool `name` + `description` from the
+ * `SKILL.md` YAML frontmatter, and canonically bundle+hash the bytes. The
+ * result rides in the session's `tools` array (next to builtin names and custom
+ * {@link Tool} bundles); `client.run` / `openSession` uploads the bundle as an
+ * asset before the run lands, and the wire ref becomes a
+ * `{ kind:"skill", assetId, name, description }` {@link SkillToolRef}.
+ *
+ * At run time the model calls the no-arg load-tool to pull the skill's
+ * `SKILL.md` body into context; the bundle's files are eagerly staged to
+ * `/workspace/skills/<name>/`.
+ *
+ * Asset deduplication makes the same bytes a no-op upload on subsequent runs.
+ * A URL is an ingestion source, not a persistent reference.
+ */
+export declare class SkillTool {
+    #private;
+    /** Internal constructor. Use the `Tools.fromSkill*` factories. */
+    private constructor();
+    /**
+     * The wire-level reference. Returns the SDK-private draft shape for
+     * un-uploaded skill-tools (kind:"draft", with name + description +
+     * contentHash). `client.run` / `openSession` walks these and uploads them
+     * before the run lands.
+     */
+    get ref(): SkillToolRef | DraftSkillToolRef;
+    /** True for local-bytes skill-tools that haven't been uploaded yet. */
+    get isDraft(): boolean;
+    /** Internal: the asset id resolved on a prior use, or undefined. */
+    get _cachedAssetId(): string | undefined;
+    /** Internal: remember the asset id resolved for this draft's bytes. */
+    _rememberAsset(assetId: string): void;
+    /** Internal: build a draft from an already-loaded skill files map. */
+    static _fromFiles(source: string, files: SkillFiles, nameOverride: string | undefined): Promise<SkillTool>;
+    /**
+     * Internal: yield the draft's bytes + metadata so `client.run` / `openSession`
+     * can upload the asset. Idempotent (non-consuming): a SkillTool is reusable
+     * across sessions — the first use caches the resolved asset id (see
+     * `_rememberAsset`) so later uses reuse it instead of re-uploading.
+     *
+     * Returns undefined for already-uploaded skill-tools.
+     */
+    _takeDraftBundle(): {
+        name: string;
+        description: string;
+        contentHash: string;
+        bytes: Uint8Array;
+    } | undefined;
+    toJSON(): SkillToolRef;
+}
+/**
+ * SDK-internal draft skill-tool marker. Never reaches the wire; the
+ * materialize step inside `client.run` / `openSession` converts these to
+ * `kind:"skill"` refs once the bundle is uploaded.
+ */
+export interface DraftSkillToolRef {
+    readonly kind: "draft";
+    readonly name: string;
+    readonly description: string;
+    readonly contentHash: string;
+}
+/**
+ * Factory namespace for skill-tools. Each factory reads a skill bundle, lifts
+ * `name` + `description` from the `SKILL.md` frontmatter (an explicit `name`
+ * argument overrides the frontmatter), and produces a {@link SkillTool} to pass
+ * in the session's `tools` array.
+ */
+export declare const Tools: {
+    /**
+     * Read a local skill directory and build a skill-tool. The directory must
+     * contain `SKILL.md` at its root, whose YAML frontmatter provides the tool
+     * `name` (unless overridden via `args.name`) and `description`. Symlinks and
+     * non-regular files are skipped. Bun/Node filesystem runtimes only.
+     */
+    readonly fromSkillDir: (rootDir: string, args?: {
+        readonly name?: string;
+    }) => Promise<SkillTool>;
+    /**
+     * Fetch a zip-archived skill from a URL and build a skill-tool. The archive is
+     * downloaded in the SDK process, so the URL is caller-controlled — host the
+     * skill yourself and pass a temporary signed URL (e.g. an S3 presigned URL).
+     * Its bytes are optionally integrity-checked against `sha256`, unzipped, and
+     * reduced to the same files map as `Tools.fromSkillDir`, so a URL-sourced
+     * skill and the identical local skill produce the same canonical asset and
+     * dedup against each other.
+     *
+     * The archive must contain `SKILL.md` at its root, or inside a single
+     * top-level folder (which is stripped). The signed URL only needs to be valid
+     * for this call; `client.run` / `openSession` snapshots the bytes into the run.
+     *
+     * Universal (Bun / Node 18+ / browser): requires a global `fetch`, or pass one.
+     */
+    readonly fromSkillUrl: (url: string, args?: {
+        readonly name?: string;
+        readonly sha256?: string;
+        readonly timeoutMs?: number;
+        readonly fetch?: FetchLike;
+    }) => Promise<SkillTool>;
+};

package/dist/skill-tool.js

@@ -0,0 +1,190 @@
+import { TOOL_NAME_PATTERN } from "./_contracts/index.js";
+import { bundleSkillFiles, hashSkillBundle } from "./bundle.js";
+import { fetchSkillArchive } from "./fetch-archive.js";
+import { readDirectoryAsFiles } from "./node-fs.js";
+/**
+ * A skill re-expressed as a TOOL. `Tools.fromSkillDir` / `Tools.fromSkillUrl`
+ * read a skill folder/zip, lift the tool `name` + `description` from the
+ * `SKILL.md` YAML frontmatter, and canonically bundle+hash the bytes. The
+ * result rides in the session's `tools` array (next to builtin names and custom
+ * {@link Tool} bundles); `client.run` / `openSession` uploads the bundle as an
+ * asset before the run lands, and the wire ref becomes a
+ * `{ kind:"skill", assetId, name, description }` {@link SkillToolRef}.
+ *
+ * At run time the model calls the no-arg load-tool to pull the skill's
+ * `SKILL.md` body into context; the bundle's files are eagerly staged to
+ * `/workspace/skills/<name>/`.
+ *
+ * Asset deduplication makes the same bytes a no-op upload on subsequent runs.
+ * A URL is an ingestion source, not a persistent reference.
+ */
+export class SkillTool {
+    #ref;
+    #inlineBytes;
+    /** Asset id cached after the first use, so reuse skips a re-upload. */
+    #assetId;
+    /** Internal constructor. Use the `Tools.fromSkill*` factories. */
+    constructor(ref, inlineBytes) {
+        this.#ref = ref;
+        this.#inlineBytes = inlineBytes;
+    }
+    /**
+     * The wire-level reference. Returns the SDK-private draft shape for
+     * un-uploaded skill-tools (kind:"draft", with name + description +
+     * contentHash). `client.run` / `openSession` walks these and uploads them
+     * before the run lands.
+     */
+    get ref() {
+        return this.#ref;
+    }
+    /** True for local-bytes skill-tools that haven't been uploaded yet. */
+    get isDraft() {
+        return this.#ref.kind === "draft";
+    }
+    /** Internal: the asset id resolved on a prior use, or undefined. */
+    get _cachedAssetId() {
+        return this.#assetId;
+    }
+    /** Internal: remember the asset id resolved for this draft's bytes. */
+    _rememberAsset(assetId) {
+        this.#assetId = assetId;
+    }
+    /** Internal: build a draft from an already-loaded skill files map. */
+    static async _fromFiles(source, files, nameOverride) {
+        const front = extractSkillFrontmatter(source, files);
+        const name = nameOverride ?? front.name;
+        if (typeof name !== "string" || name.length === 0) {
+            throw new Error(`${source}: a skill name is required — pass { name } or add a \`name:\` field to the SKILL.md YAML frontmatter`);
+        }
+        if (!TOOL_NAME_PATTERN.test(name)) {
+            throw new Error(`${source}: name must match ${TOOL_NAME_PATTERN.source}`);
+        }
+        if (name.includes("__")) {
+            throw new Error(`${source}: name must not contain "__"; that separator is reserved for MCP tools`);
+        }
+        const description = front.description;
+        if (typeof description !== "string" || description.trim().length === 0) {
+            throw new Error(`${source}: a skill description is required — add a \`description:\` field to the SKILL.md YAML frontmatter`);
+        }
+        if (description.length > 2048) {
+            throw new Error(`${source}: description must be <= 2048 chars`);
+        }
+        const bundled = bundleSkillFiles(files);
+        const contentHash = await hashSkillBundle(bundled.zip);
+        const ref = { kind: "draft", name, description, contentHash };
+        return new SkillTool(ref, bundled.zip);
+    }
+    /**
+     * Internal: yield the draft's bytes + metadata so `client.run` / `openSession`
+     * can upload the asset. Idempotent (non-consuming): a SkillTool is reusable
+     * across sessions — the first use caches the resolved asset id (see
+     * `_rememberAsset`) so later uses reuse it instead of re-uploading.
+     *
+     * Returns undefined for already-uploaded skill-tools.
+     */
+    _takeDraftBundle() {
+        if (this.#ref.kind !== "draft" || !this.#inlineBytes) {
+            return undefined;
+        }
+        return {
+            name: this.#ref.name,
+            description: this.#ref.description,
+            contentHash: this.#ref.contentHash,
+            bytes: this.#inlineBytes
+        };
+    }
+    toJSON() {
+        if (this.#ref.kind === "draft") {
+            throw new Error("SkillTool: draft skill-tools cannot be JSON-serialised — they only become wire refs when " +
+                "aex.run / openSession uploads the bytes as an asset.");
+        }
+        return this.#ref;
+    }
+}
+/**
+ * Factory namespace for skill-tools. Each factory reads a skill bundle, lifts
+ * `name` + `description` from the `SKILL.md` frontmatter (an explicit `name`
+ * argument overrides the frontmatter), and produces a {@link SkillTool} to pass
+ * in the session's `tools` array.
+ */
+export const Tools = {
+    /**
+     * Read a local skill directory and build a skill-tool. The directory must
+     * contain `SKILL.md` at its root, whose YAML frontmatter provides the tool
+     * `name` (unless overridden via `args.name`) and `description`. Symlinks and
+     * non-regular files are skipped. Bun/Node filesystem runtimes only.
+     */
+    async fromSkillDir(rootDir, args = {}) {
+        const files = await readDirectoryAsFiles(rootDir);
+        return SkillTool._fromFiles("Tools.fromSkillDir", files, args.name);
+    },
+    /**
+     * Fetch a zip-archived skill from a URL and build a skill-tool. The archive is
+     * downloaded in the SDK process, so the URL is caller-controlled — host the
+     * skill yourself and pass a temporary signed URL (e.g. an S3 presigned URL).
+     * Its bytes are optionally integrity-checked against `sha256`, unzipped, and
+     * reduced to the same files map as `Tools.fromSkillDir`, so a URL-sourced
+     * skill and the identical local skill produce the same canonical asset and
+     * dedup against each other.
+     *
+     * The archive must contain `SKILL.md` at its root, or inside a single
+     * top-level folder (which is stripped). The signed URL only needs to be valid
+     * for this call; `client.run` / `openSession` snapshots the bytes into the run.
+     *
+     * Universal (Bun / Node 18+ / browser): requires a global `fetch`, or pass one.
+     */
+    async fromSkillUrl(url, args = {}) {
+        const files = await fetchSkillArchive(url, {
+            ...(args.sha256 !== undefined ? { sha256: args.sha256 } : {}),
+            ...(args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {}),
+            ...(args.fetch !== undefined ? { fetch: args.fetch } : {})
+        });
+        return SkillTool._fromFiles("Tools.fromSkillUrl", files, args.name);
+    }
+};
+/**
+ * Read `SKILL.md` from a bundle files map and parse its YAML frontmatter for
+ * the `name` + `description` fields. Throws when the bundle has no root
+ * `SKILL.md` (that is what makes a bundle a skill).
+ */
+function extractSkillFrontmatter(source, files) {
+    const raw = files["SKILL.md"];
+    if (raw === undefined) {
+        throw new Error(`${source}: the skill bundle must contain a SKILL.md at its root`);
+    }
+    const text = typeof raw === "string" ? raw : new TextDecoder().decode(raw);
+    return parseSkillFrontmatter(text);
+}
+/**
+ * Minimal YAML-frontmatter reader: pulls the `name` and `description` scalar
+ * values out of the leading `--- … ---` block. Only simple single-line
+ * `key: value` entries are supported (surrounding single/double quotes are
+ * stripped); anything else is ignored. A skill with no frontmatter yields an
+ * empty result and the caller reports the missing field.
+ */
+function parseSkillFrontmatter(text) {
+    const src = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    const match = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(src);
+    if (!match) {
+        return {};
+    }
+    const out = {};
+    for (const line of match[1].split(/\r?\n/)) {
+        const kv = /^([A-Za-z0-9_-]+)[ \t]*:[ \t]*(.*)$/.exec(line);
+        if (!kv)
+            continue;
+        const key = kv[1].toLowerCase();
+        if (key !== "name" && key !== "description")
+            continue;
+        let value = kv[2].trim();
+        if (value.length >= 2 &&
+            ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))) {
+            value = value.slice(1, -1);
+        }
+        if (value.length > 0) {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=skill-tool.js.map

package/dist/skill-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-tool.js","sourceRoot":"","sources":["../src/skill-tool.ts"],"names":[],"mappings":"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"}

package/dist/tool.d.ts

@@ -12,7 +12,7 @@ export declare class Tool {
     private constructor();
     get ref(): ToolRef | DraftToolRef;
     get isDraft(): boolean;
-    /** Internal: the asset id resolved on a prior submit, or undefined. */
+    /** Internal: the asset id resolved on a prior use, or undefined. */
     get _cachedAssetId(): string | undefined;
     /** Internal: remember the asset id resolved for this draft's bytes. */
     _rememberAsset(assetId: string): void;

package/dist/tool.js

@@ -4,7 +4,7 @@ import { readDirectoryAsFiles } from "./node-fs.js";
 export class Tool {
     #ref;
     #inlineBytes;
-    /** Asset id cached after the first submit, so reuse skips a re-upload. */
+    /** Asset id cached after the first use, so reuse skips a re-upload. */
     #assetId;
     constructor(ref, inlineBytes) {
         this.#ref = ref;
@@ -16,7 +16,7 @@ export class Tool {
     get isDraft() {
         return this.#ref.kind === "draft";
     }
-    /** Internal: the asset id resolved on a prior submit, or undefined. */
+    /** Internal: the asset id resolved on a prior use, or undefined. */
     get _cachedAssetId() {
         return this.#assetId;
     }
@@ -90,7 +90,7 @@ export class Tool {
     }
     toJSON() {
         if (this.#ref.kind === "draft") {
-            throw new Error("Tool: draft Tools cannot be JSON-serialised — they only become wire refs when client.submit uploads the bytes as an asset.");
+            throw new Error("Tool: draft Tools cannot be JSON-serialised — they only become wire refs when aex.run / openSession uploads the bytes as an asset.");
         }
         return this.#ref;
     }

package/dist/tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -6,4 +6,4 @@
  *
  * Used by the (future) User-Agent header on outbound SDK requests.
  */
-export declare const SDK_VERSION = "0.33.0";
+export declare const SDK_VERSION = "0.34.0";

package/dist/version.js

@@ -6,5 +6,5 @@
  *
  * Used by the (future) User-Agent header on outbound SDK requests.
  */
-export const SDK_VERSION = "0.33.0";
+export const SDK_VERSION = "0.34.0";
 //# sourceMappingURL=version.js.map

package/docs/cleanup.md

@@ -17,10 +17,10 @@ retention field is rejected if supplied.
 ```ts
 import { Models } from "@aexhq/sdk";
 
-const runId = await aex.submit({
+await aex.run({
   model: Models.CLAUDE_HAIKU_4_5,
-  prompt: "...",
-  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }
+  message: "...",
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
 });
 ```
 

package/docs/concepts/agent-tools.md

@@ -4,9 +4,7 @@ description: The default builtin tools available inside managed runs.
 icon: TerminalSquare
 ---
 
-Managed runs inject a DX-first set of builtin tools to the agent by default. The
-default set is every builtin tool EXCEPT `notebook_edit` (notebook editing is
-opt-in). It includes:
+Managed runs inject the complete builtin tool set into the agent by default:
 
 - `bash`, `code_execution` — run shell commands / model-written snippets
 - `read_file`, `write_file`, `edit_file` — file read/create/patch
@@ -28,29 +26,12 @@ or pure-custom run where every tool comes from `mcpServers` or `tools`.
 ## Cherry-picking builtins
 
 The `tools` list accepts both custom tool bundles and BUILTIN tool references
-(bare name strings, preferably `BuiltinTools.<name>`). Use a builtin reference
-to add a tool the default set omits (notebook editing), or to pick a narrow
-subset alongside `includeBuiltinTools: false`.
+(bare name strings, preferably `BuiltinTools.<name>`). Use builtin references
+to pick a narrow subset alongside `includeBuiltinTools: false`.
 
 The final tool list is ordered: resolved builtin tools, then custom tools, then
 MCP tools.
 
-## Optional notebook support
-
-`notebook_edit` edits Jupyter `.ipynb` cells as JSON. It is NOT in the default
-builtin set; add it via `tools`:
-
-```ts
-import { BuiltinTools, Models } from "@aexhq/sdk";
-
-await aex.submit({
-  model: Models.CLAUDE_HAIKU_4_5,
-  prompt: "Edit the analysis notebook.",
-  tools: [BuiltinTools.notebook_edit],
-  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }
-});
-```
-
 Networking is open by default: the agent may reach any public host, subject to a
 fixed SSRF deny-list. `web_fetch` and `web_search` reach the network over a
 managed, SSRF-guarded path that is **not** governed by `environment.networking`,
@@ -64,11 +45,11 @@ See [Networking](../networking.md).
 ```ts
 import { Models } from "@aexhq/sdk";
 
-await aex.submit({
+await aex.run({
   model: Models.CLAUDE_HAIKU_4_5,
-  prompt: "Use only the declared MCP tools.",
+  message: "Use only the declared MCP tools.",
   mcpServers,
   includeBuiltinTools: false,
-  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
 });
 ```

package/docs/concepts/composition.md

@@ -4,40 +4,43 @@ description: The primitives used to assemble each run.
 icon: Blocks
 ---
 
-aex composes an agent from explicit per-run inputs. The SDK materializes local
-bytes before submission and the platform mounts them into the managed runtime
-before the first agent turn.
+aex composes an agent from explicit per-session inputs. The SDK materializes local
+bytes before the session lands and the platform mounts them into the managed
+runtime before the first agent turn.
 
 | Need | Primitive |
 | --- | --- |
-| Executable or instructional bundles | `Skill.fromPath`, `Skill.fromFiles`, `Skill.fromUrl`, `Skill.fromCatalog` |
+| Executable or instructional skill bundles (load-tools) | `Tools.fromSkillDir`, `Tools.fromSkillUrl` |
 | Agent instructions | `AgentsMd.fromPath`, `AgentsMd.fromContent` |
 | Reference files and folders | `File.fromPath`, `File.fromBytes` |
 | Remote tools | `McpServer.remote`, `McpServer.fromId` |
 | Credentialed HTTP APIs | `ProxyEndpoint.none`, `bearer`, `basic`, `header`, `query` |
-| Non-secret runtime settings | `environment.envVars`, `environment.packages`, `environment.networking` |
+| Non-secret runtime settings | `environment.variables`, `environment.packages`, `environment.networking` |
 
 ```ts
-import { AgentsMd, File, McpServer, Models, ProxyEndpoint, Skill } from "@aexhq/sdk";
+import { AgentsMd, File, McpServer, Models, ProxyEndpoint, Tools } from "@aexhq/sdk";
 
-await aex.submit({
+await aex.run({
   model: Models.CLAUDE_HAIKU_4_5,
-  prompt: "Use the attached docs and tools to produce a report.",
+  message: "Use the attached docs and tools to produce a report.",
   agentsMd: [AgentsMd.fromContent("Follow the repo conventions.")],
   files: [await File.fromPath("./input")],
-  skills: [await Skill.fromPath("./skills/report-writer", { name: "report-writer" })],
+  tools: [await Tools.fromSkillDir("./skills/report-writer", { name: "report-writer" })],
   mcpServers: [McpServer.remote({ name: "github", url: "https://example.com/mcp" })],
   proxyEndpoints: [
     ProxyEndpoint.bearer({
       name: "internal-api",
       baseUrl: "https://api.example.com",
+      token: process.env.INTERNAL_API_TOKEN!,
       allowMethods: ["GET"],
       allowPathPrefixes: ["/v1/"]
     })
   ],
-  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
 });
 ```
 
-Secrets stay out of reusable configs. Put provider keys, MCP auth, and proxy
-auth in the `secrets` bundle on the concrete submit call.
+Secrets stay out of reusable configs. Provider keys go in the top-level `apiKeys`
+map; MCP auth rides on each `McpServer` instance and proxy auth on each
+`ProxyEndpoint` instance — the SDK splits them into the vaulted secrets channel
+server-side, so they never live in a shareable config object.

package/docs/concepts/providers-and-runtimes.md

@@ -26,11 +26,11 @@ All submissions run on the managed runtime. There is no public runtime selector;
 ```ts
 import { Models, Providers } from "@aexhq/sdk";
 
-await aex.submit({
+await aex.run({
   provider: Providers.OPENAI,
   model: Models.GPT_4_1,
-  prompt: "Summarise the attached files.",
-  secrets: { apiKeys: { openai: process.env.OPENAI_API_KEY! } }
+  message: "Summarise the attached files.",
+  apiKeys: { openai: process.env.OPENAI_API_KEY! }
 });
 ```
 

package/docs/concepts/runs.md

@@ -4,40 +4,45 @@ description: The durable unit aex submits, observes, and archives.
 icon: Play
 ---
 
-A run is an immutable request to execute an autonomous agent task. The caller
-submits the model, prompt, optional system message, composition primitives,
-output policy, and one inline secrets bundle. aex snapshots the non-secret
-inputs, holds secrets for the run lifecycle, dispatches through the managed
-runtime, and records status, typed events, and outputs.
+A run is a durable, resumable **session**: the model, system message, composition
+primitives, output policy, and per-provider keys you open it with, plus every
+turn you send to it. aex snapshots the non-secret inputs, holds secrets for the
+session lifecycle, dispatches each turn through the managed runtime, and records
+status, typed events, and outputs. Sessions are the low-level API; `run()` is the
+one-shot convenience wrapper over them.
 
 ```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! });
 
-const runId = await aex.submit({
+const session = await aex.openSession({
   provider: "anthropic",
   model: Models.CLAUDE_HAIKU_4_5,
-  prompt: "Write the report and save it as a file.",
-  secrets: { apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! } }
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
 });
 
-for await (const event of aex.stream(runId)) {
+const turn = session.send("Write the report and save it as a file.");
+for await (const event of turn) {
   console.log(event.type);
 }
+await turn.done();
 
-await aex.wait(runId);
-await aex.download(runId, { to: "./run.zip" });
+await session.wait();
+await session.download({ to: "./session.zip" });
 ```
 
-The same durable record backs SDK and CLI reads. Use `getRun`/`get`, `events`,
-`stream`, `streamEnvelopes`, `wait`, `outputs`, and `download` to inspect the
-run live or after completion.
+The same durable record backs SDK and CLI reads. From the handle use `refresh`,
+`unit`, `wait`, and `download` for lifecycle, plus the grouped read accessors —
+`messages()`, `events()`, and `outputs()` (each with `list()`/`last()`/`first()`,
+and `events().stream()` / `events().streamEnvelopes()` / `outputs().read(...)` for
+streaming and byte-capped reads) — to inspect the session live or after it parks;
+from the client, `aex.sessions.list()` / `aex.sessions.get(id)` read across the
+workspace.
 
-Use `idempotencyKey` when retrying a submit from your own workflow. aex hashes
-the normalized non-secret submission, so a retry with the same key and same body
-returns the existing run while a mismatched body fails with an idempotency
-conflict.
+Use `idempotencyKey` when retrying `openSession` or `send` from your own
+workflow. aex hashes the normalized non-secret submission, so a retry with the
+same key and same body returns the existing session while a mismatched body fails
+with an idempotency conflict.
 
-aex selects product placement server-side. There is no submit-time region
-selector.
+aex selects product placement server-side. There is no region selector.