antpath 0.3.1 → 0.4.1

package/dist/_shared/blueprint.js

@@ -0,0 +1,505 @@
+/**
+ * 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})`);
+        }
+    }
+    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.d.ts

@@ -1,6 +1,11 @@
 export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 export interface HttpClientOptions {
-    readonly baseUrl: string;
+    /**
+     * Dashboard BFF root. Optional — defaults to `ANTPATH_DEFAULT_BASE_URL`
+     * (`https://antpath.ai`). Self-hosted deployments override with their
+     * own URL; no env var consults this value.
+     */
+    readonly baseUrl?: string;
     readonly apiToken: string;
     readonly fetch?: FetchLike;
 }

package/dist/_shared/http.js

@@ -1,4 +1,5 @@
 import { AntpathApiError } from "./sdk-errors.js";
+import { ANTPATH_DEFAULT_BASE_URL } from "./stable.js";
 /**
  * Thin transport used by every BFF-bound operation. The SDK class and
  * the CLI subcommands BOTH build an `HttpClient` and pass it to the
@@ -10,13 +11,11 @@ export class HttpClient {
     #apiToken;
     #fetch;
     constructor(options) {
-        if (!options.baseUrl) {
-            throw new Error("HttpClient: baseUrl is required");
-        }
         if (!options.apiToken) {
             throw new Error("HttpClient: apiToken is required");
         }
-        const normalized = options.baseUrl.endsWith("/") ? options.baseUrl : `${options.baseUrl}/`;
+        const raw = options.baseUrl ?? ANTPATH_DEFAULT_BASE_URL;
+        const normalized = raw.endsWith("/") ? raw : `${raw}/`;
         this.#baseUrl = new URL(normalized);
         this.#apiToken = options.apiToken;
         this.#fetch = options.fetch ?? fetch;
@@ -32,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 { PlatformRunSubmissionRequest } 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
@@ -8,12 +8,35 @@ import type { PlatformRunSubmissionRequest } from "./submission.js";
  *
  * Every function takes an HttpClient (so callers control auth + fetch
  * injection) and returns parsed responses.
+ *
+ * Workspace identity is derived server-side from the API token on
+ * every request — callers do not pass `workspaceId`. See
+ * `references/development-principles.md` (Agent-first surface design,
+ * Concrete rule 3).
  */
-export declare function submitRun(http: HttpClient, request: PlatformRunSubmissionRequest): Promise<Run>;
-export declare function getRun(http: HttpClient, workspaceId: string, runId: string): Promise<Run>;
-export declare function listRunEvents(http: HttpClient, workspaceId: string, runId: string): Promise<readonly RunEvent[]>;
-export declare function listOutputs(http: HttpClient, workspaceId: string, runId: string): Promise<readonly Output[]>;
-export declare function createOutputLink(http: HttpClient, workspaceId: string, runId: string, outputId: string): Promise<SignedOutputLink>;
-export declare function cancelRun(http: HttpClient, workspaceId: string, runId: string): Promise<void>;
-export declare function deleteRun(http: HttpClient, workspaceId: string, runId: string): Promise<void>;
+export declare function submitRun(http: HttpClient, request: PlatformRunSubmissionInput): Promise<Run>;
+export declare function getRun(http: HttpClient, runId: string): Promise<Run>;
+export declare function listRunEvents(http: HttpClient, runId: string): Promise<readonly RunEvent[]>;
+export declare function listOutputs(http: HttpClient, runId: string): Promise<readonly Output[]>;
+export declare function createOutputLink(http: HttpClient, runId: string, outputId: string): Promise<SignedOutputLink>;
+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>;