antpath 0.6.2 → 0.8.0

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAQlE,yBAAyB;AACzB,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,SAAS;AACT,OAAO,EACL,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,yBAAyB,EACzB,aAAa,EACb,aAAa,EACd,MAAM,iBAAiB,CAAC;AAEzB,yBAAyB;AACzB,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,wBAAwB,EACxB,2BAA2B,EAC3B,iBAAiB,EAClB,MAAM,iBAAiB,CAAC;AAsCzB,oBAAoB;AACpB,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,0BAA0B,EAC1B,sBAAsB,EACtB,yBAAyB,EACzB,WAAW,EACX,WAAW,EACX,aAAa,EACd,MAAM,iBAAiB,CAAC;AAEzB,mBAAmB;AACnB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAQlE,yBAAyB;AACzB,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAQpD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGhE,SAAS;AACT,OAAO,EACL,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,yBAAyB,EACzB,aAAa,EACb,aAAa,EACd,MAAM,iBAAiB,CAAC;AAEzB,yBAAyB;AACzB,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,wBAAwB,EACxB,2BAA2B,EAC3B,iBAAiB,EAClB,MAAM,iBAAiB,CAAC;AA2CzB,oBAAoB;AACpB,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,0BAA0B,EAC1B,sBAAsB,EACtB,yBAAyB,EACzB,WAAW,EACX,WAAW,EACX,aAAa,EACd,MAAM,iBAAiB,CAAC;AAEzB,mBAAmB;AACnB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/proxy-endpoint.d.ts

@@ -0,0 +1,131 @@
+import { type PlatformProxyAuthValue, type PlatformProxyEndpoint, type PlatformProxyEndpointAuth, type ProxyMethod, type ProxyResponseMode } from "./_shared/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 antpath 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 "./_shared/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 antpath 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

@@ -1,40 +1,80 @@
-import type { ProviderSkillRef, Skill as SkillRecord, SkillRef } from "./_shared/index.js";
+import { type ProviderSkillRef, type Skill as SkillRecord, type SkillRef } from "./_shared/index.js";
+import { type SkillFiles } from "./bundle.js";
 /**
- * Workspace `Skill` and provider `Skill` are both modeled by ONE class with
- * a discriminated wire shape under `.ref`. Keeping a single class means
- * `submitRun({ skills: [...] })` accepts a uniform array; the SDK
- * normalises every entry to its `ref` before sending the wire payload.
- *
- * Three workspace constructors:
- *
- *   - `Skill.fromId("skl_abc123")` — reference an existing workspace
- *     skill without re-uploading. Useful for sharing a skill across many
- *     `submitRun` calls or in a `defineRun` factory.
- *   - `client.skills.upload({ name, files })` — inline files map (UTF-8
- *     strings or `Uint8Array`); SDK zips and uploads.
- *   - `client.skills.fromPath("./dir", { name })` — local directory; SDK
- *     reads, zips, and uploads (Node only).
- *
- * One provider constructor:
- *
- *   - `Skill.provider({ vendor, skillId, version? })` — references a
- *     provider built-in skill (e.g. Anthropic web-search). Provider
- *     skills are NOT uploaded to your workspace and have no
- *     soft-delete semantics.
- *
- * Instances are immutable. The wire `ref` is the only state and never
- * carries credentials.
+ * One `Skill` class, one mental model, three usage modes:
+ *
+ *   - **Workspace** — uploaded to the antpath platform and reused across
+ *     runs.
+ *     ```ts
+ *     const persisted = await Skill.fromFiles({ name, files }).upload(client);
+ *     // or
+ *     const ref = Skill.fromId("skl_abc123");
+ *     ```
+ *
+ *   - **Provider built-in** — references a provider-side skill (e.g.
+ *     Anthropic web-search). Not uploaded to your workspace.
+ *     ```ts
+ *     const websearch = Skill.provider({ vendor: "anthropic", skillId: "web-search" });
+ *     ```
+ *
+ *   - **Transient (per-run)** — built from local files, never persisted.
+ *     The bytes ride alongside `submitRun` as a multipart part and the
+ *     BFF tears them down at run terminal.
+ *     ```ts
+ *     const rules = await Skill.fromFiles({ name: "rules", files: {...} });
+ *     await client.submitRun({ skills: [rules], ... });
+ *     ```
+ *
+ * ## Lifecycle of an unstaged transient Skill
+ *
+ * After `Skill.fromFiles(...)` returns, the Skill is "unstaged transient":
+ *
+ *   1. Passing it to `submitRun` uploads the bytes for that one run only
+ *      and assigns a positional slot id (`transient-0`, `transient-1`, …).
+ *      The same instance may be passed to multiple `submitRun` calls
+ *      until it is consumed by `.upload(...)`.
+ *
+ *   2. Calling `await skill.upload(client)` persists the bundle to the
+ *      workspace skill store and returns a **new** `Skill` instance
+ *      whose `.ref.kind === "workspace"`. The **original** is marked
+ *      **consumed**:
+ *      - any further use in `submitRun` throws a clear validation error,
+ *      - `.upload(...)` on the consumed instance throws,
+ *      - `JSON.stringify` / `toJSON()` on the consumed instance throws.
+ *
+ *      Use the returned (workspace) Skill from then on. The consumed
+ *      reference exists only to surface the mistake loudly the first
+ *      time the user re-uses it; it never silently re-uploads as
+ *      transient.
+ *
+ * Unstaged transient Skills do NOT round-trip through JSON (the bytes
+ * cannot be serialised back). `toJSON()` throws in that state too —
+ * persist via `.upload(client)` first, or pass the unstaged Skill
+ * directly to `submitRun`.
+ *
+ * The Skill class is the only public way to build a transient bundle;
+ * the SDK never accepts a raw `TransientSkillRef` object from user code.
  */
 export declare class Skill {
+    #private;
     /** Workspace skill record returned by the BFF (only set for workspace-uploaded skills). */
     readonly record: SkillRecord | undefined;
-    readonly ref: SkillRef;
     /**
-     * Internal constructor. Use `Skill.fromId`, `Skill.provider`, or
-     * `client.skills.upload` / `client.skills.fromPath` to create
-     * instances.
+     * Internal constructor. Use `Skill.fromId`, `Skill.provider`,
+     * `Skill.fromFiles`, or `Skill.fromPath` to create instances.
+     */
+    constructor(ref: SkillRef, record?: SkillRecord, transientBytes?: Uint8Array);
+    /**
+     * The wire-level reference. For workspace and provider skills this is
+     * stable. For unstaged transient skills it carries the placeholder
+     * `slot: "(unstaged)"` — `submitRun` rewrites the slot to a real
+     * positional id (`transient-0`, …) before sending.
+     *
+     * For consumed Skills, the getter still returns the original
+     * transient ref so error messages can be precise — but using a
+     * consumed Skill in any submit/serialise path throws.
      */
-    constructor(ref: SkillRef, record?: SkillRecord);
+    get ref(): SkillRef;
     /**
      * Reference an existing workspace skill by its id (e.g. `skl_abc123`).
      * Does NOT validate the skill exists — that check happens on the next
@@ -52,8 +92,140 @@ export declare class Skill {
         readonly skillId: string;
         readonly version?: string;
     }): Skill;
-    /** True for `Skill.fromId(...)` and skills returned by `client.skills.upload(...)`. */
+    /**
+     * Build an unstaged transient 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 that travels in the wire ref.
+     *
+     * The returned Skill carries the bytes privately. Pass it to
+     * `submitRun` for transient (per-run) use, or call `.upload(client)`
+     * to persist it as a workspace skill.
+     */
+    static fromFiles(args: {
+        readonly name: string;
+        readonly files: SkillFiles;
+    }): Promise<Skill>;
+    /**
+     * Read a local directory and build an unstaged transient Skill.
+     * Symlinks and non-regular files are skipped. Node-only.
+     *
+     * The returned Skill behaves identically to one built via
+     * `Skill.fromFiles` — pass it to `submitRun` for transient use, or
+     * call `.upload(client)` to persist as a workspace skill.
+     */
+    static fromPath(rootDir: string, args: {
+        readonly name: string;
+    }): Promise<Skill>;
+    /**
+     * Persist this unstaged transient Skill as a workspace skill and
+     * return a new `Skill` instance backed by the resulting `skl_*`
+     * record. After `upload` resolves successfully, the original
+     * instance is marked **consumed** — any further use throws a clear
+     * validation error.
+     *
+     * Only unstaged transient Skills can be uploaded. Calling this on a
+     * workspace-ref Skill, a provider-ref Skill, or a previously
+     * consumed Skill throws.
+     *
+     * Accepts either an `AntpathClient` (preferred) or its
+     * `SkillsClient` if the caller already has a handle to it.
+     */
+    upload(client: SkillUploader): Promise<Skill>;
+    /**
+     * Persist this unstaged transient Skill as a workspace skill **only
+     * if** an existing skill with the same `(name, contentHash)` is not
+     * already live.
+     *
+     * Flow:
+     *
+     *   1. Hash is already known from `Skill.fromFiles` / `fromPath`.
+     *   2. Call `client.skills.findByHash({ name, contentHash })`. If a
+     *      live row exists, mark this instance consumed and return a
+     *      new `Skill` backed by that record.
+     *   3. Otherwise call `upload(client)`.
+     *
+     * Returns either the existing or newly-created workspace Skill;
+     * callers do not need to branch.
+     *
+     * Only unstaged transient Skills can be `uploadIfChanged`. Calling
+     * this on a workspace-ref Skill, a provider-ref Skill, or a
+     * previously consumed Skill throws.
+     */
+    uploadIfChanged(client: SkillUploader & SkillLookup): Promise<Skill>;
+    /** True for `Skill.fromId(...)` and skills returned by `.upload(...)`. */
     get isWorkspace(): boolean;
     /** True for `Skill.provider(...)`. */
     get isProvider(): boolean;
+    /** True for any transient Skill (unstaged or consumed). */
+    get isTransient(): boolean;
+    /**
+     * True only while the transient Skill still carries bytes and has
+     * not been consumed by `.upload(...)`. Unstaged Skills can be passed
+     * to `submitRun` or `.upload(client)`; consumed ones cannot.
+     */
+    get isUnstaged(): boolean;
+    /** True after a successful `.upload(...)` — using this instance further throws. */
+    get isConsumed(): boolean;
+    /**
+     * Internal: yield the unstaged transient bundle's payload so the
+     * client's `submitRun` can build a multipart part. Returns undefined
+     * for non-transient or consumed skills. Throws if the instance is
+     * marked consumed (a stronger signal than "no bytes").
+     *
+     * NOT part of the public API — the `_` prefix is a "do not call from
+     * user code" marker. Callers within the SDK pass the returned bytes
+     * into the multipart body once per `submitRun` invocation.
+     */
+    _takeUnstagedBundle(): {
+        name: string;
+        bytes: Uint8Array;
+        contentHash: string;
+    } | undefined;
+    /**
+     * JSON serialisation guard. Workspace and provider Skills serialise
+     * to their `ref`. Unstaged transient Skills throw — the bytes are not
+     * in the JSON, so a round-trip would silently drop them. Consumed
+     * Skills also throw, to surface the "you forgot to use the returned
+     * Skill from `.upload(...)`" mistake at the point it happens.
+     */
+    toJSON(): SkillRef;
+}
+/**
+ * Anything that can persist a skill bundle. Both `AntpathClient` and
+ * the internal `SkillsClient` satisfy this shape — `Skill.upload`
+ * accepts either, but the SDK consumer only ever sees the
+ * `AntpathClient`-based path.
+ */
+export interface SkillUploader {
+    readonly _uploadSkillBundle?: (args: {
+        readonly name: string;
+        readonly body: Uint8Array;
+    }) => Promise<SkillRecord>;
+    readonly skills?: {
+        readonly _uploadSkillBundle?: (args: {
+            readonly name: string;
+            readonly body: Uint8Array;
+        }) => Promise<SkillRecord>;
+    };
+}
+/**
+ * Anything that can look up an existing workspace skill by hash. Used
+ * by `Skill.uploadIfChanged` — both `AntpathClient` (via
+ * `.skills.findByHash`) and the internal `SkillsClient` satisfy this
+ * shape. The lookup is optional so test doubles for `upload` need not
+ * implement it; in that case `uploadIfChanged` simply falls back to
+ * a plain `upload`.
+ */
+export interface SkillLookup {
+    readonly skills?: {
+        readonly findByHash?: (args: {
+            readonly name: string;
+            readonly contentHash: string;
+        }) => Promise<SkillRecord | null>;
+    };
+    readonly findByHash?: (args: {
+        readonly name: string;
+        readonly contentHash: string;
+    }) => Promise<SkillRecord | null>;
 }