@aexhq/sdk 0.23.0 → 0.25.0

package/README.md

@@ -2,163 +2,74 @@
 title: aex
 ---
 
-# aex
+# @aexhq/sdk
 
-aex is a TypeScript-first SDK + CLI for running autonomous agent sessions across providers through the managed aex service. Everything an agent or human needs is reachable through **one** import and **one** binary.
+aex is an agent execution platform for launching autonomous agents from a simple TypeScript SDK and CLI.
 
-```ts
-import {
-  AgentExecutor,        // the only client class — submits durable runs to aex
-  RunModels,            // closed public model id constants
-  Skill,                // local, URL, and catalog skill bundles normalized to assets
-  McpServer,            // MCP server declarations (headers split into secrets server-side)
-  ProxyEndpoint,        // per-run managed HTTP proxy endpoint
-  AgentsMd,             // AGENTS.md / CLAUDE.md uploads
-  File,                 // arbitrary workspace files mounted into the session
-  validateProxyAuth     // helper that fails fast on policy/auth mismatch
-} from "@aexhq/sdk";
-```
-
-```bash
-aex run     --config ./run.json --api-token ant_… \
-                --anthropic-api-key sk-ant-… --follow
-aex status  <run-id>             --api-token …
-aex wait    <run-id> [--timeout 8m] [--interval 2s] --api-token …
-aex events  <run-id> [--follow] [--timeout 8m]  --api-token …
-aex outputs <run-id>             --api-token …
-aex download <run-id> [--only outputs|events|metadata] [--out path] --api-token …
-aex cancel  <run-id>             --api-token …
-aex delete  <run-id>             --api-token …
-aex whoami                       --api-token …
-aex skills  <upload|list|get|delete> [flags] --api-token …
-aex delete-asset <assetId|hash>  --api-token …
-```
+The package ships:
 
-The SDK class and the CLI are backed by the same public `@aexhq/contracts` operations module — any read or write you can do through one, you can do through the other, against the same durable run records. The same npm package also ships the in-container `aex` CLI as its `bin` entry; managed runs mount that CLI inside the runner so skills can call `aex proxy …` against the per-run manifest. See [product capabilities and boundaries](docs/product-boundaries.md).
+- `AgentExecutor` for submit, run, wait, stream, inspect, download, cancel, and delete.
+- Typed run primitives: `Models`, `Providers`, `RuntimeSizes`, `Skill`, `AgentsMd`, `File`, `McpServer`, `ProxyEndpoint`, and `Secret`.
+- A bundled `aex` CLI with the same run, status, events, outputs, download, cancel, delete, whoami, and skills operations.
 
-The aex URL defaults to `https://api.aex.dev`. Set `--aex-url` on the CLI or `baseUrl` on `AgentExecutor` for local, staging, or hosted aex API planes. This is not a supported self-host deployment claim. The workspace is derived server-side from your API token (1:1 binding), so there is no `--workspace` flag and no `workspaceId` option.
+## Install
 
-## Product boundaries
-
-- Multi-provider via the managed runtime. The published surface is the same
-  regardless of provider:
-  - omit `runtime` or pass `runtime: "managed"`; every provider uses the
-    managed runtime and BYOK provider-proxy.
-  - `provider: "anthropic" | "deepseek" | "openai" | "gemini" | "mistral"`.
-  - See [provider/runtime capabilities](docs/provider-runtime-capabilities.md)
-    for the generated matrix.
-- BYO provider key + MCP credentials + skill references — passed inline on every submission and held in run-scoped custody, with cleanup/revocation attempted at terminal. Cross-provider keys are rejected loudly at submission time.
-- Workspace is the tenant boundary. Workspace identity is derived server-side from the API token (1:1 binding); the SDK / CLI never name it.
-- No SDK-side storage of provider keys, MCP credentials, or output file contents.
-- Cleanup runs by default for tracked runtime resources.
-- Product boundaries are explicit: see [product capabilities and boundaries](docs/product-boundaries.md) for what aex owns, inherits, and does not support.
+```bash
+npm install @aexhq/sdk
+```
 
-## Quickstart (SDK)
+## First Run
 
 ```ts
-import { AgentExecutor, RunModels } from "@aexhq/sdk";
+import { AgentExecutor, Models, Providers } from "@aexhq/sdk";
 
 const aex = new AgentExecutor({
-  apiToken: process.env.AEX_API_TOKEN!,
-  // baseUrl defaults to https://api.aex.dev - set it for local or staging planes.
+  apiToken: process.env.AEX_API_TOKEN!
 });
 
 const runId = await aex.submit({
-  model: RunModels.CLAUDE_HAIKU_4_5,
-  system: "You are a concise automation agent.",
-  prompt: "Write a short answer about agent-first SDK design.",
+  provider: Providers.ANTHROPIC,
+  model: Models.CLAUDE_HAIKU_4_5,
+  prompt: "Write the report and save outputs.",
   secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
 });
 
-const run = await aex.wait(runId);
-console.log(run.status);
-
-for (const output of await aex.outputs(runId)) {
-  console.log(output.id, output.filename);
-}
-
-const report = await aex.downloadOutput(runId, { path: "report.txt", match: "suffix" });
-console.log(new TextDecoder().decode(report));
-
-await aex.downloadOutputs(runId, { to: "./outputs.zip" });
-```
-
-Reusable, credential-free configs can be ordinary functions:
-
-```ts
-function summarise(topic: string) {
-  return {
-    model: RunModels.CLAUDE_HAIKU_4_5,
-    system: "You are a concise automation agent.",
-    prompt: `Write a short answer about ${topic}.`
-  };
+for await (const event of aex.stream(runId)) {
+  console.log(event.type);
 }
 
-const runId = await aex.submit({
-  ...summarise("agent-first SDK design"),
-  secrets: { apiKey: process.env.ANTHROPIC_API_KEY! }
-});
-```
-
-Stream events live with `aex.stream(runId)`:
+const run = await aex.wait(runId);
+console.log(run.status);
 
-```ts
-for await (const event of aex.stream(runId)) {
-  if (event.type === "TEXT_MESSAGE_CONTENT") {
-    // typed event helpers live under `aex`'s event guard exports.
-  }
-}
+await aex.download(runId, { to: "./run.zip" });
 ```
 
-The same flow from the CLI (two equivalent forms):
+The same request can run from the CLI:
 
 ```bash
 aex run \
   --api-token "$AEX_API_TOKEN" \
   --anthropic-api-key "$ANTHROPIC_API_KEY" \
   --model claude-haiku-4-5 \
-  --system "You are a concise automation agent." \
-  --prompt "Write a short answer about agent-first SDK design." \
-  --follow
-
-aex run \
-  --api-token "$AEX_API_TOKEN" \
-  --anthropic-api-key "$ANTHROPIC_API_KEY" \
-  --config ./run.json \
+  --prompt "Write the report and save outputs." \
   --follow
 ```
 
-`--config` accepts a plain run-config JSON file for a single run request: `{ model, system?, prompt, skills?, mcpServers?, environment?, runtimeSize?, timeout?, postHook?, proxyEndpoints?, metadata? }`. There is no saved-definition product or interpolation DSL — build the JSON at the call site. SDK code should use `RunModels`; config JSON is validated against the same `RUN_MODELS` allowlist.
+## Feature Areas
 
-Runtime controls: omit `builtins` to use the default `["developer"]` toolkit, pass `builtins: []` to disable builtins for a pure-MCP run, use `outputMode: "stream"` for per-token assistant text, prefer `RuntimeSizes` for `runtimeSize`, and use `postHook` to run a verifier command after the agent exits successfully.
+- **Agent runtime:** managed autonomous runs with shell, filesystem, editing, notebook, web fetch/search, background command, and post-hook repair tools.
+- **Durable infrastructure:** run records, status, wait/cancel/delete, idempotency, typed events, output capture, downloads, timeouts, and runtime sizes.
+- **Agent composition:** skills, files, AGENTS.md, remote MCP servers, proxy endpoints, environment variables, packages, and networking controls.
+- **Subagents:** typed parent/child lineage for async child runs, output handoff, and bounded agent delegation.
+- **Models and providers:** Anthropic, DeepSeek, OpenAI, Gemini, Mistral, OpenRouter, Doubao, and Doubao China behind one submission shape.
+- **Typed control surface:** strongly typed SDK inputs, CLI parity, BYOK secrets, scoped proxy auth, redaction, and output modes.
 
-## Test commands
-
-```text
-pnpm test                # unit (deterministic; uses fakes/snapshots)
-pnpm test:user:offline   # clean install of packed/published SDK, no live API
-pnpm test:user           # live hosted API user tests
-pnpm test:user:heavy     # explicit heavy live canary
-```
-
-User tests auto-pack the current SDK when no artifact env is set. CI can pin a
-specific artifact with exactly one of `AEX_USER_TEST_TARBALL` or
-`AEX_USER_TEST_VERSION`; live runs also need `AEX_API_URL`,
-`AEX_API_TOKEN`, and `DEEPSEEK_API_KEY`.
-
-## Guides
+## Docs
 
 - [Quickstart](docs/quickstart.md)
-- [Run config](docs/run-config.md)
-- [Run record](docs/run-record.md)
-- [Product capabilities and boundaries](docs/product-boundaries.md)
+- [Run configuration](docs/run-config.md)
+- [Agent tools](docs/concepts/agent-tools.md)
+- [Composition](docs/concepts/composition.md)
+- [Secrets](docs/secrets.md)
+- [Limits](docs/limits.md)
 - [Provider/runtime capabilities](docs/provider-runtime-capabilities.md)
-- [Credentials](docs/credentials.md)
-- [MCP](docs/mcp.md)
-- [Skills](docs/skills.md)
-- [Outputs](docs/outputs.md)
-- [Events](docs/events.md)
-- [Cleanup](docs/cleanup.md)
-- [Testing](docs/testing.md)
-- [Release](docs/release.md)
-

package/dist/_contracts/models.js

@@ -37,8 +37,7 @@ export const MODEL_PROVIDER_IDS = {
     // China Volcengine Ark gateway (`doubao-cn`). Ark accepts the API-format
     // model NAME directly in the chat-completions `model` field (no `ep-…`
     // inference-endpoint id). The native strings are the same Ark catalog ids on
-    // both gateways; BytePlus per-account availability is confirmed at live-verify
-    // (both providers ship `live-unverified` until then — provider-support.ts).
+    // both gateways.
     //   pro   — Doubao Seed 1.8 (flagship, 256K context).
     //   flash — Doubao Seed 1.6 Flash (fast/cheap, 256K context).
     "doubao-seed-pro": { doubao: "doubao-seed-1-8-251228", "doubao-cn": "doubao-seed-1-8-251228" },

package/dist/_contracts/operations.d.ts

@@ -215,8 +215,8 @@ export declare function createSecret(http: HttpClient, args: {
 export declare function listSecrets(http: HttpClient): Promise<readonly SecretRecord[]>;
 /** Metadata for one workspace secret by name. Never returns the value. */
 export declare function getSecret(http: HttpClient, name: string): Promise<SecretRecord>;
-/** Audited value read — the only path that returns a workspace secret value. */
-export declare function revealSecret(http: HttpClient, name: string): Promise<SecretReveal>;
+/** Audited value read — the preferred path that returns a workspace secret value. */
+export declare function getSecretValue(http: HttpClient, name: string): Promise<SecretReveal>;
 /** Replace the value of an existing workspace secret; bumps its version. */
 export declare function rotateSecret(http: HttpClient, args: {
     readonly name: string;

package/dist/_contracts/operations.js

@@ -547,7 +547,7 @@ function unwrapFile(result) {
 // Value-bearing requests (create/rotate) carry the value in the JSON BODY,
 // never the URL/query, so it never lands in logs or the request line. Reads
 // split by sensitivity: `getSecret`/`listSecrets` return METADATA only;
-// `revealSecret` is the audited value read (POST so it's a logged action).
+// `getSecretValue` is the audited value read (POST so it's a logged action).
 // ===========================================================================
 /** Create a named workspace secret. The value travels in the body. */
 export async function createSecret(http, args) {
@@ -569,9 +569,9 @@ export async function getSecret(http, name) {
     const result = await http.request(`/api/secrets/${encodeURIComponent(name)}`);
     return unwrapSecret(result);
 }
-/** Audited value read — the only path that returns a workspace secret value. */
-export async function revealSecret(http, name) {
-    return http.request(`/api/secrets/${encodeURIComponent(name)}/reveal`, {
+/** Audited value read — the preferred path that returns a workspace secret value. */
+export async function getSecretValue(http, name) {
+    return http.request(`/api/secrets/${encodeURIComponent(name)}/get_value`, {
         method: "POST"
     });
 }

package/dist/_contracts/provider-support.d.ts

@@ -1,5 +1,5 @@
 import type { RunProvider, RuntimeKind } from "./submission.js";
-export declare const PROVIDER_SUPPORT_STATUSES: readonly ["supported", "live-unverified", "rejected"];
+export declare const PROVIDER_SUPPORT_STATUSES: readonly ["supported", "rejected"];
 export type ProviderSupportStatus = (typeof PROVIDER_SUPPORT_STATUSES)[number];
 export interface SupportPointer {
     readonly label: string;
@@ -45,8 +45,8 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
         readonly status: "supported";
         readonly docsAnchor: "anthropic";
         readonly docs: readonly [{
-            readonly label: "Credentials";
-            readonly href: "credentials.md";
+            readonly label: "Secrets";
+            readonly href: "secrets.md";
         }, {
             readonly label: "Events";
             readonly href: "events.md";
@@ -82,8 +82,8 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
         readonly status: "supported";
         readonly docsAnchor: "deepseek";
         readonly docs: readonly [{
-            readonly label: "Credentials";
-            readonly href: "credentials.md";
+            readonly label: "Secrets";
+            readonly href: "secrets.md";
         }, {
             readonly label: "Events";
             readonly href: "events.md";
@@ -122,11 +122,11 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
     };
     readonly openai: {
         readonly displayName: "OpenAI";
-        readonly status: "live-unverified";
+        readonly status: "supported";
         readonly docsAnchor: "openai";
         readonly docs: readonly [{
-            readonly label: "Credentials";
-            readonly href: "credentials.md";
+            readonly label: "Secrets";
+            readonly href: "secrets.md";
         }, {
             readonly label: "Events";
             readonly href: "events.md";
@@ -156,11 +156,11 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
     };
     readonly gemini: {
         readonly displayName: "Gemini";
-        readonly status: "live-unverified";
+        readonly status: "supported";
         readonly docsAnchor: "gemini";
         readonly docs: readonly [{
-            readonly label: "Credentials";
-            readonly href: "credentials.md";
+            readonly label: "Secrets";
+            readonly href: "secrets.md";
         }, {
             readonly label: "Events";
             readonly href: "events.md";
@@ -190,11 +190,11 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
     };
     readonly mistral: {
         readonly displayName: "Mistral";
-        readonly status: "live-unverified";
+        readonly status: "supported";
         readonly docsAnchor: "mistral";
         readonly docs: readonly [{
-            readonly label: "Credentials";
-            readonly href: "credentials.md";
+            readonly label: "Secrets";
+            readonly href: "secrets.md";
         }, {
             readonly label: "Events";
             readonly href: "events.md";
@@ -224,11 +224,11 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
     };
     readonly openrouter: {
         readonly displayName: "OpenRouter";
-        readonly status: "live-unverified";
+        readonly status: "supported";
         readonly docsAnchor: "openrouter";
         readonly docs: readonly [{
-            readonly label: "Credentials";
-            readonly href: "credentials.md";
+            readonly label: "Secrets";
+            readonly href: "secrets.md";
         }, {
             readonly label: "Events";
             readonly href: "events.md";
@@ -258,11 +258,11 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
     };
     readonly doubao: {
         readonly displayName: "Doubao";
-        readonly status: "live-unverified";
+        readonly status: "supported";
         readonly docsAnchor: "doubao";
         readonly docs: readonly [{
-            readonly label: "Credentials";
-            readonly href: "credentials.md";
+            readonly label: "Secrets";
+            readonly href: "secrets.md";
         }, {
             readonly label: "Events";
             readonly href: "events.md";
@@ -292,11 +292,11 @@ export declare const PROVIDER_PUBLIC_SUPPORT: {
     };
     readonly "doubao-cn": {
         readonly displayName: "Doubao (China)";
-        readonly status: "live-unverified";
+        readonly status: "supported";
         readonly docsAnchor: "doubao-cn";
         readonly docs: readonly [{
-            readonly label: "Credentials";
-            readonly href: "credentials.md";
+            readonly label: "Secrets";
+            readonly href: "secrets.md";
         }, {
             readonly label: "Events";
             readonly href: "events.md";

package/dist/_contracts/provider-support.js

@@ -1,10 +1,9 @@
 export const PROVIDER_SUPPORT_STATUSES = [
     "supported",
-    "live-unverified",
     "rejected"
 ];
 const COMMON_DOCS = [
-    { label: "Credentials", href: "credentials.md" },
+    { label: "Secrets", href: "secrets.md" },
     { label: "Events", href: "events.md" }
 ];
 const COMMON_EVIDENCE = [
@@ -72,7 +71,7 @@ export const PROVIDER_PUBLIC_SUPPORT = {
     },
     openai: {
         displayName: "OpenAI",
-        status: "live-unverified",
+        status: "supported",
         docsAnchor: "openai",
         docs: COMMON_DOCS,
         evidence: COMMON_EVIDENCE,
@@ -82,7 +81,7 @@ export const PROVIDER_PUBLIC_SUPPORT = {
     },
     gemini: {
         displayName: "Gemini",
-        status: "live-unverified",
+        status: "supported",
         docsAnchor: "gemini",
         docs: COMMON_DOCS,
         evidence: COMMON_EVIDENCE,
@@ -92,7 +91,7 @@ export const PROVIDER_PUBLIC_SUPPORT = {
     },
     mistral: {
         displayName: "Mistral",
-        status: "live-unverified",
+        status: "supported",
         docsAnchor: "mistral",
         docs: COMMON_DOCS,
         evidence: COMMON_EVIDENCE,
@@ -102,7 +101,7 @@ export const PROVIDER_PUBLIC_SUPPORT = {
     },
     openrouter: {
         displayName: "OpenRouter",
-        status: "live-unverified",
+        status: "supported",
         docsAnchor: "openrouter",
         docs: COMMON_DOCS,
         evidence: COMMON_EVIDENCE,
@@ -111,13 +110,9 @@ export const PROVIDER_PUBLIC_SUPPORT = {
         }
     },
     // Doubao (ByteDance) via the official Ark API — international BytePlus gateway.
-    // Wired + parser/routing-verified but not yet proven against a live BytePlus
-    // account, so `live-unverified`. Promote to `supported` (and swap COMMON_EVIDENCE
-    // for a DOUBAO_MANAGED_EVIDENCE pointer to live-sdk-doubao.test.ts) once the
-    // live run passes.
     doubao: {
         displayName: "Doubao",
-        status: "live-unverified",
+        status: "supported",
         docsAnchor: "doubao",
         docs: COMMON_DOCS,
         evidence: COMMON_EVIDENCE,
@@ -126,11 +121,9 @@ export const PROVIDER_PUBLIC_SUPPORT = {
         }
     },
     // Doubao (ByteDance) via the official Ark API — China Volcengine gateway.
-    // Same wiring as `doubao`; additionally gated on CF Worker egress reaching the
-    // Beijing host (see apps/egress-probe). `live-unverified` until proven live.
     "doubao-cn": {
         displayName: "Doubao (China)",
-        status: "live-unverified",
+        status: "supported",
         docsAnchor: "doubao-cn",
         docs: COMMON_DOCS,
         evidence: COMMON_EVIDENCE,

package/dist/_contracts/run-config.d.ts

@@ -47,6 +47,12 @@ export declare const SKILL_ID_PATTERN: RegExp;
  * surface so callers fail at the boundary rather than in the BFF.
  */
 export declare const SKILL_NAME_PATTERN: RegExp;
+/**
+ * Provider-safe submitted tool name. Tool names share the same lowercase
+ * kebab/underscore envelope as skills. Submission parsing rejects `__`
+ * because SessionDO reserves that separator for MCP namespace routing.
+ */
+export declare const TOOL_NAME_PATTERN: RegExp;
 /**
  * Hard caps applied at upload time. The SDK enforces these before
  * computing the zip hash so a clearly-too-big bundle never wastes
@@ -87,6 +93,23 @@ export interface AssetRef {
     readonly name: string;
     readonly mountPath?: string;
 }
+type ToolJsonPrimitive = string | number | boolean | null;
+type ToolJsonValue = ToolJsonPrimitive | ToolJsonValue[] | {
+    readonly [key: string]: ToolJsonValue;
+};
+export type ToolInputSchema = {
+    readonly [key: string]: ToolJsonValue;
+};
+/**
+ * User-supplied executable tool bundle. The bytes are addressed by the same
+ * content-addressed asset ref used by Skills/Files, while the provider-visible
+ * manifest rides as value-free metadata on the submission.
+ */
+export interface ToolRef extends AssetRef {
+    readonly description: string;
+    readonly input_schema: ToolInputSchema;
+    readonly entry: string;
+}
 export interface ProviderSkillRef {
     readonly kind: "provider";
     readonly vendor: "anthropic" | "custom";
@@ -330,3 +353,4 @@ export interface NormalisedRunRequestConfig {
     }>;
 }
 export declare function normaliseRunRequestConfig(config: RunRequestConfig): NormalisedRunRequestConfig;
+export {};

package/dist/_contracts/run-config.js

@@ -48,6 +48,12 @@ export const SKILL_ID_PATTERN = /^skl_[A-Za-z0-9_-]{8,128}$/;
  * surface so callers fail at the boundary rather than in the BFF.
  */
 export const SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,127}$/;
+/**
+ * Provider-safe submitted tool name. Tool names share the same lowercase
+ * kebab/underscore envelope as skills. Submission parsing rejects `__`
+ * because SessionDO reserves that separator for MCP namespace routing.
+ */
+export const TOOL_NAME_PATTERN = SKILL_NAME_PATTERN;
 // ---------------------------------------------------------------------------
 // Skill bundle limits (uploaded bundles)
 // ---------------------------------------------------------------------------

package/dist/_contracts/run-trace.d.ts

@@ -13,9 +13,10 @@
  * a result with no matching start surfaces as an orphan (never dropped silently),
  * and timing falls back gracefully when a `recordedAt` is absent.
  *
- * Pairs with {@link Run.usage}: while a run executes `Run.usage` is empty — the
- * per-turn token counts live ONLY in the `aex.usage` CUSTOM events — so
- * {@link summarizeRunUsage} reconstructs the running total from the same stream.
+ * `summarizeRunUsage` remains tolerant of historical/internal `aex.usage`
+ * CUSTOM records when a caller has them, but the normal public `listEvents`
+ * stream is not the live usage-reporting surface. Settled provider/runtime
+ * usage is exposed through the run's `costTelemetry`.
  */
 import type { UsageSummary } from "./runtime-types.js";
 /**
@@ -89,8 +90,9 @@ interface TraceEvent {
  */
 export declare function decodeToolCalls(events: readonly TraceEvent[]): readonly ToolCallTrace[];
 /**
- * Sum the per-turn `aex.usage` CUSTOM events into one {@link UsageSummary} —
- * the running token total a customer otherwise hand-sums while watching a run.
+ * Sum any `aex.usage` CUSTOM events present in the supplied stream into one
+ * {@link UsageSummary}. This is mainly for historical/internal event arrays;
+ * current public reads expose settled provider usage through cost telemetry.
  * `totalTokens` is the sum of input + output tokens. Pure.
  */
 export declare function summarizeRunUsage(events: readonly TraceEvent[]): UsageSummary;

package/dist/_contracts/run-trace.js

@@ -13,9 +13,10 @@
  * a result with no matching start surfaces as an orphan (never dropped silently),
  * and timing falls back gracefully when a `recordedAt` is absent.
  *
- * Pairs with {@link Run.usage}: while a run executes `Run.usage` is empty — the
- * per-turn token counts live ONLY in the `aex.usage` CUSTOM events — so
- * {@link summarizeRunUsage} reconstructs the running total from the same stream.
+ * `summarizeRunUsage` remains tolerant of historical/internal `aex.usage`
+ * CUSTOM records when a caller has them, but the normal public `listEvents`
+ * stream is not the live usage-reporting surface. Settled provider/runtime
+ * usage is exposed through the run's `costTelemetry`.
  */
 const CUSTOM_USAGE_NAME = "aex.usage";
 /** snake_case `aex.usage` field → the camelCase {@link UsageSummary} field. */
@@ -89,8 +90,9 @@ export function decodeToolCalls(events) {
     return order.map((id) => byId.get(id));
 }
 /**
- * Sum the per-turn `aex.usage` CUSTOM events into one {@link UsageSummary} —
- * the running token total a customer otherwise hand-sums while watching a run.
+ * Sum any `aex.usage` CUSTOM events present in the supplied stream into one
+ * {@link UsageSummary}. This is mainly for historical/internal event arrays;
+ * current public reads expose settled provider usage through cost telemetry.
  * `totalTokens` is the sum of input + output tokens. Pure.
  */
 export function summarizeRunUsage(events) {

package/dist/_contracts/run-unit.js

@@ -52,6 +52,10 @@ function parseFlatProjection(value) {
     const outputsRaw = isRecord(submissionRaw.outputs) ? submissionRaw.outputs : {};
     const allowedDirs = toOptionalStringArray(outputsRaw.allowedDirs);
     const deniedDirs = toOptionalStringArray(outputsRaw.deniedDirs);
+    const captureTimeoutMs = toOptionalPositiveInteger(outputsRaw.captureTimeoutMs);
+    const maxFileBytes = toOptionalPositiveInteger(outputsRaw.maxFileBytes);
+    const maxTotalBytes = toOptionalPositiveInteger(outputsRaw.maxTotalBytes);
+    const maxFiles = toOptionalPositiveInteger(outputsRaw.maxFiles);
     const submission = {
         model: coerceRunUnitModel(submissionRaw.model),
         ...(typeof submissionRaw.system === "string" ? { system: submissionRaw.system } : {}),
@@ -60,6 +64,7 @@ function parseFlatProjection(value) {
         agentsMd: [],
         files: [],
         mcpServers: toMcpServerRefArray(submissionRaw.mcpServers),
+        tools: [],
         ...(parseEnvironment(submissionRaw.environment)
             ? { environment: parseEnvironment(submissionRaw.environment) }
             : {}),
@@ -67,11 +72,20 @@ function parseFlatProjection(value) {
             ? { securityProfile: parseSecurityProfile(submissionRaw.securityProfile) }
             : {}),
         ...(isJsonRecord(submissionRaw.metadata) ? { metadata: submissionRaw.metadata } : {}),
-        ...(allowedDirs || deniedDirs
+        ...(allowedDirs ||
+            deniedDirs ||
+            captureTimeoutMs !== undefined ||
+            maxFileBytes !== undefined ||
+            maxTotalBytes !== undefined ||
+            maxFiles !== undefined
             ? {
                 outputs: {
                     ...(allowedDirs ? { allowedDirs } : {}),
-                    ...(deniedDirs ? { deniedDirs } : {})
+                    ...(deniedDirs ? { deniedDirs } : {}),
+                    ...(captureTimeoutMs !== undefined ? { captureTimeoutMs } : {}),
+                    ...(maxFileBytes !== undefined ? { maxFileBytes } : {}),
+                    ...(maxTotalBytes !== undefined ? { maxTotalBytes } : {}),
+                    ...(maxFiles !== undefined ? { maxFiles } : {})
                 }
             }
             : {})
@@ -84,6 +98,9 @@ function parseFlatProjection(value) {
 function parseSecurityProfile(value) {
     return value === "strict" || value === "standard" || value === "developer" ? value : undefined;
 }
+function toOptionalPositiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}
 function fallbackFlat() {
     return {
         kind: "submission",
@@ -93,7 +110,8 @@ function fallbackFlat() {
             skills: [],
             agentsMd: [],
             files: [],
-            mcpServers: []
+            mcpServers: [],
+            tools: []
         }
     };
 }

package/dist/_contracts/runtime-types.d.ts

@@ -27,12 +27,11 @@ export interface Run {
     readonly startedAt?: string;
     readonly errorMessage?: string | null;
     /**
-     * Aggregate token usage. NOTE: mid-run this is NOT populated — detailed
-     * token counts live ONLY in the per-turn `aex.usage` CUSTOM events on the
-     * event stream until the run settles. To follow token/cost progress while a
-     * run executes, decode the event stream with `summarizeRunTrace(events)`
-     * (its `usage` totals the `aex.usage` events). Settled cost/usage rides
-     * {@link costTelemetry}.
+     * Aggregate token usage when a deployment chooses to expose it on the run
+     * record. Mid-run this is not populated. Settled provider/runtime usage is
+     * exposed through {@link costTelemetry}; per-turn usage breadcrumbs, when a
+     * deployment records them internally, are not part of the normal public event
+     * stream.
      */
     readonly usage?: UsageSummary;
     readonly costTelemetry?: import("./run-cost.js").RunCostTelemetry;
@@ -251,8 +250,8 @@ export interface SecretRecord {
     readonly [key: string]: unknown;
 }
 /**
- * Value-bearing result of an audited `aex.secrets.reveal`. The ONLY wire shape
- * that carries a workspace secret value back to the caller. Reveal is a logged
+ * Value-bearing result of an audited `aex.secrets.get_value`. The ONLY wire shape
+ * that carries a workspace secret value back to the caller. Value read is a logged
  * action (POST, not GET) so a value read is always attributable.
  */
 export interface SecretReveal {