@aexhq/sdk 0.33.0 → 0.34.0

package/dist/skill.js

@@ -1,198 +0,0 @@
-import { SKILL_NAME_PATTERN } from "./_contracts/index.js";
-import { bundleSkillFiles, hashSkillBundle } from "./bundle.js";
-import { fetchSkillArchive } from "./fetch-archive.js";
-import { readDirectoryAsFiles } from "./node-fs.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 class Skill {
-    #ref;
-    #inlineBytes;
-    /** Asset id cached after the first submit, so reuse skips a re-upload. */
-    #assetId;
-    /**
-     * Internal constructor. Use `Skill.fromFiles` or `Skill.fromPath` to create
-     * instances.
-     */
-    constructor(ref, inlineBytes) {
-        this.#ref = ref;
-        this.#inlineBytes = inlineBytes;
-    }
-    /**
-     * 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() {
-        return this.#ref;
-    }
-    /** True for local-bytes Skills that haven't been uploaded yet. */
-    get isDraft() {
-        return this.#ref.kind === "draft";
-    }
-    /** Internal: the asset id resolved on a prior submit, or undefined. */
-    get _cachedAssetId() {
-        return this.#assetId;
-    }
-    /** Internal: remember the asset id resolved for this draft's bytes. */
-    _rememberAsset(assetId) {
-        this.#assetId = assetId;
-    }
-    /**
-     * 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 async fromFiles(args) {
-        if (!args || typeof args !== "object") {
-            throw new Error("Skill.fromFiles: args is required");
-        }
-        if (typeof args.name !== "string" || !SKILL_NAME_PATTERN.test(args.name)) {
-            throw new Error(`Skill.fromFiles: name must match ${SKILL_NAME_PATTERN.source}`);
-        }
-        const bundled = bundleSkillFiles(args.files);
-        const contentHash = await hashSkillBundle(bundled.zip);
-        const ref = {
-            kind: "draft",
-            name: args.name,
-            contentHash
-        };
-        return new Skill(ref, bundled.zip);
-    }
-    /**
-     * Read a local directory and build a draft Skill. Symlinks and
-     * non-regular files are skipped. Bun/Node filesystem runtimes only.
-     */
-    static async fromPath(rootDir, args) {
-        const files = await readDirectoryAsFiles(rootDir);
-        return Skill.fromFiles({ name: args.name, files });
-    }
-    /**
-     * 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 async fromUrl(url, args) {
-        if (!args || typeof args !== "object") {
-            throw new Error("Skill.fromUrl: args is required");
-        }
-        if (typeof args.name !== "string" || !SKILL_NAME_PATTERN.test(args.name)) {
-            throw new Error(`Skill.fromUrl: name must match ${SKILL_NAME_PATTERN.source}`);
-        }
-        const files = await fetchSkillArchive(url, {
-            ...(args.sha256 !== undefined ? { sha256: args.sha256 } : {}),
-            ...(args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {}),
-            ...(args.fetch !== undefined ? { fetch: args.fetch } : {})
-        });
-        return Skill.fromFiles({ name: args.name, files });
-    }
-    /**
-     * 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) {
-        if (!record || typeof record !== "object") {
-            throw new Error("Skill.fromCatalog: a catalog skill record is required");
-        }
-        if (typeof record.name !== "string" || !SKILL_NAME_PATTERN.test(record.name)) {
-            throw new Error(`Skill.fromCatalog: record.name must match ${SKILL_NAME_PATTERN.source}`);
-        }
-        const rawHash = typeof record.hash === "string" ? record.hash : "";
-        const hashHex = rawHash.startsWith("sha256:") ? rawHash.slice("sha256:".length) : rawHash;
-        if (!/^[0-9a-f]{64}$/.test(hashHex)) {
-            throw new Error("Skill.fromCatalog: record.hash must be a sha256 digest — only `ready` catalog skills are referenceable");
-        }
-        const ref = { kind: "asset", assetId: `asset_${hashHex}`, name: record.name };
-        return new Skill(ref);
-    }
-    /**
-     * 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() {
-        if (this.#ref.kind !== "draft" || !this.#inlineBytes) {
-            return undefined;
-        }
-        return {
-            name: this.#ref.name,
-            contentHash: this.#ref.contentHash,
-            bytes: this.#inlineBytes
-        };
-    }
-    /**
-     * 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`.
-     */
-    async upload(client) {
-        const bundle = this._takeDraftBundle();
-        if (!bundle) {
-            throw new Error("Skill.upload: only draft Skills can be uploaded. A Skill from " +
-                "Skill.fromCatalog(...) is already materialized.");
-        }
-        const uploaded = await client._uploadAsset({
-            bytes: bundle.bytes,
-            hash: bundle.contentHash,
-            contentType: "application/zip"
-        });
-        const ref = { kind: "asset", assetId: uploaded.assetId, name: bundle.name };
-        return new Skill(ref);
-    }
-    toJSON() {
-        if (this.#ref.kind === "draft") {
-            throw new Error("Skill: draft Skills cannot be JSON-serialised — they only become wire refs when " +
-                "client.submit uploads the bytes as an asset.");
-        }
-        return this.#ref;
-    }
-}
-//# sourceMappingURL=skill.js.map

package/dist/skill.js.map

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