antpath 0.7.0 → 0.9.0

package/dist/_shared/submission.d.ts

@@ -175,6 +175,27 @@ export interface PlatformFlatSubmission {
     readonly mcpServers: readonly McpServerRef[];
     readonly environment?: PlatformTemplateEnvironment;
     readonly metadata?: Record<string, JsonValue>;
+    /**
+     * Opt-in container paths to capture as `output_objects` at session
+     * terminal. When omitted, the worker still persists run metadata
+     * (status, events, snapshots, cleanup state) but does not capture
+     * any container file bytes. When present, the worker drives a
+     * synthetic agent turn at session terminal that instructs the agent
+     * to register every file under these paths via the Anthropic Files
+     * API, then walks the resulting list and copies bytes into private
+     * Supabase Storage.
+     *
+     * Validation:
+     *   - Absolute UNIX paths only (starts with `/`).
+     *   - No `..` segments, no NUL bytes, no embedded newlines.
+     *   - Max 32 entries.
+     *   - Max 512 bytes per entry.
+     *
+     * Entries are normalised (collapse `/+`, drop trailing `/` except
+     * for `/`) and deduplicated. The normalised list is what travels in
+     * the idempotency hash and the run snapshot.
+     */
+    readonly outputDirs?: readonly string[];
 }
 export interface PlatformFlatRunSubmissionRequest {
     readonly workspaceId: string;

package/dist/_shared/submission.js

@@ -272,6 +272,9 @@ function parseProxyAuthShape(input, field) {
     const value = requireRecord(input, field);
     const type = requireString(value.type, `${field}.type`);
     switch (type) {
+        case "none":
+            assertOnlyKeys(value, field, ["type"]);
+            return { type: "none" };
         case "bearer":
             assertOnlyKeys(value, field, ["type"]);
             return { type: "bearer" };
@@ -293,7 +296,7 @@ function parseProxyAuthShape(input, field) {
             return { type: "query", name };
         }
         default:
-            throw new Error(`${field}.type must be one of: bearer, basic, header, query`);
+            throw new Error(`${field}.type must be one of: none, bearer, basic, header, query`);
     }
 }
 function parseProxyMethods(input, field) {
@@ -382,6 +385,16 @@ function crossValidateProxyEndpointsAndAuth(endpoints, auth) {
     const authByName = new Map(authList.map((a) => [a.name, a]));
     for (const endpoint of endpointsList) {
         const authEntry = authByName.get(endpoint.name);
+        if (endpoint.authShape.type === "none") {
+            // Keyless endpoints carry no auth value. Reject any matching
+            // auth entry so callers don't accidentally ship a secret bound
+            // to a "none" endpoint (which would be silently ignored at
+            // request time — confusing and a leak risk).
+            if (authEntry) {
+                throw new Error(`proxyEndpoints[${endpoint.name}] has authShape "none" but a matching secrets.proxyEndpointAuth entry was supplied; remove the auth entry`);
+            }
+            continue;
+        }
         if (!authEntry) {
             throw new Error(`proxyEndpoints[${endpoint.name}] has no matching secrets.proxyEndpointAuth entry`);
         }
@@ -742,7 +755,8 @@ function parseFlatSubmission(input) {
         "skills",
         "mcpServers",
         "environment",
-        "metadata"
+        "metadata",
+        "outputDirs"
     ]);
     for (const key of Object.keys(value)) {
         if (!allowed.has(key)) {
@@ -756,6 +770,7 @@ function parseFlatSubmission(input) {
     const mcpServers = parseFlatMcpServers(value.mcpServers);
     const environment = parseTemplateEnvironment(value.environment);
     const metadata = optionalJsonRecord(value.metadata, "submission.metadata");
+    const outputDirs = parseOutputDirs(value.outputDirs);
     return {
         model,
         ...(system ? { system } : {}),
@@ -763,9 +778,84 @@ function parseFlatSubmission(input) {
         skills,
         mcpServers,
         ...(environment ? { environment } : {}),
-        ...(metadata ? { metadata } : {})
+        ...(metadata ? { metadata } : {}),
+        ...(outputDirs ? { outputDirs } : {})
     };
 }
+/**
+ * Maximum number of `outputDirs` entries accepted per submission.
+ *
+ * 32 is enough room for the typical "one or two capture roots" pattern
+ * plus a generous margin for legitimate multi-root use cases (per-tool
+ * output directory + scratch state + logs, repeated across a few
+ * subdirectories), without inviting abuse of the synthetic-turn path
+ * the worker drives at session terminal.
+ */
+const MAX_OUTPUT_DIRS = 32;
+/**
+ * Maximum byte length of a single `outputDirs` entry (after UTF-8
+ * encoding). 512 bytes comfortably covers `/very/long/nested/path`
+ * style entries without letting a misuse smuggle large blobs through
+ * the field.
+ */
+const MAX_OUTPUT_DIR_BYTES = 512;
+function parseOutputDirs(input) {
+    if (input === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(input)) {
+        throw new Error("submission.outputDirs must be an array of absolute UNIX paths");
+    }
+    if (input.length === 0) {
+        // Treat an empty array as omission so the idempotency hash matches
+        // the "no outputDirs" case.
+        return undefined;
+    }
+    if (input.length > MAX_OUTPUT_DIRS) {
+        throw new Error(`submission.outputDirs has ${input.length} entries; max is ${MAX_OUTPUT_DIRS}`);
+    }
+    const seen = new Set();
+    const normalised = [];
+    for (let i = 0; i < input.length; i++) {
+        const item = input[i];
+        if (typeof item !== "string") {
+            throw new Error(`submission.outputDirs[${i}] must be a string`);
+        }
+        if (item.length === 0) {
+            throw new Error(`submission.outputDirs[${i}] must be a non-empty absolute UNIX path`);
+        }
+        const bytes = new TextEncoder().encode(item).length;
+        if (bytes > MAX_OUTPUT_DIR_BYTES) {
+            throw new Error(`submission.outputDirs[${i}] exceeds ${MAX_OUTPUT_DIR_BYTES} bytes (got ${bytes})`);
+        }
+        if (!item.startsWith("/")) {
+            throw new Error(`submission.outputDirs[${i}] must be an absolute UNIX path (start with '/')`);
+        }
+        if (item.includes("\0")) {
+            throw new Error(`submission.outputDirs[${i}] must not contain NUL bytes`);
+        }
+        if (item.includes("\n") || item.includes("\r")) {
+            throw new Error(`submission.outputDirs[${i}] must not contain newline characters`);
+        }
+        const segments = item.split("/");
+        if (segments.includes("..")) {
+            throw new Error(`submission.outputDirs[${i}] must not contain '..' segments`);
+        }
+        const collapsed = segments
+            .filter((seg, idx) => seg.length > 0 || idx === 0)
+            .join("/");
+        const stripped = collapsed.length > 1 && collapsed.endsWith("/")
+            ? collapsed.slice(0, -1)
+            : collapsed;
+        const canonical = stripped.length === 0 ? "/" : stripped;
+        if (seen.has(canonical)) {
+            continue;
+        }
+        seen.add(canonical);
+        normalised.push(canonical);
+    }
+    return normalised;
+}
 function parseFlatPrompt(input) {
     if (typeof input === "string") {
         if (input.length === 0) {

package/dist/cli.mjs

@@ -6,7 +6,12 @@ var __export = (target, all) => {
 };
 
 // dist/cli.js
-import { readFile as readFile2, writeFile } from "node:fs/promises";
+import { readFile as readFile2, writeFile, readdir as readdir2, stat as stat2 } from "node:fs/promises";
+import { resolve as resolvePath4 } from "node:path";
+
+// dist/internal.js
+var ANTPATH_INDEX_PATH = "/antpath/index.json";
+var ANTPATH_RUN_TOKEN_PATH = "/antpath/run-token";
 
 // ../shared/dist/config.js
 var DEFAULT_CAPS = {
@@ -527,7 +532,11 @@ __export(operations_exports, {
   createSkillBundle: () => createSkillBundle,
   deleteRun: () => deleteRun,
   deleteSkill: () => deleteSkill,
+  downloadRunArchive: () => downloadRunArchive,
+  findSkillByHash: () => findSkillByHash,
+  findSkillByName: () => findSkillByName,
   getRun: () => getRun,
+  getRunUnit: () => getRunUnit,
   getSkill: () => getSkill,
   listOutputs: () => listOutputs,
   listRunEvents: () => listRunEvents,
@@ -547,6 +556,9 @@ async function getRun(http, runId) {
   const result = await http.request(`/api/runs/${encodeURIComponent(runId)}`);
   return hasRun(result) ? result.run : result;
 }
+async function getRunUnit(http, runId) {
+  return http.request(`/api/runs/${encodeURIComponent(runId)}`);
+}
 async function listRunEvents(http, runId) {
   const result = await http.request(`/api/runs/${encodeURIComponent(runId)}/events`);
   return result.events;
@@ -567,6 +579,10 @@ async function deleteRun(http, runId) {
 async function whoami(http) {
   return http.request("/api/whoami");
 }
+async function downloadRunArchive(http, runId) {
+  const { response } = await http.download(`/api/runs/${encodeURIComponent(runId)}/download`);
+  return response;
+}
 async function submitRunFlat(http, request) {
   return http.request("/api/runs", {
     method: "POST",
@@ -623,6 +639,18 @@ async function deleteSkill(http, skillId) {
     method: "DELETE"
   });
 }
+async function findSkillByHash(http, args) {
+  const params = new URLSearchParams({
+    name: args.name,
+    content_hash: args.contentHash
+  });
+  const result = await http.request(`/api/skills/by-hash?${params.toString()}`);
+  return result.skill ?? null;
+}
+async function findSkillByName(http, name) {
+  const skills = await listSkills(http);
+  return skills.find((skill) => skill.name === name) ?? null;
+}
 function unwrapSkill(result) {
   if (result && typeof result === "object" && "skill" in result) {
     return result.skill;
@@ -669,10 +697,6 @@ function validateProxyAuth(endpoints, auth) {
   }
 }
 
-// dist/internal.js
-var ANTPATH_INDEX_PATH = "/antpath/index.json";
-var ANTPATH_RUN_TOKEN_PATH = "/antpath/run-token";
-
 // dist/host/common.js
 var SUCCESS = { code: 0 };
 var USAGE_ERR = { code: 2 };
@@ -830,6 +854,52 @@ function takeBooleanFlag(rest, flag) {
   return { present, remaining };
 }
 
+// dist/outputs-sync.js
+async function runOutputsSyncCmd(io2, dirs) {
+  if (dirs.length === 0) {
+    io2.stderr("usage: antpath outputs sync <dir> [<dir> ...]\n");
+    return USAGE_ERR;
+  }
+  try {
+    await io2.readFile(ANTPATH_INDEX_PATH);
+  } catch {
+    io2.stderr("`antpath outputs sync` is an in-container internal command and cannot run on the host.\n");
+    return USAGE_ERR;
+  }
+  if (!io2.walkDirectory) {
+    io2.stderr("antpath outputs sync: walkDirectory IO is not available\n");
+    return RUNTIME_ERR;
+  }
+  let scanned = 0;
+  let missing = 0;
+  for (const dir of dirs) {
+    if (!dir.startsWith("/")) {
+      io2.stderr(JSON.stringify({ dir, error: "non_absolute_path", message: "skipping non-absolute output dir" }) + "\n");
+      missing++;
+      continue;
+    }
+    let entries;
+    try {
+      entries = await io2.walkDirectory(dir);
+    } catch (err2) {
+      io2.stderr(JSON.stringify({ dir, error: "walk_failed", message: err2.message ?? "walk failed" }) + "\n");
+      missing++;
+      continue;
+    }
+    if (entries === null) {
+      io2.stderr(JSON.stringify({ dir, error: "missing_or_unreadable" }) + "\n");
+      missing++;
+      continue;
+    }
+    for (const entry of entries) {
+      io2.stdout(JSON.stringify({ dir, path: entry.path, sizeBytes: entry.sizeBytes }) + "\n");
+      scanned++;
+    }
+  }
+  io2.stdout(JSON.stringify({ summary: { dirs: dirs.length, files: scanned, missing } }) + "\n");
+  return SUCCESS;
+}
+
 // dist/proxy.js
 function parseProxyFlags(rest) {
   let endpointName = null;
@@ -2644,7 +2714,7 @@ async function runOutputsCmd(io2, argv) {
 }
 
 // dist/host/download.js
-import { resolve as resolvePath3, basename as basename2 } from "node:path";
+import { resolve as resolvePath3 } from "node:path";
 async function runDownloadCmd(io2, argv) {
   if (await refuseInsideManagedRun(io2, "download"))
     return USAGE_ERR;
@@ -2661,51 +2731,38 @@ async function runDownloadCmd(io2, argv) {
     return USAGE_ERR;
   }
   const positional = outFlag.remaining.filter((arg) => !arg.startsWith("--"));
-  if (positional.length !== 2) {
-    io2.stderr("usage: antpath download <run-id> <output-id> [--out path] [common flags]\n");
+  if (positional.length !== 1) {
+    io2.stderr("usage: antpath download <run-id> [--out path] [common flags]\n");
     return USAGE_ERR;
   }
   const runId = positional[0];
-  const outputId = positional[1];
   const http = makeHttpClient(io2, common.flags);
-  let link;
+  let response;
   try {
-    link = await operations_exports.createOutputLink(http, runId, outputId);
+    response = await operations_exports.downloadRunArchive(http, runId);
   } catch (err2) {
-    return emitJsonError(io2, "link_failed", err2.message ?? "create link failed", { runId, outputId });
+    return emitJsonError(io2, "download_failed", err2.message ?? "download failed", { runId });
   }
-  let response;
+  let bytes;
   try {
-    response = await io2.fetchImpl(link.url, { method: "GET", redirect: "follow" });
+    bytes = new Uint8Array(await response.arrayBuffer());
   } catch (err2) {
-    return emitJsonError(io2, "download_failed", `download fetch failed: ${err2.message}`, { runId, outputId });
-  }
-  if (!response.ok) {
-    return emitJsonError(io2, "download_failed", `download HTTP ${response.status}`, { runId, outputId });
+    return emitJsonError(io2, "download_failed", `download read failed: ${err2.message}`, { runId });
   }
-  const buffer = new Uint8Array(await response.arrayBuffer());
-  const destination = resolveDestination(io2, outFlag.value, outputId, link.url);
+  const destination = resolveDestination(io2, outFlag.value, runId);
   try {
-    await io2.writeFile(destination, buffer);
+    await io2.writeFile(destination, bytes);
   } catch (err2) {
-    return emitJsonError(io2, "write_failed", `failed to write output: ${err2.message}`, { destination });
+    return emitJsonError(io2, "write_failed", `failed to write archive: ${err2.message}`, { destination });
   }
-  io2.stdout(JSON.stringify({ runId, outputId, path: destination, bytes: buffer.byteLength }) + "\n");
+  io2.stdout(JSON.stringify({ runId, path: destination, bytes: bytes.byteLength }) + "\n");
   return SUCCESS;
 }
-function resolveDestination(io2, out, outputId, signedUrl) {
+function resolveDestination(io2, out, runId) {
   if (out) {
     return resolvePath3(io2.cwd(), out);
   }
-  let fileName = `${outputId}`;
-  try {
-    const url = new URL(signedUrl);
-    const tail = basename2(url.pathname);
-    if (tail)
-      fileName = tail;
-  } catch {
-  }
-  return resolvePath3(io2.cwd(), fileName);
+  return resolvePath3(io2.cwd(), `antpath-run-${runId}.zip`);
 }
 
 // dist/host/cancel.js
@@ -2815,6 +2872,9 @@ async function dispatch(io2, args) {
     case "events":
       return runEventsCmd(io2, rest);
     case "outputs":
+      if (rest[0] === "sync") {
+        return runOutputsSyncCmd(io2, rest.slice(1));
+      }
       return runOutputsCmd(io2, rest);
     case "download":
       return runDownloadCmd(io2, rest);
@@ -2864,7 +2924,7 @@ Protocol version: ${manifest.protocolVersion}
   io2.stdout("  antpath status <run-id> --api-token T\n");
   io2.stdout("  antpath events <run-id> [--follow] --api-token T\n");
   io2.stdout("  antpath outputs <run-id> --api-token T\n");
-  io2.stdout("  antpath download <run-id> <output-id> [--out path] --api-token T\n");
+  io2.stdout("  antpath download <run-id> [--out path] --api-token T\n");
   io2.stdout("  antpath cancel <run-id> --api-token T\n");
   io2.stdout("  antpath delete <run-id> --api-token T\n");
   io2.stdout("  antpath whoami --api-token T\n");
@@ -2892,6 +2952,30 @@ Protocol version: ${manifest.protocolVersion}
 }
 
 // dist/cli.js
+async function walkDirectory(root) {
+  try {
+    const rootStat = await stat2(root);
+    if (!rootStat.isDirectory())
+      return null;
+  } catch {
+    return null;
+  }
+  const out = [];
+  async function visit(dir) {
+    const entries = await readdir2(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = resolvePath4(dir, entry.name);
+      if (entry.isDirectory()) {
+        await visit(full);
+      } else if (entry.isFile()) {
+        const s = await stat2(full);
+        out.push({ path: full, sizeBytes: s.size });
+      }
+    }
+  }
+  await visit(root);
+  return out;
+}
 var io = {
   readFile: (path) => readFile2(path, "utf8"),
   writeFile: (path, data) => writeFile(path, data),
@@ -2900,6 +2984,7 @@ var io = {
   stderr: (chunk) => process.stderr.write(chunk),
   exit: (code) => process.exit(code),
   argv: process.argv,
-  cwd: () => process.cwd()
+  cwd: () => process.cwd(),
+  walkDirectory
 };
 await runCli(io);

package/dist/cli.mjs.sha256

@@ -1 +1 @@
-974924653a05ddcd4ac437ebc2c1e38f3ddc833c56c113f838f1c6df235b0473  cli.mjs
+c4520d53e89222d7073d467e376774789532d5b9a932c7ae6821e527cb718e0e  cli.mjs

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { HttpClient, type FetchLike, type Output, type PlatformFlatRunSubmissionInput, type PlatformFlatSubmission, type PlatformInlineSecrets, type PlatformProxyEndpoint, type PlatformProxyEndpointAuth, type Run, type RunEvent, type SignedOutputLink, type Skill as SkillRecord, type WhoAmI } from "./_shared/index.js";
+import { HttpClient, type FetchLike, type Output, type PlatformFlatRunSubmissionInput, type PlatformFlatSubmission, type PlatformInlineSecrets, type PlatformProxyEndpoint, type PlatformProxyEndpointAuth, type Run, type RunEvent, type RunUnit, type SignedOutputLink, type Skill as SkillRecord, type WhoAmI } from "./_shared/index.js";
 import type { Blueprint } from "./blueprint.js";
 import { McpServer } from "./mcp-server.js";
 import { ProxyEndpoint } from "./proxy-endpoint.js";
@@ -51,6 +51,21 @@ export interface SubmitRunOptions {
     readonly metadata?: PlatformFlatSubmission["metadata"];
     readonly cleanup?: PlatformFlatRunSubmissionInput["cleanup"];
     readonly proxyEndpoints?: readonly ProxyEndpoint[];
+    /**
+     * Container paths to capture as `output_objects` at session terminal.
+     *
+     * - Omitted: run metadata (status/events/snapshots/cleanup state) is
+     *   still persisted, but no container file bytes are captured.
+     * - Present: the worker drives an agent-side sync at session terminal
+     *   that registers every file under these paths via the Anthropic
+     *   Files API. The bytes land in private Supabase Storage and can be
+     *   retrieved via `RunRef.outputs()` / `RunRef.download()`.
+     *
+     * Paths are absolute UNIX paths (start with `/`), max 32 entries,
+     * max 512 bytes per entry, no `..` segments, no NUL bytes. See
+     * `packages/sdk/docs/outputs.md` for the full contract.
+     */
+    readonly outputDirs?: readonly string[];
     readonly secrets: PlatformInlineSecrets;
     readonly idempotencyKey?: string;
     readonly signal?: AbortSignal;
@@ -74,10 +89,34 @@ export declare class RunRef {
     readonly runId: string;
     constructor(client: AntpathClient, runId: string);
     get(): Promise<Run>;
+    /** Convenience wrapper for `AntpathClient.getRunUnit`. */
+    getUnit(): Promise<RunUnit>;
     events(): Promise<readonly RunEvent[]>;
     stream(options?: StreamEventsOptions): AsyncIterable<RunEvent>;
     wait(options?: WaitForRunOptions): Promise<Run>;
     outputs(): Promise<readonly Output[]>;
+    /**
+     * Download the per-run archive zip. Lifecycle-aware in one method:
+     *
+     *  - Pre-session (run still `queued`): rejects with a 409
+     *    `run_not_started` error. Poll `RunRef.get()` until the status
+     *    leaves `queued` before retrying.
+     *  - Mid-session: returns whatever has been captured so far. The
+     *    archive's `manifest.json` carries `partial: true` and a
+     *    `missing[]` entry advising the caller to redownload after
+     *    terminal for the full archive.
+     *  - Terminal: returns the complete archive sourced from durable
+     *    Supabase Storage. `manifest.json` carries `partial: false`.
+     *
+     * Pass `to` to write the archive zip to a file path; omit it to
+     * receive the raw streaming `Response` (use this for piping to a
+     * custom sink). `to` resolves through Node's `fs/promises` and is
+     * not available in browsers — browser callers omit `to` and pipe
+     * `Response.body` themselves.
+     */
+    download(options?: {
+        readonly to?: string;
+    }): Promise<Response>;
     cancel(): Promise<void>;
     delete(): Promise<void>;
 }
@@ -99,6 +138,31 @@ export declare class SkillsClient {
     list(): Promise<readonly SkillRecord[]>;
     get(skillId: string): Promise<SkillRecord>;
     delete(skillId: string): Promise<void>;
+    /**
+     * Lookup a live workspace skill by `(name, contentHash)`.
+     *
+     * Returns the matching `Skill` record or `null` when no live row
+     * carries that hash. The `contentHash` is the wire format
+     * `sha256:<hex>` returned by `hashSkillBundle` (and stored verbatim
+     * on every skill row). The hash space is unique enough that one
+     * row at most can match, so this is a single keyed lookup.
+     *
+     * Powers `Skill.uploadIfChanged(client)` internally; consumers can
+     * also call it directly when they already have a hash in hand and
+     * want to know whether the skill is already persisted.
+     */
+    findByHash(args: {
+        readonly name: string;
+        readonly contentHash: string;
+    }): Promise<SkillRecord | null>;
+    /**
+     * Lookup a live workspace skill by `name`. Returns the matching
+     * `Skill` record or `null` when no live row carries that name.
+     * Implemented as a list-and-filter against the existing `/api/skills`
+     * endpoint — typical workspace skill counts are small enough that
+     * the cost is negligible.
+     */
+    findByName(name: string): Promise<SkillRecord | null>;
     /**
      * Internal: post a pre-bundled skill zip to the BFF. Only
      * `Skill.upload` calls this. NOT part of the public API.
@@ -157,6 +221,16 @@ export declare class AntpathClient {
      */
     submitRun(options: SubmitRunOptions): Promise<RunRef>;
     getRun(runId: string): Promise<Run>;
+    /**
+     * Fetch the self-contained `RunUnit`: parsed submission inputs,
+     * attempts, indexed events (inline + cursor for the tail), raw
+     * provider-event Storage manifest, outputs, capture failures,
+     * proxy-call audit, pinned workspace skills, provider skills,
+     * transient skills. Backed by the same endpoint as `getRun` but
+     * typed against the full wire shape — use this when you need
+     * fields beyond `{id, status, timestamps, usage}`.
+     */
+    getRunUnit(runId: string): Promise<RunUnit>;
     listEvents(runId: string): Promise<readonly RunEvent[]>;
     /**
      * Poll the events endpoint and yield new events as they arrive. Stops
@@ -174,5 +248,12 @@ export declare class AntpathClient {
     cancelRun(runId: string): Promise<void>;
     deleteRun(runId: string): Promise<void>;
     whoami(): Promise<WhoAmI>;
+    /**
+     * Stream the per-run archive zip body. Returned `Response` body is
+     * `application/zip` and may be piped directly to disk; the SDK never
+     * buffers the archive. Callers requiring a "write to a path" verb
+     * should use `RunRef.download({ to })`.
+     */
+    downloadRunArchive(runId: string): Promise<Response>;
 }
 export type { Blueprint, PlatformProxyEndpoint, PlatformProxyEndpointAuth };

package/dist/client.js

@@ -17,6 +17,10 @@ export class RunRef {
     get() {
         return this.#client.getRun(this.runId);
     }
+    /** Convenience wrapper for `AntpathClient.getRunUnit`. */
+    getUnit() {
+        return this.#client.getRunUnit(this.runId);
+    }
     events() {
         return this.#client.listEvents(this.runId);
     }
@@ -29,6 +33,34 @@ export class RunRef {
     outputs() {
         return this.#client.listOutputs(this.runId);
     }
+    /**
+     * Download the per-run archive zip. Lifecycle-aware in one method:
+     *
+     *  - Pre-session (run still `queued`): rejects with a 409
+     *    `run_not_started` error. Poll `RunRef.get()` until the status
+     *    leaves `queued` before retrying.
+     *  - Mid-session: returns whatever has been captured so far. The
+     *    archive's `manifest.json` carries `partial: true` and a
+     *    `missing[]` entry advising the caller to redownload after
+     *    terminal for the full archive.
+     *  - Terminal: returns the complete archive sourced from durable
+     *    Supabase Storage. `manifest.json` carries `partial: false`.
+     *
+     * Pass `to` to write the archive zip to a file path; omit it to
+     * receive the raw streaming `Response` (use this for piping to a
+     * custom sink). `to` resolves through Node's `fs/promises` and is
+     * not available in browsers — browser callers omit `to` and pipe
+     * `Response.body` themselves.
+     */
+    async download(options) {
+        const response = await this.#client.downloadRunArchive(this.runId);
+        if (options?.to !== undefined) {
+            const buffer = new Uint8Array(await response.arrayBuffer());
+            const { writeFile } = await import("node:fs/promises");
+            await writeFile(options.to, buffer);
+        }
+        return response;
+    }
     cancel() {
         return this.#client.cancelRun(this.runId);
     }
@@ -62,6 +94,32 @@ export class SkillsClient {
     delete(skillId) {
         return operations.deleteSkill(this.#http, skillId);
     }
+    /**
+     * Lookup a live workspace skill by `(name, contentHash)`.
+     *
+     * Returns the matching `Skill` record or `null` when no live row
+     * carries that hash. The `contentHash` is the wire format
+     * `sha256:<hex>` returned by `hashSkillBundle` (and stored verbatim
+     * on every skill row). The hash space is unique enough that one
+     * row at most can match, so this is a single keyed lookup.
+     *
+     * Powers `Skill.uploadIfChanged(client)` internally; consumers can
+     * also call it directly when they already have a hash in hand and
+     * want to know whether the skill is already persisted.
+     */
+    findByHash(args) {
+        return operations.findSkillByHash(this.#http, args);
+    }
+    /**
+     * Lookup a live workspace skill by `name`. Returns the matching
+     * `Skill` record or `null` when no live row carries that name.
+     * Implemented as a list-and-filter against the existing `/api/skills`
+     * endpoint — typical workspace skill counts are small enough that
+     * the cost is negligible.
+     */
+    findByName(name) {
+        return operations.findSkillByName(this.#http, name);
+    }
     /**
      * Internal: post a pre-bundled skill zip to the BFF. Only
      * `Skill.upload` calls this. NOT part of the public API.
@@ -156,7 +214,10 @@ export class AntpathClient {
             skills: skillRefs,
             mcpServers: submissionMcpServers,
             ...(options.environment ? { environment: options.environment } : {}),
-            ...(options.metadata ? { metadata: options.metadata } : {})
+            ...(options.metadata ? { metadata: options.metadata } : {}),
+            ...(options.outputDirs && options.outputDirs.length > 0
+                ? { outputDirs: options.outputDirs }
+                : {})
         };
         const secrets = {
             ...options.secrets,
@@ -180,6 +241,18 @@ export class AntpathClient {
     getRun(runId) {
         return operations.getRun(this.#http, runId);
     }
+    /**
+     * Fetch the self-contained `RunUnit`: parsed submission inputs,
+     * attempts, indexed events (inline + cursor for the tail), raw
+     * provider-event Storage manifest, outputs, capture failures,
+     * proxy-call audit, pinned workspace skills, provider skills,
+     * transient skills. Backed by the same endpoint as `getRun` but
+     * typed against the full wire shape — use this when you need
+     * fields beyond `{id, status, timestamps, usage}`.
+     */
+    getRunUnit(runId) {
+        return operations.getRunUnit(this.#http, runId);
+    }
     listEvents(runId) {
         return operations.listRunEvents(this.#http, runId);
     }
@@ -241,6 +314,15 @@ export class AntpathClient {
     whoami() {
         return operations.whoami(this.#http);
     }
+    /**
+     * Stream the per-run archive zip body. Returned `Response` body is
+     * `application/zip` and may be piped directly to disk; the SDK never
+     * buffers the archive. Callers requiring a "write to a path" verb
+     * should use `RunRef.download({ to })`.
+     */
+    downloadRunArchive(runId) {
+        return operations.downloadRunArchive(this.#http, runId);
+    }
 }
 const TERMINAL_STATUSES = new Set([
     "succeeded",