antpath 0.4.0 → 0.4.2

package/dist/_shared/blueprint.d.ts

@@ -0,0 +1,263 @@
+/**
+ * The flat agent-first composition surface that replaces `Template`.
+ *
+ * Concepts (mirrored in references/architecture-decisions.md):
+ *
+ *   - `SkillRef` is the wire-level reference to a skill — either an
+ *     `skl_*` id pointing at a workspace-uploaded bundle, or a
+ *     `{vendor, skillId, version}` reference to a provider built-in.
+ *     The two shapes are discriminated by `kind` so consumers branch
+ *     mechanically and providers can never accidentally be looked up
+ *     in `skill_bundles`.
+ *
+ *   - `McpServerRef` is the non-secret part of an MCP server declaration:
+ *     `name` and `url`. Bearer / cookie / per-request headers travel in
+ *     the run's vaulted `secrets.mcpServers` block keyed by the same
+ *     `name`, and never enter the hashed submission payload or the
+ *     run snapshot.
+ *
+ *   - `Blueprint` is what the user authors. It excludes
+ *     `secrets`/`idempotencyKey`/`signal` so it can be safely persisted
+ *     to disk (e.g. `antpath run --config run.json`), shared between
+ *     teams, or curried via `defineRun` without leaking credentials.
+ *     Strings inside a Blueprint are **already resolved** — there are
+ *     no `{{variable}}` placeholders, no template language, no late
+ *     binding. The whole point of `defineRun` is to make the resolution
+ *     happen at the TS call site where the IDE can type-check it.
+ *
+ *   - Skill bundle validation lives here so the SDK (zipping locally),
+ *     the BFF (server-side unzip + manifest extraction), and the worker
+ *     (sanity-check before mounting) share a single source of truth for
+ *     the limits, the path normaliser, and the manifest invariants. The
+ *     DB CHECK constraints on `skill_bundles.manifest` mirror these.
+ *
+ * See `references/architecture-decisions.md` (Composition primitives,
+ * Skill custody) and `references/development-principles.md` (Agent-first
+ * surface design) for the rationale.
+ */
+import type { JsonValue, PlatformCleanupPolicy, PlatformProxyEndpoint, PlatformTemplateEnvironment } from "./submission.js";
+/**
+ * Mirrors the CHECK constraint
+ * `skill_bundles_id_format_chk = check (id ~ '^skl_[A-Za-z0-9_-]{8,128}$')`
+ * defined in supabase/migrations/20260512000000_skill_bundles.sql. Keep
+ * the two in lockstep — the DB is the ultimate authority.
+ */
+export declare const SKILL_ID_PATTERN: RegExp;
+/**
+ * Human-readable, workspace-scoped name. Lowercase, kebab-friendly,
+ * 1..128 chars. The DB enforces the length bound via
+ * `skill_bundles_name_len_chk`; this regex tightens the SDK/CLI input
+ * surface so callers fail at the boundary rather than in the BFF.
+ */
+export declare const SKILL_NAME_PATTERN: RegExp;
+/**
+ * Hard caps applied at upload time. The SDK enforces these before
+ * computing the zip hash so a clearly-too-big bundle never wastes
+ * bytes-on-the-wire; the BFF re-enforces server-side because the SDK
+ * is untrusted. Numbers are deliberately conservative for the MVP and
+ * can be tuned later; keep this object as the single tuning point.
+ */
+export declare const SKILL_BUNDLE_LIMITS: {
+    /** Compressed (.zip) ceiling. */
+    readonly maxCompressedBytes: number;
+    /** Sum of uncompressed file sizes. */
+    readonly maxDecompressedBytes: number;
+    /** Number of regular file entries (directories don't count). */
+    readonly maxFiles: 1000;
+    /** Maximum directory nesting depth — `a/b/c/d` has depth 4. */
+    readonly maxDepth: 16;
+    /** Single-entry path length cap. */
+    readonly maxPathLength: 512;
+    /** Stored file mode for ordinary files. */
+    readonly defaultFileMode: 420;
+    /** Stored directory mode. */
+    readonly defaultDirMode: 493;
+};
+export type SkillRef = WorkspaceSkillRef | ProviderSkillRef;
+export interface WorkspaceSkillRef {
+    readonly kind: "workspace";
+    readonly id: string;
+}
+export interface ProviderSkillRef {
+    readonly kind: "provider";
+    readonly vendor: "anthropic" | "custom";
+    readonly skillId: string;
+    readonly version?: string;
+}
+export declare function isWorkspaceSkillRef(ref: SkillRef): ref is WorkspaceSkillRef;
+export declare function isProviderSkillRef(ref: SkillRef): ref is ProviderSkillRef;
+/**
+ * Parse a `SkillRef` from untrusted input. Used by the BFF run parser
+ * and by the operations module when deserialising API responses. Throws
+ * with a precise path so the caller can surface a usable error.
+ */
+export declare function parseSkillRef(input: unknown, path: string): SkillRef;
+/**
+ * Manifest entry persisted in `skill_bundles.manifest` and
+ * `run_skill_snapshots.manifest`. `path` is forward-slash, relative,
+ * normalised. `mode` is the stored POSIX mode (sanitised, NOT the user's
+ * filesystem mode) — see `SKILL_BUNDLE_LIMITS.defaultFileMode`.
+ */
+export interface SkillBundleEntry {
+    readonly path: string;
+    readonly size: number;
+    readonly mode: number;
+}
+export interface SkillBundleManifest {
+    readonly entries: readonly SkillBundleEntry[];
+    /** Total uncompressed bytes (sum of `entries[i].size`). */
+    readonly totalSize: number;
+    /** Number of file entries. Equals `entries.length` by construction. */
+    readonly fileCount: number;
+}
+export declare class SkillBundleValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Reject input paths that try to escape the bundle root or smuggle
+ * platform-specific syntax. Returns the canonical forward-slash
+ * relative path; never returns paths starting or ending with `/`.
+ *
+ * Rejects:
+ *   - empty strings and pure whitespace
+ *   - absolute paths (`/foo`, `C:\foo`, `\\server\share`)
+ *   - backslash separators (Windows)
+ *   - `..` segments anywhere in the path
+ *   - `.` segments anywhere except a leading bare `.`
+ *   - paths whose length exceeds `SKILL_BUNDLE_LIMITS.maxPathLength`
+ *   - paths whose depth exceeds `SKILL_BUNDLE_LIMITS.maxDepth`
+ *   - NUL bytes
+ */
+export declare function normaliseSkillBundlePath(input: string): string;
+/**
+ * Validate one manifest entry: normalises the path, bounds the size,
+ * and sanitises the mode to one of {defaultFileMode, defaultDirMode}.
+ * The bundle is files-only, so any non-regular-file entry is rejected
+ * upstream by the caller (zip parser must skip symlinks, device files,
+ * etc. before reaching this function).
+ */
+export declare function validateSkillBundleEntry(input: {
+    readonly path: string;
+    readonly size: number;
+    readonly mode?: number;
+}): SkillBundleEntry;
+/**
+ * Validate a full manifest. Enforces:
+ *   - entries is a non-empty array
+ *   - `SKILL.md` exists at the bundle root (Claude's auto-discovery key)
+ *   - file count <= maxFiles
+ *   - total uncompressed size <= maxDecompressedBytes
+ *   - per-entry validation (see `validateSkillBundleEntry`)
+ *   - no duplicate paths
+ *
+ * Returns a canonical manifest with totals computed.
+ */
+export declare function validateSkillBundleManifest(input: ReadonlyArray<{
+    readonly path: string;
+    readonly size: number;
+    readonly mode?: number;
+}>): SkillBundleManifest;
+/**
+ * The non-secret half of an MCP server declaration. This is what enters
+ * the hashed submission, the run snapshot, and any audit log. `name`
+ * keys into `secrets.mcpServers` for the per-request headers.
+ */
+export interface McpServerRef {
+    readonly name: string;
+    readonly url: string;
+}
+export declare const MCP_SERVER_NAME_PATTERN: RegExp;
+/**
+ * A Blueprint-level MCP entry. The user is free to supply headers
+ * inline; the SDK splits the call site cleanly at submission time so
+ * the Authorization (or other auth-bearing) header never enters the
+ * non-secret wire payload.
+ */
+export interface BlueprintMcpServer extends McpServerRef {
+    readonly headers?: Readonly<Record<string, string>>;
+}
+export declare function parseMcpServerRef(input: unknown, path: string): McpServerRef;
+/**
+ * What the user authors and passes to `client.submitRun({...blueprint, secrets})`.
+ *
+ * Blueprint deliberately EXCLUDES `secrets`, `idempotencyKey`, and
+ * `signal` so:
+ *   - `defineRun((p) => Blueprint)` can be reused across calls without
+ *     re-injecting an API key,
+ *   - a Blueprint can be JSON-serialised to disk (`antpath run --config
+ *     run.json`) without ever encoding a credential,
+ *   - audit / replay tooling can persist a Blueprint as-is.
+ */
+export interface Blueprint {
+    readonly model: string;
+    readonly system?: string;
+    readonly prompt: string | readonly string[];
+    readonly skills?: readonly SkillRef[];
+    readonly mcpServers?: readonly BlueprintMcpServer[];
+    readonly environment?: PlatformTemplateEnvironment;
+    readonly cleanup?: PlatformCleanupPolicy;
+    readonly proxyEndpoints?: readonly PlatformProxyEndpoint[];
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
+}
+/**
+ * Currier for parameterised Blueprints.
+ *
+ * ```ts
+ * const investigate = defineRun((p: { repo: string; issue: number }) => ({
+ *   model: "claude-sonnet-4-5-20250929",
+ *   system: `You work on ${p.repo}.`,
+ *   prompt: `Investigate issue #${p.issue}.`,
+ *   skills: [rules],
+ * }));
+ * await client.submitRun({
+ *   ...investigate({ repo: "antpath", issue: 123 }),
+ *   secrets: { anthropic: { apiKey } },
+ * });
+ * ```
+ *
+ * The returned function is referentially transparent — it just calls
+ * the provided producer. The wrapper exists for two reasons: (a) a
+ * single named entry point makes IDEs surface the type of the inner
+ * blueprint at the call site, and (b) it pins the "no late binding"
+ * contract — strings inside the Blueprint are resolved by the TS call
+ * site, not by a server-side template engine.
+ */
+export declare function defineRun<TParams>(producer: (params: TParams) => Blueprint): (params: TParams) => Blueprint;
+/**
+ * Parse a Blueprint from JSON. Defensive — used by the host CLI to
+ * load `--config run.json`. Throws with the JSON path that failed so
+ * a user can fix their file. Headers are preserved here and split out
+ * later by the SDK normalisation step.
+ */
+export declare function parseBlueprint(input: unknown): Blueprint;
+/**
+ * Result of splitting a `Blueprint` into the non-secret submission and
+ * the secret MCP-headers bundle. The SDK calls this just before posting
+ * to /api/runs: the `submission` half is what the BFF hashes for
+ * idempotency, the `mcpServerSecrets` half is what enters the Vault.
+ *
+ * `prompt` is normalised to `readonly string[]` (single-string callers
+ * get wrapped in a length-1 array) so the wire payload, the worker, and
+ * the audit log don't have to re-handle two shapes.
+ */
+export interface NormalisedBlueprint {
+    readonly model: string;
+    readonly system?: string;
+    readonly prompt: readonly string[];
+    readonly skills: readonly SkillRef[];
+    readonly mcpServers: readonly McpServerRef[];
+    readonly environment?: PlatformTemplateEnvironment;
+    readonly cleanup?: PlatformCleanupPolicy;
+    readonly proxyEndpoints?: readonly PlatformProxyEndpoint[];
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
+    /**
+     * MCP servers whose Blueprint entry carried `headers`. Keyed by the
+     * `name` that appears in `mcpServers` so the BFF can pair them up.
+     */
+    readonly mcpServerSecrets: ReadonlyArray<{
+        readonly name: string;
+        readonly url: string;
+        readonly headers: Readonly<Record<string, string>>;
+    }>;
+}
+export declare function normaliseBlueprint(blueprint: Blueprint): NormalisedBlueprint;

package/dist/_shared/blueprint.js

@@ -0,0 +1,512 @@
+/**
+ * The flat agent-first composition surface that replaces `Template`.
+ *
+ * Concepts (mirrored in references/architecture-decisions.md):
+ *
+ *   - `SkillRef` is the wire-level reference to a skill — either an
+ *     `skl_*` id pointing at a workspace-uploaded bundle, or a
+ *     `{vendor, skillId, version}` reference to a provider built-in.
+ *     The two shapes are discriminated by `kind` so consumers branch
+ *     mechanically and providers can never accidentally be looked up
+ *     in `skill_bundles`.
+ *
+ *   - `McpServerRef` is the non-secret part of an MCP server declaration:
+ *     `name` and `url`. Bearer / cookie / per-request headers travel in
+ *     the run's vaulted `secrets.mcpServers` block keyed by the same
+ *     `name`, and never enter the hashed submission payload or the
+ *     run snapshot.
+ *
+ *   - `Blueprint` is what the user authors. It excludes
+ *     `secrets`/`idempotencyKey`/`signal` so it can be safely persisted
+ *     to disk (e.g. `antpath run --config run.json`), shared between
+ *     teams, or curried via `defineRun` without leaking credentials.
+ *     Strings inside a Blueprint are **already resolved** — there are
+ *     no `{{variable}}` placeholders, no template language, no late
+ *     binding. The whole point of `defineRun` is to make the resolution
+ *     happen at the TS call site where the IDE can type-check it.
+ *
+ *   - Skill bundle validation lives here so the SDK (zipping locally),
+ *     the BFF (server-side unzip + manifest extraction), and the worker
+ *     (sanity-check before mounting) share a single source of truth for
+ *     the limits, the path normaliser, and the manifest invariants. The
+ *     DB CHECK constraints on `skill_bundles.manifest` mirror these.
+ *
+ * See `references/architecture-decisions.md` (Composition primitives,
+ * Skill custody) and `references/development-principles.md` (Agent-first
+ * surface design) for the rationale.
+ */
+// ---------------------------------------------------------------------------
+// Skill ID + name format
+// ---------------------------------------------------------------------------
+/**
+ * Mirrors the CHECK constraint
+ * `skill_bundles_id_format_chk = check (id ~ '^skl_[A-Za-z0-9_-]{8,128}$')`
+ * defined in supabase/migrations/20260512000000_skill_bundles.sql. Keep
+ * the two in lockstep — the DB is the ultimate authority.
+ */
+export const SKILL_ID_PATTERN = /^skl_[A-Za-z0-9_-]{8,128}$/;
+/**
+ * Human-readable, workspace-scoped name. Lowercase, kebab-friendly,
+ * 1..128 chars. The DB enforces the length bound via
+ * `skill_bundles_name_len_chk`; this regex tightens the SDK/CLI input
+ * surface so callers fail at the boundary rather than in the BFF.
+ */
+export const SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,127}$/;
+// ---------------------------------------------------------------------------
+// Skill bundle limits (uploaded bundles)
+// ---------------------------------------------------------------------------
+/**
+ * Hard caps applied at upload time. The SDK enforces these before
+ * computing the zip hash so a clearly-too-big bundle never wastes
+ * bytes-on-the-wire; the BFF re-enforces server-side because the SDK
+ * is untrusted. Numbers are deliberately conservative for the MVP and
+ * can be tuned later; keep this object as the single tuning point.
+ */
+export const SKILL_BUNDLE_LIMITS = {
+    /** Compressed (.zip) ceiling. */
+    maxCompressedBytes: 10 * 1024 * 1024,
+    /** Sum of uncompressed file sizes. */
+    maxDecompressedBytes: 50 * 1024 * 1024,
+    /** Number of regular file entries (directories don't count). */
+    maxFiles: 1000,
+    /** Maximum directory nesting depth — `a/b/c/d` has depth 4. */
+    maxDepth: 16,
+    /** Single-entry path length cap. */
+    maxPathLength: 512,
+    /** Stored file mode for ordinary files. */
+    defaultFileMode: 0o644,
+    /** Stored directory mode. */
+    defaultDirMode: 0o755
+};
+export function isWorkspaceSkillRef(ref) {
+    return ref.kind === "workspace";
+}
+export function isProviderSkillRef(ref) {
+    return ref.kind === "provider";
+}
+/**
+ * Parse a `SkillRef` from untrusted input. Used by the BFF run parser
+ * and by the operations module when deserialising API responses. Throws
+ * with a precise path so the caller can surface a usable error.
+ */
+export function parseSkillRef(input, path) {
+    if (input === null || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error(`${path} must be a SkillRef object`);
+    }
+    const record = input;
+    const kind = record.kind;
+    if (kind === "workspace") {
+        for (const key of Object.keys(record)) {
+            if (key !== "kind" && key !== "id") {
+                throw new Error(`${path} contains unexpected field for workspace SkillRef: ${key}`);
+            }
+        }
+        const id = record.id;
+        if (typeof id !== "string" || !SKILL_ID_PATTERN.test(id)) {
+            throw new Error(`${path}.id must match ${SKILL_ID_PATTERN.source}`);
+        }
+        return { kind: "workspace", id };
+    }
+    if (kind === "provider") {
+        for (const key of Object.keys(record)) {
+            if (key !== "kind" && key !== "vendor" && key !== "skillId" && key !== "version") {
+                throw new Error(`${path} contains unexpected field for provider SkillRef: ${key}`);
+            }
+        }
+        const vendor = record.vendor;
+        if (vendor !== "anthropic" && vendor !== "custom") {
+            throw new Error(`${path}.vendor must be 'anthropic' or 'custom'`);
+        }
+        const skillId = record.skillId;
+        if (typeof skillId !== "string" || skillId.length === 0 || skillId.length > 256) {
+            throw new Error(`${path}.skillId must be a non-empty string (<= 256 chars)`);
+        }
+        const version = record.version;
+        if (version !== undefined && (typeof version !== "string" || version.length === 0 || version.length > 64)) {
+            throw new Error(`${path}.version, when provided, must be a non-empty string (<= 64 chars)`);
+        }
+        return {
+            kind: "provider",
+            vendor,
+            skillId,
+            ...(version !== undefined ? { version } : {})
+        };
+    }
+    throw new Error(`${path}.kind must be 'workspace' or 'provider'`);
+}
+export class SkillBundleValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SkillBundleValidationError";
+    }
+}
+/**
+ * Reject input paths that try to escape the bundle root or smuggle
+ * platform-specific syntax. Returns the canonical forward-slash
+ * relative path; never returns paths starting or ending with `/`.
+ *
+ * Rejects:
+ *   - empty strings and pure whitespace
+ *   - absolute paths (`/foo`, `C:\foo`, `\\server\share`)
+ *   - backslash separators (Windows)
+ *   - `..` segments anywhere in the path
+ *   - `.` segments anywhere except a leading bare `.`
+ *   - paths whose length exceeds `SKILL_BUNDLE_LIMITS.maxPathLength`
+ *   - paths whose depth exceeds `SKILL_BUNDLE_LIMITS.maxDepth`
+ *   - NUL bytes
+ */
+export function normaliseSkillBundlePath(input) {
+    if (typeof input !== "string") {
+        throw new SkillBundleValidationError("bundle entry path must be a string");
+    }
+    if (input.length === 0 || input.trim().length === 0) {
+        throw new SkillBundleValidationError("bundle entry path must be non-empty");
+    }
+    if (input.length > SKILL_BUNDLE_LIMITS.maxPathLength) {
+        throw new SkillBundleValidationError(`bundle entry path exceeds maxPathLength (${SKILL_BUNDLE_LIMITS.maxPathLength}): ${input}`);
+    }
+    if (input.includes("\0")) {
+        throw new SkillBundleValidationError(`bundle entry path contains NUL byte: ${JSON.stringify(input)}`);
+    }
+    if (input.includes("\\")) {
+        throw new SkillBundleValidationError(`bundle entry path uses backslash separator: ${input}`);
+    }
+    if (/^[A-Za-z]:[\\/]/.test(input)) {
+        throw new SkillBundleValidationError(`bundle entry path uses a drive letter: ${input}`);
+    }
+    if (input.startsWith("/")) {
+        throw new SkillBundleValidationError(`bundle entry path must be relative: ${input}`);
+    }
+    // Reject trailing slash so callers cannot disguise directory entries
+    // as files. The manifest is files-only.
+    if (input.endsWith("/")) {
+        throw new SkillBundleValidationError(`bundle entry path must not end with '/': ${input}`);
+    }
+    const segments = input.split("/");
+    for (const segment of segments) {
+        if (segment === "..") {
+            throw new SkillBundleValidationError(`bundle entry path contains '..' segment: ${input}`);
+        }
+        if (segment === "." || segment === "") {
+            throw new SkillBundleValidationError(`bundle entry path contains empty or '.' segment: ${input}`);
+        }
+    }
+    if (segments.length > SKILL_BUNDLE_LIMITS.maxDepth) {
+        throw new SkillBundleValidationError(`bundle entry path exceeds maxDepth (${SKILL_BUNDLE_LIMITS.maxDepth}): ${input}`);
+    }
+    return input;
+}
+/**
+ * Validate one manifest entry: normalises the path, bounds the size,
+ * and sanitises the mode to one of {defaultFileMode, defaultDirMode}.
+ * The bundle is files-only, so any non-regular-file entry is rejected
+ * upstream by the caller (zip parser must skip symlinks, device files,
+ * etc. before reaching this function).
+ */
+export function validateSkillBundleEntry(input) {
+    const path = normaliseSkillBundlePath(input.path);
+    if (!Number.isFinite(input.size) || !Number.isInteger(input.size) || input.size < 0) {
+        throw new SkillBundleValidationError(`bundle entry size must be a non-negative integer (${path})`);
+    }
+    if (input.size > SKILL_BUNDLE_LIMITS.maxDecompressedBytes) {
+        throw new SkillBundleValidationError(`bundle entry size exceeds maxDecompressedBytes (${SKILL_BUNDLE_LIMITS.maxDecompressedBytes}): ${path}`);
+    }
+    // Sanitise the stored mode. Executable bit is implied by runtime
+    // convention; we never persist arbitrary chmod from the user's FS.
+    const mode = (input.mode ?? SKILL_BUNDLE_LIMITS.defaultFileMode) & 0o777;
+    if (mode !== SKILL_BUNDLE_LIMITS.defaultFileMode && mode !== SKILL_BUNDLE_LIMITS.defaultDirMode) {
+        return { path, size: input.size, mode: SKILL_BUNDLE_LIMITS.defaultFileMode };
+    }
+    return { path, size: input.size, mode };
+}
+/**
+ * Validate a full manifest. Enforces:
+ *   - entries is a non-empty array
+ *   - `SKILL.md` exists at the bundle root (Claude's auto-discovery key)
+ *   - file count <= maxFiles
+ *   - total uncompressed size <= maxDecompressedBytes
+ *   - per-entry validation (see `validateSkillBundleEntry`)
+ *   - no duplicate paths
+ *
+ * Returns a canonical manifest with totals computed.
+ */
+export function validateSkillBundleManifest(input) {
+    if (!Array.isArray(input) || input.length === 0) {
+        throw new SkillBundleValidationError("bundle manifest must be a non-empty array of entries");
+    }
+    if (input.length > SKILL_BUNDLE_LIMITS.maxFiles) {
+        throw new SkillBundleValidationError(`bundle exceeds maxFiles (${SKILL_BUNDLE_LIMITS.maxFiles}): got ${input.length}`);
+    }
+    const seen = new Set();
+    const entries = [];
+    let totalSize = 0;
+    let hasSkillMd = false;
+    for (const raw of input) {
+        const entry = validateSkillBundleEntry(raw);
+        if (seen.has(entry.path)) {
+            throw new SkillBundleValidationError(`bundle manifest contains duplicate path: ${entry.path}`);
+        }
+        seen.add(entry.path);
+        if (entry.path === "SKILL.md") {
+            hasSkillMd = true;
+        }
+        totalSize += entry.size;
+        if (totalSize > SKILL_BUNDLE_LIMITS.maxDecompressedBytes) {
+            throw new SkillBundleValidationError(`bundle total size exceeds maxDecompressedBytes (${SKILL_BUNDLE_LIMITS.maxDecompressedBytes})`);
+        }
+        entries.push(entry);
+    }
+    if (!hasSkillMd) {
+        throw new SkillBundleValidationError("bundle manifest must contain a 'SKILL.md' entry at the bundle root");
+    }
+    return { entries, totalSize, fileCount: entries.length };
+}
+export const MCP_SERVER_NAME_PATTERN = /^[a-z][a-z0-9_-]{0,62}$/;
+export function parseMcpServerRef(input, path) {
+    if (input === null || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error(`${path} must be an object`);
+    }
+    const record = input;
+    // Headers belong on `BlueprintMcpServer`, not the non-secret wire ref;
+    // and the wire `submission.mcpServers` must NEVER contain headers. So
+    // reject any field other than {name,url} explicitly to make a caller
+    // accidentally inlining `headers` into the non-secret half fail loudly
+    // instead of silently dropping the field. `parseBlueprintMcpServer`
+    // handles the headers case separately for Blueprint-level entries.
+    for (const key of Object.keys(record)) {
+        if (key !== "name" && key !== "url") {
+            throw new Error(`${path}.${key} is not an allowed field for McpServerRef; permitted: name, url`);
+        }
+    }
+    const name = record.name;
+    if (typeof name !== "string" || !MCP_SERVER_NAME_PATTERN.test(name)) {
+        throw new Error(`${path}.name must match ${MCP_SERVER_NAME_PATTERN.source}`);
+    }
+    const url = record.url;
+    if (typeof url !== "string" || url.length === 0) {
+        throw new Error(`${path}.url must be a non-empty string`);
+    }
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+            throw new Error(`${path}.url must use http or https (got ${parsed.protocol})`);
+        }
+        // Auth belongs in `secrets.mcpServers[i].headers`, never in the URL
+        // itself. A `https://user:pass@host` style URL would be persisted in
+        // the non-secret run snapshot and hashed into the idempotency key —
+        // both unacceptable for credential material.
+        if (parsed.username !== "" || parsed.password !== "") {
+            throw new Error(`${path}.url must not contain userinfo (username/password); use secrets.mcpServers[].headers for auth`);
+        }
+    }
+    catch (cause) {
+        if (cause instanceof Error && cause.message.startsWith(path)) {
+            throw cause;
+        }
+        throw new Error(`${path}.url is not a valid URL: ${url}`);
+    }
+    return { name, url };
+}
+/**
+ * Strict parser for Blueprint-level MCP server entries. Allows only the
+ * `{name, url, headers?}` shape — used by `parseBlueprintMcpServers` so
+ * a Blueprint that came from `--config run.json` cannot smuggle
+ * unrelated fields past the parser.
+ */
+function parseBlueprintMcpServerRef(input, path) {
+    if (input === null || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error(`${path} must be an object`);
+    }
+    const record = input;
+    for (const key of Object.keys(record)) {
+        if (key !== "name" && key !== "url" && key !== "headers") {
+            throw new Error(`${path}.${key} is not an allowed field for BlueprintMcpServer; permitted: name, url, headers`);
+        }
+    }
+    // Reuse the {name,url} validator by passing the stripped object.
+    const stripped = { name: record.name, url: record.url };
+    const ref = parseMcpServerRef(stripped, path);
+    const rawHeaders = record.headers;
+    if (rawHeaders === undefined) {
+        return ref;
+    }
+    if (rawHeaders === null || typeof rawHeaders !== "object" || Array.isArray(rawHeaders)) {
+        throw new Error(`${path}.headers, when provided, must be a string-keyed object`);
+    }
+    const headers = {};
+    for (const [hk, hv] of Object.entries(rawHeaders)) {
+        if (typeof hv !== "string") {
+            throw new Error(`${path}.headers.${hk} must be a string`);
+        }
+        headers[hk] = hv;
+    }
+    return { ...ref, headers };
+}
+/**
+ * Currier for parameterised Blueprints.
+ *
+ * ```ts
+ * const investigate = defineRun((p: { repo: string; issue: number }) => ({
+ *   model: "claude-sonnet-4-5-20250929",
+ *   system: `You work on ${p.repo}.`,
+ *   prompt: `Investigate issue #${p.issue}.`,
+ *   skills: [rules],
+ * }));
+ * await client.submitRun({
+ *   ...investigate({ repo: "antpath", issue: 123 }),
+ *   secrets: { anthropic: { apiKey } },
+ * });
+ * ```
+ *
+ * The returned function is referentially transparent — it just calls
+ * the provided producer. The wrapper exists for two reasons: (a) a
+ * single named entry point makes IDEs surface the type of the inner
+ * blueprint at the call site, and (b) it pins the "no late binding"
+ * contract — strings inside the Blueprint are resolved by the TS call
+ * site, not by a server-side template engine.
+ */
+export function defineRun(producer) {
+    if (typeof producer !== "function") {
+        throw new TypeError("defineRun expects a function");
+    }
+    return (params) => producer(params);
+}
+// ---------------------------------------------------------------------------
+// Blueprint parser (used by CLI to load `run.json`)
+// ---------------------------------------------------------------------------
+/**
+ * Parse a Blueprint from JSON. Defensive — used by the host CLI to
+ * load `--config run.json`. Throws with the JSON path that failed so
+ * a user can fix their file. Headers are preserved here and split out
+ * later by the SDK normalisation step.
+ */
+export function parseBlueprint(input) {
+    if (input === null || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error("Blueprint must be an object");
+    }
+    const record = input;
+    const allowed = new Set([
+        "model",
+        "system",
+        "prompt",
+        "skills",
+        "mcpServers",
+        "environment",
+        "cleanup",
+        "proxyEndpoints",
+        "metadata"
+    ]);
+    for (const key of Object.keys(record)) {
+        if (!allowed.has(key)) {
+            throw new Error(`Blueprint contains unexpected field: ${key}`);
+        }
+    }
+    const model = record.model;
+    if (typeof model !== "string" || model.length === 0) {
+        throw new Error("Blueprint.model must be a non-empty string");
+    }
+    const system = record.system;
+    if (system !== undefined && typeof system !== "string") {
+        throw new Error("Blueprint.system, when provided, must be a string");
+    }
+    const prompt = parseBlueprintPrompt(record.prompt);
+    const skills = parseBlueprintSkills(record.skills);
+    const mcpServers = parseBlueprintMcpServers(record.mcpServers);
+    return {
+        model,
+        ...(system !== undefined ? { system } : {}),
+        prompt,
+        ...(skills !== undefined ? { skills } : {}),
+        ...(mcpServers !== undefined ? { mcpServers } : {}),
+        // environment / cleanup / proxyEndpoints / metadata: passed through
+        // as-is — the BFF revalidates them via `parseFlatRunSubmissionRequest`,
+        // so duplicating the heavyweight parsers here would mean two sources
+        // of truth. The CLI surfaces structural errors at submission time.
+        ...(record.environment !== undefined
+            ? { environment: record.environment }
+            : {}),
+        ...(record.cleanup !== undefined
+            ? { cleanup: record.cleanup }
+            : {}),
+        ...(record.proxyEndpoints !== undefined
+            ? { proxyEndpoints: record.proxyEndpoints }
+            : {}),
+        ...(record.metadata !== undefined
+            ? { metadata: record.metadata }
+            : {})
+    };
+}
+function parseBlueprintPrompt(value) {
+    if (typeof value === "string") {
+        if (value.length === 0) {
+            throw new Error("Blueprint.prompt must be a non-empty string");
+        }
+        return value;
+    }
+    if (Array.isArray(value)) {
+        const arr = [];
+        for (let i = 0; i < value.length; i++) {
+            const item = value[i];
+            if (typeof item !== "string" || item.length === 0) {
+                throw new Error(`Blueprint.prompt[${i}] must be a non-empty string`);
+            }
+            arr.push(item);
+        }
+        if (arr.length === 0) {
+            throw new Error("Blueprint.prompt must be a non-empty string or array of strings");
+        }
+        return arr;
+    }
+    throw new Error("Blueprint.prompt must be a string or array of strings");
+}
+function parseBlueprintSkills(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw new Error("Blueprint.skills must be an array");
+    }
+    return value.map((item, index) => parseSkillRef(item, `Blueprint.skills[${index}]`));
+}
+function parseBlueprintMcpServers(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw new Error("Blueprint.mcpServers must be an array");
+    }
+    const seen = new Set();
+    return value.map((item, index) => {
+        const entry = parseBlueprintMcpServerRef(item, `Blueprint.mcpServers[${index}]`);
+        if (seen.has(entry.name)) {
+            throw new Error(`Blueprint.mcpServers duplicate name: ${entry.name}`);
+        }
+        seen.add(entry.name);
+        return entry;
+    });
+}
+export function normaliseBlueprint(blueprint) {
+    const prompt = typeof blueprint.prompt === "string" ? [blueprint.prompt] : blueprint.prompt;
+    const skills = blueprint.skills ?? [];
+    const mcpServers = [];
+    const mcpServerSecrets = [];
+    for (const entry of blueprint.mcpServers ?? []) {
+        mcpServers.push({ name: entry.name, url: entry.url });
+        if (entry.headers !== undefined) {
+            mcpServerSecrets.push({ name: entry.name, url: entry.url, headers: entry.headers });
+        }
+    }
+    return {
+        model: blueprint.model,
+        ...(blueprint.system !== undefined ? { system: blueprint.system } : {}),
+        prompt,
+        skills,
+        mcpServers,
+        ...(blueprint.environment !== undefined ? { environment: blueprint.environment } : {}),
+        ...(blueprint.cleanup !== undefined ? { cleanup: blueprint.cleanup } : {}),
+        ...(blueprint.proxyEndpoints !== undefined ? { proxyEndpoints: blueprint.proxyEndpoints } : {}),
+        ...(blueprint.metadata !== undefined ? { metadata: blueprint.metadata } : {}),
+        mcpServerSecrets
+    };
+}
+//# sourceMappingURL=blueprint.js.map

package/dist/_shared/http.js

@@ -31,7 +31,13 @@ export class HttpClient {
             ...normalizeHeaders(init.headers)
         };
         if (init.body !== undefined && init.body !== null && !headers["content-type"]) {
-            headers["content-type"] = "application/json";
+            // Default to JSON only for string-shaped bodies. FormData / Blob /
+            // ArrayBuffer / streams set their own content-type (and FormData
+            // specifically needs fetch to compute the multipart boundary), so
+            // we leave content-type untouched for non-string bodies.
+            if (typeof init.body === "string") {
+                headers["content-type"] = "application/json";
+            }
         }
         const response = await this.#fetch(url, { ...init, headers });
         const body = await readJson(response);

package/dist/_shared/index.d.ts

@@ -10,6 +10,7 @@ export * from "./stable.js";
 export * from "./sdk-secrets.js";
 export * from "./sdk-errors.js";
 export * from "./template/index.js";
+export * from "./blueprint.js";
 export * from "./runtime-types.js";
 export * from "./known-events.js";
 export * from "./http.js";

package/dist/_shared/index.js

@@ -12,6 +12,7 @@ export * from "./stable.js";
 export * from "./sdk-secrets.js";
 export * from "./sdk-errors.js";
 export * from "./template/index.js";
+export * from "./blueprint.js";
 export * from "./runtime-types.js";
 export * from "./known-events.js";
 export * from "./http.js";

package/dist/_shared/operations.d.ts

@@ -1,6 +1,6 @@
 import type { HttpClient } from "./http.js";
-import type { Output, Run, RunEvent, SignedOutputLink, WhoAmI } from "./runtime-types.js";
-import type { PlatformRunSubmissionInput } from "./submission.js";
+import type { Output, Run, RunEvent, SignedOutputLink, Skill, WhoAmI } from "./runtime-types.js";
+import type { PlatformFlatRunSubmissionInput, PlatformRunSubmissionInput } from "./submission.js";
 /**
  * The single source of truth for SDK<->BFF transport. The SDK class
  * AND the CLI subcommands both call these functions; neither
@@ -22,3 +22,21 @@ export declare function createOutputLink(http: HttpClient, runId: string, output
 export declare function cancelRun(http: HttpClient, runId: string): Promise<void>;
 export declare function deleteRun(http: HttpClient, runId: string): Promise<void>;
 export declare function whoami(http: HttpClient): Promise<WhoAmI>;
+export declare function submitRunFlat(http: HttpClient, request: PlatformFlatRunSubmissionInput): Promise<Run>;
+/**
+ * Upload a workspace skill bundle as a zip blob. The dashboard BFF runs
+ * the two-phase flow internally (insert pending row, stream bytes into
+ * Supabase Storage, validate manifest, transition to ready) and returns
+ * the finalized `Skill`. Use `Skill.fromPath` / `Skill.upload` in the
+ * SDK to build the body; this transport function only knows about
+ * bytes.
+ */
+export declare function createSkillBundle(http: HttpClient, args: {
+    readonly name: string;
+    readonly body: Blob | ArrayBuffer | Uint8Array;
+    readonly contentType?: string;
+    readonly filename?: string;
+}): Promise<Skill>;
+export declare function listSkills(http: HttpClient): Promise<readonly Skill[]>;
+export declare function getSkill(http: HttpClient, skillId: string): Promise<Skill>;
+export declare function deleteSkill(http: HttpClient, skillId: string): Promise<void>;

package/dist/_shared/operations.js

@@ -41,6 +41,62 @@ export async function deleteRun(http, runId) {
 export async function whoami(http) {
     return http.request("/api/whoami");
 }
+// ===========================================================================
+// Flat (Skill / McpServer / Blueprint) operations
+// ===========================================================================
+export async function submitRunFlat(http, request) {
+    return http.request("/api/runs", {
+        method: "POST",
+        body: JSON.stringify(request)
+    });
+}
+/**
+ * Upload a workspace skill bundle as a zip blob. The dashboard BFF runs
+ * the two-phase flow internally (insert pending row, stream bytes into
+ * Supabase Storage, validate manifest, transition to ready) and returns
+ * the finalized `Skill`. Use `Skill.fromPath` / `Skill.upload` in the
+ * SDK to build the body; this transport function only knows about
+ * bytes.
+ */
+export async function createSkillBundle(http, args) {
+    const form = new FormData();
+    form.append("name", args.name);
+    const blobBody = toBlob(args.body, args.contentType ?? "application/zip");
+    form.append("bundle", blobBody, args.filename ?? `${args.name}.zip`);
+    return http.request("/api/skills", {
+        method: "POST",
+        body: form
+    });
+}
+export async function listSkills(http) {
+    const result = await http.request("/api/skills");
+    if (Array.isArray(result)) {
+        return result;
+    }
+    return result.skills;
+}
+export async function getSkill(http, skillId) {
+    return http.request(`/api/skills/${encodeURIComponent(skillId)}`);
+}
+export async function deleteSkill(http, skillId) {
+    await http.request(`/api/skills/${encodeURIComponent(skillId)}`, {
+        method: "DELETE"
+    });
+}
+function toBlob(input, contentType) {
+    if (input instanceof Blob) {
+        return input;
+    }
+    if (input instanceof Uint8Array) {
+        // BlobPart accepts ArrayBufferView, but lib.dom's overload set
+        // narrows on the underlying buffer kind. Slice into a fresh
+        // ArrayBuffer so a SharedArrayBuffer-backed Uint8Array works.
+        const copy = new Uint8Array(input.byteLength);
+        copy.set(input);
+        return new Blob([copy.buffer], { type: contentType });
+    }
+    return new Blob([input], { type: contentType });
+}
 function hasRun(value) {
     return Boolean(value && typeof value === "object" && "run" in value);
 }

package/dist/_shared/runtime-types.d.ts

@@ -73,6 +73,36 @@ export interface WhoAmI {
     readonly scopes?: readonly string[];
     readonly [key: string]: unknown;
 }
+/**
+ * Workspace skill bundle as the dashboard BFF returns it. Mirrors a row
+ * of `skill_bundles` joined with its computed manifest. `state` is the
+ * upload lifecycle (`pending` -> `ready`); only `ready` rows are
+ * referenceable from a run. `deletedAt` is the soft-delete tombstone
+ * (`null` for live bundles).
+ *
+ * See `references/repo-architecture.md` (Skill custody) and
+ * supabase/migrations/20260512000000_skill_bundles.sql for the
+ * authoritative shape.
+ */
+export interface Skill {
+    readonly id: string;
+    readonly workspaceId?: string;
+    readonly name: string;
+    readonly state: "pending" | "ready";
+    readonly hash?: string | null;
+    readonly sizeBytes?: number | null;
+    readonly fileCount?: number | null;
+    readonly manifest?: ReadonlyArray<{
+        readonly path: string;
+        readonly size: number;
+        readonly mode: number;
+    }>;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly finalizedAt?: string | null;
+    readonly deletedAt?: string | null;
+    readonly [key: string]: unknown;
+}
 /**
  * Full submission as the SDK and CLI assemble it before posting. The
  * `template` is the SDK-level ResolvedTemplate (or a JSON-encoded one);

package/dist/_shared/submission.d.ts

@@ -1,4 +1,5 @@
 import { type ProxyAuthShape, type ProxyMethod, type ProxyResponseMode } from "./proxy-protocol.js";
+import type { McpServerRef, SkillRef } from "./blueprint.js";
 export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | JsonValue[] | {
     readonly [key: string]: JsonValue;
@@ -155,3 +156,42 @@ export declare const PROXY_ENDPOINT_DEFAULTS: {
     readonly responseByteBudget: number;
 };
 export declare function parseRunSubmissionRequest(input: unknown): PlatformRunSubmissionRequest;
+/**
+ * Wire-level submission posted to /api/runs in the flat surface. The
+ * `prompt` is always an array internally so the worker, the audit log,
+ * and the BFF idempotency hash all see one shape. `mcpServers` carries
+ * only the non-secret half; bearer headers travel in
+ * `secrets.mcpServers` keyed by `name`.
+ *
+ * `skills` is a list of `SkillRef`s — workspace refs point at
+ * `skill_bundles.id` (validated by the BFF before acceptance and pinned
+ * into `run_skill_snapshots`), provider refs pass through unchanged.
+ */
+export interface PlatformFlatSubmission {
+    readonly model: string;
+    readonly system?: string;
+    readonly prompt: readonly string[];
+    readonly skills: readonly SkillRef[];
+    readonly mcpServers: readonly McpServerRef[];
+    readonly environment?: PlatformTemplateEnvironment;
+    readonly metadata?: Record<string, JsonValue>;
+}
+export interface PlatformFlatRunSubmissionRequest {
+    readonly workspaceId: string;
+    readonly idempotencyKey: string;
+    readonly submission: PlatformFlatSubmission;
+    readonly cleanup?: PlatformCleanupPolicy;
+    readonly secrets: PlatformInlineSecrets;
+    readonly proxyEndpoints?: readonly PlatformProxyEndpoint[];
+}
+/**
+ * Same `workspaceId is optional` rule as the template-path
+ * `PlatformRunSubmissionInput`: token-authenticated clients leave it
+ * out, the BFF route injects it from the token before invoking the
+ * parser. Dashboard UI callers (Auth.js user principal) pass it
+ * explicitly.
+ */
+export type PlatformFlatRunSubmissionInput = Omit<PlatformFlatRunSubmissionRequest, "workspaceId"> & {
+    readonly workspaceId?: string;
+};
+export declare function parseFlatRunSubmissionRequest(input: unknown): PlatformFlatRunSubmissionRequest;

package/dist/_shared/submission.js

@@ -1,4 +1,5 @@
 import { authShapeHeaderName, PROXY_ALLOWED_METHODS, PROXY_RESPONSE_MODES } from "./proxy-protocol.js";
+import { parseMcpServerRef, parseSkillRef } from "./blueprint.js";
 const SECRETS_KEY = "secrets";
 /**
  * Default caps for a proxy endpoint when the submission doesn't specify
@@ -459,7 +460,15 @@ function parseMcpServers(input) {
     if (!Array.isArray(input)) {
         throw new Error("secrets.mcpServers must be an array");
     }
-    return input.map((entry, index) => parseMcpServer(entry, `secrets.mcpServers[${index}]`));
+    const seen = new Set();
+    return input.map((entry, index) => {
+        const parsed = parseMcpServer(entry, `secrets.mcpServers[${index}]`);
+        if (seen.has(parsed.name)) {
+            throw new Error(`secrets.mcpServers duplicate name: ${parsed.name}`);
+        }
+        seen.add(parsed.name);
+        return parsed;
+    });
 }
 function parseMcpServer(input, path) {
     const value = requireRecord(input, path);
@@ -678,4 +687,147 @@ function isJsonValue(input) {
     }
     return false;
 }
+export function parseFlatRunSubmissionRequest(input) {
+    const value = requireRecord(input, "submission");
+    // Defence in depth: scan every non-secrets field for credential-named
+    // keys, exactly like `parseRunSubmissionRequest`. The `secrets` key is
+    // the only allow-listed home for credential material.
+    for (const [key, fieldValue] of Object.entries(value)) {
+        if (key === SECRETS_KEY) {
+            continue;
+        }
+        if (deniedSecretFields.has(key)) {
+            throw new Error(`Secret-bearing field is not allowed in platform submission: ${key}`);
+        }
+        assertNoSecretBearingFields(fieldValue, [key]);
+    }
+    const cleanup = parseCleanupPolicy(value.cleanup);
+    const proxyEndpoints = parseProxyEndpoints(value.proxyEndpoints);
+    const secrets = parseInlineSecrets(value.secrets);
+    crossValidateProxyEndpointsAndAuth(proxyEndpoints, secrets.proxyEndpointAuth);
+    const submission = parseFlatSubmission(value.submission);
+    // mcpServers names must agree across the submission half and the
+    // secrets half — every secrets.mcpServers[i].name MUST resolve to a
+    // submission.mcpServers entry (no orphan secrets) AND the URL must
+    // match exactly. The reverse is allowed (an MCP server with no auth
+    // headers is a valid public-MCP mode).
+    if (secrets.mcpServers !== undefined) {
+        const declared = new Map(submission.mcpServers.map((m) => [m.name, m.url]));
+        for (const secret of secrets.mcpServers) {
+            const declaredUrl = declared.get(secret.name);
+            if (declaredUrl === undefined) {
+                throw new Error(`secrets.mcpServers[name=${secret.name}] has no matching submission.mcpServers entry`);
+            }
+            if (declaredUrl !== secret.url) {
+                throw new Error(`secrets.mcpServers[name=${secret.name}].url must equal submission.mcpServers[name=${secret.name}].url ` +
+                    `(got submission=${declaredUrl}, secrets=${secret.url})`);
+            }
+        }
+    }
+    return {
+        workspaceId: requireString(value.workspaceId, "workspaceId"),
+        idempotencyKey: requireString(value.idempotencyKey, "idempotencyKey"),
+        submission,
+        ...(cleanup ? { cleanup } : {}),
+        ...(proxyEndpoints ? { proxyEndpoints } : {}),
+        secrets
+    };
+}
+function parseFlatSubmission(input) {
+    const value = requireRecord(input, "submission.submission");
+    const allowed = new Set([
+        "model",
+        "system",
+        "prompt",
+        "skills",
+        "mcpServers",
+        "environment",
+        "metadata"
+    ]);
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key)) {
+            throw new Error(`submission.${key} is not an allowed field; permitted: ${[...allowed].join(", ")}`);
+        }
+    }
+    const model = requireString(value.model, "submission.model");
+    const system = optionalString(value.system, "submission.system");
+    const prompt = parseFlatPrompt(value.prompt);
+    const skills = parseFlatSkills(value.skills);
+    const mcpServers = parseFlatMcpServers(value.mcpServers);
+    const environment = parseTemplateEnvironment(value.environment);
+    const metadata = optionalJsonRecord(value.metadata, "submission.metadata");
+    return {
+        model,
+        ...(system ? { system } : {}),
+        prompt,
+        skills,
+        mcpServers,
+        ...(environment ? { environment } : {}),
+        ...(metadata ? { metadata } : {})
+    };
+}
+function parseFlatPrompt(input) {
+    if (typeof input === "string") {
+        if (input.length === 0) {
+            throw new Error("submission.prompt must be non-empty");
+        }
+        return [input];
+    }
+    if (!Array.isArray(input)) {
+        throw new Error("submission.prompt must be a string or an array of strings");
+    }
+    if (input.length === 0) {
+        throw new Error("submission.prompt array must be non-empty");
+    }
+    return input.map((item, index) => {
+        if (typeof item !== "string" || item.length === 0) {
+            throw new Error(`submission.prompt[${index}] must be a non-empty string`);
+        }
+        return item;
+    });
+}
+function parseFlatSkills(input) {
+    if (input === undefined) {
+        return [];
+    }
+    if (!Array.isArray(input)) {
+        throw new Error("submission.skills must be an array of SkillRef objects");
+    }
+    const seenWorkspace = new Set();
+    const seenProvider = new Set();
+    return input.map((item, index) => {
+        const ref = parseSkillRef(item, `submission.skills[${index}]`);
+        if (ref.kind === "workspace") {
+            if (seenWorkspace.has(ref.id)) {
+                throw new Error(`submission.skills duplicate workspace skill id: ${ref.id}`);
+            }
+            seenWorkspace.add(ref.id);
+        }
+        else {
+            const key = `${ref.vendor}:${ref.skillId}:${ref.version ?? ""}`;
+            if (seenProvider.has(key)) {
+                throw new Error(`submission.skills duplicate provider skill: ${ref.vendor}:${ref.skillId}${ref.version ? `:${ref.version}` : ""}`);
+            }
+            seenProvider.add(key);
+        }
+        return ref;
+    });
+}
+function parseFlatMcpServers(input) {
+    if (input === undefined) {
+        return [];
+    }
+    if (!Array.isArray(input)) {
+        throw new Error("submission.mcpServers must be an array of {name, url} objects");
+    }
+    const seen = new Set();
+    return input.map((item, index) => {
+        const ref = parseMcpServerRef(item, `submission.mcpServers[${index}]`);
+        if (seen.has(ref.name)) {
+            throw new Error(`submission.mcpServers duplicate name: ${ref.name}`);
+        }
+        seen.add(ref.name);
+        return ref;
+    });
+}
 //# sourceMappingURL=submission.js.map

package/dist/cli.mjs

@@ -52,6 +52,24 @@ var TERMINAL_RUN_STATUSES = [
 ];
 var terminalRunStatuses = new Set(TERMINAL_RUN_STATUSES);
 
+// ../shared/dist/blueprint.js
+var SKILL_BUNDLE_LIMITS = {
+  /** Compressed (.zip) ceiling. */
+  maxCompressedBytes: 10 * 1024 * 1024,
+  /** Sum of uncompressed file sizes. */
+  maxDecompressedBytes: 50 * 1024 * 1024,
+  /** Number of regular file entries (directories don't count). */
+  maxFiles: 1e3,
+  /** Maximum directory nesting depth — `a/b/c/d` has depth 4. */
+  maxDepth: 16,
+  /** Single-entry path length cap. */
+  maxPathLength: 512,
+  /** Stored file mode for ordinary files. */
+  defaultFileMode: 420,
+  /** Stored directory mode. */
+  defaultDirMode: 493
+};
+
 // ../shared/dist/submission.js
 var PROXY_ENDPOINT_DEFAULTS = {
   allowHeaders: [],
@@ -350,7 +368,9 @@ var HttpClient = class {
       ...normalizeHeaders(init.headers)
     };
     if (init.body !== void 0 && init.body !== null && !headers["content-type"]) {
-      headers["content-type"] = "application/json";
+      if (typeof init.body === "string") {
+        headers["content-type"] = "application/json";
+      }
     }
     const response = await this.#fetch(url, { ...init, headers });
     const body = await readJson(response);
@@ -414,11 +434,16 @@ var operations_exports = {};
 __export(operations_exports, {
   cancelRun: () => cancelRun,
   createOutputLink: () => createOutputLink,
+  createSkillBundle: () => createSkillBundle,
   deleteRun: () => deleteRun,
+  deleteSkill: () => deleteSkill,
   getRun: () => getRun,
+  getSkill: () => getSkill,
   listOutputs: () => listOutputs,
   listRunEvents: () => listRunEvents,
+  listSkills: () => listSkills,
   submitRun: () => submitRun,
+  submitRunFlat: () => submitRunFlat,
   whoami: () => whoami
 });
 async function submitRun(http, request) {
@@ -451,6 +476,48 @@ async function deleteRun(http, runId) {
 async function whoami(http) {
   return http.request("/api/whoami");
 }
+async function submitRunFlat(http, request) {
+  return http.request("/api/runs", {
+    method: "POST",
+    body: JSON.stringify(request)
+  });
+}
+async function createSkillBundle(http, args) {
+  const form = new FormData();
+  form.append("name", args.name);
+  const blobBody = toBlob(args.body, args.contentType ?? "application/zip");
+  form.append("bundle", blobBody, args.filename ?? `${args.name}.zip`);
+  return http.request("/api/skills", {
+    method: "POST",
+    body: form
+  });
+}
+async function listSkills(http) {
+  const result = await http.request("/api/skills");
+  if (Array.isArray(result)) {
+    return result;
+  }
+  return result.skills;
+}
+async function getSkill(http, skillId) {
+  return http.request(`/api/skills/${encodeURIComponent(skillId)}`);
+}
+async function deleteSkill(http, skillId) {
+  await http.request(`/api/skills/${encodeURIComponent(skillId)}`, {
+    method: "DELETE"
+  });
+}
+function toBlob(input, contentType) {
+  if (input instanceof Blob) {
+    return input;
+  }
+  if (input instanceof Uint8Array) {
+    const copy = new Uint8Array(input.byteLength);
+    copy.set(input);
+    return new Blob([copy.buffer], { type: contentType });
+  }
+  return new Blob([input], { type: contentType });
+}
 function hasRun(value) {
   return Boolean(value && typeof value === "object" && "run" in value);
 }

package/dist/cli.mjs.sha256

@@ -1 +1 @@
-a602b27fb33ed22e122096a17bbe0a1f132a6981e55db03ace316dddc048eac2  cli.mjs
+2d4fdd070358ffea5d49c62d5cca10863da0fc6279a88fe78fa7f11eb6eb18d7  cli.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antpath",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "TypeScript SDK for running autonomous Claude Managed Agents sessions.",
   "repository": {
     "type": "git",