@aexhq/sdk 0.13.6

package/dist/mcp-server.js

@@ -0,0 +1,114 @@
+import { rejectStdioMcpShape } from "./_contracts/index.js";
+const WORKSPACE_MCP_ID_PATTERN = /^mcp_[A-Za-z0-9_-]{8,128}$/;
+/**
+ * Inline MCP server reference OR a workspace-persistent ref via
+ * `McpServer.fromId("mcp_...")`.
+ *
+ * For inline refs, headers (typically `Authorization`) are vaulted
+ * server-side under `secrets.mcpServers` and excluded from the
+ * idempotency hash; the non-secret `{name, url}` part is hashed.
+ *
+ * The SDK splits the header bag from the public ref BEFORE the wire
+ * payload is built, so a single inline `McpServer` instance becomes:
+ *
+ *   - a `submission.mcpServers` entry of `{ name, url }`, and
+ *   - (when `headers` is present) a `secrets.mcpServers` entry of
+ *     `{ name, headers }`.
+ *
+ * For workspace refs (`McpServer.fromId(id)`), the submission entry
+ * is `{kind:"workspace", id}`; the BFF resolves it to inline at
+ * submit time. The user still supplies auth separately via
+ * `secrets.mcpServers[<workspace-name>]` keyed by the workspace
+ * MCP's persisted `name`.
+ */
+export class McpServer {
+    kind;
+    name;
+    url;
+    transport;
+    id;
+    headers;
+    /** Internal constructor. Use `McpServer.remote(...)` or `McpServer.fromId(...)`. */
+    constructor(args) {
+        if (!args || typeof args !== "object") {
+            throw new Error("McpServer: args is required");
+        }
+        // Defence in depth: any stdio-shaped input that slips past the
+        // builder type (callers will reach in with `as never` to feed stdio
+        // shapes) is rejected with the canonical error.
+        rejectStdioMcpShape(args);
+        if (args.kind === "workspace") {
+            if (typeof args.id !== "string" || !WORKSPACE_MCP_ID_PATTERN.test(args.id)) {
+                throw new Error(`McpServer.fromId: id must match ${WORKSPACE_MCP_ID_PATTERN.source}`);
+            }
+            this.kind = "workspace";
+            this.id = args.id;
+            // `name` and `url` are resolved server-side; populate placeholders so
+            // type-level access never returns undefined, but mark the workspace
+            // ref so callers can branch.
+            this.name = "";
+            this.url = "";
+            this.transport = undefined;
+            this.headers = undefined;
+            return;
+        }
+        if (typeof args.name !== "string" || !args.name) {
+            throw new Error("McpServer: name is required");
+        }
+        if (typeof args.url !== "string" || !args.url) {
+            throw new Error("McpServer: url is required");
+        }
+        this.kind = "inline";
+        this.id = undefined;
+        this.name = args.name;
+        this.url = args.url;
+        this.transport = args.transport;
+        this.headers = args.headers && Object.keys(args.headers).length > 0 ? { ...args.headers } : undefined;
+    }
+    /**
+     * Inline remote MCP server reachable over HTTP(S) by URL. `transport`
+     * defaults to the runtime's choice when omitted; pass it explicitly
+     * to pin `"http"` (streamable) or `"sse"` (event-stream). Stdio is
+     * not supported — see {@link rejectStdioMcpShape}.
+     */
+    static remote(args) {
+        return new McpServer({ kind: "inline", ...args });
+    }
+    /**
+     * Reference a workspace-persistent MCP server by id. The BFF
+     * resolves the ref to inline `{name, url}` at submit time using the
+     * row from `workspace_mcp_servers`. Auth still arrives inline at
+     * the call site — pass it in `secrets.mcpServers[<workspace-name>]`.
+     */
+    static fromId(id) {
+        return new McpServer({ kind: "workspace", id });
+    }
+    /** Wire shape for the non-secret `submission.mcpServers` entry. */
+    toSubmissionEntry() {
+        if (this.kind === "workspace") {
+            return { kind: "workspace", id: this.id };
+        }
+        return this.transport
+            ? { name: this.name, transport: this.transport, url: this.url }
+            : { name: this.name, url: this.url };
+    }
+    /**
+     * Wire shape for the `secrets.mcpServers` entry, or `undefined`
+     * when no headers were provided. Returned headers are a defensive
+     * copy.
+     *
+     * Workspace refs never emit a secret entry from the SDK — the
+     * caller knows the resolved `name` (from the dashboard or from a
+     * prior list call) and supplies the headers under that name
+     * directly on the `secrets.mcpServers[]` array. Mixing SDK-side
+     * auth into a workspace ref's `name` would create a name/auth
+     * mismatch the BFF can't validate.
+     */
+    toSecretEntry() {
+        if (this.kind === "workspace" || !this.headers) {
+            return undefined;
+        }
+        return { name: this.name, url: this.url, headers: { ...this.headers } };
+    }
+}
+//# sourceMappingURL=mcp-server.js.map

package/dist/mcp-server.js.map

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

package/dist/node-fs.d.ts

@@ -0,0 +1,12 @@
+import type { SkillFiles } from "./bundle.js";
+/**
+ * Walk a local directory and load every regular file into an in-memory
+ * `SkillFiles` map. Symlinks and non-regular files are skipped (a
+ * symlink that points outside the root would still be skipped because
+ * we use `lstat` semantics). Paths are normalised to forward-slash
+ * relative form so they can flow into `bundleSkillFiles` directly.
+ *
+ * Node-only. Browser callers should use `bundleSkillFiles` with a
+ * pre-built files map instead.
+ */
+export declare function readDirectoryAsFiles(rootDir: string): Promise<SkillFiles>;

package/dist/node-fs.js

@@ -0,0 +1,44 @@
+import { readFile, readdir, stat } from "node:fs/promises";
+import { join, posix, relative, sep } from "node:path";
+/**
+ * Walk a local directory and load every regular file into an in-memory
+ * `SkillFiles` map. Symlinks and non-regular files are skipped (a
+ * symlink that points outside the root would still be skipped because
+ * we use `lstat` semantics). Paths are normalised to forward-slash
+ * relative form so they can flow into `bundleSkillFiles` directly.
+ *
+ * Node-only. Browser callers should use `bundleSkillFiles` with a
+ * pre-built files map instead.
+ */
+export async function readDirectoryAsFiles(rootDir) {
+    if (typeof rootDir !== "string" || !rootDir) {
+        throw new Error("readDirectoryAsFiles: rootDir is required");
+    }
+    const rootStat = await stat(rootDir);
+    if (!rootStat.isDirectory()) {
+        throw new Error(`readDirectoryAsFiles: ${rootDir} is not a directory`);
+    }
+    const files = {};
+    await walk(rootDir, rootDir, files);
+    return files;
+}
+async function walk(rootDir, currentDir, out) {
+    const entries = await readdir(currentDir, { withFileTypes: true });
+    for (const dirent of entries) {
+        const full = join(currentDir, dirent.name);
+        if (dirent.isSymbolicLink()) {
+            continue;
+        }
+        if (dirent.isDirectory()) {
+            await walk(rootDir, full, out);
+            continue;
+        }
+        if (!dirent.isFile()) {
+            continue;
+        }
+        const rel = relative(rootDir, full);
+        const posixPath = sep === "/" ? rel : rel.split(sep).join(posix.sep);
+        out[posixPath] = await readFile(full);
+    }
+}
+//# sourceMappingURL=node-fs.js.map

package/dist/node-fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-fs.js","sourceRoot":"","sources":["../src/node-fs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAGvD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,OAAe;IACxD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,OAAO,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,yBAAyB,OAAO,qBAAqB,CAAC,CAAC;IACzE,CAAC;IACD,MAAM,KAAK,GAA+B,EAAE,CAAC;IAC7C,MAAM,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;IACpC,OAAO,KAAK,CAAC;AACf,CAAC;AAED,KAAK,UAAU,IAAI,CAAC,OAAe,EAAE,UAAkB,EAAE,GAA+B;IACtF,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACnE,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,MAAM,CAAC,cAAc,EAAE,EAAE,CAAC;YAC5B,SAAS;QACX,CAAC;QACD,IAAI,MAAM,CAAC,WAAW,EAAE,EAAE,CAAC;YACzB,MAAM,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;YAC/B,SAAS;QACX,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YACrB,SAAS;QACX,CAAC;QACD,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACpC,MAAM,SAAS,GAAG,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACrE,GAAG,CAAC,SAAS,CAAC,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;AACH,CAAC"}

package/dist/proxy-endpoint.d.ts

@@ -0,0 +1,131 @@
+import { type PlatformProxyAuthValue, type PlatformProxyEndpoint, type PlatformProxyEndpointAuth, type ProxyMethod, type ProxyResponseMode } from "./_contracts/index.js";
+/**
+ * Constructor-only surface for declaring a per-run HTTP proxy endpoint.
+ *
+ * Why a class rather than a raw object literal: the raw
+ * `PlatformProxyEndpoint` + `PlatformProxyEndpointAuth` shape lets the
+ * caller assemble two halves of one logical thing (the auth shape and
+ * the auth value), and they often drift — agents writing freeform
+ * objects regularly hit runtime rejections with `responseMode: "json"`
+ * (real values are `status_only | headers_only | full`) or
+ * `authShape: { type: "header", header: "X-Api-Key" }` (real field is
+ * `name`). The constructor signatures here put the auth secret on the
+ * same call as the shape, so any drift becomes a TypeScript error at
+ * the call site, not an HTTP 400 a round-trip later.
+ *
+ * Wire-format unchanged: the SDK splits each `ProxyEndpoint` instance
+ * into a `PlatformProxyEndpoint` (the non-secret declaration) plus a
+ * `PlatformProxyEndpointAuth` entry (the per-request secret) at
+ * `submitRun` time, exactly the way `McpServer` already splits
+ * `headers` into `secrets.mcpServers`.
+ *
+ * Five named constructors:
+ *
+ *   - `ProxyEndpoint.none  ({ name, baseUrl, ... })` — keyless upstream
+ *   - `ProxyEndpoint.bearer({ name, baseUrl, token, ... })`
+ *   - `ProxyEndpoint.header({ name, baseUrl, header, value, ... })`
+ *   - `ProxyEndpoint.basic ({ name, baseUrl, username, password, ... })`
+ *   - `ProxyEndpoint.query ({ name, baseUrl, query, value, ... })`
+ *
+ * All five share the same allow-list / response-mode / cap parameters.
+ * The four authenticated variants split into `secrets.proxyEndpointAuth[].value`
+ * at submit time; `none` produces only a declaration (no secret).
+ */
+export interface ProxyEndpointCommonOptions {
+    /**
+     * Endpoint name. Lowercase letters, digits, `_`, `-`, up to 63
+     * chars. Matches the BFF's `PROXY_ENDPOINT_NAME_PATTERN`. Used as
+     * the path segment in `/api/runs/:runId/proxy/:name` and as the
+     * cross-reference key in `secrets.proxyEndpointAuth`.
+     */
+    readonly name: string;
+    /** Upstream base URL. Must be an absolute `https://` URL. */
+    readonly baseUrl: string;
+    /** HTTP methods the in-container caller is allowed to use. */
+    readonly allowMethods: readonly ProxyMethod[];
+    /** Path prefixes the in-container caller is allowed to hit. */
+    readonly allowPathPrefixes: readonly string[];
+    /**
+     * Caller-supplied headers permitted to pass through the proxy. The
+     * auth header (Bearer/Basic/custom-name) is enforced by the proxy
+     * itself and MUST NOT appear here.
+     */
+    readonly allowHeaders?: readonly string[];
+    /** Default narrowest response disclosure mode. */
+    readonly responseMode?: ProxyResponseMode;
+    readonly maxRequestBytes?: number;
+    readonly maxResponseBytes?: number;
+    readonly timeoutMs?: number;
+    readonly perCallBudget?: number;
+    readonly responseByteBudget?: number;
+}
+export interface BearerProxyEndpointOptions extends ProxyEndpointCommonOptions {
+    /** Bearer token sent as `Authorization: Bearer <token>`. */
+    readonly token: string;
+}
+/**
+ * Options for `ProxyEndpoint.none` — keyless upstream. Same shape as
+ * `ProxyEndpointCommonOptions`; declared as an empty extension so the
+ * call site reads symmetrically with the other constructors and stays
+ * a stable extension point if a future field becomes auth-shape-only.
+ */
+export interface NoneProxyEndpointOptions extends ProxyEndpointCommonOptions {
+}
+export interface BasicProxyEndpointOptions extends ProxyEndpointCommonOptions {
+    readonly username: string;
+    readonly password: string;
+}
+export interface HeaderProxyEndpointOptions extends ProxyEndpointCommonOptions {
+    /** Header name the upstream expects the auth value in. */
+    readonly header: string;
+    /** Header value (the actual secret). */
+    readonly value: string;
+}
+export interface QueryProxyEndpointOptions extends ProxyEndpointCommonOptions {
+    /** Query parameter name the upstream expects the auth value in. */
+    readonly query: string;
+    /** Query parameter value (the actual secret). */
+    readonly value: string;
+}
+export declare class ProxyEndpoint {
+    /** Non-secret half of the wire shape — declaration only. */
+    readonly declaration: PlatformProxyEndpoint;
+    /**
+     * Per-request secret half — auth value keyed by the same `name`.
+     * `null` for keyless (`ProxyEndpoint.none`) endpoints; `splitProxyEndpoints`
+     * filters those out so they never land in `secrets.proxyEndpointAuth`.
+     */
+    readonly auth: PlatformProxyEndpointAuth | null;
+    private constructor();
+    /**
+     * Keyless endpoint. Routes through the aex managed proxy for
+     * unified egress, audit, and budget enforcement, but the BFF injects
+     * no auth header or query parameter. Use for public APIs (Wikimedia
+     * Commons, NASA Images, Library of Congress, NARA, GDELT, etc.).
+     */
+    static none(options: NoneProxyEndpointOptions): ProxyEndpoint;
+    /** Bearer-token endpoint. */
+    static bearer(options: BearerProxyEndpointOptions): ProxyEndpoint;
+    /** Basic-auth endpoint. */
+    static basic(options: BasicProxyEndpointOptions): ProxyEndpoint;
+    /** Custom-header endpoint. */
+    static header(options: HeaderProxyEndpointOptions): ProxyEndpoint;
+    /** Query-string-auth endpoint. */
+    static query(options: QueryProxyEndpointOptions): ProxyEndpoint;
+}
+/**
+ * Split a list of `ProxyEndpoint` instances into the public declarations
+ * (`proxyEndpoints[]`) and the per-request auth bundle
+ * (`secrets.proxyEndpointAuth[]`). Mirrors the way `submitRun` already
+ * splits `McpServer.headers` into `secrets.mcpServers[]`.
+ *
+ * Throws on duplicate endpoint names — names are the cross-reference
+ * key between the two halves and the BFF rejects collisions; failing
+ * here gives the caller a precise message at the call site instead of
+ * an opaque HTTP error.
+ */
+export declare function splitProxyEndpoints(inputs: readonly ProxyEndpoint[]): {
+    endpoints: readonly PlatformProxyEndpoint[];
+    auth: readonly PlatformProxyEndpointAuth[];
+};
+export type { PlatformProxyAuthValue as ProxyAuthValue };

package/dist/proxy-endpoint.js

@@ -0,0 +1,147 @@
+import { authShapeHeaderName, PROXY_RESPONSE_MODES } from "./_contracts/index.js";
+export class ProxyEndpoint {
+    /** Non-secret half of the wire shape — declaration only. */
+    declaration;
+    /**
+     * Per-request secret half — auth value keyed by the same `name`.
+     * `null` for keyless (`ProxyEndpoint.none`) endpoints; `splitProxyEndpoints`
+     * filters those out so they never land in `secrets.proxyEndpointAuth`.
+     */
+    auth;
+    constructor(declaration, auth) {
+        this.declaration = declaration;
+        this.auth = auth;
+    }
+    /**
+     * Keyless endpoint. Routes through the aex managed proxy for
+     * unified egress, audit, and budget enforcement, but the BFF injects
+     * no auth header or query parameter. Use for public APIs (Wikimedia
+     * Commons, NASA Images, Library of Congress, NARA, GDELT, etc.).
+     */
+    static none(options) {
+        const common = buildCommonDeclaration(options, { type: "none" });
+        return new ProxyEndpoint(common, null);
+    }
+    /** Bearer-token endpoint. */
+    static bearer(options) {
+        const common = buildCommonDeclaration(options, { type: "bearer" });
+        requireNonEmpty(options.token, "ProxyEndpoint.bearer: token is required");
+        return new ProxyEndpoint(common, {
+            name: common.name,
+            value: { type: "bearer", token: options.token }
+        });
+    }
+    /** Basic-auth endpoint. */
+    static basic(options) {
+        const common = buildCommonDeclaration(options, { type: "basic" });
+        requireNonEmpty(options.username, "ProxyEndpoint.basic: username is required");
+        requireNonEmpty(options.password, "ProxyEndpoint.basic: password is required");
+        return new ProxyEndpoint(common, {
+            name: common.name,
+            value: { type: "basic", username: options.username, password: options.password }
+        });
+    }
+    /** Custom-header endpoint. */
+    static header(options) {
+        requireNonEmpty(options.header, "ProxyEndpoint.header: header is required");
+        const common = buildCommonDeclaration(options, { type: "header", name: options.header });
+        requireNonEmpty(options.value, "ProxyEndpoint.header: value is required");
+        return new ProxyEndpoint(common, {
+            name: common.name,
+            value: { type: "header", value: options.value }
+        });
+    }
+    /** Query-string-auth endpoint. */
+    static query(options) {
+        requireNonEmpty(options.query, "ProxyEndpoint.query: query is required");
+        const common = buildCommonDeclaration(options, { type: "query", name: options.query });
+        requireNonEmpty(options.value, "ProxyEndpoint.query: value is required");
+        return new ProxyEndpoint(common, {
+            name: common.name,
+            value: { type: "query", value: options.value }
+        });
+    }
+}
+/**
+ * Split a list of `ProxyEndpoint` instances into the public declarations
+ * (`proxyEndpoints[]`) and the per-request auth bundle
+ * (`secrets.proxyEndpointAuth[]`). Mirrors the way `submitRun` already
+ * splits `McpServer.headers` into `secrets.mcpServers[]`.
+ *
+ * Throws on duplicate endpoint names — names are the cross-reference
+ * key between the two halves and the BFF rejects collisions; failing
+ * here gives the caller a precise message at the call site instead of
+ * an opaque HTTP error.
+ */
+export function splitProxyEndpoints(inputs) {
+    if (inputs.length === 0) {
+        return { endpoints: [], auth: [] };
+    }
+    const endpoints = [];
+    const auth = [];
+    const seen = new Set();
+    for (let i = 0; i < inputs.length; i++) {
+        const entry = inputs[i];
+        if (!(entry instanceof ProxyEndpoint)) {
+            throw new TypeError(`proxyEndpoints[${i}] must be a ProxyEndpoint built via ProxyEndpoint.none / bearer / header / basic / query`);
+        }
+        if (seen.has(entry.declaration.name)) {
+            throw new Error(`proxyEndpoints duplicate name: ${entry.declaration.name}`);
+        }
+        seen.add(entry.declaration.name);
+        endpoints.push(entry.declaration);
+        if (entry.auth !== null) {
+            auth.push(entry.auth);
+        }
+    }
+    return { endpoints, auth };
+}
+function buildCommonDeclaration(options, authShape) {
+    requireNonEmpty(options.name, "ProxyEndpoint: name is required");
+    requireNonEmpty(options.baseUrl, "ProxyEndpoint: baseUrl is required");
+    if (!Array.isArray(options.allowMethods) || options.allowMethods.length === 0) {
+        throw new Error("ProxyEndpoint: allowMethods must be a non-empty array");
+    }
+    if (!Array.isArray(options.allowPathPrefixes) || options.allowPathPrefixes.length === 0) {
+        throw new Error("ProxyEndpoint: allowPathPrefixes must be a non-empty array");
+    }
+    if (options.responseMode !== undefined && !PROXY_RESPONSE_MODES.includes(options.responseMode)) {
+        throw new Error(`ProxyEndpoint: responseMode must be one of ${PROXY_RESPONSE_MODES.join(" | ")}`);
+    }
+    // Defence in depth: don't let the caller list the auth carrier
+    // header in `allowHeaders`. The BFF rejects this too, but a precise
+    // SDK-side error message is clearer.
+    if (options.allowHeaders) {
+        const carrier = authShapeHeaderName(authShape);
+        if (carrier) {
+            for (const h of options.allowHeaders) {
+                if (h.toLowerCase() === carrier) {
+                    throw new Error(`ProxyEndpoint: allowHeaders MUST NOT include the auth header "${h}" — ` +
+                        `it's set by the proxy on every request`);
+                }
+            }
+        }
+    }
+    return {
+        name: options.name,
+        baseUrl: options.baseUrl,
+        authShape,
+        allowMethods: options.allowMethods,
+        allowPathPrefixes: options.allowPathPrefixes,
+        ...(options.allowHeaders ? { allowHeaders: options.allowHeaders } : {}),
+        ...(options.responseMode ? { responseMode: options.responseMode } : {}),
+        ...(options.maxRequestBytes !== undefined ? { maxRequestBytes: options.maxRequestBytes } : {}),
+        ...(options.maxResponseBytes !== undefined ? { maxResponseBytes: options.maxResponseBytes } : {}),
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        ...(options.perCallBudget !== undefined ? { perCallBudget: options.perCallBudget } : {}),
+        ...(options.responseByteBudget !== undefined
+            ? { responseByteBudget: options.responseByteBudget }
+            : {})
+    };
+}
+function requireNonEmpty(value, message) {
+    if (typeof value !== "string" || !value) {
+        throw new Error(message);
+    }
+}
+//# sourceMappingURL=proxy-endpoint.js.map

package/dist/proxy-endpoint.js.map

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

package/dist/skill.d.ts

@@ -0,0 +1,117 @@
+import { type AssetRef, type FetchLike, type SkillRef } from "./_contracts/index.js";
+import { type SkillFiles } from "./bundle.js";
+/**
+ * One `Skill` class for skill bytes. `client.submitRun` 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(...)` and no `.upload(client)` — a URL is an
+ * ingestion source, not a persistent reference.
+ */
+export declare class Skill {
+    #private;
+    /**
+     * Internal constructor. Use `Skill.fromFiles` or `Skill.fromPath` to create
+     * instances.
+     */
+    private constructor();
+    /**
+     * The wire-level reference. Returns the SDK-private draft shape for
+     * un-materialized skills (kind:"draft", with name + contentHash).
+     * `client.submitRun` walks these and uploads them before the run
+     * lands.
+     */
+    get ref(): AssetRef | DraftSkillRef;
+    /** True for local-bytes Skills that haven't been uploaded yet. */
+    get isDraft(): boolean;
+    get isConsumed(): boolean;
+    /**
+     * 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.submitRun` materializes
+     * these before the run lands.
+     */
+    static fromFiles(args: {
+        readonly name: string;
+        readonly files: SkillFiles;
+    }): Promise<Skill>;
+    /**
+     * Read a local directory and build a draft Skill. Symlinks and
+     * non-regular files are skipped. Node-only.
+     */
+    static fromPath(rootDir: string, args: {
+        readonly name: string;
+    }): Promise<Skill>;
+    /**
+     * 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.submitRun` snapshots the bytes into the run.
+     *
+     * Universal (Node 18+ / browser): requires a global `fetch`, or pass one.
+     */
+    static fromUrl(url: string, args: {
+        readonly name: string;
+        readonly sha256?: string;
+        readonly timeoutMs?: number;
+        readonly fetch?: FetchLike;
+    }): Promise<Skill>;
+    /**
+     * Reference a skill already uploaded to the workspace catalog
+     * (`aex skills upload` / `operations.createSkillBundle`) 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.submitRun({ ..., 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: {
+        readonly name: string;
+        readonly hash?: string | null;
+    }): Skill;
+    /**
+     * Internal: yield the draft's bytes + metadata so `client.submitRun`
+     * can upload the asset. After this returns, the Skill is marked consumed
+     * so a second submitRun call against the same instance throws
+     * (avoid silently re-uploading; explicit re-construction is the
+     * supported retry pattern).
+     *
+     * Returns undefined for already-materialized Skills.
+     */
+    _takeDraftBundle(): {
+        name: string;
+        contentHash: string;
+        bytes: Uint8Array;
+    } | undefined;
+    toJSON(): SkillRef;
+}
+/**
+ * SDK-internal draft skill marker. Never reaches the wire; the
+ * materialize step inside `client.submitRun` converts these to
+ * `kind:"asset"` refs.
+ */
+export interface DraftSkillRef {
+    readonly kind: "draft";
+    readonly name: string;
+    readonly contentHash: string;
+}