@aexhq/sdk 0.38.1 → 0.40.0

package/dist/skill-tool.js

@@ -1,190 +0,0 @@
-import { TOOL_NAME_PATTERN } from "./_contracts/index.js";
-import { bundleSkillFiles, hashSkillBundle } from "./bundle.js";
-import { fetchSkillArchive } from "./fetch-archive.js";
-import { readDirectoryAsFiles } from "./node-fs.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 class SkillTool {
-    #ref;
-    #inlineBytes;
-    /** Asset id cached after the first use, so reuse skips a re-upload. */
-    #assetId;
-    /** Internal constructor. Use the `Tools.fromSkill*` factories. */
-    constructor(ref, inlineBytes) {
-        this.#ref = ref;
-        this.#inlineBytes = inlineBytes;
-    }
-    /**
-     * 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() {
-        return this.#ref;
-    }
-    /** True for local-bytes skill-tools that haven't been uploaded yet. */
-    get isDraft() {
-        return this.#ref.kind === "draft";
-    }
-    /** Internal: the asset id resolved on a prior use, or undefined. */
-    get _cachedAssetId() {
-        return this.#assetId;
-    }
-    /** Internal: remember the asset id resolved for this draft's bytes. */
-    _rememberAsset(assetId) {
-        this.#assetId = assetId;
-    }
-    /** Internal: build a draft from an already-loaded skill files map. */
-    static async _fromFiles(source, files, nameOverride) {
-        const front = extractSkillFrontmatter(source, files);
-        const name = nameOverride ?? front.name;
-        if (typeof name !== "string" || name.length === 0) {
-            throw new Error(`${source}: a skill name is required — pass { name } or add a \`name:\` field to the SKILL.md YAML frontmatter`);
-        }
-        if (!TOOL_NAME_PATTERN.test(name)) {
-            throw new Error(`${source}: name must match ${TOOL_NAME_PATTERN.source}`);
-        }
-        if (name.includes("__")) {
-            throw new Error(`${source}: name must not contain "__"; that separator is reserved for MCP tools`);
-        }
-        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 SkillTool(ref, bundled.zip);
-    }
-    /**
-     * 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() {
-        if (this.#ref.kind !== "draft" || !this.#inlineBytes) {
-            return undefined;
-        }
-        return {
-            name: this.#ref.name,
-            description: this.#ref.description,
-            contentHash: this.#ref.contentHash,
-            bytes: this.#inlineBytes
-        };
-    }
-    toJSON() {
-        if (this.#ref.kind === "draft") {
-            throw new Error("SkillTool: draft skill-tools cannot be JSON-serialised — they only become wire refs when " +
-                "aex.run / openSession uploads the bytes as an asset.");
-        }
-        return this.#ref;
-    }
-}
-/**
- * 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 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.
-     */
-    async fromSkillDir(rootDir, args = {}) {
-        const files = await readDirectoryAsFiles(rootDir);
-        return SkillTool._fromFiles("Tools.fromSkillDir", files, args.name);
-    },
-    /**
-     * 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.
-     */
-    async fromSkillUrl(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 } : {})
-        });
-        return SkillTool._fromFiles("Tools.fromSkillUrl", files, args.name);
-    }
-};
-/**
- * Read `SKILL.md` from a bundle files map and parse its YAML frontmatter for
- * the `name` + `description` fields. 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. A skill with no frontmatter yields an
- * empty result and the caller reports the missing field.
- */
-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-tool.js.map

package/dist/skill-tool.js.map

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