@aexhq/sdk 0.33.1 → 0.35.0

package/docs/skills.md

@@ -4,132 +4,77 @@ title: Skills
 
 # Skills
 
-A skill is executable or instructional content that is mounted into a run before
-the first agent turn. Every accepted skill ends up as a storage-neutral
-`kind:"asset"` reference in the run submission, and the hosted platform snapshots
-that asset into durable run asset storage before dispatch.
-
-There are three sources for skill bytes:
-
-- **Inline/local draft:** `Skill.fromFiles(...)`, `Skill.fromPath(...)`, or
-  `Skill.fromUrl(...)` builds a draft in the SDK process. `submit` uploads
-  it before posting `/runs`.
-- **Pre-uploaded workspace asset:** call `await draft.upload(aex)` and reuse the
-  returned materialized `Skill`, or pass an existing `kind:"asset"` ref from a
-  config file.
-- **Workspace skill catalog:** upload with `aex skills upload` or the dashboard,
-  then pass the returned record to `Skill.fromCatalog(record)`.
-
-All three sources normalize to the same content-addressed asset. Identical bytes
-dedup by hash, so repeated submissions of the same bundle are no-op uploads.
-There is no per-run auto-suffixed `skl_*` row for inline skills.
-
-## Materialization
-
-For each run, the platform copies referenced skill assets into durable run asset
-storage (`runs/<runId>/assets/<hash>`) and the runner downloads them into the
-workspace under `skills/<name>/`.
-
-A bundle's `SKILL.md` is mounted at `skills/<name>/SKILL.md`, and the agent's
-instructions list each mounted skill with that path. The full skill body stays
-on disk, so prompts or `AGENTS.md` guidance that rely on a skill should tell the
-agent when to read or use it. Bundles without `SKILL.md` are still mounted as
-files at `skills/<name>/`, but nothing prompts the agent to read them; reference
-them explicitly from the prompt or your `AGENTS.md`.
-
-The platform also mounts the `aex` CLI and a per-run manifest into every run.
-Skills call managed HTTP proxy endpoints through the mounted CLI
-(`aex proxy ...`); see `credentials.md` for the policy and auth model.
-
-Run-scoped asset copies are part of the run record and are removed by run deletion
-or retention cleanup. Catalog assets are separate workspace records: deleting a
-catalog skill hard-deletes its metadata and removes the shared asset object only
-when no other catalog row still references those bytes. Existing run snapshots
-keep their run-scoped copy.
-
-## Inline And Local Drafts
-
-`Skill.fromFiles({ name, files })`, `Skill.fromPath(rootDir, { name })`, and
-`Skill.fromUrl(url, { name })` build an unstaged `Skill`. The instance carries
-canonical zip bytes and a `sha256:<hex>` content hash.
+A skill is a bundle of instructional or executable content (`SKILL.md` plus any
+supporting files) that the agent can pull into context on demand. In the SDK a
+skill is expressed as a per-skill **load-tool**: it rides in the session's
+`tools` array next to builtin tool names and custom `Tool` bundles, and the model
+loads it by calling it.
+
+Build a skill-tool with the `Tools.fromSkill*` factories. Each factory reads a
+skill bundle, lifts the tool `name` and `description` from the `SKILL.md` YAML
+frontmatter (an explicit `{ name }` overrides the frontmatter), canonically
+zips + hashes the bytes, and returns a `SkillTool`:
+
+- **Local directory:** `Tools.fromSkillDir(rootDir, { name? })` reads a folder
+  that has `SKILL.md` at its root (Bun/Node filesystem runtimes).
+- **Signed URL:** `Tools.fromSkillUrl(url, { name?, sha256?, timeoutMs?, fetch? })`
+  fetches a zip archive with `SKILL.md` at the archive root (universal — needs a
+  global `fetch`, or pass one).
 
 ```ts
-import { AgentExecutor, Models, Skill } from "@aexhq/sdk";
+import { Aex, Models, Tools } from "@aexhq/sdk";
 
-const aex = new AgentExecutor({ apiToken });
+const aex = new Aex({ apiToken });
 
-await aex.submit({
+await aex.run({
   model: Models.CLAUDE_HAIKU_4_5,
-  prompt,
-  skills: [await Skill.fromPath("./skills/rules", { name: "rules" })],
-  secrets: { apiKeys: { anthropic: apiKey } }
+  message,
+  tools: [await Tools.fromSkillDir("./skills/rules", { name: "rules" })],
+  apiKeys: { anthropic: apiKey }
 });
 ```
 
-Before it posts `/runs`, the SDK uploads each draft through the asset upload
-flow:
+`Tools.fromSkillDir("./skills/rules", …)` resolves relative to the process CWD,
+so run the script from the directory that *contains* `skills/`. The `SKILL.md`
+frontmatter must supply a `description` (max 2048 chars) and, unless you pass
+`{ name }`, a `name`. Names must match the tool-name pattern and must not contain
+`__` (that separator is reserved for MCP tools).
+
+## How a skill-tool rides on the wire
+
+Before the session lands, `openSession` / `run` walks the `tools` array and
+uploads each draft skill-tool's bundle through the asset upload flow:
 
 1. `POST /assets/presign` checks for a dedup hit and, when needed, returns a
    signed upload URL.
 2. The SDK PUTs bytes directly to object storage with the signed checksum headers.
 3. `POST /assets/finalize` confirms the object exists.
 
-The runner re-verifies the content hash when it downloads the asset.
-
-## Pre-Upload For Reuse
-
-If you want to build a local skill once and reuse the materialized asset across
-multiple submissions, upload the draft explicitly:
-
-```ts
-const draft = await Skill.fromFiles({ name: "rules", files });
-const uploaded = await draft.upload(aex);
-
-await aex.submit({
-  model: Models.CLAUDE_HAIKU_4_5,
-  prompt,
-  skills: [uploaded],
-  secrets: { apiKeys: { anthropic: apiKey } }
-});
-```
-
-The returned `uploaded` skill carries a plain `kind:"asset"` ref. Submitting it
-does not upload bytes again.
-
-## Fetch From A Signed URL
-
-When your app runs in the cloud with limited local storage, host the skill
-yourself as a zip archive with `SKILL.md` at the archive root and pass a
-temporary signed URL:
-
-```ts
-const skill = await Skill.fromUrl(signedUrl, {
-  name: "rules",
-  sha256: "sha256:<hex>"
-});
-```
-
-`Skill.fromUrl` fetches the archive in the SDK process. The hosted platform does
-not fetch the caller-controlled URL. The signed URL only needs to be valid for
-this call; the SDK snapshots the bytes into the asset store before the run is
-submitted.
+The wire ref then becomes a `{ kind:"skill", assetId, name, description }` entry
+inside `submission.tools`. Identical bytes dedup by content hash, so re-submitting
+the same bundle is a no-op upload; a `SkillTool` instance also caches its resolved
+asset id, so reusing the same instance across sessions skips the re-upload. A URL
+is an ingestion source, not a persistent reference — the SDK snapshots the fetched
+bytes into the asset store, and the hosted platform never fetches the
+caller-controlled URL.
 
-## Workspace Catalog
+## Loading and materialization
 
-Catalog skills are workspace records backed by the same content-addressed
-assets. Use them when a team wants a named, listed skill record:
+The skill-tool's `name` and `description` are what the agent sees in its tool
+list. At run time the model calls the **no-arg load-tool** to pull the skill's
+`SKILL.md` body into context — the description tells the agent when that is worth
+doing.
 
-```ts
-const [record] = await aex.skills.list();
+Independently of whether the model calls the load-tool, the platform copies the
+referenced skill asset into durable run asset storage
+(`runs/<runId>/assets/<hash>`) and the runner **eagerly stages** the bundle's
+files into the workspace under `/workspace/skills/<name>/`. So the `SKILL.md` body
+and every supporting file are on disk from the first turn; the load-tool call is
+how that body enters the model's context, not how the files get written.
 
-await aex.submit({
-  model: Models.CLAUDE_HAIKU_4_5,
-  prompt,
-  skills: [Skill.fromCatalog(record)],
-  secrets: { apiKeys: { anthropic: apiKey } }
-});
-```
+The platform also mounts the `aex` CLI and a per-run manifest into every run.
+Skills call managed HTTP proxy endpoints through the mounted CLI
+(`aex proxy ...`); see [Credentials](credentials.md) for the policy and auth model.
 
-The record must be `ready` and carry a content hash. `Skill.fromCatalog` performs
-no upload; it produces a `kind:"asset"` ref directly against bytes already in
-the catalog.
+Run-scoped asset copies are part of the run record and are removed by run deletion
+or retention cleanup.

package/docs/vision-skills.md

@@ -8,8 +8,8 @@ aex has no built-in vision tool. The agent's `provider`/`model` selects the
 *reasoning* model — it is not an endpoint a skill can POST an image to mid-run.
 To give a run image understanding (or to call any other model/HTTP API), ship a
 **skill** that POSTs to the provider's OpenAI-compatible endpoint **through the
-managed proxy**, with the key supplied via `secrets.proxyEndpointAuth`. The raw
-key never enters the container.
+managed proxy**, with the key supplied on a `ProxyEndpoint.bearer(...)` instance.
+The raw key never enters the container.
 
 This is the same proxy described in `credentials.md` — this page is the worked
 recipe for the model-API case, which has two wrinkles a plain JSON call does not:
@@ -18,54 +18,44 @@ large enough to need a raised `maxRequestBytes`.
 
 The canonical, runnable example lives in the repo at
 [`examples/vision-skill/`](../../../examples/vision-skill) (`SKILL.md`,
-`caption_frame.py`, `verify_frame.py`, `submit_with_vision_skill.mjs`). It
+`caption_frame.py`, `verify_frame.py`, `run_with_vision_skill.mjs`). It
 captions a frame with ByteDance Doubao Seed Vision (Ark) and returns a per-noun
 "does the frame depict X?" verdict. Everything below is taken from it.
 
 ## 1. Declare the model endpoint as a proxy endpoint
 
-The vision provider's API is just an HTTPS host. Declare it as a `bearer` proxy
-endpoint and supply the key in `secrets.proxyEndpointAuth`. The two model-specific
-settings are `responseMode: "full"` (so the skill gets the upstream JSON back) and
-a raised `maxRequestBytes` (so the base64 image fits):
+The vision provider's API is just an HTTPS host. Declare it with
+`ProxyEndpoint.bearer(...)`, which carries the key on the instance. The two
+model-specific settings are `responseMode: "full"` (so the skill gets the upstream
+JSON back) and a raised `maxRequestBytes` (so the base64 image fits):
 
 ```ts
-import { AgentExecutor, Models, Skill, ProxyEndpoint, validateProxyAuth } from "@aexhq/sdk";
-
-const aex = new AgentExecutor({ apiToken: process.env.AEX_API_TOKEN! });
-
-const proxyEndpoints = [
-  ProxyEndpoint.bearer({
-    name: "doubao-ark",
-    baseUrl: "https://ark.ap-southeast.bytepluses.com", // intl BytePlus gateway
-    allowMethods: ["POST"],
-    allowPathPrefixes: ["/api/v3/chat/completions"],
-    maxRequestBytes: 2_000_000, // base64 image POSTs — see note below
-    responseMode: "full",
-    timeoutMs: 60_000
-  })
-];
-
-const proxyEndpointAuth = [
-  { name: "doubao-ark", value: { type: "bearer", token: process.env.DOUBAO_API_KEY! } }
-];
-
-validateProxyAuth(proxyEndpoints, proxyEndpointAuth); // fail fast at submit time
+import { Aex, Models, Tools, ProxyEndpoint } from "@aexhq/sdk";
+
+const aex = new Aex({ apiToken: process.env.AEX_API_TOKEN! });
+
+const doubaoArk = ProxyEndpoint.bearer({
+  name: "doubao-ark",
+  baseUrl: "https://ark.ap-southeast.bytepluses.com", // intl BytePlus gateway
+  token: process.env.DOUBAO_API_KEY!,
+  allowMethods: ["POST"],
+  allowPathPrefixes: ["/api/v3/chat/completions"],
+  maxRequestBytes: 2_000_000, // base64 image POSTs — see note below
+  responseMode: "full",
+  timeoutMs: 60_000
+});
 
-const runId = await aex.submit({
+await aex.run({
   model: Models.CLAUDE_HAIKU_4_5,
-  prompt: "…read skills/frame-vision-gate/SKILL.md, then caption + verify the frame…",
-  skills: [await Skill.fromPath("./vision-skill", { name: "frame-vision-gate" })],
-  proxyEndpoints,
-  secrets: {
-    apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! },
-    proxyEndpointAuth
-  }
+  message: "…read skills/frame-vision-gate/SKILL.md, then caption + verify the frame…",
+  tools: [await Tools.fromSkillDir("./vision-skill", { name: "frame-vision-gate" })],
+  proxyEndpoints: [doubaoArk],
+  apiKeys: { anthropic: process.env.ANTHROPIC_API_KEY! }
 });
 ```
 
-`Skill.fromPath("./vision-skill", …)` is resolved relative to the process CWD, so
-run the submit script from the directory that *contains* `vision-skill/` (in the
+`Tools.fromSkillDir("./vision-skill", …)` is resolved relative to the process CWD, so
+run the script from the directory that *contains* `vision-skill/` (in the
 repo, that is `examples/`). The same pattern works for OpenAI, Gemini's
 OpenAI-compatible endpoint, or any other OpenAI-chat-shaped vision API — only
 `baseUrl` and the path prefix change.
@@ -147,8 +137,7 @@ so full-res frames do not add payload and model cost without useful signal.
 - **Host selection.** Use the provider endpoint that matches your account and
   declare it as the proxy endpoint `baseUrl`.
 - **Keyless model hosts.** If the upstream takes no credential, declare the
-  endpoint with `authShape: { type: "none" }` and omit the `proxyEndpointAuth`
-  entry (see `credentials.md`).
+  endpoint with `ProxyEndpoint.none(...)` (see `credentials.md`).
 - **Response size.** `responseMode: "full"` is required to read the model's reply
   back. Leave `maxResponseBytes` at its default (`0` = unlimited, streamed) unless
   you want a truncation cap.

package/examples/chat-corpus.ts

@@ -3,10 +3,9 @@
  *
  * Combines the public `@aexhq/sdk` corpus read-tools (`createCorpusTools`) with a
  * direct Claude chat loop (`@anthropic-ai/sdk`). The importable `@aexhq/sdk` stays
- * LLM-vendor-free; the vendor dependency lives only here in the example (and in
- * the bundled `aex chat` CLI command).
+ * LLM-vendor-free; the vendor dependency lives only here in the example.
  *
- * Run (Bun): ANTHROPIC_API_KEY=… AEX_TOKEN=… bun examples/chat-corpus.ts <runId> [runId…]
+ * Run (Bun): ANTHROPIC_API_KEY=… AEX_API_TOKEN=… bun examples/chat-corpus.ts <sessionId> [sessionId…]
  *
  * The model answers ONLY from the named runs' outputs (read via the corpus
  * tools); a run outside the corpus is refused by the tool layer.
@@ -14,17 +13,17 @@
 import Anthropic from "@anthropic-ai/sdk";
 import { AgentExecutor, createCorpusTools, DataToolError } from "@aexhq/sdk";
 
-const runIds = process.argv.slice(2);
-if (runIds.length === 0) {
-  console.error("usage: bun examples/chat-corpus.ts <runId> [runId…]");
+const sessionIds = process.argv.slice(2);
+if (sessionIds.length === 0) {
+  console.error("usage: bun examples/chat-corpus.ts <sessionId> [sessionId…]");
   process.exit(2);
 }
 
 const aex = new AgentExecutor({
-  apiToken: process.env.AEX_TOKEN!,
-  ...(process.env.AEX_URL ? { baseUrl: process.env.AEX_URL } : {})
+  apiToken: process.env.AEX_API_TOKEN!,
+  ...(process.env.AEX_API_URL ? { baseUrl: process.env.AEX_API_URL } : {})
 });
-const tools = createCorpusTools(aex, { runIds });
+const tools = createCorpusTools(aex, { sessionIds });
 const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });
 
 const SYSTEM =

package/examples/feature-tour.ts

@@ -0,0 +1,301 @@
+/**
+ * SDK feature tour: one managed session that uses typed model/runtime constants,
+ * inline AGENTS.md guidance, uploaded files, a custom tool bundle, selected
+ * built-in tools, runtime env vars/secrets, streamed events, output reads, and
+ * corpus-scoped data tools.
+ *
+ * Run from the repository root after building the workspace package:
+ *
+ *   AEX_API_TOKEN=... DEEPSEEK_API_KEY=... bun packages/sdk/examples/feature-tour.ts
+ *
+ * Optional:
+ *
+ *   AEX_API_URL=https://api.aex.dev
+ *   AEX_FEATURE_TOUR_DOWNLOAD=./feature-tour-session.zip
+ *   AEX_DEMO_RUNTIME_SECRET=...       # mounted as a runtime secret; never printed
+ *   AEX_DEMO_MCP_URL=https://...      # declares an optional remote MCP server
+ *   AEX_DEMO_MCP_TOKEN=...            # optional bearer auth for that MCP server
+ */
+import {
+  AgentsMd,
+  Aex,
+  BuiltinTools,
+  createCorpusTools,
+  File,
+  isRateLimited,
+  isTextMessage,
+  McpServer,
+  Models,
+  ProxyEndpoint,
+  Providers,
+  Secret,
+  Sizes,
+  Tool
+} from "@aexhq/sdk";
+
+process.on("uncaughtException", handleFatal);
+process.on("unhandledRejection", handleFatal);
+
+const apiToken = required("AEX_API_TOKEN");
+const deepseekKey = required("DEEPSEEK_API_KEY");
+const apiUrl = process.env.AEX_API_URL;
+const demoMcpUrl = process.env.AEX_DEMO_MCP_URL;
+const demoMcpToken = process.env.AEX_DEMO_MCP_TOKEN;
+const demoRuntimeSecret = process.env.AEX_DEMO_RUNTIME_SECRET;
+const downloadPath = process.env.AEX_FEATURE_TOUR_DOWNLOAD;
+const textEncoder = new TextEncoder();
+
+const aex = new Aex({
+  apiToken,
+  ...(apiUrl ? { baseUrl: apiUrl } : {}),
+  retry: {
+    maxAttempts: 4,
+    initialDelayMs: 500,
+    maxDelayMs: 10_000,
+    maxElapsedMs: 90_000
+  }
+});
+
+const metricLookup = await Tool.fromFiles({
+  name: "metric_lookup",
+  description: "Looks up normalized demo metrics for one product line.",
+  inputSchema: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      product: {
+        type: "string",
+        enum: ["atlas", "beacon", "cinder"],
+        description: "Product line to inspect."
+      }
+    },
+    required: ["product"]
+  },
+  entry: "index.js",
+  files: {
+    "index.js": `
+const DATA = {
+  atlas: { customerCount: 118, activationHealthPct: 72.4, supportTickets: 11 },
+  beacon: { customerCount: 74, activationHealthPct: 65.1, supportTickets: 19 },
+  cinder: { customerCount: 43, activationHealthPct: 58.8, supportTickets: 7 }
+};
+
+export default async function ({ input }) {
+  const key = String(input.product ?? "").toLowerCase();
+  const row = DATA[key];
+  if (!row) {
+    return { content: [{ type: "text", text: \`unknown product: \${key}\` }], is_error: true };
+  }
+  return { content: [{ type: "text", text: JSON.stringify({ product: key, ...row }) }] };
+}
+`
+  }
+});
+
+const demoCsv = [
+  "product,region,q1_revenue_usd,q2_revenue_usd,activation_rate",
+  "atlas,na,120000,139500,0.84",
+  "beacon,emea,98000,104300,0.79",
+  "cinder,apac,67000,81000,0.91"
+].join("\n");
+
+const attachedFile = await File.fromBytes({
+  name: "quarterly-metrics.csv",
+  bytes: textEncoder.encode(`${demoCsv}\n`),
+  mountPath: "/workspace/input"
+});
+
+const runRules = await AgentsMd.fromContent(
+  [
+    "# Feature tour rules",
+    "- Use `/workspace/input/quarterly-metrics.csv` as the source table.",
+    "- Call `metric_lookup` for atlas, beacon, and cinder before writing conclusions.",
+    "- Write final artifacts under `/workspace/outputs`.",
+    "- Never print runtime secret values or provider keys."
+  ].join("\n"),
+  { name: "feature-tour-rules" }
+);
+
+const mcpServers = demoMcpUrl
+  ? [
+      McpServer.remote({
+        name: "demo-mcp",
+        url: demoMcpUrl,
+        ...(demoMcpToken
+          ? { headers: { Authorization: `Bearer ${demoMcpToken}` } }
+          : {})
+      })
+    ]
+  : [];
+
+const environmentSecrets = demoRuntimeSecret
+  ? { DEMO_RUNTIME_SECRET: Secret.value(demoRuntimeSecret) }
+  : undefined;
+
+const proxyEndpoints = [
+  ProxyEndpoint.none({
+    name: "httpbin",
+    baseUrl: "https://httpbin.org",
+    allowMethods: ["GET"],
+    allowPathPrefixes: ["/json"],
+    responseMode: "full",
+    timeoutMs: 10_000
+  })
+];
+
+console.log("creating feature-tour session...");
+console.log(`optional mcp: ${mcpServers.length > 0 ? "enabled" : "disabled"}`);
+console.log(`optional runtime secret: ${environmentSecrets ? "enabled" : "disabled"}`);
+
+const session = await aex.openSession({
+  provider: Providers.DEEPSEEK,
+  model: Models.DEEPSEEK_V4_FLASH,
+  system: [
+    "You are a concise analytics agent.",
+    "Prefer exact calculations and write durable files for the caller."
+  ].join(" "),
+  agentsMd: [runRules],
+  files: [attachedFile],
+  includeBuiltinTools: false,
+  tools: [
+    BuiltinTools.read_file,
+    BuiltinTools.write_file,
+    BuiltinTools.bash,
+    BuiltinTools.grep,
+    BuiltinTools.code_execution,
+    metricLookup
+  ],
+  proxyEndpoints,
+  mcpServers,
+  environment: {
+    networking: { mode: "open" },
+    variables: {
+      FEATURE_TOUR: "true",
+      REPORT_DIR: "/workspace/outputs"
+    },
+    ...(environmentSecrets ? { secrets: environmentSecrets } : {})
+  },
+  outputs: {
+    allowedDirs: ["/workspace/outputs"],
+    deniedDirs: ["*.tmp"],
+    maxFiles: 10,
+    maxFileBytes: 1_000_000
+  },
+  outputMode: "stream",
+  runtime: Sizes.SHARED_0_25X_1GB,
+  metadata: {
+    example: "sdk-feature-tour",
+    sdkSurface: "public"
+  },
+  overrides: {
+    idleTtl: "5m",
+    timeout: "10m",
+    maxSpendUsd: 2
+  },
+  apiKeys: { deepseek: deepseekKey }
+});
+
+console.log(`session: ${session.id}`);
+
+const prompt = [
+  "Analyze the attached quarterly metrics.",
+  "Call metric_lookup for atlas, beacon, and cinder.",
+  "Create /workspace/outputs/feature-tour-report.md with a short table, a ranking by q2_revenue_usd, and two risks.",
+  "Create /workspace/outputs/summary.json with keys topProduct, totalQ2RevenueUsd, highestActivationProduct, and riskCount.",
+  "Mention whether the httpbin proxy endpoint is declared, but do not call it unless you need to."
+].join(" ");
+
+const firstTurn = session.send(prompt);
+const firstTurnIterator = firstTurn[Symbol.asyncIterator]();
+let result: Awaited<ReturnType<typeof firstTurn.done>> | undefined;
+for (;;) {
+  const next = await firstTurnIterator.next();
+  if (next.done) {
+    result = next.value as Awaited<ReturnType<typeof firstTurn.done>>;
+    break;
+  }
+  const event = next.value;
+  if (isTextMessage(event)) {
+    process.stdout.write(event.data.text);
+  } else if (event.type === "TOOL_CALL_START") {
+    const name = typeof event.data.name === "string" ? event.data.name : "tool";
+    process.stdout.write(`\n[tool:start] ${name}\n`);
+  } else if (event.type === "TOOL_CALL_RESULT") {
+    process.stdout.write("[tool:result]\n");
+  }
+}
+
+if (!result) {
+  throw new Error("first turn stream ended without a result");
+}
+console.log(`\nfirst turn parked with status: ${result.status}`);
+
+const followUp = await session
+  .send("Read summary.json back and answer with one sentence confirming the top product and total Q2 revenue.")
+  .done();
+console.log(`follow-up status: ${followUp.status}`);
+if (followUp.text) {
+  console.log(`follow-up text: ${followUp.text.trim()}`);
+}
+
+const parked = await session.wait({ timeoutMs: 60_000, intervalMs: 2_000 });
+console.log(`settled session status: ${parked.status}`);
+
+const messages = await session.messages().list();
+console.log(`assistant messages: ${messages.length}`);
+
+const events = await session.events().list();
+console.log(`captured events: ${events.length}`);
+
+const outputs = await session.outputs().list();
+console.log("outputs:");
+for (const output of outputs) {
+  console.log(`- ${output.filename ?? output.id} (${output.contentType ?? "unknown"})`);
+}
+
+const summary = await session.outputs().read(
+  { path: "summary.json", match: "suffix" },
+  { maxBytes: 20_000 }
+);
+console.log("summary.json:");
+console.log(summary.text);
+
+const report = await session.outputs().findOne({
+  filename: "feature-tour-report.md"
+});
+if (report) {
+  const reportPreview = await session.outputs().read(report, {
+    maxBytes: 4_000,
+    grep: "risk"
+  });
+  console.log("report risk lines:");
+  console.log(reportPreview.text || "(no risk lines found)");
+}
+
+const corpusTools = createCorpusTools(aex, { sessionIds: [session.id] }, { defaultReadBytes: 4_000 });
+const corpusOutputs = await corpusTools.execute("list_outputs", { session_id: session.id });
+console.log("corpus-scoped list_outputs result:");
+console.log(JSON.stringify(corpusOutputs, null, 2));
+
+if (downloadPath) {
+  const bytes = await session.download({ to: downloadPath });
+  console.log(`downloaded session archive: ${downloadPath} (${bytes.byteLength} bytes)`);
+}
+
+function required(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    console.error(`Missing env var ${name}`);
+    process.exit(1);
+  }
+  return value;
+}
+
+function handleFatal(err: unknown): void {
+  if (isRateLimited(err)) {
+    console.error(`rate limited after ${err.attempts} attempts; retry after ${err.retryAfterMs ?? "unknown"}ms`);
+    process.exit(1);
+  }
+  console.error(err instanceof Error ? err.stack ?? err.message : String(err));
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.33.1",
+  "version": "0.35.0",
   "description": "TypeScript SDK for running autonomous agent sessions across providers (Anthropic, OpenAI, DeepSeek, Gemini, Mistral) behind one interface.",
   "license": "Apache-2.0",
   "repository": {