@aexhq/sdk 0.46.5-canary → 0.50.0

package/dist/submission-wire.js

@@ -1,69 +0,0 @@
-import { McpServer } from "./mcp-server.js";
-import { configError } from "./session-validate.js";
-export function fileCaptureForWire(fileCapture) {
-    if (fileCapture === undefined) {
-        return undefined;
-    }
-    const allowedDirs = fileCapture.allowedDirs?.filter((dir) => dir.length > 0);
-    const deniedDirs = fileCapture.deniedDirs?.filter((dir) => dir.length > 0);
-    const hasNumericOverride = fileCapture.captureTimeoutMs !== undefined ||
-        fileCapture.maxFileBytes !== undefined ||
-        fileCapture.maxTotalBytes !== undefined ||
-        fileCapture.maxFiles !== undefined;
-    if ((allowedDirs?.length ?? 0) === 0 && (deniedDirs?.length ?? 0) === 0 && !hasNumericOverride) {
-        return undefined;
-    }
-    return {
-        ...(allowedDirs && allowedDirs.length > 0 ? { allowedDirs } : {}),
-        ...(deniedDirs && deniedDirs.length > 0 ? { deniedDirs } : {}),
-        ...(fileCapture.captureTimeoutMs !== undefined ? { captureTimeoutMs: fileCapture.captureTimeoutMs } : {}),
-        ...(fileCapture.maxFileBytes !== undefined ? { maxFileBytes: fileCapture.maxFileBytes } : {}),
-        ...(fileCapture.maxTotalBytes !== undefined ? { maxTotalBytes: fileCapture.maxTotalBytes } : {}),
-        ...(fileCapture.maxFiles !== undefined ? { maxFiles: fileCapture.maxFiles } : {})
-    };
-}
-const DEFAULT_SESSION_IDLE_TTL = "3m";
-export function sessionRetentionForWire(options) {
-    return {
-        idleTtl: options.overrides?.idleTtl ?? DEFAULT_SESSION_IDLE_TTL
-    };
-}
-export function sessionEnvironmentForWire(environment) {
-    if (environment === undefined) {
-        return undefined;
-    }
-    const { variables, secrets: _secrets, ...rest } = environment;
-    void _secrets;
-    const out = {
-        ...rest,
-        ...(variables !== undefined ? { envVars: variables } : {})
-    };
-    return Object.keys(out).length === 0 ? undefined : out;
-}
-export function mergeMcpServers(inputs, explicitSecrets) {
-    const submissionMcpServers = [];
-    const secretByName = new Map();
-    for (const secret of explicitSecrets) {
-        secretByName.set(secret.name, secret);
-    }
-    for (let i = 0; i < inputs.length; i++) {
-        const entry = inputs[i];
-        if (!(entry instanceof McpServer)) {
-            throw configError("aex", `mcpServers[${i}]`, `mcpServers[${i}] must be an McpServer instance`);
-        }
-        submissionMcpServers.push(entry.toSubmissionEntry());
-        const secret = entry.toSecretEntry();
-        if (secret) {
-            const existing = secretByName.get(secret.name);
-            if (existing && existing.url !== secret.url) {
-                throw configError("aex", `mcpServers[${i}].url`, `mcpServers[${i}].url conflicts with another MCP declaration`);
-            }
-            secretByName.set(secret.name, secret);
-        }
-    }
-    return {
-        submissionMcpServers,
-        mergedMcpSecrets: Array.from(secretByName.values())
-    };
-}
-//# sourceMappingURL=submission-wire.js.map

package/dist/submission-wire.js.map

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

package/dist/tool.d.ts

@@ -1,41 +0,0 @@
-import { type ToolInputSchema, type ToolRef } from "./_contracts/index.js";
-import { type BundleMeta, type SkillFiles } from "./bundle.js";
-import type { IgnoreOptions } from "./node-walk.js";
-export interface ToolManifestInput {
-    readonly name: string;
-    readonly description: string;
-    readonly inputSchema?: ToolInputSchema;
-    readonly input_schema?: ToolInputSchema;
-    readonly entry: string;
-}
-export declare class Tool {
-    #private;
-    private constructor();
-    get ref(): DraftToolRef;
-    get isDraft(): boolean;
-    static fromFiles(args: ToolManifestInput & {
-        readonly files: SkillFiles;
-        readonly meta?: BundleMeta;
-    }): Promise<Tool>;
-    /**
-     * Read a local tool bundle directory (`tool.json` at its root + support files).
-     * The directory is walked with FIDELITY (the same walk `File.fromPath` uses):
-     * `.aexignore` + the always-on defaults (`.git/`, `node_modules/`, …) prune the
-     * upload, and executable bits + symlinks are captured into a `.aexmeta.json`
-     * sidecar (emitted only when such metadata exists, so a pure-content tool dir
-     * stays byte-identical → dedup continuity). Bun/Node filesystem runtimes only.
-     */
-    static fromPath(rootDir: string, args?: {
-        readonly ignore?: IgnoreOptions;
-    }): Promise<Tool>;
-    _takeDraftBundle(): {
-        ref: ToolRef;
-        contentHash: string;
-        bytes: Uint8Array;
-    };
-    toJSON(): never;
-}
-export interface DraftToolRef extends Omit<ToolRef, "kind"> {
-    readonly kind: "draft";
-    readonly contentHash: string;
-}

package/dist/tool.js

@@ -1,76 +0,0 @@
-import { normalizeToolManifest } from "./_contracts/internal.js";
-import { bundleToolFiles, hashSkillBundle } from "./bundle.js";
-import { readDirectoryWithFidelity } from "./node-fs.js";
-export class Tool {
-    #ref;
-    #inlineBytes;
-    constructor(ref, inlineBytes) {
-        this.#ref = ref;
-        this.#inlineBytes = inlineBytes;
-    }
-    get ref() {
-        return this.#ref;
-    }
-    get isDraft() {
-        return true;
-    }
-    static async fromFiles(args) {
-        if (!args || typeof args !== "object") {
-            throw new Error("Tool.fromFiles: args is required");
-        }
-        const manifest = normalizeToolManifest("Tool.fromFiles", args, args.files);
-        const bundled = bundleToolFiles(args.files, manifest, args.meta);
-        const contentHash = await hashSkillBundle(bundled.zip);
-        const ref = {
-            kind: "draft",
-            assetId: `asset_${contentHash.slice("sha256:".length)}`,
-            contentHash,
-            ...manifest
-        };
-        return new Tool(ref, bundled.zip);
-    }
-    /**
-     * Read a local tool bundle directory (`tool.json` at its root + support files).
-     * The directory is walked with FIDELITY (the same walk `File.fromPath` uses):
-     * `.aexignore` + the always-on defaults (`.git/`, `node_modules/`, …) prune the
-     * upload, and executable bits + symlinks are captured into a `.aexmeta.json`
-     * sidecar (emitted only when such metadata exists, so a pure-content tool dir
-     * stays byte-identical → dedup continuity). Bun/Node filesystem runtimes only.
-     */
-    static async fromPath(rootDir, args) {
-        const { files, meta } = await readDirectoryWithFidelity(rootDir, args?.ignore);
-        const rawManifest = files["tool.json"];
-        if (rawManifest === undefined) {
-            throw new Error('Tool.fromPath: tool.json is required at the tool bundle root');
-        }
-        const text = typeof rawManifest === "string" ? rawManifest : new TextDecoder().decode(rawManifest);
-        let parsed;
-        try {
-            parsed = JSON.parse(text);
-        }
-        catch (err) {
-            throw new Error(`Tool.fromPath: tool.json is not valid JSON: ${err.message}`);
-        }
-        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-            throw new Error("Tool.fromPath: tool.json must be an object");
-        }
-        const { ["tool.json"]: _manifest, ...bundleFiles } = files;
-        return Tool.fromFiles({
-            ...parsed,
-            files: bundleFiles,
-            meta
-        });
-    }
-    _takeDraftBundle() {
-        const { kind: _kind, contentHash, ...ref } = this.#ref;
-        return {
-            ref: { kind: "asset", ...ref },
-            contentHash,
-            bytes: this.#inlineBytes
-        };
-    }
-    toJSON() {
-        throw new Error("Tool drafts cannot be submitted directly; publish with aex.workspace.tools.publish(...)");
-    }
-}
-//# sourceMappingURL=tool.js.map

package/dist/tool.js.map

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

package/dist/version.d.ts

@@ -1,9 +0,0 @@
-/**
- * Single source of truth for the SDK version exposed at runtime.
- *
- * Must match `packages/sdk/package.json`'s `version` field — a unit
- * test asserts this. Bump both on every release.
- *
- * Used by the (future) User-Agent header on outbound SDK requests.
- */
-export declare const SDK_VERSION = "0.46.5-canary";

package/dist/version.js

@@ -1,10 +0,0 @@
-/**
- * Single source of truth for the SDK version exposed at runtime.
- *
- * Must match `packages/sdk/package.json`'s `version` field — a unit
- * test asserts this. Bump both on every release.
- *
- * Used by the (future) User-Agent header on outbound SDK requests.
- */
-export const SDK_VERSION = "0.46.5-canary";
-//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,eAAe,CAAC"}

package/docs/authentication.md

@@ -1,125 +0,0 @@
----
-title: Authentication
----
-
-# Authentication
-
-Every SDK and CLI call authenticates with an **aex API key**: a bearer
-credential that is **workspace-scoped** — the workspace is derived server-side
-from the token, so there is no workspace parameter anywhere in the API. A
-request either carries a valid token for a workspace or it is rejected with
-`401 unauthorized` (see [Errors](errors.md)).
-
-## Getting a token (invite-only beta)
-
-aex is currently in **invite-only beta**. Workspaces and their initial API
-tokens are provisioned by the aex team — contact <support@aex.dev> for beta
-access. Once your workspace exists, you can create and delete additional tokens
-in the dashboard at <https://aex.dev>.
-
-## Using a token
-
-Pass the token to the SDK constructor, the CLI's `--api-key` flag, or persist
-it once with `aex login`:
-
-```ts
-import { Aex } from "@aexhq/sdk";
-
-const aex = new Aex(process.env.AEX_API_KEY!);
-```
-
-```bash
-npx aex whoami --api-key "$AEX_API_KEY"
-
-# or persist it once, then omit --api-key on later commands:
-npx aex login --api-key "$AEX_API_KEY"
-npx aex whoami
-```
-
-(`new Aex(apiKey)` is the canonical constructor; the equivalent options form is
-documented once in [Credentials](credentials.md).)
-
-The token travels as a standard `Authorization: Bearer` header. Treat it like
-any other secret: keep it in environment variables or a secret manager, never
-in session config, prompts, or committed files.
-
-## Plane routing and the `baseUrl` guard
-
-An aex API key is **self-describing**: it embeds the plane (`dev` / `prd`) and
-region it was minted for. The constructor parses the key and routes accordingly,
-with **zero network**:
-
-- **Omit `baseUrl`** and the key routes to its canonical hosted API plane:
-  `prd` keys route to `https://api.aex.dev`, and `dev` keys route to
-  `https://dev-api.aex.dev`.
-- **Supply a `baseUrl` whose plane disagrees with the key** (e.g. a `dev` key
-  pointed at `https://api.aex.dev`) and the constructor throws
-  `CredentialValidationError` **before any request** — you no longer discover the
-  mismatch as a late `401 token_invalid` after a full round-trip.
-
-```ts
-// prd key → routes to https://api.aex.dev automatically:
-const prd = new Aex(process.env.AEX_PRD_KEY!);
-
-// dev key → routes to https://dev-api.aex.dev automatically:
-const dev = new Aex(process.env.AEX_DEV_KEY!);
-```
-
-## Scopes
-
-A token carries a set of **scopes**; every API route requires one, and a token
-that lacks the route's scope fails with `403 insufficient_scope` naming the
-missing scope. The customer-grantable scopes:
-
-| Scope | Grants |
-| --- | --- |
-| `sessions:read` | Read sessions, their events and event archives, and webhook delivery ledgers. |
-| `sessions:write` | Create sessions, send messages, suspend/resume, redeliver webhooks, reveal the webhook signing secret. |
-| `sessions:cancel` | Cancel a session/run. |
-| `sessions:delete` | Delete a session and its record. |
-| `files:read` | Read captured session files and reusable workspace-file metadata. |
-| `files:write` / `files:delete` | Publish and delete reusable workspace-file resources. |
-| `assets:write` | Upload content-addressed bytes before publishing a typed workspace resource. |
-| `assets:delete` | Delete unreferenced content-addressed bytes. |
-| `skills:read` / `skills:write` / `skills:delete` | Administer workspace skills. |
-| `tools:read` / `tools:write` / `tools:delete` | Administer workspace custom tools. |
-| `instructions:read` / `instructions:write` / `instructions:delete` | Administer workspace instructions. |
-| `secrets:read` | List workspace secrets and read their metadata (never values). |
-| `secrets:write` | Create, rotate, and delete workspace secrets. |
-| `mcp:read` | List and read workspace MCP server configurations. |
-| `mcp:write` | Create workspace MCP server configurations. |
-| `mcp:delete` | Delete workspace MCP server configurations. |
-| `billing:read` | Read billing state and create hosted billing sessions. |
-| `workspaces:delete` | Owner self-service workspace hard-erase. |
-
-A typical automation token carries `sessions:read`, `sessions:write`, and
-`files:read`, plus the resource scopes it publishes. Grant the rest only where the workload needs them — a read-only
-reporting token, for example, needs no `sessions:write`.
-
-## Introspection: `whoami`
-
-`aex.whoami()` (CLI: `aex whoami`) validates the token and returns the
-workspace id, the token's scopes, and — on current platform deployments — a
-`limits` object with the workspace's effective admission caps
-(`maxConcurrentSessions`, `submitRatePerMinute`, `spendCapUsd`, `monthSpendUsd`,
-`balanceUsd`, `balanceGraceFloorUsd`, `paymentMethodStatus`), resolved by the
-same code the submit gates enforce. Use it as a cheap credential check and to
-anticipate `429`/`402` rejections before submitting — see
-[Limits & quotas](limits-and-quotas.md) and [Errors](errors.md).
-
-## Rotation and revocation
-
-- **Rotate** by creating a new token in the dashboard, switching your
-  deployment to it, then deleting the old one. Tokens are independent — both
-  stay valid during the switch, so rotation needs no downtime.
-- **Revoke** by deleting the token in the dashboard; deletion takes effect
-  immediately (allow up to a minute for in-flight caches to expire).
-- Token create/delete are rate-limited per workspace (see
-  [Limits & quotas](limits-and-quotas.md)).
-- If you cannot reach the dashboard (or suspect workspace-level compromise),
-  contact <support@aex.dev>.
-
-Model access needs no provider key of your own — the platform's managed gateway
-key serves every run. Runtime secrets your code and MCP servers need are a
-separate, per-call surface — see [Credentials](credentials.md) and
-[Secrets](secrets.md).

package/docs/billing.md

@@ -1,164 +0,0 @@
----
-title: Billing & webhook signing secret
----
-
-# Billing & webhook signing secret
-
-Workspace-level billing and webhook verification calls are token-scoped like
-every other client call — the workspace is derived server-side from the API key.
-
-The billing reads — `aex.billing()`, `aex.billingLedger()`, and the CLI
-`aex billing` (and its `ledger` sub-verb) — require the **`billing:read`**
-scope; a token without it fails with `403 insufficient_scope` (see
-[Errors](errors.md)). This is why the [Quickstart](quickstart.md) mints
-`billing:read` alongside `sessions:read` / `sessions:write` / `files:read`.
-
-## How you are charged
-
-There are no plans. Every workspace gets a **free monthly allowance in each
-metered dimension**, which resets at the start of each UTC month; usage past an
-allowance is paid for out of **prepaid credit**. A card is optional — without
-one, work stops when the model-usage allowance runs out.
-
-## Read the billing summary
-
-`aex.billing()` returns the prepaid balance, current-month spend, the spend cap
-enforced on new sessions, this period's allowances, the auto-recharge settings
-and the saved card:
-
-```ts
-import { Aex } from "@aexhq/sdk";
-
-const aex = new Aex(process.env.AEX_API_KEY!);
-const billing = await aex.billing();
-
-console.log(billing.balanceUsd, billing.monthSpendUsd, billing.spendCapUsd);
-for (const allowance of billing.allowances) {
-  console.log(`${allowance.label}: ${allowance.remaining} of ${allowance.quota} ${allowance.unit} left`);
-}
-```
-
-`billing.admissionState` is `"free"` (no card), `"carded_manual"` or
-`"carded_auto"` — card presence is the only lever. The returned
-`BillingSummary` is additive-tolerant: fields a newer deployment reports that
-this SDK version does not know yet pass through on the object instead of being
-rejected.
-
-CLI equivalent:
-
-```bash
-aex billing            # balance / month spend / spend cap / allowances
-aex billing --json     # the raw wire body for scripting
-```
-
-## Buy prepaid credit
-
-`aex.billingTopup({ amountUsd })` creates a hosted checkout session. Open the
-returned URL in a browser; the same flow saves the card on first use, and the
-balance moves once the charge settles.
-
-```ts
-const { url } = await aex.billingTopup({
-  amountUsd: 25
-}, {
-  idempotencyKey: crypto.randomUUID()
-});
-console.log(url);
-```
-
-Amounts below the published minimum are refused — read it from
-`billing.autoTopup.minimumAmountUsd` rather than hard-coding a figure.
-
-The optional second argument identifies the mutation and is sent only as the
-`Idempotency-Key` header. When omitted, the SDK generates one before transport
-retries begin and reuses it for every attempt.
-
-## Auto-recharge
-
-`aex.billingAutoTopup(...)` turns automatic top-ups on and sets the trigger and
-the amount. It is **off by default** and stays off until you ask for it: a saved
-card is not consent to a standing charge. Enabling it requires a saved card, and
-`thresholdUsd` must stay strictly below `amountUsd`.
-
-```ts
-const { autoTopup } = await aex.billingAutoTopup({
-  enabled: true,
-  thresholdUsd: 5,
-  amountUsd: 20
-});
-console.log(autoTopup.enabled, autoTopup.maxPerDay);
-```
-
-Omitted fields keep their stored value. `autoTopup.maxPerDay` is the cap on
-successful automatic recharges in a rolling 24 hours — a runaway workload trips
-it rather than draining the card.
-
-`aex.billingPortal()` creates a hosted billing portal session for the workspace:
-
-```ts
-const { url } = await aex.billingPortal(
-  { returnUrl: "https://aex.dev/billing" },
-  { idempotencyKey: crypto.randomUUID() }
-);
-console.log(url);
-```
-
-CLI equivalents:
-
-```bash
-aex billing topup 25 --idempotency-key "$KEY"
-aex billing autotopup --enable --threshold 5 --amount 20
-aex billing portal --idempotency-key "$KEY"
-```
-
-## Read the credit ledger
-
-`aex.billingLedger({ limit })` returns recent credit-ledger rows, newest first —
-top-ups, adjustments, and run charges with signed `amountUsd` (credits positive,
-charges negative). The ledger holds cash only: free allowances are quantities and
-never appear as ledger rows. `limit` is clamped server-side to [1, 100] (default
-25); the read is not cursor-paged.
-
-```ts
-const { entries } = await aex.billingLedger({ limit: 50 });
-for (const entry of entries) {
-  console.log(entry.createdAt, entry.entryType, entry.amountUsd);
-}
-```
-
-CLI equivalent:
-
-```bash
-aex billing ledger --limit 50   # JSON rows, newest first
-```
-
-## Reveal the webhook signing secret
-
-Session webhooks are signed Standard-Webhooks style with a per-workspace secret.
-`aex.webhookSigningSecret()` reveals it (creating one on first use) as the
-`whsec_<base64>` string that `verifyAexWebhook` takes as `secret`:
-
-```ts
-import { Aex, verifyAexWebhook } from "@aexhq/sdk";
-
-const aex = new Aex(process.env.AEX_API_KEY!);
-const { whsec } = await aex.webhookSigningSecret();
-
-// In your webhook receiver:
-const verified = await verifyAexWebhook({
-  rawBody,          // the exact request body bytes as a string
-  headers,          // the inbound request headers
-  secret: whsec
-});
-```
-
-Repeat calls return the SAME value — the hosted API does not rotate the
-signing secret. Treat the reveal as sensitive: store it in your secret manager
-and never log it.
-
-CLI equivalent (prints the bare `whsec_...` string, pipeable into a secret
-store; the reveal never goes to stderr or debug traces):
-
-```bash
-aex webhooks secret
-```

package/docs/cleanup.md

@@ -1,27 +0,0 @@
----
-title: Cleanup
----
-
-# Cleanup
-
-aex owns runtime cleanup after a run ends. This internal work is not a public
-session lifecycle state and is not represented by a synthetic `cleanupStatus`
-field. A terminal RUN event means the run's checkpoint, files, billing, and
-public read model are consistent; explicit session deletion remains a separate
-operation.
-
-The hosted product uses managed runtimes for all supported providers. Reusable
-provider-session retention is not a supported session option, and the removed
-retention field is rejected if supplied.
-
-```ts
-import {  } from "@aexhq/sdk";
-
-await aex.start({
-  model: "anthropic/claude-haiku-4-5",
-  message: "...",
-});
-```
-
-Session sequencing is exposed only through `currentRun` and `lastRun`. Use
-`session.delete()` when the session itself should be deleted.

package/docs/concepts/agent-tools.md

@@ -1,47 +0,0 @@
----
-title: Agent tools
-description: Select builtin capabilities and attach published custom tools.
-icon: TerminalSquare
----
-
-`builtinTools` controls platform-provided capabilities:
-
-- `"default"` enables the standard set and is the default.
-- `"none"` disables all builtin tools.
-- An array such as `[BuiltinTools.bash, BuiltinTools.read_file]` selects an
-  explicit subset.
-
-Custom tools are workspace resources. Build and publish them, then attach the
-returned ref under `assets.tools`.
-
-```ts
-import { BuiltinTools, Tool } from "@aexhq/sdk";
-
-const draft = await Tool.fromFiles({
-  name: "lookup_metric",
-  description: "Looks up one metric.",
-  inputSchema: {
-    type: "object",
-    properties: { name: { type: "string" } },
-    required: ["name"]
-  },
-  entry: "index.js",
-  files: {
-    "index.js": "export default async ({ input }) => ({ content: [{ type: 'text', text: input.name }] });"
-  }
-});
-const lookup = await aex.workspace.tools.publish(draft);
-
-await aex.start({
-  model,
-  message: "Look up revenue and save the result.",
-  builtinTools: [BuiltinTools.write_file],
-  assets: { tools: [lookup] }
-});
-```
-
-Tool entries must be `.js`, `.mjs`, or `.cjs` modules present in the bundle.
-The SDK validates the manifest before any network request.
-
-Use `mcpServers` for remote MCP tools. The final runtime tool set consists of
-the selected builtins, pinned custom tools, and declared MCP tools.

package/docs/concepts/composition.md

@@ -1,60 +0,0 @@
----
-title: Composition
-description: Publish reusable workspace resources and pin them to sessions.
-icon: Blocks
----
-
-Files, skills, custom tools, and instructions follow one lifecycle:
-
-1. Build a local draft with `File`, `Skill`, `Tool`, or `Instructions`.
-2. Publish it through `aex.workspace.<kind>.publish(...)`.
-3. Pass the returned immutable, version-pinned ref under `assets`.
-
-```ts
-import { Aex, File, Instructions, Skill } from "@aexhq/sdk";
-
-const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
-const [input, rules, reportWriter] = await Promise.all([
-  File.fromPath("./input").then((draft) => aex.workspace.files.publish(draft)),
-  Instructions.fromContent("Follow the repository conventions.", { name: "repo-rules" })
-    .then((draft) => aex.workspace.instructions.publish(draft)),
-  Skill.fromDir("./skills/report-writer", { name: "report-writer" })
-    .then((draft) => aex.workspace.skills.publish(draft))
-]);
-
-await aex.start({
-  model: "anthropic/claude-haiku-4-5",
-  message: "Use the attached material to produce a report.",
-  assets: {
-    files: [input],
-    instructions: [rules],
-    skills: [reportWriter]
-  },
-});
-```
-
-Published refs contain `resourceId`, `version`, `assetId`, and `contentHash`.
-Changing a logical resource creates a new version; an existing session remains
-pinned to the exact bytes it received.
-
-An `Instructions` name is the persisted workspace resource name supplied by
-the caller. It is preserved exactly—never trimmed, lowercased, or otherwise
-normalized—and must be 1–128 ASCII characters: an alphanumeric first character,
-then alphanumeric characters, `.`, `_`, or `-`. The `__` sequence is reserved.
-This direct-name contract is deliberately different from `File`, which accepts
-a filename-shaped input and derives a shorter lowercase storage slug while
-preserving the real mounted filename.
-
-Builtin capabilities stay in `builtinTools`, and remote MCP servers stay in
-`mcpServers`. Neither is mixed into `assets.tools`.
-
-Workspace lists are cursor paged:
-
-```ts
-const page = await aex.workspace.files.list({ limit: 100 });
-const next = page.nextCursor
-  ? await aex.workspace.files.list({ cursor: page.nextCursor, limit: 100 })
-  : undefined;
-```
-
-The default and maximum page size are both 100.