@aexhq/sdk 0.38.1 → 0.40.0

package/docs/skills.md

@@ -5,76 +5,106 @@ title: Skills
 # Skills
 
 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? })`
+supporting files) that the agent can pull into context on demand. Skills are a
+**first-class concept, separate from tools**: you pass them on the session's own
+`skills` input (not `tools`), and the run gets a single `skills` meta-tool the
+model uses to list and load them.
+
+Build a skill with the `Skill.from*` factories. Each reads a bundle, lifts the
+`name` and `description` from the `SKILL.md` YAML frontmatter (an explicit
+`{ name }` overrides the frontmatter), canonically zips + hashes the bytes, and
+returns a `Skill`:
+
+- **Local directory:** `Skill.fromDir(rootDir, { name? })` reads a folder with
+  `SKILL.md` at its root. With no `{ name }` and no frontmatter `name:`, the
+  slugified directory basename is used (Bun/Node filesystem runtimes).
+- **Signed URL:** `Skill.fromUrl(url, { name?, sha256?, timeoutMs?, fetch? })`
   fetches a zip archive with `SKILL.md` at the archive root (universal — needs a
   global `fetch`, or pass one).
+- **In-memory:** `Skill.fromFiles({ name?, files })` from a path→bytes map,
+  `Skill.fromContent(skillMd, { name? })` from a single `SKILL.md` string, or
+  `Skill.fromBytes({ name?, zip })` from a pre-zipped bundle.
+
+Names must match the skill-name pattern (`^[a-z0-9][a-z0-9_-]{0,127}$`), must not
+contain `__` (reserved for MCP tools), and must not be the reserved names
+`skills` / `skill`. The frontmatter `description` (max 2048 chars) is required.
 
 ```ts
-import { Aex, Models, Tools } from "@aexhq/sdk";
+import { Aex, Models, Skill } from "@aexhq/sdk";
 
 const aex = new Aex({ apiKey });
 
 await aex.run({
   model: Models.CLAUDE_HAIKU_4_5,
   message,
-  tools: [await Tools.fromSkillDir("./skills/rules", { name: "rules" })],
+  skills: [await Skill.fromDir("./skills/rules", { name: "rules" })],
   apiKeys: { anthropic: apiKey }
 });
 ```
 
-`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).
+## By-name, mutable binding
+
+A skill is bound to the workspace **by name**. `skill.upload(client)` UPSERTS the
+workspace skill under its name; a re-upload under the same name changes what
+every future run referencing that name sees. The wire ref is name-only —
+`{ kind:"skill", name }` — with no `assetId` and no hash, so the idempotency hash
+of two runs that reference the same skill name is identical even if the skill's
+bytes changed between them.
+
+Passing a **draft** `Skill` in `skills:` auto-upserts it on submit (the same
+ergonomic as a draft `Tool` / `File`). To upsert explicitly and reuse the name
+across many runs:
+
+```ts
+const rules = await Skill.fromDir("./skills/rules", { name: "rules" });
+await rules.upload(aex);              // stage bytes + PUT /skills/rules
+await aex.run({ model, message, skills: [rules], apiKeys });
+```
+
+`upload()` is idempotent on an instance (it caches the resolved name, so reuse
+across submits skips the round-trip) and identical bytes are a server no-op.
 
-## How a skill-tool rides on the wire
+### How a skill 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:
+Before the session lands, `openSession` / `run` walks the `skills` array and, for
+each draft, upserts it by name:
 
 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.
+4. `PUT /skills/{name}` binds that content hash to the mutable workspace skill
+   name (identical `contentHash` ⇒ no-op).
+
+The submission then carries only `submission.skills: [{ kind:"skill", name }]`.
+The four prepare passes (tools, skills, agentsMd, files) upload with bounded
+concurrency and run concurrently with each other.
+
+## The `skills` meta-tool
 
-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.
+When a run references at least one skill, the platform injects a single `skills`
+meta-tool:
 
-## Loading and materialization
+- `skills({ action: "list" })` returns each skill's `name` + `description`
+  (cheap — do this first).
+- `skills({ action: "load", name: "<skill>"})` reads that skill's full `SKILL.md`
+  instructions into context.
 
-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.
+A skill's supporting files are staged to disk under `/workspace/skills/<name>/`
+from the first turn, so `load` pulls the instructions while `read_file` / `bash`
+read the rest. The run resolves each referenced name to the workspace skill's
+current bytes at submit time and snapshots them into durable run asset storage
+(`runs/<runId>/assets/<hash>`); run-scoped copies are removed by run deletion or
+retention cleanup.
 
-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.
+## Workspace skill admin
+
+`client.skills` is the metadata surface for the named registry:
+
+- `client.skills.list()` — skill metadata (never bytes).
+- `client.skills.get(name)` — one skill's metadata.
+- `client.skills.delete(name)` — remove a workspace skill.
 
 Skills that call external HTTP APIs should read credentials from
 `environment.secrets` and use the normal client for that service. See
 [Credentials](credentials.md) for the secret model.
-
-Run-scoped asset copies are part of the run record and are removed by run deletion
-or retention cleanup.

package/docs/vision-skills.md

@@ -16,14 +16,14 @@ per-noun "does the frame depict X?" verdict.
 ## Submit the run
 
 ```ts
-import { Aex, Models, Secret, Tools } from "@aexhq/sdk";
+import { Aex, Models, Secret, Skill } from "@aexhq/sdk";
 
 const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
 
 const result = await aex.run({
   model: Models.CLAUDE_HAIKU_4_5,
   message: "Read skills/frame-vision-gate/SKILL.md, then caption and verify the frame.",
-  tools: [await Tools.fromSkillDir("./vision-skill", { name: "frame-vision-gate" })],
+  skills: [await Skill.fromDir("./vision-skill", { name: "frame-vision-gate" })],
   environment: {
     secrets: {
       DOUBAO_API_KEY: Secret.value(process.env.DOUBAO_API_KEY!)
@@ -39,7 +39,7 @@ const result = await aex.run({
 console.log(result.runId, result.text);
 ```
 
-`Tools.fromSkillDir("./vision-skill", ...)` is resolved relative to the process
+`Skill.fromDir("./vision-skill", ...)` is resolved relative to the process
 CWD. Run the script from the directory that contains `vision-skill/` (in this
 repo, `examples/`).
 

package/examples/feature-tour.ts

@@ -22,7 +22,6 @@ import {
   BuiltinTools,
   File,
   isRateLimited,
-  isTextMessage,
   McpServer,
   Models,
   Providers,
@@ -200,12 +199,11 @@ for (;;) {
     break;
   }
   const event = next.value;
-  if (isTextMessage(event)) {
+  if (event.isTextMessage()) {
     process.stdout.write(event.data.text);
-  } else if (event.type === "TOOL_CALL_START") {
-    const name = typeof event.data.name === "string" ? event.data.name : "tool";
-    process.stdout.write(`\n[tool:start] ${name}\n`);
-  } else if (event.type === "TOOL_CALL_RESULT") {
+  } else if (event.isToolCallStart()) {
+    process.stdout.write(`\n[tool:start] ${event.data.name}\n`);
+  } else if (event.isToolCallResult()) {
     process.stdout.write("[tool:result]\n");
   }
 }

package/examples/spike-settle-latency.ts

@@ -0,0 +1,125 @@
+/**
+ * SPIKE (throwaway): measure the real park-event -> record-idle gap for interactive
+ * session turns. This is the extra wall-clock Option B (settle-consistent turn stream)
+ * would force onto EVERY turn: the turn stream currently ends on the RUN_FINISHED park
+ * event, but the session RECORD flips running->idle later, in the async settle lambda.
+ *
+ *   AEX_API_KEY=... DEEPSEEK_API_KEY=... AEX_API_URL=... bun packages/sdk/examples/spike-settle-latency.ts
+ *
+ * Optional: SPIKE_TURNS=8 (samples), SPIKE_POLL_MS=120 (record poll interval).
+ *
+ * Method per turn:
+ *   1) send a tiny prompt, stream events, capture t_runFinished at the RUN_FINISHED event
+ *      (this is where the default turn stream ends), then stop consuming.
+ *   2) tight-poll session.refresh() until status === "idle"; capture t_idle.
+ *   3) settleGapMs = t_idle - t_runFinished  <-- the Option B tax.
+ * The next turn is only sent AFTER idle, so each measurement is isolated (no reconcile).
+ */
+import { Aex, Models, Providers, Sizes } from "@aexhq/sdk";
+
+const apiKey = required("AEX_API_KEY");
+const deepseekKey = required("DEEPSEEK_API_KEY");
+const apiUrl = process.env.AEX_API_URL;
+const turns = Number(process.env.SPIKE_TURNS ?? "8");
+const pollMs = Number(process.env.SPIKE_POLL_MS ?? "120");
+
+const aex = new Aex({
+  apiKey,
+  ...(apiUrl ? { baseUrl: apiUrl } : {}),
+  retry: { maxAttempts: 4, initialDelayMs: 500, maxDelayMs: 10_000, maxElapsedMs: 90_000 }
+});
+
+console.log(`opening session (dev)...`);
+const session = await aex.openSession({
+  provider: Providers.DEEPSEEK,
+  model: Models.DEEPSEEK_V4_FLASH,
+  system: "Reply with a single short sentence. Never use tools or write files.",
+  includeBuiltinTools: false,
+  tools: [],
+  runtime: Sizes.SHARED_0_25X_1GB,
+  overrides: { idleTtl: "10m", timeout: "5m", maxSpendUsd: 1 },
+  apiKeys: { deepseek: deepseekKey }
+});
+console.log(`session: ${session.id}`);
+
+type Sample = { turn: number; turnMs: number; settleGapMs: number; polls: number; timedOut: boolean };
+const samples: Sample[] = [];
+
+for (let i = 0; i < turns; i++) {
+  const stream = session.send(`Say hello #${i + 1} in one short sentence.`);
+  const tStart = performance.now();
+  let tRunFinished = 0;
+  let errored = false;
+  for await (const event of stream) {
+    if (event.isRunError()) {
+      errored = true;
+      tRunFinished = performance.now();
+      break;
+    }
+    if (event.isRunFinished()) {
+      tRunFinished = performance.now();
+      break; // default turn stream would end HERE
+    }
+  }
+  if (tRunFinished === 0) tRunFinished = performance.now();
+  const turnMs = tRunFinished - tStart;
+
+  // Tight-poll the authoritative record until it leaves running.
+  let polls = 0;
+  let tIdle = 0;
+  let timedOut = false;
+  const deadline = performance.now() + 90_000;
+  for (;;) {
+    polls++;
+    const rec = await session.refresh().catch(() => undefined);
+    const status = rec?.status;
+    if (status === "idle" || status === "suspended" || status === "error") {
+      tIdle = performance.now();
+      break;
+    }
+    if (performance.now() >= deadline) {
+      tIdle = performance.now();
+      timedOut = true;
+      break;
+    }
+    await sleep(pollMs);
+  }
+  const settleGapMs = tIdle - tRunFinished;
+  samples.push({ turn: i + 1, turnMs, settleGapMs, polls, timedOut });
+  console.log(
+    `turn ${String(i + 1).padStart(2)}  turn=${fmt(turnMs)}  settleGap=${fmt(settleGapMs)}  polls=${polls}` +
+      (errored ? "  (RUN_ERROR)" : "") +
+      (timedOut ? "  (TIMEOUT>90s)" : "")
+  );
+}
+
+const gaps = samples.map((s) => s.settleGapMs).sort((a, b) => a - b);
+console.log("\n=== settle-gap distribution (park event -> record idle) ===");
+console.log(`n=${gaps.length}`);
+console.log(`min    ${fmt(gaps[0])}`);
+console.log(`median ${fmt(pct(gaps, 50))}`);
+console.log(`p90    ${fmt(pct(gaps, 90))}`);
+console.log(`max    ${fmt(gaps[gaps.length - 1])}`);
+console.log(`mean   ${fmt(gaps.reduce((a, b) => a + b, 0) / gaps.length)}`);
+console.log("\nInterpretation: settleGap is the per-turn latency Option B adds before the");
+console.log("caller regains control (the turn stream would block until the record is idle).");
+
+function pct(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  const idx = Math.min(sorted.length - 1, Math.floor((p / 100) * sorted.length));
+  return sorted[idx];
+}
+function fmt(ms: number): string {
+  return ms >= 1000 ? `${(ms / 1000).toFixed(2)}s` : `${Math.round(ms)}ms`;
+}
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+function required(name: string): string {
+  const v = process.env[name];
+  if (!v) {
+    console.error(`Missing env var ${name}`);
+    process.exit(1);
+  }
+  return v;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexhq/sdk",
-  "version": "0.38.1",
+  "version": "0.40.0",
   "description": "TypeScript SDK for running autonomous agent sessions across providers (Anthropic, OpenAI, DeepSeek, Gemini, Mistral) behind one interface.",
   "license": "Apache-2.0",
   "repository": {
@@ -27,7 +27,7 @@
   ],
   "scripts": {
     "build": "bun ../../scripts/with-generated-dist-lock.mjs bun run build:unlocked",
-    "build:unlocked": "bun ./scripts/clean-dist.mjs && bun run --cwd ../.. --filter @aexhq/contracts build && bun run --cwd ../.. --filter @aexhq/cli build && tsc -p tsconfig.build.json && bun ./scripts/bundle-cli.mjs && bun ./scripts/inline-contracts.mjs",
+    "build:unlocked": "bun ./scripts/clean-dist.mjs && bun run --cwd ../.. --filter @aexhq/contracts build && tsc -p tsconfig.build.json && bun run --cwd ../.. --filter @aexhq/cli build && bun ./scripts/bundle-cli.mjs && bun ./scripts/inline-contracts.mjs",
     "lint": "bun ../../scripts/with-generated-dist-lock.mjs bun run lint:unlocked",
     "lint:unlocked": "tsc --noEmit",
     "test": "bun run test:unit",
@@ -47,6 +47,7 @@
     "bun": ">=1.3.14"
   },
   "dependencies": {
-    "fflate": "0.8.2"
+    "fflate": "0.8.2",
+    "ignore": "7.0.5"
   }
 }

package/dist/_contracts/event-guards.d.ts

@@ -1,67 +0,0 @@
-/**
- * Type-narrowing guards over the loose {@link RunEvent} `listEvents` shape.
- *
- * The envelope guards in `event-envelope.ts` operate on the coordinator
- * {@link import("./event-envelope.js").AexEvent} and return a plain `boolean`.
- * These mirror the same AG-UI discriminants but operate on the {@link RunEvent}
- * snapshot shape returned by `listEvents` / `RunResult.events` and NARROW
- * `event.data` to the fields that event type carries, so a consumer reads
- * `event.data.text` (etc.) without a manual cast.
- *
- * They are DISCRIMINANT-only at runtime (they test `event.type`), matching the
- * envelope guards: the narrowed `data` shape is a typing convenience, not a deep
- * runtime validation. Parse/verify the payload fields before trusting them when
- * the producer is untrusted.
- *
- * The parameter is the minimal `{ type }` discriminant both the {@link RunEvent}
- * snapshot and the coordinator `AexEvent` envelope satisfy, so the guards accept
- * either shape while narrowing to the {@link RunEvent}-typed payloads.
- */
-import type { RunEvent } from "./runtime-types.js";
-/** A `TEXT_MESSAGE_CONTENT` run event with its assistant-text payload narrowed. */
-export interface TextMessageRunEvent extends RunEvent {
-    readonly type: "TEXT_MESSAGE_CONTENT";
-    readonly data: {
-        readonly text: string;
-        readonly messageId?: string;
-    };
-}
-/** A `TOOL_CALL_START` run event with the tool-call id/name/args narrowed. */
-export interface ToolCallStartRunEvent extends RunEvent {
-    readonly type: "TOOL_CALL_START";
-    readonly data: {
-        readonly id: string;
-        readonly name: string;
-        readonly arguments?: Record<string, unknown>;
-    };
-}
-/** A `TOOL_CALL_RESULT` run event with the correlating id + result narrowed. */
-export interface ToolCallResultRunEvent extends RunEvent {
-    readonly type: "TOOL_CALL_RESULT";
-    readonly data: {
-        readonly id: string;
-        readonly content?: unknown;
-        readonly isError?: boolean;
-    };
-}
-/** A terminal `RUN_FINISHED` run event. */
-export interface RunFinishedRunEvent extends RunEvent {
-    readonly type: "RUN_FINISHED";
-    readonly data: Record<string, unknown>;
-}
-/** True for an assistant text event; narrows `event.data.text` to `string`. */
-export declare function isTextMessage(event: {
-    readonly type: string;
-}): event is TextMessageRunEvent;
-/** True for a tool-call start event; narrows `event.data` to `{ id, name }`. */
-export declare function isToolCallStart(event: {
-    readonly type: string;
-}): event is ToolCallStartRunEvent;
-/** True for a tool-call result event; narrows `event.data` to `{ id, content }`. */
-export declare function isToolCallResult(event: {
-    readonly type: string;
-}): event is ToolCallResultRunEvent;
-/** True for the terminal success event; narrows `event.data` to a record. */
-export declare function isRunFinished(event: {
-    readonly type: string;
-}): event is RunFinishedRunEvent;

package/dist/_contracts/event-guards.js

@@ -1,36 +0,0 @@
-/**
- * Type-narrowing guards over the loose {@link RunEvent} `listEvents` shape.
- *
- * The envelope guards in `event-envelope.ts` operate on the coordinator
- * {@link import("./event-envelope.js").AexEvent} and return a plain `boolean`.
- * These mirror the same AG-UI discriminants but operate on the {@link RunEvent}
- * snapshot shape returned by `listEvents` / `RunResult.events` and NARROW
- * `event.data` to the fields that event type carries, so a consumer reads
- * `event.data.text` (etc.) without a manual cast.
- *
- * They are DISCRIMINANT-only at runtime (they test `event.type`), matching the
- * envelope guards: the narrowed `data` shape is a typing convenience, not a deep
- * runtime validation. Parse/verify the payload fields before trusting them when
- * the producer is untrusted.
- *
- * The parameter is the minimal `{ type }` discriminant both the {@link RunEvent}
- * snapshot and the coordinator `AexEvent` envelope satisfy, so the guards accept
- * either shape while narrowing to the {@link RunEvent}-typed payloads.
- */
-/** True for an assistant text event; narrows `event.data.text` to `string`. */
-export function isTextMessage(event) {
-    return event.type === "TEXT_MESSAGE_CONTENT";
-}
-/** True for a tool-call start event; narrows `event.data` to `{ id, name }`. */
-export function isToolCallStart(event) {
-    return event.type === "TOOL_CALL_START";
-}
-/** True for a tool-call result event; narrows `event.data` to `{ id, content }`. */
-export function isToolCallResult(event) {
-    return event.type === "TOOL_CALL_RESULT";
-}
-/** True for the terminal success event; narrows `event.data` to a record. */
-export function isRunFinished(event) {
-    return event.type === "RUN_FINISHED";
-}
-//# sourceMappingURL=event-guards.js.map

package/dist/skill-tool.d.ts

@@ -1,102 +0,0 @@
-import { type FetchLike, type SkillToolRef } from "./_contracts/index.js";
-import { type SkillFiles } from "./bundle.js";
-/**
- * A skill re-expressed as a TOOL. `Tools.fromSkillDir` / `Tools.fromSkillUrl`
- * read a skill folder/zip, lift the tool `name` + `description` from the
- * `SKILL.md` YAML frontmatter, and canonically bundle+hash the bytes. The
- * result rides in the session's `tools` array (next to builtin names and custom
- * {@link Tool} bundles); `client.run` / `openSession` uploads the bundle as an
- * asset before the run lands, and the wire ref becomes a
- * `{ kind:"skill", assetId, name, description }` {@link SkillToolRef}.
- *
- * At run time the model calls the no-arg load-tool to pull the skill's
- * `SKILL.md` body into context; the bundle's files are eagerly staged to
- * `/workspace/skills/<name>/`.
- *
- * Asset deduplication makes the same bytes a no-op upload on subsequent runs.
- * A URL is an ingestion source, not a persistent reference.
- */
-export declare class SkillTool {
-    #private;
-    /** Internal constructor. Use the `Tools.fromSkill*` factories. */
-    private constructor();
-    /**
-     * The wire-level reference. Returns the SDK-private draft shape for
-     * un-uploaded skill-tools (kind:"draft", with name + description +
-     * contentHash). `client.run` / `openSession` walks these and uploads them
-     * before the run lands.
-     */
-    get ref(): SkillToolRef | DraftSkillToolRef;
-    /** True for local-bytes skill-tools that haven't been uploaded yet. */
-    get isDraft(): boolean;
-    /** Internal: the asset id resolved on a prior use, or undefined. */
-    get _cachedAssetId(): string | undefined;
-    /** Internal: remember the asset id resolved for this draft's bytes. */
-    _rememberAsset(assetId: string): void;
-    /** Internal: build a draft from an already-loaded skill files map. */
-    static _fromFiles(source: string, files: SkillFiles, nameOverride: string | undefined): Promise<SkillTool>;
-    /**
-     * Internal: yield the draft's bytes + metadata so `client.run` / `openSession`
-     * can upload the asset. Idempotent (non-consuming): a SkillTool is reusable
-     * across sessions — the first use caches the resolved asset id (see
-     * `_rememberAsset`) so later uses reuse it instead of re-uploading.
-     *
-     * Returns undefined for already-uploaded skill-tools.
-     */
-    _takeDraftBundle(): {
-        name: string;
-        description: string;
-        contentHash: string;
-        bytes: Uint8Array;
-    } | undefined;
-    toJSON(): SkillToolRef;
-}
-/**
- * SDK-internal draft skill-tool marker. Never reaches the wire; the
- * materialize step inside `client.run` / `openSession` converts these to
- * `kind:"skill"` refs once the bundle is uploaded.
- */
-export interface DraftSkillToolRef {
-    readonly kind: "draft";
-    readonly name: string;
-    readonly description: string;
-    readonly contentHash: string;
-}
-/**
- * Factory namespace for skill-tools. Each factory reads a skill bundle, lifts
- * `name` + `description` from the `SKILL.md` frontmatter (an explicit `name`
- * argument overrides the frontmatter), and produces a {@link SkillTool} to pass
- * in the session's `tools` array.
- */
-export declare const Tools: {
-    /**
-     * Read a local skill directory and build a skill-tool. The directory must
-     * contain `SKILL.md` at its root, whose YAML frontmatter provides the tool
-     * `name` (unless overridden via `args.name`) and `description`. Symlinks and
-     * non-regular files are skipped. Bun/Node filesystem runtimes only.
-     */
-    readonly fromSkillDir: (rootDir: string, args?: {
-        readonly name?: string;
-    }) => Promise<SkillTool>;
-    /**
-     * Fetch a zip-archived skill from a URL and build a skill-tool. 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 `Tools.fromSkillDir`, 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.run` / `openSession` snapshots the bytes into the run.
-     *
-     * Universal (Bun / Node 18+ / browser): requires a global `fetch`, or pass one.
-     */
-    readonly fromSkillUrl: (url: string, args?: {
-        readonly name?: string;
-        readonly sha256?: string;
-        readonly timeoutMs?: number;
-        readonly fetch?: FetchLike;
-    }) => Promise<SkillTool>;
-};