@aexhq/sdk 0.13.6

package/dist/agents-md.d.ts

@@ -0,0 +1,46 @@
+import type { AgentsMdRef } from "./_contracts/index.js";
+/**
+ * AgentsMd — a single markdown file delivered to the agent as the
+ * first user turn of the session (matches Claude Code's CLAUDE.md
+ * behaviour).
+ *
+ *   const rules = await AgentsMd.fromContent("# Be helpful", { name: "rules" });
+ *   await client.submitRun({ agentsMd: [rules], ... });
+ *
+ * `client.submitRun` materializes the bytes to the hosted asset store before
+ * the run lands. Asset deduplication handles repeated uploads automatically.
+ */
+export declare class AgentsMd {
+    #private;
+    constructor(ref: AgentsMdRef | DraftAgentsMdRef, zipBytes?: Uint8Array);
+    get ref(): AgentsMdRef | DraftAgentsMdRef;
+    get isDraft(): boolean;
+    get isConsumed(): boolean;
+    /**
+     * Build a draft AgentsMd from a markdown string. The SDK zips the
+     * content under the canonical filename `AGENTS.md` so the hash is a
+     * pure function of the markdown text.
+     */
+    static fromContent(content: string, args: {
+        readonly name: string;
+    }): Promise<AgentsMd>;
+    /** Node-only convenience: read a markdown file from disk. */
+    static fromPath(path: string, args: {
+        readonly name: string;
+    }): Promise<AgentsMd>;
+    /**
+     * Internal: yield the draft's zipped bytes + metadata so
+     * `client.submitRun` can upload it as an asset.
+     */
+    _takeDraftBundle(): {
+        name: string;
+        contentHash: string;
+        bytes: Uint8Array;
+    } | undefined;
+    toJSON(): AgentsMdRef;
+}
+export interface DraftAgentsMdRef {
+    readonly kind: "draft";
+    readonly name: string;
+    readonly contentHash: string;
+}

package/dist/agents-md.js

@@ -0,0 +1,83 @@
+import { readFile } from "node:fs/promises";
+import { hashSkillBundle } from "./bundle.js";
+import { strToU8, zipSync } from "fflate";
+/**
+ * AgentsMd — a single markdown file delivered to the agent as the
+ * first user turn of the session (matches Claude Code's CLAUDE.md
+ * behaviour).
+ *
+ *   const rules = await AgentsMd.fromContent("# Be helpful", { name: "rules" });
+ *   await client.submitRun({ agentsMd: [rules], ... });
+ *
+ * `client.submitRun` materializes the bytes to the hosted asset store before
+ * the run lands. Asset deduplication handles repeated uploads automatically.
+ */
+export class AgentsMd {
+    #ref;
+    #zipBytes;
+    #consumed = false;
+    constructor(ref, zipBytes) {
+        this.#ref = ref;
+        this.#zipBytes = zipBytes;
+    }
+    get ref() {
+        return this.#ref;
+    }
+    get isDraft() {
+        return this.#ref.kind === "draft" && !this.#consumed;
+    }
+    get isConsumed() {
+        return this.#consumed;
+    }
+    /**
+     * Build a draft AgentsMd from a markdown string. The SDK zips the
+     * content under the canonical filename `AGENTS.md` so the hash is a
+     * pure function of the markdown text.
+     */
+    static async fromContent(content, args) {
+        if (typeof content !== "string" || content.length === 0) {
+            throw new Error("AgentsMd.fromContent: content must be a non-empty string");
+        }
+        if (!args || typeof args.name !== "string" || !WORKSPACE_NAME_RE.test(args.name)) {
+            throw new Error(`AgentsMd.fromContent: name must match ${WORKSPACE_NAME_RE.source}`);
+        }
+        const zip = zipSync({ "AGENTS.md": [strToU8(content), { mtime: ZIP_EPOCH }] }, { level: 6 });
+        const contentHash = await hashSkillBundle(zip);
+        const ref = { kind: "draft", name: args.name, contentHash };
+        return new AgentsMd(ref, zip);
+    }
+    /** Node-only convenience: read a markdown file from disk. */
+    static async fromPath(path, args) {
+        const content = await readFile(path, "utf8");
+        return AgentsMd.fromContent(content, args);
+    }
+    /**
+     * Internal: yield the draft's zipped bytes + metadata so
+     * `client.submitRun` can upload it as an asset.
+     */
+    _takeDraftBundle() {
+        if (this.#consumed) {
+            throw new Error("AgentsMd: cannot reuse a consumed AgentsMd in submitRun. Build a fresh one " +
+                "via AgentsMd.fromContent(...) / AgentsMd.fromPath(...) per submitRun call.");
+        }
+        if (this.#ref.kind !== "draft" || !this.#zipBytes) {
+            return undefined;
+        }
+        this.#consumed = true;
+        return {
+            name: this.#ref.name,
+            contentHash: this.#ref.contentHash,
+            bytes: this.#zipBytes
+        };
+    }
+    toJSON() {
+        if (this.#ref.kind === "draft") {
+            throw new Error("AgentsMd: draft AgentsMd cannot be JSON-serialised — it only becomes a wire " +
+                "ref when client.submitRun uploads the bytes as an asset.");
+        }
+        return this.#ref;
+    }
+}
+const WORKSPACE_NAME_RE = /^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$/;
+const ZIP_EPOCH = new Date(Date.UTC(1980, 0, 1));
+//# sourceMappingURL=agents-md.js.map

package/dist/agents-md.js.map

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

package/dist/asset-upload.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Asset materialization for the SDK submit path.
+ *
+ * Every inline `Skill` / `AgentsMd` / `File` draft is materialized to the
+ * hosted API's content-addressable asset store before the submit round-trip,
+ * so the wire submission carries only storage-neutral `kind:"asset"` refs.
+ *
+ * Upload is direct-to-storage (no bytes through the hosted API, so bundle size
+ * is bounded by the object store rather than by the API's memory /
+ * request-payload limits):
+ *
+ *   1. POST /assets/presign  → { exists } | { uploadUrl, requiredHeaders }
+ *      - `exists:true` is a dedup hit; we're done.
+ *      - otherwise the Worker mints a presigned PUT scoped to the exact
+ *        content-addressed key and signs `x-amz-checksum-sha256` so the object
+ *        store enforces integrity server-side.
+ *   2. PUT the bytes straight to `uploadUrl` with `requiredHeaders` (the signed
+ *      checksum). The store rejects a byte mismatch — a 2xx proves bytes == hash.
+ *   3. POST /assets/finalize → confirms the object exists (HEAD only).
+ *
+ * Fallback: when the hosted API has no object-store upload credentials it
+ * answers presign with 503 `presign_unconfigured`; we POST the bytes to the
+ * buffered `/assets`
+ * path (small bundles only). The runner re-verifies the hash on download in
+ * every case.
+ */
+/**
+ * Subset of `HttpClient` needed by the asset uploader. Defined as a
+ * structural type so tests can supply a thin stub without dragging in
+ * the full client.
+ */
+export interface AssetsHttpClient {
+    request<T>(path: string, init?: RequestInit, query?: Record<string, string>): Promise<T>;
+}
+/** Minimal fetch shape for the direct-to-storage PUT (defaults to global fetch). */
+export type AssetFetch = (input: string, init?: RequestInit) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    text(): Promise<string>;
+}>;
+export interface UploadAssetArgs {
+    readonly http: AssetsHttpClient;
+    readonly bytes: Uint8Array;
+    /** `sha256:<hex>` — the canonical content hash declared on the wire. */
+    readonly hash: string;
+    readonly contentType?: string;
+    /** Injected in tests; defaults to `globalThis.fetch` for the direct PUT. */
+    readonly fetch?: AssetFetch;
+}
+export interface UploadedAsset {
+    readonly assetId: string;
+    readonly contentHash: string;
+    readonly sizeBytes: number;
+    /** true if identical bytes were already present (dedup hit). */
+    readonly exists: boolean;
+}
+/**
+ * Upload `bytes` to the hosted API's content-addressable asset store via the
+ * direct-to-storage presign flow, falling back to the buffered `/assets` POST
+ * when the hosted API has no object-store upload credentials.
+ *
+ * Verifies the advisory hash matches the bytes BEFORE sending so a mismatch
+ * fails fast on the client. The store (or the buffered endpoint) re-verifies, and the
+ * runner re-checks on download.
+ */
+export declare function uploadAsset(args: UploadAssetArgs): Promise<UploadedAsset>;

package/dist/asset-upload.js

@@ -0,0 +1,168 @@
+/**
+ * Asset materialization for the SDK submit path.
+ *
+ * Every inline `Skill` / `AgentsMd` / `File` draft is materialized to the
+ * hosted API's content-addressable asset store before the submit round-trip,
+ * so the wire submission carries only storage-neutral `kind:"asset"` refs.
+ *
+ * Upload is direct-to-storage (no bytes through the hosted API, so bundle size
+ * is bounded by the object store rather than by the API's memory /
+ * request-payload limits):
+ *
+ *   1. POST /assets/presign  → { exists } | { uploadUrl, requiredHeaders }
+ *      - `exists:true` is a dedup hit; we're done.
+ *      - otherwise the Worker mints a presigned PUT scoped to the exact
+ *        content-addressed key and signs `x-amz-checksum-sha256` so the object
+ *        store enforces integrity server-side.
+ *   2. PUT the bytes straight to `uploadUrl` with `requiredHeaders` (the signed
+ *      checksum). The store rejects a byte mismatch — a 2xx proves bytes == hash.
+ *   3. POST /assets/finalize → confirms the object exists (HEAD only).
+ *
+ * Fallback: when the hosted API has no object-store upload credentials it
+ * answers presign with 503 `presign_unconfigured`; we POST the bytes to the
+ * buffered `/assets`
+ * path (small bundles only). The runner re-verifies the hash on download in
+ * every case.
+ */
+/**
+ * Upload `bytes` to the hosted API's content-addressable asset store via the
+ * direct-to-storage presign flow, falling back to the buffered `/assets` POST
+ * when the hosted API has no object-store upload credentials.
+ *
+ * Verifies the advisory hash matches the bytes BEFORE sending so a mismatch
+ * fails fast on the client. The store (or the buffered endpoint) re-verifies, and the
+ * runner re-checks on download.
+ */
+export async function uploadAsset(args) {
+    const expected = args.hash.startsWith("sha256:") ? args.hash.slice("sha256:".length) : args.hash;
+    const actual = await computeSha256Hex(args.bytes);
+    if (actual !== expected) {
+        throw new Error(`uploadAsset: client-side hash mismatch: computed sha256:${actual} ` +
+            `but caller declared ${args.hash}. Aborting to avoid uploading corrupted data.`);
+    }
+    const contentHashHeader = `sha256:${actual}`;
+    // ---- Step 1: presign (control plane) ----
+    let presign;
+    try {
+        presign = await args.http.request("/assets/presign", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ hash: contentHashHeader, sizeBytes: args.bytes.byteLength })
+        });
+    }
+    catch (err) {
+        // 503 presign_unconfigured → fall back to the buffered upload path.
+        if (isPresignUnconfigured(err)) {
+            return uploadAssetBuffered(args, actual);
+        }
+        throw err;
+    }
+    // Dedup hit — identical bytes already vaulted under this workspace.
+    if (presign.exists) {
+        const contentHash = presign.contentHash ?? contentHashHeader;
+        return {
+            assetId: presign.assetId ?? assetIdFromContentHash(contentHash),
+            contentHash,
+            sizeBytes: presign.sizeBytes ?? args.bytes.byteLength,
+            exists: true
+        };
+    }
+    if (!presign.uploadUrl) {
+        throw new Error("uploadAsset: presign returned no uploadUrl and exists:false");
+    }
+    // ---- Step 2: PUT bytes straight to object storage (data plane, bypasses the hosted API) ----
+    const doFetch = args.fetch ?? globalThis.fetch;
+    const putHeaders = {
+        "content-type": args.contentType ?? "application/zip",
+        ...(presign.requiredHeaders ?? {})
+    };
+    const putRes = await doFetch(presign.uploadUrl, {
+        method: "PUT",
+        headers: putHeaders,
+        body: args.bytes
+    });
+    if (!putRes.ok) {
+        const detail = await putRes.text().catch(() => "");
+        throw new Error(`uploadAsset: direct upload PUT failed with status ${putRes.status}` +
+            (detail ? `: ${detail.slice(0, 500)}` : ""));
+    }
+    // ---- Step 3: finalize (control plane confirms existence via HEAD) ----
+    const fin = await args.http.request("/assets/finalize", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ hash: contentHashHeader, sizeBytes: args.bytes.byteLength })
+    });
+    const contentHash = fin.contentHash ?? presign.contentHash ?? contentHashHeader;
+    return {
+        assetId: fin.assetId ?? presign.assetId ?? assetIdFromContentHash(contentHash),
+        contentHash,
+        sizeBytes: fin.sizeBytes ?? args.bytes.byteLength,
+        exists: false
+    };
+}
+/** Detect the 503 `presign_unconfigured` rejection, regardless of error class. */
+function isPresignUnconfigured(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const e = err;
+    if (e.status !== 503)
+        return false;
+    const detailCode = e.details?.code;
+    return e.code === "presign_unconfigured" || detailCode === "presign_unconfigured";
+}
+/**
+ * Fallback: POST the bytes to the buffered `/assets` endpoint. Used only when
+ * the hosted API has no object-store upload credentials (presign 503). Subject to the API's
+ * payload limit, so suitable for small bundles only.
+ */
+async function uploadAssetBuffered(args, actualHex) {
+    const body = await args.http.request("/assets", {
+        method: "POST",
+        headers: {
+            "content-type": args.contentType ?? "application/zip",
+            "content-length": String(args.bytes.byteLength),
+            "x-asset-hash": `sha256:${actualHex}`
+        },
+        body: args.bytes
+    });
+    const contentHash = body.contentHash ?? body.hash ?? `sha256:${actualHex}`;
+    return {
+        assetId: body.assetId ?? assetIdFromContentHash(contentHash),
+        contentHash,
+        sizeBytes: body.sizeBytes,
+        exists: body.exists
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Compute SHA-256 over `bytes` and return the lowercase hex digest.
+ * Uses Web Crypto when available (Node 18+ / browser); the SDK already
+ * requires Web Crypto for `hashSkillBundle`.
+ */
+async function computeSha256Hex(bytes) {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        throw new Error("uploadAsset: globalThis.crypto.subtle is not available; " +
+            "Node 18+ or a Web-Crypto-capable runtime is required");
+    }
+    const copy = new Uint8Array(bytes.byteLength);
+    copy.set(bytes);
+    const digest = await subtle.digest("SHA-256", copy.buffer);
+    return bufferToHex(digest);
+}
+function assetIdFromContentHash(contentHash) {
+    const hex = contentHash.startsWith("sha256:") ? contentHash.slice("sha256:".length) : contentHash;
+    return `asset_${hex}`;
+}
+function bufferToHex(buffer) {
+    const view = new Uint8Array(buffer);
+    let out = "";
+    for (let i = 0; i < view.length; i++) {
+        const byte = view[i];
+        out += byte.toString(16).padStart(2, "0");
+    }
+    return out;
+}
+//# sourceMappingURL=asset-upload.js.map

package/dist/asset-upload.js.map

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

package/dist/bundle.d.ts

@@ -0,0 +1,33 @@
+/**
+ * In-memory skill bundle: a flat path -> bytes map and the
+ * deterministically-zipped representation.
+ *
+ * The SDK runs only the cheap, safety-critical checks here
+ * (`validateSkillBundleEntry`: no `..`, no absolute paths, no Windows
+ * backslashes, depth/length limits). The BFF re-canonicalises and
+ * recomputes the canonical hash on receipt — SDK-side hashing is NOT
+ * part of any contract, so we don't expose one for workspace uploads.
+ *
+ * For transient (per-run) skills the SDK does compute an advisory
+ * `sha256` of the canonicalised zip via `hashSkillBundle()` — it travels
+ * in the `InlineSkillRef.contentHash` field, is used for retry
+ * de-dup and janitor reconciliation, and is recomputed server-side
+ * (mismatch → submission rejected).
+ */
+export interface BundledSkill {
+    readonly zip: Uint8Array;
+    readonly fileCount: number;
+    readonly compressedSize: number;
+}
+/** Inline files map: path -> contents (UTF-8 string or raw bytes). */
+export type SkillFiles = Readonly<Record<string, string | Uint8Array>>;
+export declare function bundleSkillFiles(files: SkillFiles): BundledSkill;
+/**
+ * Compute `sha256:<hex>` of the given canonicalised zip bytes. Used by
+ * `Skill.fromFiles` / `Skill.fromPath` to populate the
+ * `InlineSkillRef.contentHash` field. The hash is advisory — the BFF
+ * recomputes server-side after re-canonicalising the zip; a mismatch is
+ * rejected. Web-Crypto-only so the SDK works in Node, edge runtimes,
+ * and browsers without polyfills.
+ */
+export declare function hashSkillBundle(zipBytes: Uint8Array): Promise<string>;

package/dist/bundle.js

@@ -0,0 +1,89 @@
+import { zipSync } from "fflate";
+import { SKILL_BUNDLE_LIMITS, validateSkillBundleEntry } from "./_contracts/index.js";
+const TEXT = new TextEncoder();
+export function bundleSkillFiles(files) {
+    if (!files || typeof files !== "object") {
+        throw new Error("Skill files map is required");
+    }
+    const entries = Object.entries(files);
+    if (entries.length === 0) {
+        throw new Error("Skill files map cannot be empty");
+    }
+    if (entries.length > SKILL_BUNDLE_LIMITS.maxFiles) {
+        throw new Error(`Skill bundle exceeds ${SKILL_BUNDLE_LIMITS.maxFiles} file limit (got ${entries.length})`);
+    }
+    const collected = new Map();
+    let hasSkillMd = false;
+    let totalDecompressed = 0;
+    for (const [rawPath, contents] of entries) {
+        const bytes = typeof contents === "string" ? TEXT.encode(contents) : contents;
+        if (!(bytes instanceof Uint8Array)) {
+            throw new Error(`Skill file "${rawPath}" must be a string or Uint8Array`);
+        }
+        const entry = validateSkillBundleEntry({ path: rawPath, size: bytes.byteLength });
+        if (entry.path === "SKILL.md") {
+            hasSkillMd = true;
+        }
+        totalDecompressed += bytes.byteLength;
+        if (totalDecompressed > SKILL_BUNDLE_LIMITS.maxDecompressedBytes) {
+            throw new Error(`Skill bundle exceeds decompressed cap of ${SKILL_BUNDLE_LIMITS.maxDecompressedBytes} bytes`);
+        }
+        if (collected.has(entry.path)) {
+            throw new Error(`Skill bundle contains duplicate path: ${entry.path}`);
+        }
+        collected.set(entry.path, bytes);
+    }
+    if (!hasSkillMd) {
+        throw new Error('Skill bundle must contain a "SKILL.md" file at the root. ' +
+            "If you want to upload an instructions file or generic agent context, " +
+            "use AgentsMd.fromPath / File.fromPath instead.");
+    }
+    // Sort entries and pin every mtime to the epoch so the byte output is
+    // identical across machines and re-runs (the BFF re-canonicalises and
+    // recomputes the canonical hash, so this is for retry-safety / debug
+    // reproducibility rather than a wire-shape contract).
+    const sorted = [...collected.entries()].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+    const zippable = {};
+    for (const [path, bytes] of sorted) {
+        zippable[path] = [bytes, { mtime: ZIP_EPOCH }];
+    }
+    const zip = zipSync(zippable, { level: 6 });
+    if (zip.byteLength > SKILL_BUNDLE_LIMITS.maxCompressedBytes) {
+        throw new Error(`Skill bundle exceeds compressed cap of ${SKILL_BUNDLE_LIMITS.maxCompressedBytes} bytes (got ${zip.byteLength})`);
+    }
+    return { zip, fileCount: entries.length, compressedSize: zip.byteLength };
+}
+const ZIP_EPOCH = new Date(Date.UTC(1980, 0, 1));
+/**
+ * Compute `sha256:<hex>` of the given canonicalised zip bytes. Used by
+ * `Skill.fromFiles` / `Skill.fromPath` to populate the
+ * `InlineSkillRef.contentHash` field. The hash is advisory — the BFF
+ * recomputes server-side after re-canonicalising the zip; a mismatch is
+ * rejected. Web-Crypto-only so the SDK works in Node, edge runtimes,
+ * and browsers without polyfills.
+ */
+export async function hashSkillBundle(zipBytes) {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        throw new Error("hashSkillBundle: globalThis.crypto.subtle is not available; Node 18+ or a Web-Crypto-capable runtime is required");
+    }
+    // crypto.subtle.digest expects a BufferSource. Pass a freshly-sliced
+    // copy to detach from any external Uint8Array view (Web Crypto rejects
+    // non-zero byteOffset SharedArrayBuffer views, and view detach also
+    // protects against the caller mutating the input after the digest is
+    // computed).
+    const view = new Uint8Array(zipBytes.byteLength);
+    view.set(zipBytes);
+    const digest = await subtle.digest("SHA-256", view.buffer);
+    return "sha256:" + bufferToHex(digest);
+}
+function bufferToHex(buffer) {
+    const view = new Uint8Array(buffer);
+    let out = "";
+    for (let i = 0; i < view.length; i++) {
+        const byte = view[i];
+        out += byte.toString(16).padStart(2, "0");
+    }
+    return out;
+}
+//# sourceMappingURL=bundle.js.map

package/dist/bundle.js.map

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