@aexhq/sdk 0.38.1 → 0.40.0

package/dist/skill.js

@@ -0,0 +1,298 @@
+import { SKILL_NAME_PATTERN, SKILL_RESERVED_NAMES } from "./_contracts/index.js";
+import { bundleSkillFiles, hashSkillBundle } from "./bundle.js";
+import { fetchSkillArchive } from "./fetch-archive.js";
+import { readDirectoryWithFidelity } from "./node-fs.js";
+import { unzipSync } from "fflate";
+/**
+ * A Skill is a FIRST-CLASS, workspace-scoped, by-name bundle of instructional /
+ * executable content (`SKILL.md` at the bundle root plus any supporting files).
+ * It is DISTINCT from a {@link Tool}: skills are passed on the session's separate
+ * `skills:` input, not `tools:`, and a run gets a single `skills` meta-tool
+ * (list/load) rather than one load-tool per skill.
+ *
+ * Lifecycle mirrors `Secret` promotion, but keyed to a workspace name:
+ *   - The `Skill.from*` factories read a bundle, lift `name` + `description` from
+ *     the `SKILL.md` YAML frontmatter (an explicit `{ name }` overrides), and
+ *     canonically zip + hash the bytes → a DRAFT skill.
+ *   - `skill.upload(client)` UPSERTS the workspace skill by name: it stages the
+ *     bytes to the content-addressed asset store (presign/finalize) and PUTs the
+ *     registry entry. Identical bytes are a no-op. Returns an uploaded `Skill`
+ *     whose wire ref is `{ kind:"skill", name }` (BY NAME — no assetId, no hash).
+ *   - Passing a DRAFT skill in `skills:` auto-upserts it on submit (same
+ *     ergonomic as a draft `Tool` / `File`).
+ *
+ * Binding is by name and mutable: a re-upload under the same name changes what
+ * every future run referencing that name sees.
+ */
+export class Skill {
+    #ref;
+    #description;
+    #bundleBytes;
+    /** Set once this instance has upserted its bytes, so reuse skips the round-trip. */
+    #uploadedName;
+    /** Internal constructor. Use the `Skill.from*` factories. */
+    constructor(ref, description, bundleBytes) {
+        this.#ref = ref;
+        this.#description = description;
+        this.#bundleBytes = bundleBytes;
+        if (ref.kind === "skill") {
+            this.#uploadedName = ref.name;
+        }
+    }
+    /** The wire ref: `{ kind:"skill", name }` once uploaded, or the draft shape before. */
+    get ref() {
+        return this.#ref;
+    }
+    /** True for a local-bytes skill that has not been upserted to the workspace yet. */
+    get isDraft() {
+        return this.#ref.kind === "draft";
+    }
+    get name() {
+        return this.#ref.name;
+    }
+    get description() {
+        return this.#description;
+    }
+    /** Internal: the workspace name this instance already upserted, or undefined. */
+    get _cachedName() {
+        return this.#uploadedName;
+    }
+    /** Internal: remember that this instance's bytes were upserted under `name`. */
+    _rememberUpload(name) {
+        this.#uploadedName = name;
+    }
+    // --- factories (source symmetry with File / AgentsMd / Tool) --------------
+    /**
+     * Read a local skill directory. It must contain `SKILL.md` at its root, whose
+     * YAML frontmatter supplies `description` and (unless `args.name` is given)
+     * `name`. When neither an explicit name nor a frontmatter name is present, the
+     * slugified directory basename is used.
+     *
+     * The directory is walked with FIDELITY (the same walk `File.fromPath` uses):
+     * `.aexignore` + the always-on defaults (`.git/`, `node_modules/`, …) prune the
+     * upload — so a skill dir carrying `node_modules` no longer ships it — and
+     * executable bits + symlinks are captured into a `.aexmeta.json` sidecar
+     * (emitted only when such metadata exists, so a pure-content skill dir stays
+     * byte-identical → dedup continuity). Bun/Node filesystem runtimes only.
+     */
+    static async fromDir(rootDir, args = {}) {
+        const { files, meta } = await readDirectoryWithFidelity(rootDir, args.ignore);
+        return Skill.#fromFiles("Skill.fromDir", files, args.name, dirBasename(rootDir), meta);
+    }
+    /**
+     * Fetch a zip-archived skill from a URL. The archive is downloaded in the SDK
+     * process (caller-controlled URL — no SSRF surface), optionally integrity-checked
+     * against `sha256`, and reduced to the same files map as `Skill.fromDir` (a
+     * single wrapping top-level folder is stripped). It must expose `SKILL.md` at
+     * the root. The signed URL only needs to be valid for this call.
+     */
+    static async fromUrl(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 } : {})
+        });
+        // A URL has no reliable directory basename, so no slug fallback.
+        return Skill.#fromFiles("Skill.fromUrl", files, args.name, undefined);
+    }
+    /**
+     * Build a draft skill from an in-memory files map (path -> string | bytes).
+     * Requires a root `SKILL.md`. Universal (no filesystem access). An optional
+     * `meta` (exec bits + symlinks) is threaded to the bundler for callers that
+     * carry fidelity metadata alongside a hand-built map; omit it and a plain map
+     * stays byte-identical to the pre-fidelity output.
+     */
+    static async fromFiles(args) {
+        if (!args || typeof args !== "object" || args.files === undefined) {
+            throw new Error("Skill.fromFiles: { files } is required");
+        }
+        return Skill.#fromFiles("Skill.fromFiles", args.files, args.name, undefined, args.meta);
+    }
+    /** Convenience: build a single-file skill from a `SKILL.md` string. */
+    static async fromContent(skillMd, args = {}) {
+        if (typeof skillMd !== "string" || skillMd.length === 0) {
+            throw new Error("Skill.fromContent: skillMd must be a non-empty string");
+        }
+        return Skill.#fromFiles("Skill.fromContent", { "SKILL.md": skillMd }, args.name, undefined);
+    }
+    /**
+     * Build a draft skill from an already-zipped bundle. The zip is unpacked to a
+     * files map (directory entries dropped), then re-canonicalised so a
+     * `fromBytes` skill and the identical `fromDir` / `fromFiles` skill dedup by
+     * content hash. Requires `SKILL.md` at the archive root.
+     */
+    static async fromBytes(args) {
+        if (!args || !(args.zip instanceof Uint8Array) || args.zip.byteLength === 0) {
+            throw new Error("Skill.fromBytes: { zip } must be a non-empty Uint8Array");
+        }
+        let entries;
+        try {
+            entries = unzipSync(args.zip);
+        }
+        catch (err) {
+            throw new Error(`Skill.fromBytes: could not unzip the bundle (expected a .zip): ${err.message}`);
+        }
+        const files = {};
+        for (const [rawPath, bytes] of Object.entries(entries)) {
+            const path = rawPath.replace(/\\/g, "/");
+            if (path.endsWith("/"))
+                continue; // directory entry
+            files[path] = bytes;
+        }
+        return Skill.#fromFiles("Skill.fromBytes", files, args.name, undefined);
+    }
+    // --- workspace upsert -----------------------------------------------------
+    /**
+     * UPSERT this skill into the workspace registry by name and return an uploaded
+     * `Skill` whose ref is `{ kind:"skill", name }`. Two steps: stage the bytes to
+     * the content-addressed asset store (dedup makes identical bytes a no-op PUT),
+     * then PUT the registry entry (identical `contentHash` ⇒ server no-op). Reusing
+     * the SAME instance across submits skips both round-trips.
+     *
+     * Throws on an already-uploaded (non-draft) skill, mirroring `Tool.upload`.
+     */
+    async upload(client) {
+        const bundle = this._takeDraftBundle();
+        if (!bundle) {
+            throw new Error("Skill.upload: only draft skills can be uploaded. This skill is already a workspace ref " +
+                "({ kind:'skill', name }); reference it by name in skills:[...].");
+        }
+        if (this.#uploadedName === undefined) {
+            await client._uploadAsset({
+                bytes: bundle.bytes,
+                hash: bundle.contentHash,
+                contentType: "application/zip"
+            });
+            await client._upsertSkill({
+                name: bundle.name,
+                contentHash: bundle.contentHash,
+                description: bundle.description,
+                sizeBytes: bundle.bytes.byteLength
+            });
+            this.#uploadedName = bundle.name;
+        }
+        return new Skill({ kind: "skill", name: bundle.name }, bundle.description);
+    }
+    /**
+     * Internal: yield the draft's bytes + metadata so `client.run` / `openSession`
+     * can auto-upsert it. Non-consuming: a Skill is reusable across sessions — the
+     * first use caches the resolved name so later uses skip the round-trip. Returns
+     * undefined for an already-uploaded skill.
+     */
+    _takeDraftBundle() {
+        if (this.#ref.kind !== "draft" || !this.#bundleBytes) {
+            return undefined;
+        }
+        return {
+            name: this.#ref.name,
+            description: this.#ref.description,
+            contentHash: this.#ref.contentHash,
+            bytes: this.#bundleBytes
+        };
+    }
+    toJSON() {
+        if (this.#ref.kind === "draft") {
+            throw new Error("Skill: a draft skill cannot be JSON-serialised — it only becomes a by-name wire ref once " +
+                "skill.upload(client) upserts it (or run / openSession auto-upserts it from skills:[...]).");
+        }
+        return this.#ref;
+    }
+    static async #fromFiles(source, files, explicitName, dirBasename, meta) {
+        const front = extractSkillFrontmatter(source, files);
+        const name = deriveSkillName(source, front.name, explicitName, dirBasename);
+        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, meta);
+        const contentHash = await hashSkillBundle(bundled.zip);
+        const ref = { kind: "draft", name, description, contentHash };
+        return new Skill(ref, description, bundled.zip);
+    }
+}
+/**
+ * Resolve a skill name: `{ name }` arg → SKILL.md frontmatter `name:` →
+ * (fromDir only) slugified directory basename; else error. Then validate the
+ * pattern, reject the `__` MCP separator, and reject reserved names. Never
+ * returns an invalid name silently — an underivable / non-conforming name throws.
+ */
+function deriveSkillName(source, frontmatterName, explicitName, dirBasename) {
+    let name = explicitName ?? frontmatterName;
+    if (name === undefined && dirBasename !== undefined) {
+        const slug = slugifyName(dirBasename);
+        if (slug.length > 0) {
+            name = slug;
+        }
+    }
+    if (typeof name !== "string" || name.length === 0) {
+        throw new Error(`${source}: a skill name is required — pass { name }, add a \`name:\` field to the SKILL.md ` +
+            `YAML frontmatter, or (for fromDir) use a directory whose basename slugifies to a valid name`);
+    }
+    if (!SKILL_NAME_PATTERN.test(name)) {
+        throw new Error(`${source}: name ${JSON.stringify(name)} must match ${SKILL_NAME_PATTERN.source}`);
+    }
+    if (name.includes("__")) {
+        throw new Error(`${source}: name must not contain "__"; that separator is reserved for MCP tools`);
+    }
+    if (SKILL_RESERVED_NAMES.has(name)) {
+        throw new Error(`${source}: name ${JSON.stringify(name)} is reserved (${[...SKILL_RESERVED_NAMES].join(", ")}); pick another`);
+    }
+    return name;
+}
+/** Lowercase, collapse non-`[a-z0-9]` runs to `-`, trim leading/trailing `-`. */
+function slugifyName(input) {
+    return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+/** Directory basename of a filesystem path (handles `/` and `\`, trailing slashes). */
+function dirBasename(path) {
+    const normalised = path.replace(/\\/g, "/").replace(/\/+$/, "");
+    return normalised.split("/").at(-1) ?? "";
+}
+/**
+ * Read `SKILL.md` from a bundle files map and parse its YAML frontmatter for
+ * `name` + `description`. 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.
+ */
+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.js.map

package/dist/skill.js.map

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

package/dist/tool.d.ts

@@ -1,5 +1,6 @@
 import { type ToolInputSchema, type ToolRef } from "./_contracts/index.js";
-import { type SkillFiles } from "./bundle.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;
@@ -18,8 +19,19 @@ export declare class Tool {
     _rememberAsset(assetId: string): void;
     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>;
-    static fromPath(rootDir: string): Promise<Tool>;
     static fromAsset(ref: ToolRef): Tool;
     _takeDraftBundle(): {
         ref: ToolRef;

package/dist/tool.js

@@ -1,6 +1,6 @@
 import { TOOL_NAME_PATTERN, normaliseSkillBundlePath } from "./_contracts/index.js";
 import { bundleToolFiles, hashSkillBundle } from "./bundle.js";
-import { readDirectoryAsFiles } from "./node-fs.js";
+import { readDirectoryWithFidelity } from "./node-fs.js";
 export class Tool {
     #ref;
     #inlineBytes;
@@ -28,8 +28,8 @@ export class Tool {
         if (!args || typeof args !== "object") {
             throw new Error("Tool.fromFiles: args is required");
         }
-        const manifest = normalizeToolManifest("Tool.fromFiles", args);
-        const bundled = bundleToolFiles(args.files, manifest);
+        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",
@@ -39,8 +39,16 @@ export class Tool {
         };
         return new Tool(ref, bundled.zip);
     }
-    static async fromPath(rootDir) {
-        const files = await readDirectoryAsFiles(rootDir);
+    /**
+     * 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');
@@ -59,7 +67,8 @@ export class Tool {
         const { ["tool.json"]: _manifest, ...bundleFiles } = files;
         return Tool.fromFiles({
             ...parsed,
-            files: bundleFiles
+            files: bundleFiles,
+            meta
         });
     }
     static fromAsset(ref) {
@@ -95,7 +104,7 @@ export class Tool {
         return this.#ref;
     }
 }
-function normalizeToolManifest(source, input) {
+function normalizeToolManifest(source, input, files) {
     const name = input.name;
     if (typeof name !== "string" || !TOOL_NAME_PATTERN.test(name)) {
         throw new Error(`${source}: name must match ${TOOL_NAME_PATTERN.source}`);
@@ -115,6 +124,7 @@ function normalizeToolManifest(source, input) {
         throw new Error(`${source}: inputSchema.type must be "object"`);
     }
     const entry = normaliseSkillBundlePath(input.entry);
+    assertJsModuleEntry(source, entry, input.entry, files);
     return {
         name,
         description,
@@ -122,6 +132,22 @@ function normalizeToolManifest(source, input) {
         entry
     };
 }
+const JS_MODULE_ENTRY = /\.(?:js|mjs|cjs)$/i;
+/**
+ * Validate the tool's ENTRY is a JS module at authoring time (fail-fast), not
+ * mid-run when the runtime module-loader rejects a `run.sh`. The entry must end
+ * in `.js`/`.mjs`/`.cjs` and — when the bundle files are known
+ * ({@link Tool.fromFiles}) — must be present in `files`.
+ */
+function assertJsModuleEntry(source, entry, rawEntry, files) {
+    const basename = entry.split("/").pop() ?? entry;
+    if (!JS_MODULE_ENTRY.test(basename)) {
+        throw new Error(`${source}: entry must be a JS module (.js/.mjs/.cjs) that default-exports a function or { execute }; got ${JSON.stringify(rawEntry)}`);
+    }
+    if (files !== undefined && !(entry in files) && !(rawEntry in files)) {
+        throw new Error(`${source}: entry ${JSON.stringify(rawEntry)} is not present in files (keys: ${Object.keys(files).join(", ") || "(none)"})`);
+    }
+}
 function normalizeToolRef(source, ref) {
     const manifest = normalizeToolManifest(source, {
         name: ref.name,

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.38.1";
+export declare const SDK_VERSION = "0.40.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.38.1";
+export const SDK_VERSION = "0.40.0";
 //# sourceMappingURL=version.js.map

package/docs/authentication.md

@@ -25,22 +25,46 @@ it once with `aex login`:
 ```ts
 import { Aex } from "@aexhq/sdk";
 
-const aex = new Aex(process.env.AEX_API_KEY!); // preferred
-// also accepted: new Aex({ apiKey: ... }) and the alias new Aex({ apiKey: ... })
+const aex = new Aex(process.env.AEX_API_KEY!);
 ```
 
 ```bash
-aex whoami --api-key "$AEX_API_KEY"
+npx aex whoami --api-key "$AEX_API_KEY"
 
 # or persist it once, then omit --api-key on later commands:
-aex login --api-key "$AEX_API_KEY"
-aex whoami
+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 run 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 a `prd` key routes to the canonical hosted API plane
+  (`https://api.aex.dev`). A `dev` key has no stable public host yet, so a dev
+  key with no `baseUrl` throws `CredentialValidationError` asking you to pass one.
+- **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 → pass the dev plane's baseUrl explicitly:
+const dev = new Aex(process.env.AEX_DEV_KEY!, { baseUrl: process.env.AEX_DEV_URL! });
+```
+
 ## Scopes
 
 A token carries a set of **scopes**; every API route requires one, and a token

package/docs/billing.md

@@ -8,6 +8,12 @@ Workspace-level billing, subscription, 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 `runs:read` / `runs:write` / `outputs:read`.
+
 ## Read the billing summary
 
 `aex.billing()` returns the workspace's prepaid balance, current-month spend,

package/docs/concepts/agent-tools.md

@@ -10,6 +10,7 @@ Managed runs inject the complete builtin tool set into the agent by default:
 - `read_file`, `write_file`, `edit_file` — file read/create/patch
 - `grep`, `glob` — search file contents and paths
 - `head`, `tail` — read bounded file slices
+- `ls`, `stat`, `wc` — list a directory, inspect path metadata, count lines/words/bytes
 - `web_fetch`, `web_search` — fetch a URL / managed web search
 - `todo_write` — maintain a todo list
 - `subagent`, `subagent_result` — delegate to and read back from child runs (see [Subagents](subagents.md))
@@ -32,6 +33,16 @@ to pick a narrow subset alongside `includeBuiltinTools: false`.
 The final tool list is ordered: resolved builtin tools, then custom tools, then
 MCP tools.
 
+## Custom tools
+
+Attach your own tool in `tools` as a bundle built with `Tool.fromFiles(...)` (an
+explicit `{ entry, files }`) or `Tool.fromPath(dir)` (a directory with a
+`tool.json` at its root). The bundle's **entry must be a JS module** — a
+`.js`/`.mjs`/`.cjs` file present in the bundle that **default-exports a function
+or an object with an `execute` method**. This is validated at authoring time, so
+a non-JS entry (e.g. a `run.sh`) is rejected right where you build the tool, not
+opaquely mid-run when the runtime's module loader would fail to import it.
+
 Networking is open by default within the platform's managed egress ceiling and
 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`,

package/docs/concepts/composition.md

@@ -10,7 +10,7 @@ runtime before the first agent turn.
 
 | Need | Primitive |
 | --- | --- |
-| Executable or instructional skill bundles (load-tools) | `Tools.fromSkillDir`, `Tools.fromSkillUrl` |
+| Instructional skill bundles | `Skill.fromDir`, `Skill.fromUrl`, `Skill.fromFiles` |
 | Agent instructions | `AgentsMd.fromPath`, `AgentsMd.fromContent` |
 | Reference files and folders | `File.fromPath`, `File.fromBytes` |
 | Remote tools | `McpServer.remote`, `McpServer.fromId` |
@@ -18,14 +18,14 @@ runtime before the first agent turn.
 | Runtime secrets for your code | `Secret.value`, `Secret.ref`, `environment.secrets` |
 
 ```ts
-import { AgentsMd, File, McpServer, Models, Secret, Tools } from "@aexhq/sdk";
+import { AgentsMd, File, McpServer, Models, Secret, Skill } from "@aexhq/sdk";
 
 await aex.run({
   model: Models.CLAUDE_HAIKU_4_5,
   message: "Use the attached docs and tools to produce a report.",
   agentsMd: [await AgentsMd.fromContent("Follow the repo conventions.", { name: "repo-rules" })],
   files: [await File.fromPath("./input")],
-  tools: [await Tools.fromSkillDir("./skills/report-writer", { name: "report-writer" })],
+  skills: [await Skill.fromDir("./skills/report-writer", { name: "report-writer" })],
   mcpServers: [McpServer.remote({ name: "github", url: "https://example.com/mcp" })],
   environment: {
     secrets: { INTERNAL_API_TOKEN: Secret.value(process.env.INTERNAL_API_TOKEN!) },

package/docs/defaults.md

@@ -23,6 +23,7 @@ For the hard ceilings and who can raise them, see
 | `timeout` (run deadline) | 8 hours (also the ceiling) | Per-session via `overrides.timeout` (e.g. `"30m"`, `"2h"`). Values outside the run-timeout floor (1 minute) / ceiling (8 hours) are rejected with `RunConfigValidationError` before submission. | `RUN_DEFAULT_TIMEOUT_MS` |
 | `runtime` (machine size) | `shared-0.25x-1gb` — 0.25 vCPU, 1 GB | Per-session via `runtime` (use `Sizes.*` in TypeScript). | `RUN_DEFAULT_RUNTIME_SIZE` |
 | `overrides.maxSpendUsd` (per-session spend cap) | None — no spend cap (the session is still bounded by its `timeout` and any workspace-level cap) | Per-session via `overrides.maxSpendUsd` (a positive USD amount); the session is stopped once its spend would exceed the cap. | — |
+| `overrides.maxTurns` (agent iterations per run) | 20 (ceiling 200) | Per-session via `overrides.maxTurns` (a positive integer, clamped to the ceiling). | `RUN_DEFAULT_MAX_TURNS` |
 
 ## Tools