@aexhq/sdk 0.33.0 → 0.34.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/package.json

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

package/dist/skill.d.ts

@@ -1,149 +0,0 @@
-import { type AssetRef, type FetchLike, type SkillRef } from "./_contracts/index.js";
-import { type SkillFiles } from "./bundle.js";
-/**
- * One `Skill` class for skill bytes. `client.submit` materializes the bytes
- * as an uploaded asset before the run lands; the wire ref becomes
- * `kind:"asset"`.
- *
- * Build from an inline files map (`Skill.fromFiles`), a local directory
- * (`Skill.fromPath`), or a remote zip archive over a signed URL
- * (`Skill.fromUrl`). All three converge on the same canonical bundle, so
- * identical content dedups across sources.
- *
- * Asset deduplication makes the same bytes a no-op upload on subsequent runs.
- * There is no `Skill.fromId(...)`. A URL is an ingestion source, not a
- * persistent reference.
- *
- * An inline draft is auto-staged to the content-addressable asset store at
- * submit time (the bytes upload before `POST /runs`; the wire ref becomes
- * `kind:"asset"`). Call `await skill.upload(client)` to pre-stage the bytes
- * explicitly — useful when you want to reuse the resulting `kind:"asset"`
- * Skill across multiple runs.
- */
-export declare class Skill {
-    #private;
-    /**
-     * Internal constructor. Use `Skill.fromFiles` or `Skill.fromPath` to create
-     * instances.
-     */
-    private constructor();
-    /**
-     * The wire-level reference. Returns the SDK-private draft shape for
-     * un-materialized skills (kind:"draft", with name + contentHash).
-     * `client.submit` walks these and uploads them before the run
-     * lands.
-     */
-    get ref(): AssetRef | DraftSkillRef;
-    /** True for local-bytes Skills that haven't been uploaded yet. */
-    get isDraft(): boolean;
-    /** Internal: the asset id resolved on a prior submit, or undefined. */
-    get _cachedAssetId(): string | undefined;
-    /** Internal: remember the asset id resolved for this draft's bytes. */
-    _rememberAsset(assetId: string): void;
-    /**
-     * Build a draft Skill from an inline files map. The SDK validates
-     * basic safety (no path traversal, size caps, has `SKILL.md`),
-     * deterministically zips the bundle, and computes the
-     * `sha256:<hex>` content hash. `client.submit` materializes
-     * these before the run lands.
-     */
-    static fromFiles(args: {
-        readonly name: string;
-        readonly files: SkillFiles;
-    }): Promise<Skill>;
-    /**
-     * Read a local directory and build a draft Skill. Symlinks and
-     * non-regular files are skipped. Bun/Node filesystem runtimes only.
-     */
-    static fromPath(rootDir: string, args: {
-        readonly name: string;
-    }): Promise<Skill>;
-    /**
-     * Fetch a zip-archived skill from a URL and build a draft Skill. The archive
-     * is downloaded in the SDK process, so the URL is caller-controlled — host
-     * the skill yourself and pass a temporary signed URL (e.g. an S3 presigned
-     * URL). Its bytes are optionally integrity-checked against `sha256`, unzipped,
-     * and reduced to the same files map as `Skill.fromFiles` — so a URL-sourced
-     * skill and the identical local skill produce the same canonical asset and
-     * dedup against each other.
-     *
-     * The archive must contain `SKILL.md` at its root, or inside a single
-     * top-level folder (which is stripped). The signed URL only needs to be valid
-     * for this call; `client.submit` snapshots the bytes into the run.
-     *
-     * Universal (Bun / Node 18+ / browser): requires a global `fetch`, or pass one.
-     */
-    static fromUrl(url: string, args: {
-        readonly name: string;
-        readonly sha256?: string;
-        readonly timeoutMs?: number;
-        readonly fetch?: FetchLike;
-    }): Promise<Skill>;
-    /**
-     * Reference a skill already uploaded to the workspace catalog
-     * (`aex skills upload`) in a run.
-     *
-     * A catalog skill's bytes are a content-addressed asset, so referencing it
-     * is just an `{ kind:"asset" }` ref — once a run snapshots the bytes, it is
-     * the identical normalized flow as an inline or file-sourced skill. Pass the
-     * `Skill` record returned by `client.skills.list()` / `.get()`:
-     *
-     *   const [s] = await client.skills.list();
-     *   await client.submit({ ..., skills: [Skill.fromCatalog(s)] });
-     *
-     * The record must be `ready` (it has a content hash). Unlike the draft
-     * builders this performs no upload — the bytes already live in the catalog.
-     */
-    static fromCatalog(record: {
-        readonly name: string;
-        readonly hash?: string | null;
-    }): Skill;
-    /**
-     * Internal: yield the draft's bytes + metadata so `client.submit` can upload
-     * the asset. Idempotent (non-consuming): a Skill is reusable across submits —
-     * the first submit caches the resolved asset id (see `_rememberAsset`) so
-     * later submits reuse it instead of re-uploading.
-     *
-     * Returns undefined for already-materialized Skills.
-     */
-    _takeDraftBundle(): {
-        name: string;
-        contentHash: string;
-        bytes: Uint8Array;
-    } | undefined;
-    /**
-     * Pre-upload a draft Skill's bytes to the workspace asset store and return a
-     * NEW materialized Skill carrying a `kind:"asset"` ref. Blocking: the upload
-     * completes before this resolves. Submitting the returned Skill sends a plain
-     * asset ref and the run pulls the bytes from storage.
-     *
-     * Consumes this draft (a draft becomes an asset exactly once); call only on a
-     * draft built via `Skill.fromFiles` / `Skill.fromPath` / `Skill.fromUrl`.
-     */
-    upload(client: SkillUploader): Promise<Skill>;
-    toJSON(): SkillRef;
-}
-/**
- * SDK-internal draft skill marker. Never reaches the wire; the
- * materialize step inside `client.submit` converts these to
- * `kind:"asset"` refs.
- */
-export interface DraftSkillRef {
-    readonly kind: "draft";
-    readonly name: string;
-    readonly contentHash: string;
-}
-/**
- * Minimal client surface `Skill.upload` needs. `AgentExecutor` satisfies it via
- * its internal `_uploadAsset`; defined structurally here so `skill.ts` does not
- * import `client.ts` (which would be circular — `client.ts` imports `Skill`).
- */
-export interface SkillUploader {
-    _uploadAsset(args: {
-        readonly bytes: Uint8Array;
-        readonly hash: string;
-        readonly contentType?: string;
-    }): Promise<{
-        readonly assetId: string;
-    }>;
-}