antpath 0.6.2 → 0.8.0

package/dist/skill.js

@@ -1,41 +1,88 @@
+import { SKILL_NAME_PATTERN } from "./_shared/index.js";
+import { bundleSkillFiles, hashSkillBundle } from "./bundle.js";
+import { readDirectoryAsFiles } from "./node-fs.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.
+ * One `Skill` class, one mental model, three usage modes:
  *
- * Three workspace constructors:
+ *   - **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");
+ *     ```
  *
- *   - `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).
+ *   - **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" });
+ *     ```
  *
- * One provider constructor:
+ *   - **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], ... });
+ *     ```
  *
- *   - `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.
+ * ## Lifecycle of an unstaged transient Skill
  *
- * Instances are immutable. The wire `ref` is the only state and never
- * carries credentials.
+ * 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 class Skill {
     /** Workspace skill record returned by the BFF (only set for workspace-uploaded skills). */
     record;
-    ref;
+    #ref;
+    #transientBytes;
+    #consumed = false;
     /**
-     * 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, record) {
-        this.ref = ref;
+    constructor(ref, record, transientBytes) {
+        this.#ref = ref;
         this.record = record;
+        this.#transientBytes = transientBytes;
+    }
+    /**
+     * 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.
+     */
+    get ref() {
+        return this.#ref;
     }
     /**
      * Reference an existing workspace skill by its id (e.g. `skl_abc123`).
@@ -47,8 +94,7 @@ export class Skill {
         if (typeof id !== "string" || !id) {
             throw new Error("Skill.fromId: id is required");
         }
-        const ref = { kind: "workspace", id };
-        return new Skill(ref);
+        return new Skill({ kind: "workspace", id });
     }
     /**
      * Reference a provider built-in skill. The vendor decides what the
@@ -70,13 +116,214 @@ export class Skill {
             : { kind: "provider", vendor: args.vendor, skillId: args.skillId };
         return new Skill(ref);
     }
-    /** 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 async fromFiles(args) {
+        if (!args || typeof args !== "object") {
+            throw new Error("Skill.fromFiles: args is required");
+        }
+        if (typeof args.name !== "string" || !SKILL_NAME_PATTERN.test(args.name)) {
+            throw new Error(`Skill.fromFiles: name must match ${SKILL_NAME_PATTERN.source}`);
+        }
+        const bundled = bundleSkillFiles(args.files);
+        const contentHash = await hashSkillBundle(bundled.zip);
+        const ref = {
+            kind: "transient",
+            slot: UNSTAGED_SLOT,
+            name: args.name,
+            contentHash
+        };
+        return new Skill(ref, undefined, bundled.zip);
+    }
+    /**
+     * 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 async fromPath(rootDir, args) {
+        const files = await readDirectoryAsFiles(rootDir);
+        return Skill.fromFiles({ name: args.name, files });
+    }
+    /**
+     * 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.
+     */
+    async upload(client) {
+        if (this.#consumed) {
+            throw new Error(consumedMessage());
+        }
+        if (this.#ref.kind !== "transient" || !this.#transientBytes) {
+            throw new Error("Skill.upload: only unstaged transient Skills (built via Skill.fromFiles / Skill.fromPath) can be uploaded; " +
+                "use Skill.fromId(record.id) to reference an already-persisted skill");
+        }
+        const uploader = resolveUploader(client);
+        const record = await uploader({ name: this.#ref.name, body: this.#transientBytes });
+        // Only mark consumed AFTER a successful upload — a failed upload
+        // leaves the original instance reusable so the caller can retry.
+        this.#consumed = true;
+        return new Skill({ kind: "workspace", id: record.id }, record);
+    }
+    /**
+     * 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.
+     */
+    async uploadIfChanged(client) {
+        if (this.#consumed) {
+            throw new Error(consumedMessage());
+        }
+        if (this.#ref.kind !== "transient" || !this.#transientBytes) {
+            throw new Error("Skill.uploadIfChanged: only unstaged transient Skills (built via Skill.fromFiles / Skill.fromPath) can be checked; " +
+                "use Skill.fromId(record.id) to reference an already-persisted skill");
+        }
+        const lookup = resolveLookup(client);
+        if (lookup) {
+            const existing = await lookup({
+                name: this.#ref.name,
+                contentHash: this.#ref.contentHash
+            });
+            if (existing) {
+                this.#consumed = true;
+                return new Skill({ kind: "workspace", id: existing.id }, existing);
+            }
+        }
+        return this.upload(client);
+    }
+    /** True for `Skill.fromId(...)` and skills returned by `.upload(...)`. */
     get isWorkspace() {
-        return this.ref.kind === "workspace";
+        return this.#ref.kind === "workspace";
     }
     /** True for `Skill.provider(...)`. */
     get isProvider() {
-        return this.ref.kind === "provider";
+        return this.#ref.kind === "provider";
+    }
+    /** True for any transient Skill (unstaged or consumed). */
+    get isTransient() {
+        return this.#ref.kind === "transient";
+    }
+    /**
+     * 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() {
+        return (this.#ref.kind === "transient" &&
+            this.#ref.slot === UNSTAGED_SLOT &&
+            !this.#consumed &&
+            this.#transientBytes !== undefined);
+    }
+    /** True after a successful `.upload(...)` — using this instance further throws. */
+    get isConsumed() {
+        return this.#consumed;
+    }
+    /**
+     * 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() {
+        if (this.#consumed) {
+            throw new Error(consumedMessage());
+        }
+        if (!this.isUnstaged) {
+            return undefined;
+        }
+        if (this.#ref.kind !== "transient" || !this.#transientBytes) {
+            return undefined;
+        }
+        return {
+            name: this.#ref.name,
+            bytes: this.#transientBytes,
+            contentHash: this.#ref.contentHash
+        };
     }
+    /**
+     * 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() {
+        if (this.#consumed) {
+            throw new Error(consumedMessage());
+        }
+        if (this.isUnstaged) {
+            throw new Error("Cannot JSON-serialise an unstaged transient Skill — the bytes are not in the JSON. " +
+                "Persist via skill.upload(client) and serialise the returned (workspace) Skill, " +
+                "or pass the unstaged Skill directly to submitRun without serialising.");
+        }
+        return this.#ref;
+    }
+}
+/** Sentinel slot id used by unstaged transient Skills. */
+const UNSTAGED_SLOT = "(unstaged)";
+function resolveUploader(client) {
+    const direct = client._uploadSkillBundle;
+    if (typeof direct === "function") {
+        return direct.bind(client);
+    }
+    const nested = client.skills?._uploadSkillBundle;
+    if (typeof nested === "function") {
+        return nested.bind(client.skills);
+    }
+    throw new Error("Skill.upload: client argument does not expose an upload entry point — " +
+        "pass the AntpathClient instance or its `client.skills`");
+}
+function resolveLookup(client) {
+    const nested = client.skills?.findByHash;
+    if (typeof nested === "function") {
+        return nested.bind(client.skills);
+    }
+    const direct = client.findByHash;
+    if (typeof direct === "function") {
+        return direct.bind(client);
+    }
+    return undefined;
+}
+function consumedMessage() {
+    return ("this Skill was already uploaded via skill.upload(client); use the returned Skill or " +
+        "Skill.fromId(record.id) for subsequent runs");
 }
 //# sourceMappingURL=skill.js.map

package/dist/skill.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill.js","sourceRoot":"","sources":["../src/skill.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,OAAO,KAAK;IAChB,2FAA2F;IAClF,MAAM,CAA0B;IAChC,GAAG,CAAW;IAEvB;;;;OAIG;IACH,YAAY,GAAa,EAAE,MAAoB;QAC7C,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,EAAU;QACtB,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,CAAC,EAAE,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAClD,CAAC;QACD,MAAM,GAAG,GAAsB,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;QACzD,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,IAA0G;QACxH,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;QACtD,CAAC;QACD,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACpD,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACxD,CAAC;QACD,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;QACzD,CAAC;QACD,MAAM,GAAG,GAAqB,IAAI,CAAC,OAAO;YACxC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE;YACzF,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QACrE,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAED,uFAAuF;IACvF,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,WAAW,CAAC;IACvC,CAAC;IAED,sCAAsC;IACtC,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,UAAU,CAAC;IACtC,CAAC;CACF"}
+{"version":3,"file":"skill.js","sourceRoot":"","sources":["../src/skill.ts"],"names":[],"mappings":"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"}

package/docs/credentials.md

@@ -84,6 +84,40 @@ Inside the run container, every session has the platform CLI mounted at `/antpat
 
 The CLI reads the per-run bearer from `/antpath/run-token`, attaches the `X-Antpath-Proxy-Protocol` header, and the BFF injects the bearer/header/query/basic credential before dispatching the outbound call. Only the response (subject to `responseMode` and `maxResponseBytes`) reaches the container. `--response-mode` can only narrow below the policy ceiling.
 
+#### Keyless upstreams (`authShape: { type: "none" }`)
+
+For public APIs that take no credential (Wikimedia Commons, Internet Archive, Library of Congress, NASA Images, NARA, GDELT, etc.), declare the endpoint with `authShape: { type: "none" }` and omit the matching `proxyEndpointAuth[]` entry entirely:
+
+```ts
+const proxyEndpoints = [
+  {
+    name: "wikimedia",
+    baseUrl: "https://commons.wikimedia.org",
+    authShape: { type: "none" },
+    allowMethods: ["GET"],
+    allowPathPrefixes: ["/wiki/", "/w/api.php"]
+  }
+] as const;
+
+const ref = await client.submitRun(template, {
+  proxyEndpoints,
+  secrets: { anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! } }
+});
+```
+
+The keyless endpoint still routes through the antpath managed proxy: every call is allow-listed, audited, redacted, and counted against per-run budgets. The BFF injects no `Authorization` header and no query-string credential. Shipping a `proxyEndpointAuth` entry for a `none`-shape endpoint is rejected at submission time. Equivalent class-based form:
+
+```ts
+import { ProxyEndpoint } from "antpath";
+
+ProxyEndpoint.none({
+  name: "wikimedia",
+  baseUrl: "https://commons.wikimedia.org",
+  allowMethods: ["GET"],
+  allowPathPrefixes: ["/wiki/", "/w/api.php"]
+});
+```
+
 `/antpath/antpath --help` reads endpoint details from `/antpath/index.json`. Runs that do not declare any `proxyEndpoints` still have the CLI and an empty manifest mounted, so agents never need to introspect whether the surface exists.
 
 ### Networking

package/docs/events.md

@@ -23,6 +23,13 @@ for await (const event of ref.stream({ intervalMs: 1000 })) {
 }
 ```
 
+> **Transport.** `stream()` polls under the hood — it issues `GET
+> /api/runs/:id/events?since=…` calls at `intervalMs` until the run
+> reaches a terminal status. There is no SSE / WebSocket push from the
+> BFF today. For latency-sensitive UIs this is acceptable down to about
+> 500 ms; below that, every dashboard request is one round-trip. A push
+> transport is on the public backlog — not committed to a release.
+
 The CLI mirrors the same surface:
 
 ```bash

package/docs/mcp.md

@@ -16,3 +16,31 @@ Rules:
 - Only provider-native bearer/OAuth auth is supported.
 
 Use allowlists for sensitive servers whenever possible.
+
+## Large-payload responses
+
+antpath is a session dispatcher, not an MCP runtime. We intentionally do
+**not** interpose on the transport between Claude and an upstream MCP
+server, so we cannot elide MCP responses or write them to the session
+filesystem on the user's behalf. Anything an MCP tool returns lands
+directly in the model's context.
+
+For ingestion-style tools that return large JSON blobs (search results,
+catalogue dumps, bulk reads), use the **CLI-as-skill + managed proxy**
+pattern instead of MCP:
+
+1. Package the upstream as a `Skill` — a CLI binary the agent invokes
+   with its bash tool.
+2. Route every upstream HTTPS call through a per-run `ProxyEndpoint`
+   (audit, byte caps, budget enforcement).
+3. Have the CLI write the full payload under one of the directories you
+   passed to `outputDirs`. Return only a small handle (path, item count,
+   summary) to the model.
+
+The agent sees the handle in context; the bytes ride out through
+`download()` as a normal captured output.
+
+If you genuinely want everything in context (small responses, code
+search, etc.), use MCP. If the payload would blow your context budget,
+the CLI-as-skill pattern is the supported answer — there is no platform
+flag to elide MCP responses.

package/docs/outputs.md

@@ -4,24 +4,104 @@ title: Outputs
 
 # Outputs
 
-Every run captures provider session-scoped files into private Supabase Storage. List and download them through whichever surface is convenient.
+Every run produces durable metadata (status, events, snapshots, cleanup state). File bytes are **opt-in** via the submission's `outputDirs` field. There is a single method, `RunRef.download()`, that returns the whole run — metadata plus opt-in file bytes — as a streaming zip.
+
+## Quickstart
 
 ```ts
-const outputs = await ref.outputs();             // OutputSummary[]
-const { url } = await client.createOutputLink(ref.runId, outputs[0].id);
+const ref = await client.submitRun({
+  model: "claude-opus-4-7",
+  prompt: "Produce a report and stash working files",
+  outputDirs: ["/workspace/outputs", "/workspace/state"],
+  secrets: { anthropic: { apiKey } }
+});
+
+await ref.download({ to: "./run-archive.zip" });
 ```
 
 ```bash
-antpath outputs list <run-id>       --api-token … --workspace … --dashboard-url …
-antpath outputs download <run-id> <output-id> --out ./dir \
-                                    --api-token … --workspace … --dashboard-url …
+antpath download <run-id> --out ./run-archive.zip --api-token …
+```
+
+## What `download()` returns
+
+A zip with this layout:
+
+```
+run.json          # run record (status, runId, timestamps, snapshot)
+events.jsonl      # one event per line, ordered
+outputs/<name>    # one file per captured output object
+manifest.json     # { source, partial, outputs, missing }
+```
+
+`manifest.json` carries:
+
+| Field | Meaning |
+| --- | --- |
+| `source: "live" \| "s3"` | Where file bytes came from. `live` = streamed from Anthropic Files API (mid-session); `s3` = streamed from Supabase Storage (after capture completed). |
+| `partial: boolean` | `true` if the run had not finished capture yet — more bytes may exist on a later call. |
+| `outputs[]` | `{ id, path, byteSize, contentType? }` — each row corresponds to a file under `outputs/` in the zip. |
+| `missing[]` | `{ id?, path?, reason, message? }` — anything the platform tried to include but could not. Reasons documented below. |
+
+## Lifecycle behaviour
+
+`download()` is lifecycle-aware in one method. You never branch on state — check `manifest.partial` if you care about staleness.
+
+| Run state | Behaviour |
+| --- | --- |
+| `pending` / `queued` / `provisioning` | HTTP 409 `run_not_started`. Wait for the run to start. |
+| `provider_running`, mid-session | Live: stream-zip from Anthropic Files API + DB metadata/events. `source: "live"`, `partial: true`. |
+| `cleaning_up` | Same as `provider_running` until S3 capture completes; then same as terminal. |
+| `succeeded` / `failed` / `cancelled` / `terminated` | Terminal: stream-zip from S3 `output_objects` + DB. `source: "s3"`, `partial: false`. |
+
+## `outputDirs` — opt-in file capture
+
+```ts
+client.submitRun({
+  /* ... */,
+  outputDirs: ["/workspace/outputs", "/workspace/state"]
+});
 ```
 
-`/antpath/outputs` is a recommended convention, not a provider default. Templates may instruct agents to write important artifacts there, but every session-scoped provider file is captured unconditionally (bounded only by the workspace storage cap; skipped files are recorded as `output_capture_failures`).
+Validation:
+
+- absolute UNIX paths only (`/...`),
+- no `..` segments, no NUL bytes,
+- maximum 32 entries,
+- maximum 512 bytes per entry.
+
+Mechanism (no platform-magical paths — this is honest):
+
+1. Worker submits the run, sends the user prompt, streams events.
+2. At session-idle (the agent's primary task is done), the worker sends one synthetic `user.message` to the agent:
+   *"Run `/antpath/antpath outputs sync <dirs>` once."*
+3. The agent runs that command via its bash tool. The in-container CLI walks the listed dirs, prints a JSON line per file, and the agent's tool output triggers Anthropic Managed Agents' file registration.
+4. Worker walks the Files API, copies bytes into Supabase Storage, and tears down the session.
+
+Cost: one extra agent turn (~hundreds of tokens, observable in `span.model_request_*` events). Document this against your token budget if you submit very high-volume runs.
+
+Failure modes — anything that did not make it into the zip lands in `manifest.missing[]`:
+
+| `reason` | What happened |
+| --- | --- |
+| `agent_did_not_sync` | The agent refused or skipped the synthetic instruction. Run still succeeded, just no file bytes. |
+| `agent_reported_error` | The `/antpath/antpath outputs sync` invocation returned non-zero (e.g. dir did not exist). |
+| `session_terminated_pre_sync` | Session was terminated (cancel / timeout) before the sync turn ran. |
+| `storage_cap_exceeded` | Workspace storage quota would have been breached. |
+| `download_failed` | Files API entry could not be fetched. |
+| `pending_session_terminal` | Mid-session download — file may show up on a later `download()` once the session reaches terminal. |
+
+## Runs without `outputDirs`
+
+Metadata still gets the full treatment. `download()` returns a zip with `run.json`, `events.jsonl`, and an empty `outputs/` directory (manifest `outputs: []`). No file bytes are captured because no path was opted in. This is the default and is intentional — see `references/architecture-decisions.md` for the design rationale.
+
+## Mid-session download semantics
+
+Mid-session calls are **best-effort and side-effect-free**: the BFF reads whatever the agent has already registered with the Files API and streams that. It does **not** trigger a synthetic sync — that would interfere with the running agent's plan. If you need the full output set, wait for the run to reach terminal status and call `download()` again. The manifest's `partial: true` flag tells you when to retry.
 
-Safety rules:
+## Safety
 
-- filenames are sanitized;
-- downloads stay within the requested local directory;
-- signed download links are short-lived;
-- manifests contain provider file IDs, local paths, names, and sizes only — never file bytes.
+- Filenames are sanitized for cross-platform safety; collisions are disambiguated with a short id suffix before the extension.
+- Downloads stay within the requested local directory.
+- The archive endpoint is workspace-scoped (`outputs:read` scope) and rate-limited (`ANTPATH_RATE_LIMIT_RUN_ARCHIVE_PER_MINUTE`, default 30/min/workspace).
+- `manifest.json` never contains file bytes — only ids, paths, sizes, content types.

package/docs/quickstart.md

@@ -45,3 +45,40 @@ antpath run ./template.json \
 ```
 
 Both surfaces hit the same dashboard BFF and operate on the same durable run records — pick whichever is most convenient.
+
+## Safe retries with `idempotencyKey`
+
+Every `submitRun` call carries an `idempotencyKey`. When omitted the SDK auto-generates a UUID per call. Supplying your own key makes retries deterministic:
+
+| Submit shape | Server response |
+| --- | --- |
+| New `idempotencyKey` | HTTP 201 — new run created. |
+| Same key + identical request body hash | HTTP 200 — returns the original run. The SDK call resolves with the existing `RunRef`. |
+| Same key + **different** request body hash | HTTP 409 — body `{ error: { message, code: "idempotency_conflict", details: { existingRunId } } }`. The SDK throws an `HttpError` carrying that body. Use `details.existingRunId` to adopt the pre-existing run, or pick a fresh key. |
+| Omitted `idempotencyKey` | A new UUID is generated on every call — repeat submissions create new runs. |
+
+The request hash is computed server-side over the canonical submission JSON (model, prompt, system, environment, skill refs, MCP server descriptors, proxy endpoints, `outputDirs`, etc.) so reordering JSON keys, adding whitespace, or rotating the inline secret bundle does **not** change the hash. Bumping a variable or changing the prompt does.
+
+Pattern for safe retries:
+
+```ts
+const idempotencyKey = crypto.randomUUID();
+async function submitWithRetry() {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      return await client.submitRun({
+        model: "claude-haiku-4-5",
+        prompt: "...",
+        idempotencyKey,
+        secrets: { anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! } }
+      });
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("network")) continue;
+      throw err;
+    }
+  }
+  throw new Error("submitRun failed after retries");
+}
+```
+
+The same `idempotencyKey` reused with the same body will deterministically resolve to the same run id regardless of how many times the network drops between attempts.

package/docs/skills.md

@@ -16,3 +16,52 @@ Local directories are packaged as zip files and mounted under `/antpath/skills/`
 Inline skills are uploaded as markdown files and mounted under `/antpath/skills/` unless overridden.
 
 The platform also mounts the `antpath` CLI at `/antpath/antpath` and a per-run manifest at `/antpath/index.json` on **every** run. Skills can invoke the managed HTTP proxy via `/antpath/antpath proxy …` — see `credentials.md` for the policy/auth model.
+
+## Workspace skills: upload, find, reuse
+
+Workspace skills persist across runs. Build a `Skill` from files, upload once, reference by `skl_*` id thereafter:
+
+```ts
+import { AntpathClient, Skill } from "antpath";
+
+const client = new AntpathClient({ apiToken });
+
+// First publish.
+const draft = await Skill.fromPath("./skills/broll-provider-ingest", {
+  name: "broll-provider-ingest"
+});
+const persisted = await draft.upload(client);
+console.log(persisted.record!.id);   // skl_…
+```
+
+### `uploadIfChanged(client)`
+
+Repeat publishes are common in CI. `uploadIfChanged` first checks whether a live skill with the same `(name, contentHash)` already exists, and only uploads when the bytes have actually changed:
+
+```ts
+const skill = await Skill.fromPath("./skills/broll-provider-ingest", {
+  name: "broll-provider-ingest"
+}).then((draft) => draft.uploadIfChanged(client));
+```
+
+`contentHash` is `sha256:<hex>` of the canonical bundle zip (the SDK normalises file order, mtime, and permissions before hashing). Identical inputs always produce the same hash, so a no-op `uploadIfChanged` returns the existing record without re-uploading bytes.
+
+After the call resolves, the returned `Skill` is workspace-backed regardless of whether bytes were uploaded — pass it straight to `submitRun({ skills: [...] })` or call `.record!.id` to persist the id in your manifest.
+
+### `client.skills.findByHash(...)` / `findByName(...)`
+
+You can also look up workspace skills directly:
+
+```ts
+const byHash = await client.skills.findByHash({
+  name: "broll-provider-ingest",
+  contentHash: "sha256:..."
+});
+
+const byName = await client.skills.findByName("broll-provider-ingest");
+```
+
+Both return `null` when no live, undeleted skill matches. `findByHash` is an indexed lookup on `(name, hash)` — use it when you have a precomputed hash. `findByName` is a list-and-filter convenience for the common "what's the current id of this skill?" case.
+
+Soft-deleted skills are never returned by either method. Runs that pinned a soft-deleted skill at submission time keep working via their snapshot — see `references/architecture-decisions.md` for the full snapshot model.
+