antpath 0.7.0 → 0.8.0

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.
+

package/package.json

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