@aexhq/sdk 0.38.1 → 0.39.0

package/dist/fetch-archive.js

@@ -2,7 +2,7 @@ import { unzipSync } from "fflate";
 import { SKILL_BUNDLE_LIMITS } from "./_contracts/index.js";
 /**
  * Fetch a zip-archived skill from a URL and reduce it to the same in-memory
- * `SkillFiles` map that `Tools.fromSkillDir` consumes.
+ * `SkillFiles` map that `Skill.fromDir` consumes.
  *
  * This runs in the SDK process (the caller's own app), so the URL is
  * caller-controlled — there is no SSRF surface here. Host the skill yourself
@@ -16,11 +16,11 @@ import { SKILL_BUNDLE_LIMITS } from "./_contracts/index.js";
 const DEFAULT_TIMEOUT_MS = 30_000;
 export async function fetchSkillArchive(url, opts = {}) {
     if (typeof url !== "string" || url.length === 0) {
-        throw new Error("Tools.fromSkillUrl: url is required");
+        throw new Error("Skill.fromUrl: url is required");
     }
     const fetchImpl = opts.fetch ?? globalThis.fetch;
     if (typeof fetchImpl !== "function") {
-        throw new Error("Tools.fromSkillUrl: global fetch is unavailable; pass args.fetch " +
+        throw new Error("Skill.fromUrl: global fetch is unavailable; pass args.fetch " +
             "(Bun, Node 18+, or a fetch-capable runtime is required)");
     }
     const bytes = await download(url, fetchImpl, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
@@ -41,40 +41,40 @@ async function download(url, fetchImpl, timeoutMs) {
         res = await fetchImpl(url, { signal: controller.signal });
     }
     catch (err) {
-        throw new Error(`Tools.fromSkillUrl: fetch failed for ${redactUrl(url)}: ${errMessage(err)}`);
+        throw new Error(`Skill.fromUrl: fetch failed for ${redactUrl(url)}: ${errMessage(err)}`);
     }
     finally {
         clearTimeout(timer);
     }
     if (!res.ok) {
-        throw new Error(`Tools.fromSkillUrl: fetch for ${redactUrl(url)} returned HTTP ${res.status}`);
+        throw new Error(`Skill.fromUrl: fetch for ${redactUrl(url)} returned HTTP ${res.status}`);
     }
     // Early guard on a declared size so a clearly-too-big archive fails before
     // we buffer it. The authoritative caps are re-checked by bundleSkillFiles.
     const declared = Number(res.headers.get("content-length"));
     if (Number.isFinite(declared) && declared > SKILL_BUNDLE_LIMITS.maxCompressedBytes) {
-        throw new Error(`Tools.fromSkillUrl: archive at ${redactUrl(url)} declares ${declared} bytes, ` +
+        throw new Error(`Skill.fromUrl: archive at ${redactUrl(url)} declares ${declared} bytes, ` +
             `exceeding the ${SKILL_BUNDLE_LIMITS.maxCompressedBytes}-byte compressed cap`);
     }
     const bytes = new Uint8Array(await res.arrayBuffer());
     if (bytes.byteLength > SKILL_BUNDLE_LIMITS.maxCompressedBytes) {
-        throw new Error(`Tools.fromSkillUrl: archive at ${redactUrl(url)} is ${bytes.byteLength} bytes, ` +
+        throw new Error(`Skill.fromUrl: archive at ${redactUrl(url)} is ${bytes.byteLength} bytes, ` +
             `exceeding the ${SKILL_BUNDLE_LIMITS.maxCompressedBytes}-byte compressed cap`);
     }
     if (bytes.byteLength === 0) {
-        throw new Error(`Tools.fromSkillUrl: archive at ${redactUrl(url)} is empty`);
+        throw new Error(`Skill.fromUrl: archive at ${redactUrl(url)} is empty`);
     }
     return bytes;
 }
 async function verifySha256(bytes, expected, url) {
     const want = (expected.startsWith("sha256:") ? expected.slice("sha256:".length) : expected).toLowerCase();
     if (!/^[0-9a-f]{64}$/.test(want)) {
-        throw new Error(`Tools.fromSkillUrl: sha256 must be 64 hex chars (optionally prefixed "sha256:"), ` +
+        throw new Error(`Skill.fromUrl: sha256 must be 64 hex chars (optionally prefixed "sha256:"), ` +
             `got ${JSON.stringify(expected)}`);
     }
     const got = await sha256Hex(bytes);
     if (got !== want) {
-        throw new Error(`Tools.fromSkillUrl: archive integrity check failed for ${redactUrl(url)}: ` +
+        throw new Error(`Skill.fromUrl: archive integrity check failed for ${redactUrl(url)}: ` +
             `expected sha256:${want} but downloaded bytes hash to sha256:${got}`);
     }
 }
@@ -86,7 +86,7 @@ function unzip(bytes, url) {
         return unzipSync(bytes);
     }
     catch (err) {
-        throw new Error(`Tools.fromSkillUrl: could not unzip the archive at ${redactUrl(url)} ` +
+        throw new Error(`Skill.fromUrl: could not unzip the archive at ${redactUrl(url)} ` +
             `(expected a .zip): ${errMessage(err)}`);
     }
 }
@@ -114,7 +114,7 @@ function resolveSkillRoot(entries, url) {
     }
     const paths = Object.keys(files);
     if (paths.length === 0) {
-        throw new Error(`Tools.fromSkillUrl: archive at ${redactUrl(url)} contains no files`);
+        throw new Error(`Skill.fromUrl: archive at ${redactUrl(url)} contains no files`);
     }
     if (Object.prototype.hasOwnProperty.call(files, "SKILL.md")) {
         return files;
@@ -131,7 +131,7 @@ function resolveSkillRoot(entries, url) {
         }
     }
     const roots = [...new Set(paths.map((p) => (p.includes("/") ? `${p.split("/")[0]}/` : p)))].sort();
-    throw new Error(`Tools.fromSkillUrl: fetched archive at ${redactUrl(url)} must contain SKILL.md at its root, ` +
+    throw new Error(`Skill.fromUrl: fetched archive at ${redactUrl(url)} must contain SKILL.md at its root, ` +
         `or inside a single top-level folder. Found top-level entries: ${roots.join(", ")}`);
 }
 // ---------------------------------------------------------------------------
@@ -154,7 +154,7 @@ function errMessage(err) {
 async function sha256Hex(bytes) {
     const subtle = globalThis.crypto?.subtle;
     if (!subtle) {
-        throw new Error("Tools.fromSkillUrl: globalThis.crypto.subtle is unavailable; " +
+        throw new Error("Skill.fromUrl: globalThis.crypto.subtle is unavailable; " +
             "Bun, Node 18+, or a Web-Crypto-capable runtime is required");
     }
     const copy = new Uint8Array(bytes.byteLength);

package/dist/fetch-archive.js.map

@@ -1 +1 @@
-{"version":3,"file":"fetch-archive.js","sourceRoot":"","sources":["../src/fetch-archive.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fetch-archive.js","sourceRoot":"","sources":["../src/fetch-archive.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EAAE,mBAAmB,EAAkB,MAAM,kBAAkB,CAAC;AAGvE;;;;;;;;;;;;GAYG;AAEH,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAgBlC,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,GAAW,EACX,OAAiC,EAAE;IAEnC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,IAAK,UAAoC,CAAC,KAAK,CAAC;IAC5E,IAAI,OAAO,SAAS,KAAK,UAAU,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CACb,8DAA8D;YAC5D,yDAAyD,CAC5D,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,kBAAkB,CAAC,CAAC;IACnF,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,MAAM,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC9C,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAClC,OAAO,gBAAgB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;AACxC,CAAC;AAED,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E,KAAK,UAAU,QAAQ,CAAC,GAAW,EAAE,SAAoB,EAAE,SAAiB;IAC1E,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;IAC9D,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,mCAAmC,SAAS,CAAC,GAAG,CAAC,KAAK,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC3F,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,4BAA4B,SAAS,CAAC,GAAG,CAAC,kBAAkB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5F,CAAC;IACD,2EAA2E;IAC3E,2EAA2E;IAC3E,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAC3D,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,mBAAmB,CAAC,kBAAkB,EAAE,CAAC;QACnF,MAAM,IAAI,KAAK,CACb,6BAA6B,SAAS,CAAC,GAAG,CAAC,aAAa,QAAQ,UAAU;YACxE,iBAAiB,mBAAmB,CAAC,kBAAkB,sBAAsB,CAChF,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC;IACtD,IAAI,KAAK,CAAC,UAAU,GAAG,mBAAmB,CAAC,kBAAkB,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CACb,6BAA6B,SAAS,CAAC,GAAG,CAAC,OAAO,KAAK,CAAC,UAAU,UAAU;YAC1E,iBAAiB,mBAAmB,CAAC,kBAAkB,sBAAsB,CAChF,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,UAAU,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,6BAA6B,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,KAAK,UAAU,YAAY,CAAC,KAAiB,EAAE,QAAgB,EAAE,GAAW;IAC1E,MAAM,IAAI,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;IAC1G,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,8EAA8E;YAC5E,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CACpC,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CACb,qDAAqD,SAAS,CAAC,GAAG,CAAC,IAAI;YACrE,mBAAmB,IAAI,wCAAwC,GAAG,EAAE,CACvE,CAAC;IACJ,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,gCAAgC;AAChC,8EAA8E;AAE9E,SAAS,KAAK,CAAC,KAAiB,EAAE,GAAW;IAC3C,IAAI,CAAC;QACH,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,iDAAiD,SAAS,CAAC,GAAG,CAAC,GAAG;YAChE,sBAAsB,UAAU,CAAC,GAAG,CAAC,EAAE,CAC1C,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAS,gBAAgB,CAAC,OAAmC,EAAE,GAAW;IACxE,MAAM,KAAK,GAA+B,EAAE,CAAC;IAC7C,KAAK,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACzC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACvB,SAAS,CAAC,kBAAkB;QAC9B,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACjC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,6BAA6B,SAAS,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;IACnF,CAAC;IAED,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,EAAE,CAAC;QAC5D,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,IAAI,WAAW,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QACzC,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,MAAM,UAAU,CAAC,EAAE,CAAC;YACrE,MAAM,QAAQ,GAA+B,EAAE,CAAC;YAChD,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC3C,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC;YACvC,CAAC;YACD,OAAO,QAAQ,CAAC;QAClB,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACnG,MAAM,IAAI,KAAK,CACb,qCAAqC,SAAS,CAAC,GAAG,CAAC,sCAAsC;QACvF,iEAAiE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACtF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,gFAAgF;AAChF,SAAS,SAAS,CAAC,GAAW;IAC5B,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC9E,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;IAC/C,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,GAAY;IAC9B,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED,KAAK,UAAU,SAAS,CAAC,KAAiB;IACxC,MAAM,MAAM,GAAI,UAAqD,CAAC,MAAM,EAAE,MAAM,CAAC;IACrF,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,0DAA0D;YACxD,4DAA4D,CAC/D,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAC9C,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAChB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAC3D,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;IACpC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,GAAG,IAAK,IAAI,CAAC,CAAC,CAAY,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/index.d.ts

@@ -1,14 +1,14 @@
 /**
  * Public surface of the `aex` SDK.
  *
- * `Aex` is the single SDK client. Composition primitives are `Tool` / `Tools`
- * (skill-tools), `McpServer`, `AgentsMd`, `File`, and `Secret`. Everything else
- * is types, errors, and event type guards re-exported from `@aexhq/contracts`.
+ * `Aex` is the single SDK client. Composition primitives are `Tool`, `Skill`,
+ * `McpServer`, `AgentsMd`, `File`, and `Secret`. Everything else is types,
+ * errors, and event type guards re-exported from `@aexhq/contracts`.
  */
-export { Aex, AgentsMdClient, FilesClient, SecretsClient, SessionClient, SessionHandle, SessionTurnStream } from "./client.js";
+export { Aex, AgentsMdClient, FilesClient, SecretsClient, SessionClient, SessionHandle, SessionTurnStream, SkillsClient } from "./client.js";
 export type { AexOptions, Message, OutputDownloadOptions, OutputFilePathMatch, OutputFilePathSelector, OutputFileSelector, OutputLinkSelector, RunCollectOptions, RunResult, SessionCreateOptions, SessionEnvironmentOptions, SessionEvents, SessionInput, SessionMessages, SessionOutputs, SessionOverrides, SessionRunOptions, SessionRunResult, SessionSendOptions, SessionTurnResult, SessionWebhooks, StreamEventsOptions, WaitForRunOptions } from "./client.js";
 export { Tool } from "./tool.js";
-export { SkillTool, Tools } from "./skill-tool.js";
+export { Skill } from "./skill.js";
 export { AgentsMd } from "./agents-md.js";
 export { File } from "./file.js";
 export { McpServer } from "./mcp-server.js";
@@ -19,8 +19,8 @@ export type { BundledSkill, BundledTool, SkillFiles, ToolBundleManifest } from "
 export { AexApiError, AexError, AexNetworkError, CleanupError, CredentialValidationError, ProviderError, RunConfigValidationError, RunStateError } from "./_contracts/index.js";
 export { AexRateLimitError, isRateLimited, isThrottleFault, parseProviderFault } from "./retry.js";
 export type { ProviderFault, RetryOptions } from "./retry.js";
-export { MCP_SERVER_NAME_PATTERN, SKILL_BUNDLE_LIMITS, SkillBundleValidationError, normaliseSkillBundlePath, validateSkillBundleEntry, validateSkillBundleManifest } from "./_contracts/index.js";
-export type { AssetRef, AgentsMdRef, FileRef, McpServerRef, SkillBundleEntry, SkillBundleManifest, SkillToolRef, ToolInputSchema, ToolRef } from "./_contracts/index.js";
+export { MCP_SERVER_NAME_PATTERN, SKILL_BUNDLE_LIMITS, SKILL_NAME_PATTERN, SKILL_RESERVED_NAMES, SkillBundleValidationError, normaliseSkillBundlePath, validateSkillBundleEntry, validateSkillBundleManifest } from "./_contracts/index.js";
+export type { AssetRef, AgentsMdRef, FileRef, McpServerRef, SkillBundleEntry, SkillBundleManifest, SkillRecord as SkillRecordWire, SkillRef, ToolInputSchema, ToolRef } from "./_contracts/index.js";
 export type { AgentsMdRecord as AgentsMdRecordWire, BillingCheckoutPlanKey, BillingCheckoutRequest, BillingHostedSession, BillingLedgerEntry, BillingLedgerPage, BillingLedgerQuery, BillingPortalRequest, BillingSummary, FileRecord as FileRecordWire, Output, OutputFileType, OutputLink, OutputLinkOptions, OutputQuery, OutputSearchQuery, OutputSearchHit, OutputSearchPage, OutputText, ProviderEvent, ReadOutputTextOptions, Run, Session, SessionEvent, SessionListPage, SessionListQuery, SessionRetentionPolicy, SessionStatus, SessionSummary, SessionTurn, RunRecordArchiveFileV1, RunRecordArchiveFileRoleV1, RunRecordArchiveNamespaceV1, RunRecordCostV1, RunRecordDownloadErrorV1, RunRecordFileStatusV1, RunRecordManifestV1, RunRecordMetadataV1, RunRecordNamespaceV1, RunRecordSubmissionSnapshotV1, RunRecordV1, RunEvent, RunWebhookDelivery, RunWebhookDeliveryStatus, RuntimeManifest, SecretRecord, UsageSummary, WebhookSigningSecret, WhoAmI } from "./_contracts/index.js";
 export type { PlatformInlineSecrets as InlineSecrets, PlatformMcpServerSecret as McpServerSecret, PlatformEnvironment as RunEnvironment, PlatformRunSubmissionRequest, RunLimits, RunWebhookSpec, } from "./_contracts/index.js";
 export { CUSTODY_MANIFEST_SCHEMA_VERSION, RUN_RECORD_MANIFEST_SCHEMA_VERSION, RUN_RECORD_SCHEMA_VERSION, DEFAULT_RUNTIME_SIZE, RUNTIME_SIZE_PRESETS, RUNTIME_SIZES } from "./_contracts/index.js";

package/dist/index.js

@@ -1,14 +1,14 @@
 /**
  * Public surface of the `aex` SDK.
  *
- * `Aex` is the single SDK client. Composition primitives are `Tool` / `Tools`
- * (skill-tools), `McpServer`, `AgentsMd`, `File`, and `Secret`. Everything else
- * is types, errors, and event type guards re-exported from `@aexhq/contracts`.
+ * `Aex` is the single SDK client. Composition primitives are `Tool`, `Skill`,
+ * `McpServer`, `AgentsMd`, `File`, and `Secret`. Everything else is types,
+ * errors, and event type guards re-exported from `@aexhq/contracts`.
  */
-export { Aex, AgentsMdClient, FilesClient, SecretsClient, SessionClient, SessionHandle, SessionTurnStream } from "./client.js";
+export { Aex, AgentsMdClient, FilesClient, SecretsClient, SessionClient, SessionHandle, SessionTurnStream, SkillsClient } from "./client.js";
 // Composition primitives
 export { Tool } from "./tool.js";
-export { SkillTool, Tools } from "./skill-tool.js";
+export { Skill } from "./skill.js";
 export { AgentsMd } from "./agents-md.js";
 export { File } from "./file.js";
 export { McpServer } from "./mcp-server.js";
@@ -23,7 +23,7 @@ export { AexApiError, AexError, AexNetworkError, CleanupError, CredentialValidat
 // `isRateLimited`), which can carry an upstream `ProviderFault`.
 export { AexRateLimitError, isRateLimited, isThrottleFault, parseProviderFault } from "./retry.js";
 // Skill-bundle / MCP wire types
-export { MCP_SERVER_NAME_PATTERN, SKILL_BUNDLE_LIMITS, SkillBundleValidationError, normaliseSkillBundlePath, validateSkillBundleEntry, validateSkillBundleManifest } from "./_contracts/index.js";
+export { MCP_SERVER_NAME_PATTERN, SKILL_BUNDLE_LIMITS, SKILL_NAME_PATTERN, SKILL_RESERVED_NAMES, SkillBundleValidationError, normaliseSkillBundlePath, validateSkillBundleEntry, validateSkillBundleManifest } from "./_contracts/index.js";
 // Runtime sizing — the closed set of valid managed runtime presets.
 // Prefer the `Sizes` symbol const (e.g. `Sizes.SHARED_2X_8GB`)
 // so an invalid token is a compile error, not a runtime 400.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,GAAG,EACH,cAAc,EACd,WAAW,EACX,aAAa,EACb,aAAa,EACb,aAAa,EACb,iBAAiB,EAClB,MAAM,aAAa,CAAC;AA2BrB,yBAAyB;AACzB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGhE,SAAS;AACT,OAAO,EACL,WAAW,EACX,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,yBAAyB,EACzB,aAAa,EACb,wBAAwB,EACxB,aAAa,EACd,MAAM,kBAAkB,CAAC;AAE1B,2EAA2E;AAC3E,yEAAyE;AACzE,2EAA2E;AAC3E,qEAAqE;AACrE,iEAAiE;AACjE,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGnG,gCAAgC;AAChC,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,0BAA0B,EAC1B,wBAAwB,EACxB,wBAAwB,EACxB,2BAA2B,EAC5B,MAAM,kBAAkB,CAAC;AA6E1B,oEAAoE;AACpE,+DAA+D;AAC/D,6DAA6D;AAC7D,OAAO,EACL,+BAA+B,EAC/B,kCAAkC,EAClC,yBAAyB,EACzB,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,IAAI,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAGzD,8EAA8E;AAC9E,oFAAoF;AACpF,wEAAwE;AACxE,8EAA8E;AAC9E,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAGpH,4EAA4E;AAC5E,mCAAmC;AACnC,OAAO,EACL,oBAAoB,EACpB,UAAU,EACV,sBAAsB,EACtB,kBAAkB,EAClB,MAAM,EACN,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,UAAU,EACV,aAAa,EACb,SAAS,EACT,aAAa,EACd,MAAM,kBAAkB,CAAC;AAM1B,gFAAgF;AAChF,2EAA2E;AAC3E,iFAAiF;AACjF,2EAA2E;AAC3E,OAAO,EACL,oBAAoB,EACpB,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,KAAK,EACL,UAAU,EACV,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAQ1B,mBAAmB;AACnB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE/D,yEAAyE;AACzE,6EAA6E;AAC7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,GAAG,EACH,cAAc,EACd,WAAW,EACX,aAAa,EACb,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,YAAY,EACb,MAAM,aAAa,CAAC;AA2BrB,yBAAyB;AACzB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGhE,SAAS;AACT,OAAO,EACL,WAAW,EACX,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,yBAAyB,EACzB,aAAa,EACb,wBAAwB,EACxB,aAAa,EACd,MAAM,kBAAkB,CAAC;AAE1B,2EAA2E;AAC3E,yEAAyE;AACzE,2EAA2E;AAC3E,qEAAqE;AACrE,iEAAiE;AACjE,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGnG,gCAAgC;AAChC,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,0BAA0B,EAC1B,wBAAwB,EACxB,wBAAwB,EACxB,2BAA2B,EAC5B,MAAM,kBAAkB,CAAC;AA8E1B,oEAAoE;AACpE,+DAA+D;AAC/D,6DAA6D;AAC7D,OAAO,EACL,+BAA+B,EAC/B,kCAAkC,EAClC,yBAAyB,EACzB,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,IAAI,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAGzD,8EAA8E;AAC9E,oFAAoF;AACpF,wEAAwE;AACxE,8EAA8E;AAC9E,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAGpH,4EAA4E;AAC5E,mCAAmC;AACnC,OAAO,EACL,oBAAoB,EACpB,UAAU,EACV,sBAAsB,EACtB,kBAAkB,EAClB,MAAM,EACN,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,UAAU,EACV,aAAa,EACb,SAAS,EACT,aAAa,EACd,MAAM,kBAAkB,CAAC;AAM1B,gFAAgF;AAChF,2EAA2E;AAC3E,iFAAiF;AACjF,2EAA2E;AAC3E,OAAO,EACL,oBAAoB,EACpB,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,KAAK,EACL,UAAU,EACV,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAQ1B,mBAAmB;AACnB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE/D,yEAAyE;AACzE,6EAA6E;AAC7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/skill.d.ts

@@ -0,0 +1,139 @@
+import { type FetchLike, type SkillRef } from "./_contracts/index.js";
+import { type SkillFiles } from "./bundle.js";
+/**
+ * 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 declare class Skill {
+    #private;
+    /** Internal constructor. Use the `Skill.from*` factories. */
+    private constructor();
+    /** The wire ref: `{ kind:"skill", name }` once uploaded, or the draft shape before. */
+    get ref(): SkillRef | DraftSkillRef;
+    /** True for a local-bytes skill that has not been upserted to the workspace yet. */
+    get isDraft(): boolean;
+    get name(): string;
+    get description(): string;
+    /** Internal: the workspace name this instance already upserted, or undefined. */
+    get _cachedName(): string | undefined;
+    /** Internal: remember that this instance's bytes were upserted under `name`. */
+    _rememberUpload(name: string): void;
+    /**
+     * 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. Symlinks / non-regular files are
+     * skipped. Bun/Node filesystem runtimes only.
+     */
+    static fromDir(rootDir: string, args?: {
+        readonly name?: string;
+    }): Promise<Skill>;
+    /**
+     * 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 fromUrl(url: string, args?: {
+        readonly name?: string;
+        readonly sha256?: string;
+        readonly timeoutMs?: number;
+        readonly fetch?: FetchLike;
+    }): Promise<Skill>;
+    /**
+     * Build a draft skill from an in-memory files map (path -> string | bytes).
+     * Requires a root `SKILL.md`. Universal (no filesystem access).
+     */
+    static fromFiles(args: {
+        readonly name?: string;
+        readonly files: SkillFiles;
+    }): Promise<Skill>;
+    /** Convenience: build a single-file skill from a `SKILL.md` string. */
+    static fromContent(skillMd: string, args?: {
+        readonly name?: string;
+    }): Promise<Skill>;
+    /**
+     * 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 fromBytes(args: {
+        readonly name?: string;
+        readonly zip: Uint8Array;
+    }): Promise<Skill>;
+    /**
+     * 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`.
+     */
+    upload(client: SkillUploader): Promise<Skill>;
+    /**
+     * 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(): {
+        name: string;
+        description: string;
+        contentHash: string;
+        bytes: Uint8Array;
+    } | undefined;
+    toJSON(): SkillRef;
+}
+/**
+ * SDK-internal draft marker. Never reaches the wire; `skill.upload` /
+ * `run` / `openSession` converts it to a by-name {@link SkillRef} once the bytes
+ * are upserted.
+ */
+export interface DraftSkillRef {
+    readonly kind: "draft";
+    readonly name: string;
+    readonly description: string;
+    readonly contentHash: string;
+}
+/**
+ * Minimal client surface `skill.upload` needs to upsert a workspace skill.
+ * `Aex` satisfies it; 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;
+    }>;
+    _upsertSkill(args: {
+        readonly name: string;
+        readonly contentHash: string;
+        readonly description: string;
+        readonly sizeBytes: number;
+    }): Promise<{
+        readonly updated: boolean;
+    }>;
+}

package/dist/skill.js

@@ -0,0 +1,289 @@
+import { SKILL_NAME_PATTERN, SKILL_RESERVED_NAMES } from "./_contracts/index.js";
+import { bundleSkillFiles, hashSkillBundle } from "./bundle.js";
+import { fetchSkillArchive } from "./fetch-archive.js";
+import { readDirectoryAsFiles } 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. Symlinks / non-regular files are
+     * skipped. Bun/Node filesystem runtimes only.
+     */
+    static async fromDir(rootDir, args = {}) {
+        const files = await readDirectoryAsFiles(rootDir);
+        return Skill.#fromFiles("Skill.fromDir", files, args.name, dirBasename(rootDir));
+    }
+    /**
+     * 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).
+     */
+    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);
+    }
+    /** 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) {
+        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);
+        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